API 接口设计
1. 设计说明
接口设计遵循当前 mlkj-website/backend 的风格:
- 公开接口使用
/api/site、/api/competition、/api/works、/api/courses。
- 后台接口统一使用
/api/admin。
- 返回结构继续使用
ApiResult 风格。
- 后台写接口必须带 JWT,并校验权限码。
- Swagger 设计稿见 swagger/openapi.yaml。
2. 通用响应
成功:
分页:
失败:
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 获取上传凭证
请求:
返回:
6.2 上传完成登记
请求:
7. Swagger
完整 Swagger 设计稿位于: