# 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](swagger/openapi.yaml)。 ## 2. 通用响应 成功: ```json { "code": 0, "message": "ok", "data": {} } ``` 分页: ```json { "code": 0, "message": "ok", "data": { "list": [], "page": 1, "pageSize": 20, "total": 100 } } ``` 失败: ```json { "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 获取上传凭证 请求: ```json { "fileName": "cover.png", "mimeType": "image/png", "size": 204800, "scene": "work", "usage": "cover" } ``` 返回: ```json { "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 上传完成登记 请求: ```json { "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 设计稿位于: ```text docs/swagger/openapi.yaml ```