Files
mlkj-website-admin/docs/07-api-design.md
T
2026-06-29 19:27:33 +08:00

7.2 KiB

API 接口设计

1. 设计说明

接口设计遵循当前 mlkj-website/backend 的风格:

  1. 公开接口使用 /api/site、/api/competition、/api/works、/api/courses。
  2. 后台接口统一使用 /api/admin。
  3. 返回结构继续使用 ApiResult 风格。
  4. 后台写接口必须带 JWT,并校验权限码。
  5. Swagger 设计稿见 swagger/openapi.yaml。

2. 通用响应

成功:

{
  "code": 0,
  "message": "ok",
  "data": {}
}

分页:

{
  "code": 0,
  "message": "ok",
  "data": {
    "list": [],
    "page": 1,
    "pageSize": 20,
    "total": 100
  }
}

失败:

{
  "code": 40001,
  "message": "无权限",
  "data": null
}

3. 权限分组

模块 权限码
登录 无
控制台 dashboard:read
官网内容 site:read、site:write、site:publish
赛道内容 competition:read、competition:write、competition:publish
素材库 file:read、file:upload、file:archive
课程 course:read、course:write、course:publish
作品 work:read、work:write、work:publish
评选 evaluation:manage、evaluation:score
线索 inquiry:read、inquiry:write
系统 system:manage

4. 后台接口分组

4.1 鉴权

方法 路径 说明
POST /api/admin/auth/login 登录
POST /api/admin/auth/refresh 刷新 token
POST /api/admin/auth/logout 退出
GET /api/admin/me 当前用户信息

4.2 内容管理

方法 路径 说明
GET /api/admin/site/config 获取站点配置
PATCH /api/admin/site/config 更新站点配置草稿
GET /api/admin/content/pages/:pageKey/sections 获取页面区块
POST /api/admin/content/pages/:pageKey/sections 新建区块
GET /api/admin/content/sections/:id 区块详情
PATCH /api/admin/content/sections/:id 更新区块草稿
POST /api/admin/content/sections/:id/publish 发布区块
DELETE /api/admin/content/sections/:id 归档区块

4.3 赛道管理

方法 路径 说明
GET /api/admin/competitions 赛道列表
POST /api/admin/competitions 新建赛道
GET /api/admin/competitions/:id 赛道详情
PATCH /api/admin/competitions/:id 更新赛道
GET /api/admin/competitions/:id/schedules 赛程列表
POST /api/admin/competitions/:id/schedules 新建赛程
PATCH /api/admin/competition-schedules/:id 更新赛程
DELETE /api/admin/competition-schedules/:id 删除赛程
GET /api/admin/competitions/:id/resources 资源列表
POST /api/admin/competitions/:id/resources 新建资源
PATCH /api/admin/competition-resources/:id 更新资源
DELETE /api/admin/competition-resources/:id 删除资源

4.4 素材上传

方法 路径 说明
POST /api/admin/uploads/policy 获取 OSS 上传凭证
POST /api/admin/uploads/complete 上传完成登记
GET /api/admin/files 文件列表
GET /api/admin/files/:id 文件详情
PATCH /api/admin/files/:id 更新文件元信息
POST /api/admin/files/:id/archive 归档文件

4.5 课程视频

方法 路径 说明
GET /api/admin/courses 课程列表
POST /api/admin/courses 新建课程
GET /api/admin/courses/:id 课程详情
PATCH /api/admin/courses/:id 更新课程
PATCH /api/admin/courses/:id/status 更新状态
DELETE /api/admin/courses/:id 删除课程

4.6 作品

方法 路径 说明
GET /api/admin/works 作品列表
POST /api/admin/works 新建作品
GET /api/admin/works/:id 作品详情
PATCH /api/admin/works/:id 更新作品
PATCH /api/admin/works/:id/status 更新发布状态
POST /api/admin/works/:id/images 添加作品图片
DELETE /api/admin/work-images/:id 删除作品图片
POST /api/admin/works/:id/files 添加作品附件
DELETE /api/admin/work-files/:id 删除作品附件
DELETE /api/admin/works/:id 删除作品

4.7 评选

方法 路径 说明
GET /api/admin/evaluation/rounds 评审轮次列表
POST /api/admin/evaluation/rounds 创建评审轮次
GET /api/admin/evaluation/rounds/:id 轮次详情
PATCH /api/admin/evaluation/rounds/:id 更新轮次
POST /api/admin/evaluation/rounds/:id/lock 锁定轮次
GET /api/admin/evaluation/rounds/:id/criteria 指标列表
POST /api/admin/evaluation/rounds/:id/criteria 创建指标
GET /api/admin/evaluation/rounds/:id/assignments 任务列表
POST /api/admin/evaluation/rounds/:id/assignments 分配作品
GET /api/admin/evaluation/my-assignments 评委查看自己的任务
POST /api/admin/evaluation/assignments/:id/scores 提交评分
GET /api/admin/evaluation/rounds/:id/results 查看结果汇总
POST /api/admin/evaluation/rounds/:id/results/calculate 重新计算排名
POST /api/admin/evaluation/rounds/:id/results/publish 发布结果

4.8 咨询线索

方法 路径 说明
GET /api/admin/inquiries 线索列表
GET /api/admin/inquiries/:id 线索详情
PATCH /api/admin/inquiries/:id/status 更新状态
PATCH /api/admin/inquiries/:id/remark 更新备注

5. 公开接口扩展

方法 路径 说明
GET /api/site/config 官网基础配置
GET /api/site/home 官网首页区块
GET /api/competition 赛道页聚合数据
GET /api/competition/schedule 赛程
GET /api/competition/resources 资源包
GET /api/courses 课程列表
GET /api/courses/:id 课程详情
GET /api/works 作品列表
GET /api/works/:id 作品详情
POST /api/works/:id/vote 公众投票

6. 上传接口约定

6.1 获取上传凭证

请求:

{
  "fileName": "cover.png",
  "mimeType": "image/png",
  "size": 204800,
  "scene": "work",
  "usage": "cover"
}

返回:

{
  "uploadUrl": "https://oss.example.com",
  "method": "POST",
  "fileKey": "mlkj-website/works/covers/2026/06/xxx.png",
  "formData": {
    "policy": "...",
    "signature": "..."
  },
  "expiresAt": "2026-06-29T12:00:00.000Z"
}

6.2 上传完成登记

请求:

{
  "fileKey": "mlkj-website/works/covers/2026/06/xxx.png",
  "originalName": "cover.png",
  "url": "https://cdn.example.com/mlkj-website/works/covers/2026/06/xxx.png",
  "mimeType": "image/png",
  "extension": "png",
  "size": 204800,
  "width": 1200,
  "height": 800,
  "scene": "work",
  "fileCategory": "image"
}

7. Swagger

完整 Swagger 设计稿位于:

docs/swagger/openapi.yaml