# 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"，实现快速回滚。