DP/开发准则.md

# 开发准则与规范 (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 目录结构建议 (参考)

```
Designer/src/
  ├── api/
  │   ├── ai.ts                          # AI 聊天/图片/模型 API 接口
  │   ├── auth.ts                        # 认证接口
  │   ├── user.ts                        # 用户接口
  │   └── jsxApi/inline/
  │       ├── utils.ts                   # JSX 公共工具库 (evalInlineJSX)
  │       ├── pattern-ai.ts             # AI 套图 JSX（置入/填色/标签/剪贴蒙版）
  │       ├── layer.ts                   # 图层操作
  │       ├── document.ts               # 文档操作
  │       └── ...
  ├── view/
  │   ├── AiChat.vue                     # AI 聊天页面（Gemini 风格 UI）
  │   └── ...
  ├── utils/
  │   ├── aiToolExecutor.ts             # AI 工具执行器（tool_call → JSX 映射）
  │   ├── aiCanvasCapture.ts            # 画布截图 / 临时文件管理
  │   ├── logger.ts                      # 日志工具
  │   └── request.ts                     # Axios 封装
  ├── components/      # 通用组件
  ├── router/          # 路由配置
  ├── hooks/           # 组合式函数 (Composables)
  ├── types/           # TypeScript 类型定义
  ├── App.vue
  └── main.ts

Server/app/api/v1/
  ├── ai_chat.py       # AI 聊天路由（对话/会话/图片处理端点）
  ├── ai_llm.py        # AI 模型调用层（Qwen/Gemini/Vision/Image 统一路由）
  ├── ai_tools.py      # AI 工具定义（PS 操作的 function calling schema）
  ├── auth.py          # 认证路由
  └── ...
```

### 3.5.5 AI 模块开发规范

1. **模型调用统一走 `ai_llm.py`**：
   - 所有 LLM/Vision/Image 调用逻辑集中在此文件
   - 自动路由 Qwen（DashScope）和 Gemini（第三方代理）
   - 禁止在路由端点中直接调用 `OpenAI()` 客户端

2. **工具执行器模式**（前端）：
   - AI 返回 `tool_calls` → 前端 `aiToolExecutor.ts` 执行 → 回传结果给后端
   - 工具函数映射表 `toolHandlers` 统一管理
   - 状态（预览图 URL、裁片分析结果等）存在模块级变量中

3. **CEP 中的 IME（中文输入）兼容**：
   - ❌ **禁止使用 Arco Design 的 `a-textarea` 做主输入框**（会拦截 IME composition 事件）
   - ✅ **使用原生 `<textarea>`** 确保输入法正常工作
   - ✅ **必须注册全量键盘事件**：`registerKeyEventsInterest` 要注册所有 keyCode × 16 种 modifier 组合
   - ✅ **Enter 发送时检查 IME 状态**：`e.isComposing && e.keyCode !== 229`

4. **图案分层处理**（4 种类型）：
   - `solid` — 纯色 PS 填充
   - `fill_pattern` — AI 花型铺满
   - `theme_pattern` — AI 主题图案（白底）+ PS 纯色底 + 正片叠底
   - `mixed_pattern` — AI 主题图案（白底）+ AI 花型底 + 正片叠底

### 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/v1/
  │   │   ├── ai_chat.py      # AI 聊天路由（对话/会话/图片处理）
  │   │   ├── ai_llm.py       # AI 模型调用层（Qwen/Gemini 统一路由）
  │   │   ├── ai_tools.py     # AI 工具定义（function calling schema）
  │   │   ├── auth.py         # 认证接口
  │   │   ├── algorithm.py    # 算法接口（PLT 处理等）
  │   │   └── ...
  │   ├── core/                # 核心配置 (Config, Security)
  │   ├── models/              # 数据库模型 (SQLAlchemy)
  │   └── main.py              # 程序入口
  ├── debug_images/            # AI 调试图片（自动生成，不提交）
  ├── pyproject.toml           # uv 依赖管理
  └── .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 的数据接口服务，含 AI 模型调用层（Qwen/Gemini 双路由）。                         |
| **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 配置。