722 lines
26 KiB
Markdown
722 lines
26 KiB
Markdown
# 开发准则与规范 (DesignerCEP / Photoshop Plugin)
|
||
|
||
## 1. 项目概述
|
||
|
||
本项目是一个基于 **Vue 3 + Vite + TypeScript** 的 Adobe Photoshop 扩展插件 (CEP) 项目。
|
||
|
||
## 2. 技术栈
|
||
|
||
### 2.1 核心框架与语言
|
||
|
||
- **核心框架**: Vue 3 (Composition API + `<script setup>`)
|
||
- **语言**: TypeScript
|
||
- **UI 组件库**: Arco Design Vue (`@arco-design/web-vue` v2.57.0)
|
||
- **CEP 环境**: Adobe CEP (宿主环境: **Adobe Photoshop**)
|
||
|
||
### 2.2 状态管理库
|
||
|
||
- **Pinia** (v3.0.4)
|
||
- Vue 3 官方推荐的状态管理库
|
||
- 使用 Composition API 风格,支持 TypeScript
|
||
- 项目中的使用:
|
||
- 在 `main.ts` 中全局注册: `app.use(createPinia())`
|
||
- Store 模块位于 `src/store/` 目录
|
||
- 示例: `src/store/app.ts` (应用全局状态)、`src/store/counter.ts`
|
||
- 使用方式:
|
||
|
||
```typescript
|
||
import { defineStore } from "pinia";
|
||
import { ref } from "vue";
|
||
|
||
export const useAppStore = defineStore("app", () => {
|
||
const loading = ref(false);
|
||
function setLoading(status: boolean) {
|
||
loading.value = status;
|
||
}
|
||
return { loading, setLoading };
|
||
});
|
||
```
|
||
|
||
### 2.3 请求管理库
|
||
|
||
- **Axios** (v1.6.8)
|
||
- 基于 Promise 的 HTTP 客户端
|
||
- 项目中的封装:
|
||
- 统一请求实例: `src/utils/request.ts`
|
||
- 请求拦截器: 自动添加 Token 到请求头
|
||
- 响应拦截器: 统一错误处理 (401 自动跳转登录、错误提示等)
|
||
- API 模块化: `src/api/` 目录下按功能模块划分
|
||
- `auth.ts` - 认证相关接口
|
||
- `user.ts` - 用户相关接口
|
||
- `checkin.ts` - 签到相关接口
|
||
- `analytics.ts` - 数据分析接口
|
||
- 配置说明:
|
||
- baseURL 通过 `src/config/index.ts` 统一管理
|
||
- 开发环境通过 Vite 代理转发到本地后端 (localhost:8000)
|
||
- 生产环境直接请求远程 API 服务器
|
||
|
||
### 2.4 工程管理库
|
||
|
||
- **Vite** (v4.3.9) - 构建工具
|
||
- 配置文件: `vite.config.ts`
|
||
- 开发服务器: 端口 5173,支持热更新
|
||
- 代理配置: `/api` 代理到本地后端
|
||
- 插件系统:
|
||
- `@vitejs/plugin-vue` - Vue 3 支持
|
||
- `@vitejs/plugin-legacy` - 兼容旧版 Chrome (CEP 环境)
|
||
- `vite-tsconfig-paths` - TypeScript 路径别名支持
|
||
- 自定义 `cepPlugin` - CEP 开发环境支持
|
||
- **Vue Router** (v4.2.4) - 路由管理
|
||
|
||
- 路由配置: `src/router/index.ts`
|
||
- 支持 Hash 模式 (适配 CEP 环境)
|
||
- 路由守卫: 登录验证、权限控制
|
||
|
||
- **TypeScript** (v5.1.5) - 类型系统
|
||
|
||
- 严格模式开启
|
||
- 类型定义: `src/types/` 目录
|
||
- 禁止使用 `any` (除非必要且需注释说明)
|
||
|
||
- **Vitest** (v1.6.0) - 测试框架
|
||
- 配置在 `vite.config.ts` 中
|
||
- 测试环境: jsdom
|
||
- 支持 UI 模式: `npm run test:ui`
|
||
|
||
### 2.5 其他重要库
|
||
|
||
- **@vueuse/core** (v10.4.1) - Vue 组合式工具库
|
||
- **dayjs** (v1.11.9) - 日期处理库
|
||
- **types-for-adobe** (v7.0.12) - Adobe CEP TypeScript 类型定义
|
||
|
||
---
|
||
|
||
## 3. 开发规范
|
||
|
||
### 3.1 Vue 3 & 代码风格
|
||
|
||
1. **Composition API**:
|
||
|
||
- 必须使用 `<script setup lang="ts">` 语法糖。
|
||
- 优先使用 `ref` 定义基本类型，`reactive` 定义对象类型。
|
||
- 逻辑复用应提取为 **Composables (Hooks)** (`useXxx`)，存放于 `src/hooks` 或 `src/composables`。
|
||
|
||
2. **组件 (Components)**:
|
||
|
||
- **单一职责**: 每个组件应只负责一个功能模块。
|
||
- **命名**: 文件名使用 **PascalCase** (如 `userProfile.vue` -> `UserProfile.vue`)。
|
||
- **Props 定义**: 使用 `defineProps<{ ... }>()` 进行类型安全的 Props 定义。
|
||
|
||
3. **TypeScript 类型安全**:
|
||
|
||
- ❌ **严禁使用 `any`**：除非是在不得不对接极度混乱的 legacy 代码时（需加注释说明）。
|
||
- **接口定义**: 数据模型应定义 interface，存放于 `src/types` 或组件同级目录。
|
||
- **CEP 交互**: 与 Photoshop 宿主环境交互时 (CSInterface, JSX 脚本)，应注意类型转换和错误处理。
|
||
|
||
4. **样式 (CSS/Less/Sass)**:
|
||
- 使用 **Scoped CSS** (`<style scoped>`) 避免全局因污染。
|
||
- 利用 Arco Design 的 Token 进行样式定制，保持 UI 风格统一。
|
||
|
||
### 3.2 日志管理规范
|
||
|
||
本项目使用统一的全局日志管理工具 (`logger`)，禁止直接使用 `console.*` 方法。
|
||
|
||
1. **核心原则**:
|
||
|
||
- ❌ **严禁直接使用 `console.log/warn/error/info/debug`**。
|
||
- ✅ **必须统一使用 `logger` 工具类**，位于 `src/utils/logger.ts`。
|
||
- ✅ **一键控制**：所有日志可通过全局开关统一开启/关闭，便于生产环境清理日志。
|
||
|
||
2. **使用方法**:
|
||
|
||
```typescript
|
||
import { logger } from "@/utils/logger";
|
||
|
||
// 普通日志
|
||
logger.log("用户登录成功");
|
||
|
||
// 信息日志
|
||
logger.info("正在加载数据...");
|
||
|
||
// 警告日志
|
||
logger.warn("Token 即将过期");
|
||
|
||
// 错误日志（始终显示，不受开关控制）
|
||
logger.error("API 请求失败:", error);
|
||
|
||
// 可控制的错误日志
|
||
logger.errorSilent("这个错误只在开启日志时显示");
|
||
|
||
// 调试日志
|
||
logger.debug("调试信息:", data);
|
||
|
||
// 分隔线
|
||
logger.separator(); // 输出 60 个 '='
|
||
logger.separator("-", 40); // 输出 40 个 '-'
|
||
```
|
||
|
||
3. **日志开关控制**:
|
||
|
||
```typescript
|
||
// 开启日志（开发环境）
|
||
logger.enable();
|
||
|
||
// 关闭日志（生产环境）
|
||
logger.disable();
|
||
|
||
// 切换日志状态
|
||
logger.toggle();
|
||
|
||
// 查询当前状态
|
||
console.log(logger.enabled); // true/false
|
||
```
|
||
|
||
4. **浏览器控制台访问**:
|
||
|
||
- 日志工具自动挂载到 `window.logger`，可在浏览器控制台直接操作：
|
||
|
||
```javascript
|
||
// 在 Chrome DevTools 控制台中
|
||
window.logger.enable(); // 开启日志
|
||
window.logger.disable(); // 关闭日志
|
||
window.logger.toggle(); // 切换状态
|
||
```
|
||
|
||
5. **特殊说明**:
|
||
|
||
- **错误日志策略**:
|
||
- `logger.error()` 始终输出，即使日志开关关闭（用于捕获关键错误）。
|
||
- 如需可控的错误日志，使用 `logger.errorSilent()`。
|
||
- **默认状态**: 日志默认为**关闭**状态，需要手动开启。
|
||
- **性能考虑**: 关闭日志后，所有日志调用不会产生任何输出，不影响性能。
|
||
|
||
6. **禁止事项**:
|
||
|
||
- ❌ 禁止在代码中直接使用 `console.log()` 等原生方法。
|
||
- ❌ 禁止删除日志代码（保留代码，通过开关控制）。
|
||
- ❌ 禁止在生产环境中开启日志（避免信息泄露）。
|
||
|
||
### 3.3 Adobe CEP & Photoshop 特有规范
|
||
|
||
1. **CSInterface**: 所有与 Photoshop 的交互必须通过 `CSInterface` 进行。
|
||
2. **Photoshop 脚本 (JSX)**:
|
||
- 宿主脚本（ExtendScript）位于 `/jsx` 目录。
|
||
- 优先使用 **ActionManager (ActionDescriptor/Reference)** 代码（通常更高效），但也支持 DOM 操作 (`app.activeDocument` 等)。
|
||
- **调试**: 使用 **ExtendScript Toolkit** 或 **VSCode ExtendScript Debugger** 调试 `.jsx` 文件。
|
||
3. **事件监听**: 使用 `CSInterface` 监听 Photoshop 事件（如文档切换、选区改变 `com.adobe.PhotoshopJSONCallback`）时，需注意性能开销。
|
||
4. **文件系统**: 利用 Node.js 上下文 (`fs`, `path`) 处理本地文件操作，比 JSX 传参更灵活。
|
||
5. **主题同步机制**:
|
||
- **Shell (AdminPanel)**: 监听 Photoshop 主题变化事件 (`com.adobe.csxs.events.ThemeColorChanged`)，并将主题数据（背景色、亮度等）通过 `postMessage` 发送给 iframe。
|
||
- **Content (Designer)**: 监听 `message` 事件接收主题数据，并根据动态算法计算出完整的主题色板（主色、侧边栏色、悬浮色等），通过 CSS 变量应用到页面。
|
||
- **双向通信**: Content 加载时会发送 `REQUEST_THEME` 消息主动请求当前主题，确保初始化时颜色正确。
|
||
|
||
### 3.4 目录结构建议 (参考)
|
||
|
||
```
|
||
src/
|
||
├── assets/ # 静态资源
|
||
├── components/ # 通用组件
|
||
├── view/ # 页面视图 (Pages)
|
||
├── router/ # 路由配置
|
||
├── hooks/ # 组合式函数 (Composables)
|
||
├── types/ # TypeScript 类型定义
|
||
├── utils/ # 工具函数 (含 CSInterface 封装)
|
||
├── App.vue
|
||
└── main.ts
|
||
```
|
||
|
||
### 3.5 CEP 插件 UI/UX 设计规范 ⭐⭐⭐
|
||
|
||
#### 1. **面板尺寸规范**（基于竞品实测）
|
||
|
||
CEP 插件运行在 Photoshop 侧边栏面板，**尺寸约束极其严格**，必须按照以下规范设计：
|
||
|
||
##### manifest.xml 配置（标准参数）
|
||
|
||
```xml
|
||
<Geometry>
|
||
<Size>
|
||
<Height>600</Height>
|
||
<Width>280</Width> <!-- 默认宽度 280px -->
|
||
</Size>
|
||
<MaxSize>
|
||
<Height>4080</Height>
|
||
<Width>600</Width> <!-- 最大宽度 600px -->
|
||
</MaxSize>
|
||
<MinSize>
|
||
<Height>600</Height>
|
||
<Width>280</Width> <!-- 最小宽度 280px -->
|
||
</MinSize>
|
||
</Geometry>
|
||
```
|
||
|
||
##### 设计约束
|
||
|
||
- **默认宽度**: 280px（竞品标准）
|
||
- **最小宽度**: 280px（不可再窄）
|
||
- **最大宽度**: 600px（不建议超过 450px）
|
||
- **高度**: 600px 起，支持无限垂直滚动
|
||
- **布局方向**: 必须是垂直布局，禁止横向滚动
|
||
|
||
##### CSS 设计准则
|
||
|
||
```css
|
||
/* 容器最大宽度约束 */
|
||
.cep-container {
|
||
max-width: 450px; /* 不要超过这个宽度 */
|
||
min-width: 280px;
|
||
width: 100%;
|
||
}
|
||
|
||
/* 侧边栏（仅图标）*/
|
||
.sidebar {
|
||
width: 40px; /* 仅显示图标，节省空间 */
|
||
position: fixed;
|
||
left: 0;
|
||
}
|
||
|
||
/* 主内容区 */
|
||
.main-content {
|
||
margin-left: 40px; /* 侧边栏宽度 */
|
||
padding: 8px; /* 紧凑内边距 */
|
||
}
|
||
|
||
/* 功能网格（自适应列数）*/
|
||
.feature-grid {
|
||
display: grid;
|
||
grid-template-columns: repeat(auto-fill, minmax(70px, 1fr));
|
||
gap: 8px;
|
||
}
|
||
```
|
||
|
||
#### 2. **间距系统**（紧凑设计）
|
||
|
||
```css
|
||
/* 不要用网页的大间距！ */
|
||
--spacing-xs: 4px; /* 最小间距 */
|
||
--spacing-sm: 6px; /* 小间距 */
|
||
--spacing-md: 8px; /* 中等间距（常用）*/
|
||
--spacing-lg: 12px; /* 大间距 */
|
||
--spacing-xl: 16px; /* 超大间距（很少用）*/
|
||
|
||
/* ❌ 错误示例 */
|
||
padding: 40px; /* 太大了！会浪费空间 */
|
||
margin: 24px 0; /* 太大了！ */
|
||
|
||
/* ✅ 正确示例 */
|
||
padding: 8px; /* 紧凑 */
|
||
margin: 12px 0; /* 适中 */
|
||
```
|
||
|
||
#### 3. **字体大小**（精简尺寸）
|
||
|
||
```css
|
||
--font-xs: 10px; /* 辅助文字 */
|
||
--font-sm: 11px; /* 说明文字 */
|
||
--font-base: 12px; /* 正文（默认）*/
|
||
--font-md: 13px; /* 小标题 */
|
||
--font-lg: 14px; /* 主标题（最大）*/
|
||
|
||
/* ❌ 不要用网页的大字体 */
|
||
h1 {
|
||
font-size: 24px;
|
||
} /* 太大！ */
|
||
h2 {
|
||
font-size: 20px;
|
||
} /* 太大！ */
|
||
|
||
/* ✅ CEP 插件标准 */
|
||
h1 {
|
||
font-size: 14px;
|
||
font-weight: 600;
|
||
}
|
||
h2 {
|
||
font-size: 13px;
|
||
font-weight: 500;
|
||
}
|
||
p {
|
||
font-size: 12px;
|
||
}
|
||
```
|
||
|
||
#### 4. **组件尺寸**
|
||
|
||
```css
|
||
/* 图标 */
|
||
--icon-sm: 16px; /* 小图标（菜单、按钮）*/
|
||
--icon-md: 24px; /* 中等图标 */
|
||
--icon-lg: 32px; /* 功能入口图标 */
|
||
--icon-xl: 48px; /* 主要功能图标（背景）*/
|
||
|
||
/* 按钮 */
|
||
--button-height-sm: 24px;
|
||
--button-height-md: 28px;
|
||
--button-height-lg: 32px; /* 最大 */
|
||
|
||
/* 输入框 */
|
||
--input-height: 28px;
|
||
|
||
/* ❌ 错误：不要用大尺寸 */
|
||
.button {
|
||
height: 48px;
|
||
} /* 太高！*/
|
||
|
||
/* ✅ 正确 */
|
||
.button {
|
||
height: 28px;
|
||
padding: 0 12px;
|
||
}
|
||
```
|
||
|
||
#### 5. **响应式网格**（自适应列数）
|
||
|
||
```css
|
||
/* 根据面板宽度自动调整列数 */
|
||
.feature-grid {
|
||
display: grid;
|
||
gap: 8px;
|
||
}
|
||
|
||
/* 窄面板 (<280px 不会出现，但做兜底) */
|
||
@media (max-width: 280px) {
|
||
.feature-grid {
|
||
grid-template-columns: repeat(2, 1fr);
|
||
}
|
||
}
|
||
|
||
/* 标准面板 (280-350px) - 最常见 */
|
||
@media (min-width: 280px) and (max-width: 350px) {
|
||
.feature-grid {
|
||
grid-template-columns: repeat(3, 1fr); /* 3列 */
|
||
}
|
||
}
|
||
|
||
/* 宽面板 (>350px) */
|
||
@media (min-width: 350px) {
|
||
.feature-grid {
|
||
grid-template-columns: repeat(4, 1fr); /* 4列 */
|
||
}
|
||
}
|
||
```
|
||
|
||
#### 6. **PS 主题适配 (Native Look)**
|
||
|
||
1. **PS 主题适配 (Native Look)**:
|
||
|
||
- ✅ **必须适配 Photoshop 的 4 种颜色主题**（深黑、深灰、浅灰、白）。
|
||
- ✅ **核心机制**:
|
||
- **获取颜色**: 通过 `new CSInterface().getHostEnvironment().appSkinInfo` 获取宿主环境颜色 (`panelBackgroundColor`)。
|
||
- **监听切换**: 必须监听 `com.adobe.csxs.events.ThemeColorChanged` 事件，实现实时自动切换。
|
||
- **实现参考代码**:
|
||
|
||
```typescript
|
||
const updateTheme = () => {
|
||
const csInterface = new CSInterface();
|
||
const skinInfo = csInterface.getHostEnvironment().appSkinInfo;
|
||
const color = skinInfo.panelBackgroundColor.color;
|
||
// 将 RGB 转换为 CSS 变量或应用到 body
|
||
const bgColor = `rgb(${Math.round(color.red)}, ${Math.round(
|
||
color.green
|
||
)}, ${Math.round(color.blue)})`;
|
||
document.body.style.backgroundColor = bgColor;
|
||
// TODO: 更新 Arco Design 的 Token (如 --color-bg-1)
|
||
};
|
||
|
||
// 初始化运行 + 监听事件
|
||
updateTheme();
|
||
new CSInterface().addEventListener(
|
||
"com.adobe.csxs.events.ThemeColorChanged",
|
||
updateTheme
|
||
);
|
||
```
|
||
|
||
- ❌ 禁止使用固定死颜色，导致在不同主题下看不清文字。
|
||
|
||
2. **样式库选择**:
|
||
|
||
- 虽然 Adobe 官方推荐 **Spectrum** (React)，但在 Vue 项目中，建议使用 **Arco Design** 并自定义通过 CSS 变量映射 PS 主题色。
|
||
- **Mac 兼容性**: 如果遇到点击事件无效，尝试 hack: `delete window.PointerEvent` (常见于 CEF 环境兼容问题)。
|
||
|
||
3. **视觉美感 (Aesthetics)**:
|
||
- ✅ **高级感**: 界面设计要精致，拒绝简陋的“工程师审美”。
|
||
- ✅ **微交互**: 按钮、列表项必须有 Hover/Active 状态和过渡动画 (`transition: all 0.2s`)。
|
||
- ✅ **排版**: 使用系统字体或 Inter，保持良好的留白 (Spacing) 和层级感。
|
||
|
||
---
|
||
|
||
## 4. 后端开发规范 (Python / FastAPI)
|
||
|
||
本项目后端采用 **FastAPI** 框架，必须遵循**模块化、组件化**的开发原则。
|
||
|
||
### 4.1 核心原则
|
||
|
||
1. **分层架构**: 严格分离 控制层(API)、业务层(Service) 和 数据模型(Schema/Model)。
|
||
- ❌ **禁止**在 API 路由函数中编写通过复杂的业务逻辑。
|
||
- ✅ 业务逻辑应封装在 `services/` 目录下的服务类中。
|
||
2. **类型安全**: 全面使用 **Pydantic** (`schemas/`) 定义请求和响应模型，利用 Python Type Hints。
|
||
3. **依赖注入**: 使用 FastAPI 的 `Depends` 进行服务注入和权限验证。
|
||
|
||
### 4.2 目录结构规范
|
||
|
||
后端代码位于 `Server/` 目录，内部结构如下：
|
||
|
||
```
|
||
Server/
|
||
├── app/
|
||
│ ├── api/ # 路由层 (Endpoints)
|
||
│ │ └── v1/ # 版本控制
|
||
│ │ ├── auth.py # 认证相关接口
|
||
│ │ └── user.py # 用户相关接口
|
||
│ ├── core/ # 核心配置 (Config, Security, Exceptions)
|
||
│ ├── schemas/ # 数据模型 (Pydantic Models) - 用于请求/响应
|
||
│ ├── services/ # 业务逻辑服务层
|
||
│ ├── models/ # 数据库模型 (SQLAlchemy/Tortoise) - 如需数据库
|
||
│ └── main.py # 程序入口
|
||
├── requirements.txt # 依赖列表
|
||
└── .env # 环境变量
|
||
```
|
||
|
||
### 4.3 编码规范
|
||
|
||
- **路由定义**: 使用 `APIRouter` 分散管理路由，不要全部写在 `main.py`。
|
||
- **错误处理**: 使用 `HTTPException` 抛出标准 HTTP 错误。
|
||
- **配置管理**: 所有配置项（数据库 URL、密钥等）必须从环境变量或 `core/config.py` 读取。
|
||
|
||
### 4.4 错误信息与本地化
|
||
|
||
- **后端接口返回的错误信息必须为中文**，统一由后端产生，不由前端拼接或翻译。
|
||
- 错误示例（`HTTPException.detail` 字段）：
|
||
- 登录失败：`用户名或密码错误`（401）
|
||
- 注册失败（密码不一致）：`两次输入的密码不一致`（400）
|
||
- 注册失败（用户名占用）：`用户名已被注册`（400）
|
||
- 单设备限制：`该账号已在其他设备在线`（403）
|
||
- 用户不存在：`用户不存在`（404）
|
||
- 前端显示层可以自行决定文案风格，但不得修改后端错误语义；建议原样展示或在 UI 上补充说明。
|
||
|
||
### 4.5 登录并发与在线时长
|
||
|
||
- **单设备同时在线限制**：后端基于 `device_id` 限制同账号仅允许一个设备在线；若另一设备尝试登录，返回 403 `该账号已在其他设备在线`。
|
||
- **会话记录**：后端在登录时记录 `login_at`，在登出时记录 `logout_at` 并计算在线时长 `duration_seconds`（秒）。
|
||
- **时长统计接口**：`GET /api/v1/auth/online-time/{username}` 返回该用户历史累计在线时长（秒）与当前活跃会话的实时在线时长（秒）。
|
||
- **前端约定**：登录时必须传入稳定的 `device_id`；登出时调用 `POST /api/v1/auth/logout` 释放会话，保证统计准确。
|
||
|
||
### 4.6 HTTP 接口交互与错误码规范
|
||
|
||
#### 1. 请求方法 (HTTP Methods)
|
||
|
||
- **GET (Get Request)**
|
||
|
||
- **用途**: 仅用于**获取/查询数据**。
|
||
- **特点**: 安全且幂等（多次请求结果一致），参数通常拼接在 URL Query 中。
|
||
- **场景**: 获取用户列表、查询订单详情。
|
||
|
||
- **POST (Post Request)**
|
||
|
||
- **用途**: 用于**创建新资源**、**提交表单**或**执行非幂等操作**。
|
||
- **特点**: 数据放在 Body 中，支持大数据量，安全性高于 GET。
|
||
- **场景**: 用户注册、登录、上传文件、合并图层。
|
||
|
||
- **PUT (Put Request)**
|
||
|
||
- **用途**: 用于**全量更新**资源。
|
||
- **特点**: 幂等操作。通常需要提供被更新资源的全部字段，未提供的字段可能被置空。
|
||
- **场景**: 覆盖保存用户个人信息（包含所有字段）。
|
||
|
||
- **PATCH (Patch Request)**
|
||
|
||
- **用途**: 用于**局部更新**资源。
|
||
- **特点**: 仅发送需要修改的字段，未发送的字段保持原样。
|
||
- **场景**: 仅修改用户的“昵称”或“头像”，而不影响其他信息。
|
||
|
||
- **DELETE (Delete Request)**
|
||
|
||
- **用途**: 用于**删除资源**。
|
||
- **特点**: 幂等操作。
|
||
- **场景**: 删除订单、注销账号。
|
||
|
||
- **OPTIONS (Options Request)**
|
||
|
||
- **用途**: **预检请求 (Pre-flight)**。
|
||
- **特点**: 浏览器在跨域请求 (CORS) 前自动发起，用于询问服务器支持哪些方法和 Header。
|
||
- **场景**: 本地开发环境调用远程 API 时的跨域检查。
|
||
|
||
- **HEAD (Head Request)**
|
||
- **用途**: 获取资源的元信息（Headers），但不返回 Body。
|
||
- **特点**: 速度快，用于检查资源是否存在或是否有更新。
|
||
- **场景**: 检查大文件下载链接是否有效、检查文件最后修改时间。
|
||
|
||
#### 2. 状态码规范 (Status Codes)
|
||
|
||
所有接口应遵循标准 HTTP 状态码，结合业务错误码 (`code`) 使用。
|
||
|
||
| 状态码 | 含义 | 常见场景 |
|
||
| :------ | :-------------------- | :----------------------------------------------------------------------------- |
|
||
| **200** | OK | 请求成功，业务逻辑执行完成。 |
|
||
| **400** | Bad Request | **客户端错误**。通常是参数缺失、格式错误或业务逻辑校验失败（如“密码不一致”）。 |
|
||
| **401** | Unauthorized | **未授权**。Token 无效、过期或未登录。前端应跳转至登录页。 |
|
||
| **403** | Forbidden | **禁止访问**。已登录但权限不足，或账号被在其他设备挤下线。 |
|
||
| **404** | Not Found | 请求的资源（用户、订单等）不存在。 |
|
||
| **500** | Internal Server Error | **服务器内部错误**。代码崩溃或数据库连接失败，需联系后端排查。 |
|
||
|
||
### 4.7 配置管理与可配置化原则 ⭐⭐⭐（核心）
|
||
|
||
#### 1. 统一配置管理
|
||
|
||
- ❌ **严禁硬编码**：所有路径地址、数据库连接字符串、API 请求地址、密钥等敏感或可变信息，禁止直接写在代码中。
|
||
- ✅ **集中管理**：
|
||
- 后端：必须使用环境变量 (`.env`) 或 `app/core/config.py` 进行管理。
|
||
- 前端/客户端：必须使用 `.env` 文件或专门的 `config.ts` 模块。
|
||
- 工具脚本：必须在脚本头部定义常量或读取外部配置文件。
|
||
|
||
#### 2. 业务配置可配置化原则 ⭐
|
||
|
||
> **目标**：本项目将分销给其他用户，所有业务配置必须可通过管理后台动态修改，不得写死在代码中。
|
||
|
||
##### 2.1 **必须可配置的业务规则**
|
||
|
||
| 配置项 | 存储位置 | 说明 |
|
||
| ------------------ | ------------------------- | ----------------------------------- |
|
||
| **功能积分消耗** | `features_config` 表 | 每个功能的积分价格（普通/VIP/SVIP） |
|
||
| **VIP 价格与权益** | `vip_config` 表 | VIP 套餐价格、每日配额、签到倍数 |
|
||
| **签到奖励规则** | `check_in_config` 表 | 连续签到天数对应的积分奖励 |
|
||
| **功能开关** | `features_config.enabled` | 动态启用/禁用功能 |
|
||
|
||
##### 2.2 **配置存储规范**
|
||
|
||
- ✅ **数据库存储**：所有可变业务配置必须存储在数据库表中
|
||
- ✅ **管理后台可视化**：必须在 AdminTool 提供可视化编辑界面
|
||
- ✅ **实时生效**：配置修改后无需重启服务，立即生效
|
||
- ❌ **禁止硬编码**：禁止在代码中写死任何业务规则（如 `if consecutive_days == 7: bonus = 20`）
|
||
|
||
##### 2.3 **配置修改流程**
|
||
|
||
```
|
||
分销商/运营人员
|
||
↓
|
||
AdminTool 管理后台（可视化界面）
|
||
↓
|
||
后端 API (`/api/v1/admin/config`)
|
||
↓
|
||
数据库表（features_config / vip_config / check_in_config）
|
||
↓
|
||
前端/插件读取（实时生效）
|
||
```
|
||
|
||
##### 2.4 **示例：正确 vs 错误**
|
||
|
||
**❌ 错误示例（硬编码）：**
|
||
|
||
```python
|
||
# 错误：写死在代码里
|
||
def calculate_bonus(consecutive_days):
|
||
if consecutive_days == 7:
|
||
return 20 # 硬编码
|
||
elif consecutive_days == 15:
|
||
return 50 # 硬编码
|
||
return 0
|
||
```
|
||
|
||
**✅ 正确示例（可配置）：**
|
||
|
||
```python
|
||
# 正确：从配置表读取
|
||
def calculate_bonus(consecutive_days):
|
||
config = get_checkin_config(consecutive_days) # 从数据库读取
|
||
return config.bonus_points
|
||
```
|
||
|
||
##### 2.5 **管理后台要求**
|
||
|
||
- ✅ 必须在 `AdminTool/admin_gui.py` 中实现配置管理界面
|
||
- ✅ 必须使用表格/表单展示配置项
|
||
- ✅ 必须提供「新增/编辑/删除」操作
|
||
- ✅ 必须提供「保存/刷新」按钮
|
||
- ✅ 必须有操作确认提示
|
||
|
||
#### 3. 代码规模限制
|
||
|
||
- ❌ **严禁"巨型文件"**：单个代码文件（`.py`, `.ts`, `.vue` 等）的行数 **不得超过 500 行**。
|
||
- ✅ **拆分重构**：
|
||
- 一旦文件接近 500 行，必须立即进行拆分。
|
||
- 将逻辑提取为独立的 Service、Utility 函数、Composable Hook 或子组件。
|
||
- 保持代码的"高内聚、低耦合"。
|
||
|
||
---
|
||
|
||
## 5. Git 提交规范
|
||
|
||
请遵循 **Conventional Commits** 规范：
|
||
|
||
- `feat`: 新增功能
|
||
- `fix`: 修复 Bug
|
||
- `docs`: 文档变更
|
||
- `style`: 代码格式调整（不影响逻辑）
|
||
- `refactor`: 代码重构
|
||
- `chore`: 构建工具或依赖变更
|
||
|
||
**示例**: `feat: 增加PS图层自动重命名功能`
|
||
|
||
---
|
||
|
||
## 5. 调试与构建
|
||
|
||
- **开发模式**: `npm run dev` (在浏览器预览 UI)
|
||
- **构建**: `npm run build`
|
||
- **CEP 调试**: 在 Photoshop 中加载扩展，访问 `http://localhost:XXXX` 进行 Chrome DevTools 调试 UI。
|
||
|
||
---
|
||
|
||
## 6. 项目架构与工作流 (2025 重构版)
|
||
|
||
经过 2025 年底的深度重构，项目采用了高效的 **"壳(Shell) + 核(Core)"** 架构：
|
||
|
||
### 6.1 核心模块分工
|
||
|
||
| 模块 | 目录 | 类型 | 职责 |
|
||
| :------------- | :------------------------------- | :------------------ | :--------------------------------------------------------------------------------------------- |
|
||
| **Designer** | `d:\main\DesignerCEP\Designer` | **核心业务 (Core)** | 包含所有设计工具、UI 界面和业务逻辑。开发时的主要工作区。 |
|
||
| **AdminPanel** | `d:\main\DesignerCEP\AdminPanel` | **加载壳 (Shell)** | 一个轻量级的 CEP 容器，负责在 PS 中运行。它不包含业务代码，只负责通过 `iframe` 加载 Designer。 |
|
||
| **Server** | `d:\main\DesignerCEP\Server` | **后端 (API)** | 基于 FastAPI 的纯数据接口服务。不负责托管静态页面（由 Caddy/Nginx 接管）。 |
|
||
| **AdminTool** | `d:\main\DesignerCEP\AdminTool` | **运维工具** | 负责自动化部署、版本管理和配置修改的 Python GUI 工具。 |
|
||
|
||
### 6.2 开发流程 (Dev Workflow)
|
||
|
||
1. **启动后端** (可选，如需 API):
|
||
|
||
```bash
|
||
cd Server
|
||
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000
|
||
```
|
||
|
||
2. **启动前端核心**:
|
||
|
||
```bash
|
||
cd Designer
|
||
npm run dev
|
||
# 运行在 http://localhost:5173
|
||
```
|
||
|
||
3. **在 PS 中调试**:
|
||
- 打开 Photoshop。
|
||
- 启动 **AdminPanel** 扩展。
|
||
- **智能连接**: AdminPanel 会自动检测环境。开发模式下，它会自动加载 `http://localhost:5173`，实现**热更新**。
|
||
|
||
### 6.3 生产发布 (Production)
|
||
|
||
1. **构建核心**:
|
||
|
||
```bash
|
||
cd Designer
|
||
npm run build
|
||
# 产物输出到 dist_core
|
||
```
|
||
|
||
2. **部署**:
|
||
- 使用 **AdminTool** 将 `dist_core` 上传到服务器。
|
||
- 生产环境的 AdminPanel 会自动加载服务器地址 (`https://app.aidg168.uk`)。
|
||
|
||
### 6.4 目录清理说明
|
||
|
||
- **冗余移除**: 所有旧的测试脚本、文档草稿、`dist` 目录、`buildLauncher` 脚本等均已移至 `temp_backup`。
|
||
- **配置收敛**: Designer 仅保留 `cep.config.ts`，移除了重复的 dev/prod 配置。
|