feat:系统框架

This commit is contained in:
wlx committed 2026-06-29 19:27:33 +08:00
commit c1f1b39e81
25 files changed
+7515

No files matched your search

+242
View File
@@ -0,0 +1,242 @@
# 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
```