20251222

开发准则.md

@@ -146,7 +146,161 @@ src/
   └── main.ts
 ```
 
-### 3.5 UI/UX 设计规范 (Photoshop Theme)
+### 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)**:
 
@@ -305,21 +459,86 @@ Server/
 | **404** | Not Found             | 请求的资源（用户、订单等）不存在。                                             |
 | **500** | Internal Server Error | **服务器内部错误**。代码崩溃或数据库连接失败，需联系后端排查。                 |
 
-### 4.7 配置管理与代码规模限制
+### 4.7 配置管理与可配置化原则 ⭐⭐⭐（核心）
 
-1.  **统一配置管理**:
-    -   ❌ **严禁硬编码**：所有路径地址、数据库连接字符串、API 请求地址、密钥等敏感或可变信息，禁止直接写在代码中。
-    -   ✅ **集中管理**：
-        -   后端：必须使用环境变量 (`.env`) 或 `app/core/config.py` 进行管理。
-        -   前端/客户端：必须使用 `.env` 文件或专门的 `config.ts` 模块。
-        -   工具脚本：必须在脚本头部定义常量或读取外部配置文件。
+#### 1. 统一配置管理
 
-2.  **代码规模限制**:
-    -   ❌ **严禁“巨型文件”**：单个代码文件（`.py`, `.ts`, `.vue` 等）的行数 **不得超过 500 行**。
-    -   ✅ **拆分重构**：
-        -   一旦文件接近 500 行，必须立即进行拆分。
-        -   将逻辑提取为独立的 Service、Utility 函数、Composable Hook 或子组件。
-        -   保持代码的“高内聚、低耦合”。
+-   ❌ **严禁硬编码**：所有路径地址、数据库连接字符串、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 或子组件。
+    -   保持代码的"高内聚、低耦合"。
 
 ---