Initial commit - DesignerCEP Project with Caddy deployment

tempdocs/后端开发需求文档.md

@@ -0,0 +1,116 @@
+# DesignerCEP 后端开发需求文档
+
+请根据以下需求使用 Python (Flask/FastAPI) + MySQL 开发后端服务。
+
+## 1. 核心需求概览
+
+我们需要实现一个 **“灰度发布系统”**。
+
+- **用户与权限**: 用户属于不同的“组” (Group)，如 "Stable Group", "Dev Group"。
+- **版本控制**: 不同的组对应不同的插件版本 (ZIP 包)。
+- **客户端交互**: 客户端插件 (Shell) 登录时，根据用户所在的组，返回对应的 ZIP 包下载地址。
+
+---
+
+## 2. 数据库设计 (Database Schema)
+
+请创建以下两张核心表（基于 MySQL）：
+
+### 2.1 用户组表 (`plugin_group`)
+
+用于管理不同的发布通道。
+
+| 字段名                 | 类型     | 描述                     | 示例值              |
+| :--------------------- | :------- | :----------------------- | :------------------ |
+| `id`                   | INT (PK) | 组 ID                    | 1                   |
+| `name`                 | VARCHAR  | 组名称                   | "正式版用户组"      |
+| `current_version_file` | VARCHAR  | **当前使用的版本文件名** | "plugin_v1.0.2.zip" |
+| `comment`              | TEXT     | 备注                     | "稳定版本通道"      |
+
+### 2.2 用户表 (`user`)
+
+_需关联到组表_
+
+| 字段名        | 类型     | 描述                    | 示例值                     |
+| :------------ | :------- | :---------------------- | :------------------------- |
+| `id`          | INT (PK) | 用户 ID                 | 1001                       |
+| `username`    | VARCHAR  | 用户名                  | "designer01"               |
+| `password`    | VARCHAR  | 密码                    | "123456"                   |
+| `group_id`    | INT (FK) | **所属组 ID**           | 1 (关联 `plugin_group.id`) |
+| `permissions` | TEXT     | **权限列表** (逗号分隔) | "batch_process,vip_export" |
+| `expire_date` | DATETIME | **过期时间**            | "2025-12-31 23:59:59"      |
+
+---
+
+## 3. API 接口规范 (API Specification)
+
+所有接口前缀建议为 `/api/v1`。
+
+### 3.1 检查更新 (Client 接口)
+
+客户端插件启动时调用，查询自己应该下载哪个版本。
+
+- **URL**: `POST /api/v1/client/check_update`
+- **请求参数**: `{ "username": "..." }`
+- **逻辑**:
+  1.  检查用户是否过期 (`expire_date` < user.expire_date). 如果过期，返回 403 或特定状态码。
+  2.  根据 `username` 查询用户所在的 `group_id`。
+  3.  根据 `group_id` 查询 `plugin_group` 表，获取 `current_version_file`。
+  4.  拼接下载链接。
+- **返回示例**:
+  ```json
+  {
+    "code": 200,
+    "data": {
+      "version": "v1.0.2",
+      "download_url": "http://your-server.com/download/plugin_v1.0.2.zip",
+      "force_update": false,
+      "is_expired": false // 明确告知是否过期
+    },
+    "message": "success"
+  }
+  ```
+
+### 3.2 登录验证 (Client 接口)
+
+- **URL**: `POST /api/v1/client/login`
+- **请求参数**: `{ "username": "...", "password": "..." }`
+- **逻辑**: 校验密码及过期状态。
+- **返回**:
+  ```json
+  {
+    "code": 200,
+    "data": {
+      "token": "...",
+      "username": "...",
+      "expire_date": "2025-12-31",
+      "permissions": ["batch_process", "vip_export"] // 返回权限数组
+    }
+  }
+  ```
+
+### 3.3 上传新版本 (Admin/CI 接口)
+
+用于发布脚本上传新的 ZIP 包。
+
+- **请求参数**: `file` (multipart/form-data)
+- **逻辑**:
+  1.  校验管理员权限（可硬编码 Token 或密码）。
+  2.  将上传的文件保存到服务器的 `archives/` 目录。
+  3.  文件名通常包含版本号或时间戳，如 `plugin_v1.0.3_20251216.zip`。
+  4.  (可选) 自动更新相关数据库记录。
+
+### 3.4 文件下载 (Download)
+
+- **URL**: `GET /download/<filename>`
+- **功能**: 提供静态文件下载服务（指向 `archives/` 目录）。
+
+---
+
+## 4. 后台管理功能 (Admin Tool 支持)
+
+后端需要提供基础的数据增删改查接口，以支持 PyQt 或 Web 管理后台：
+
+1.  **用户管理**: 新增用户、修改用户所属组 (`group_id`)。
+2.  **组管理**: 修改组指向的版本 (`current_version_file`)。
+    - _场景_: 管理员发现 "v1.1-beta" 有 Bug，可以将 "Dev Group" 的 `current_version_file` 改回 "v1.0-stable"，实现快速回滚。