117 lines
4.2 KiB
Markdown
117 lines
4.2 KiB
Markdown
# 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"，实现快速回滚。
|