feat:系统框架
This commit is contained in:
commit
c1f1b39e81
25 files changed
+7515
No files matched your search
@@ -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
|
||||
```
|
||||
Reference in new issue
Block a user