161 lines
3.4 KiB
Markdown
161 lines
3.4 KiB
Markdown
# DesignerCEP 后端 API 接口文档
|
||
|
||
本文档描述了 DesignerCEP 后端服务的 API 接口规范，包括客户端插件接口和后台管理接口。
|
||
|
||
## 1. 基础信息
|
||
|
||
- **Base URL**: `http://localhost:8000/api/v1`
|
||
- **文件下载 Base URL**: `http://localhost:8000/download/`
|
||
- **鉴权方式**:
|
||
- **Client**: Bearer Token (JWT)
|
||
- **Admin**: 简单 Token (Header `x-admin-token` 或 Form `token`) - *开发阶段*
|
||
|
||
## 2. 客户端接口 (Client)
|
||
|
||
用于 Photoshop 插件端的交互。
|
||
|
||
### 2.1 登录 (Login)
|
||
|
||
客户端登录，获取 Token、权限及过期时间。
|
||
|
||
- **URL**: `/client/login`
|
||
- **Method**: `POST`
|
||
- **Request Body**:
|
||
```json
|
||
{
|
||
"username": "user1",
|
||
"password": "password123",
|
||
"device_id": "unique-device-id"
|
||
}
|
||
```
|
||
- **Response**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"token": "eyJhbGciOiJIUzI1...",
|
||
"username": "user1",
|
||
"expire_date": "2025-12-31",
|
||
"permissions": ["batch_process", "export"]
|
||
},
|
||
"message": "success"
|
||
}
|
||
```
|
||
|
||
### 2.2 检查更新 (Check Update)
|
||
|
||
根据用户所在组检查是否有新版本。
|
||
|
||
- **URL**: `/client/check_update`
|
||
- **Method**: `POST`
|
||
- **Request Body**:
|
||
```json
|
||
{
|
||
"username": "user1"
|
||
}
|
||
```
|
||
- **Response**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"data": {
|
||
"version": "v1.0",
|
||
"download_url": "/download/plugin_v1.0.zip",
|
||
"force_update": false,
|
||
"is_expired": false
|
||
},
|
||
"message": "success"
|
||
}
|
||
```
|
||
- `is_expired`: 若为 `true`，表示用户授权已过期，客户端应限制功能。
|
||
- `download_url`: 拼接 Base URL 使用。
|
||
|
||
---
|
||
|
||
## 3. 管理端接口 (Admin)
|
||
|
||
用于发布系统管理（CI/CD 或管理后台）。需在 Header 中携带 `x-admin-token: admin-secret-token` (默认开发Token)。
|
||
|
||
### 3.1 上传版本文件 (Upload Version)
|
||
|
||
上传插件 ZIP 包到服务器。
|
||
|
||
- **URL**: `/admin/upload_version`
|
||
- **Method**: `POST`
|
||
- **Content-Type**: `multipart/form-data`
|
||
- **Form Data**:
|
||
- `file`: (Binary Zip File)
|
||
- `token`: "admin-secret-token" (作为 Form 字段兼容脚本)
|
||
- **Response**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "File 'plugin_v1.0.zip' uploaded successfully",
|
||
"filename": "plugin_v1.0.zip"
|
||
}
|
||
```
|
||
|
||
### 3.2 创建用户组 (Create Group)
|
||
|
||
- **URL**: `/admin/groups`
|
||
- **Method**: `POST`
|
||
- **Request Body**:
|
||
```json
|
||
{
|
||
"name": "Dev Group",
|
||
"current_version_file": "plugin_v1.0_beta.zip",
|
||
"comment": "开发测试组"
|
||
}
|
||
```
|
||
- **Response**: 返回创建的组对象。
|
||
|
||
### 3.3 更新用户组 (Update Group)
|
||
|
||
用于切换组的版本。
|
||
|
||
- **URL**: `/admin/groups/{group_id}`
|
||
- **Method**: `PUT`
|
||
- **Request Body**:
|
||
```json
|
||
{
|
||
"current_version_file": "plugin_v1.1_stable.zip"
|
||
}
|
||
```
|
||
|
||
### 3.4 获取所有组 (List Groups)
|
||
|
||
- **URL**: `/admin/groups`
|
||
- **Method**: `GET`
|
||
- **Response**: 组列表数组。
|
||
|
||
### 3.5 修改用户所属组 (Update User Group)
|
||
|
||
- **URL**: `/admin/users/{user_id}/group`
|
||
- **Method**: `PUT`
|
||
- **Query Params**:
|
||
- `group_id`: 目标组 ID
|
||
- **Response**:
|
||
```json
|
||
{
|
||
"code": 200,
|
||
"message": "User group updated"
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 4. 数据库模型说明
|
||
|
||
### PluginGroup (用户组)
|
||
- `id`: ID
|
||
- `name`: 组名 (Unique)
|
||
- `current_version_file`: 当前关联的 ZIP 文件名
|
||
- `comment`: 备注
|
||
|
||
### User (用户)
|
||
- `id`: ID
|
||
- `username`: 用户名
|
||
- `group_id`: 所属组 ID (Foreign Key)
|
||
- `permissions`: 权限列表 (逗号分隔字符串)
|
||
- `expire_date`: 过期时间
|