DP/tempdocs/后端API接口文档.md

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:

  {
    "username": "user1",
    "password": "password123",
    "device_id": "unique-device-id"
  }
  

• Response:

  {
    "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:

  {
    "username": "user1"
  }
  

• Response:

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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: 过期时间