DP/开发准则.md

开发准则与规范 (DesignerCEP / Photoshop Plugin)

1. 项目概述

本项目是一个基于 Vue 3 + Vite + TypeScript 的 Adobe Photoshop 扩展插件 (CEP) 项目。

2. 技术栈

• 核心框架: Vue 3 (Composition API + <script setup>)
• 构建工具: Vite
• 语言: TypeScript
• UI 组件库: Arco Design Vue (@arco-design/web-vue)
• 路由: Vue Router 4
• CEP 环境: Adobe CEP (宿主环境: Adobe Photoshop)
• HTTP: Axios / Umi-request

---

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. 使用方法:

   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. 日志开关控制:

   // 开启日志（开发环境）
   logger.enable();
   
   // 关闭日志（生产环境）
   logger.disable();
   
   // 切换日志状态
   logger.toggle();
   
   // 查询当前状态
   console.log(logger.enabled);  // true/false
   

4. 浏览器控制台访问:

   • 日志工具自动挂载到 window.logger，可在浏览器控制台直接操作：

   // 在 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 传参更灵活。

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 配置（标准参数）

<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 设计准则

/* 容器最大宽度约束 */
.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. 间距系统（紧凑设计）

/* 不要用网页的大间距！ */
--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. 字体大小（精简尺寸）

--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. 组件尺寸

/* 图标 */
--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. 响应式网格（自适应列数）

/* 根据面板宽度自动调整列数 */
.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 事件，实现实时自动切换。

   • 实现参考代码:

     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 错误

❌ 错误示例（硬编码）：

# 错误：写死在代码里
def calculate_bonus(consecutive_days):
    if consecutive_days == 7:
        return 20  # 硬编码
    elif consecutive_days == 15:
        return 50  # 硬编码
    return 0

✅ 正确示例（可配置）：

# 正确：从配置表读取
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。