En
b805f456a6
- 添加 Lombok 配置支持 - 完善枚举类和常量定义 - 新增工具类（TraceId、限流、OSS 等） - 添加切面（日志、限流、TraceId） - 更新数据库索引规范（应用层防重） - 登录页面样式优化 - 前后端项目文档补充
415 lines
20 KiB
Markdown
415 lines
20 KiB
Markdown
# 前后端接口差异对比报告
|
||
|
||
> 分析时间：2026-03-30
|
||
> 前端目录：java-frontend/src/api/
|
||
> 后端目录：java-backend/src/main/java/com/lesingle/creation/controller/
|
||
|
||
---
|
||
|
||
## 核心问题总结
|
||
|
||
### 1. 路径前缀不一致（最严重）
|
||
|
||
| 模块 | 前端路径前缀 | 后端路径前缀 | 差异 |
|
||
|:------|:------------|:------------|:-----|
|
||
| 竞赛管理 | `/contests` | `/api/contests` | 缺少 `/api` |
|
||
| 作业管理 | `/homework/homeworks` | `/api/homeworks` | 路径结构不同 |
|
||
| AI 3D | `/ai-3d` | `/api/ai-3d` | 缺少 `/api` |
|
||
|
||
**影响**：前端所有 API 请求都无法匹配到后端接口
|
||
|
||
### 2. HTTP 方法不一致
|
||
|
||
| 模块 | 前端方法 | 后端方法 | 接口 |
|
||
|:------|:--------|:--------|:-----|
|
||
| 竞赛更新 | PATCH | PUT | `/contests/{id}` |
|
||
| 团队更新 | PATCH | PUT | `/contests/teams/{id}` |
|
||
| 评审规则更新 | PATCH | PUT | `/contests/review-rules/{id}` |
|
||
| 作业更新 | PATCH | PUT | `/homework/homeworks/{id}` |
|
||
| AI 3D 重试 | POST | PUT | `/ai-3d/tasks/{id}/retry` |
|
||
|
||
### 3. 接口路径不一致
|
||
|
||
| 模块 | 前端路径 | 后端路径 | 说明 |
|
||
|:------|:--------|:--------|:-----|
|
||
| 作品列表 | `/contests/works` | `/api/contests/works/page` | 后端多了 `/page` |
|
||
| 作品提交 | `/contests/works/submit` | `/api/contests/works` | 路径不同 |
|
||
| 作业列表 | `/homework/homeworks` | `/api/homeworks/page` | 后端多了 `/page` |
|
||
| 作业提交 | `/homework/submissions` | `/api/homeworks/submit` | 路径不同 |
|
||
| 作业批改 | `/homework/scores` | `/api/homeworks/review` | 路径不同 |
|
||
| AI 3D 创建 | `/ai-3d/generate` | `/api/ai-3d` | 路径不同 |
|
||
| AI 3D 列表 | `/ai-3d/tasks` | `/api/ai-3d/page` | 后端多了 `/page` |
|
||
|
||
---
|
||
|
||
## 模块详细对比
|
||
|
||
### 一、竞赛管理模块 (contests.ts)
|
||
|
||
#### 1.1 活动管理 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/contests/stats` | GET `/api/contests/stats` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests` | GET `/api/contests` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/my-contests` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/contests/{id}` | GET `/api/contests/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests` | POST `/api/contests` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/{id}` | PUT `/api/contests/{id}` | ⚠️ | 方法不同 + 路径前缀 |
|
||
| PATCH `/contests/{id}/publish` | PATCH `/api/contests/{id}/publish` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/{id}/finish` | PATCH `/api/contests/{id}/finish` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/{id}/reopen` | PATCH `/api/contests/{id}/reopen` | ⚠️ | 路径前缀不一致 |
|
||
| DELETE `/contests/{id}` | DELETE `/api/contests/{id}` | ⚠️ | 路径前缀不一致 |
|
||
|
||
#### 1.2 报名管理 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/contests/registrations/stats` | GET `/api/contests/registrations/stats` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/registrations` | GET `/api/contests/registrations` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/registrations/my/{contestId}` | GET `/api/contests/registrations/my/{contestId}` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/registrations/{id}` | GET `/api/contests/registrations/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/registrations` | POST `/api/contests/registrations` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/registrations/{id}/teachers` | POST `/api/contests/registrations/{id}/teachers` | ⚠️ | 路径前缀不一致 |
|
||
| DELETE `/contests/registrations/{id}/teachers/{teacherUserId}` | ❌ | ❌ | **后端缺失** |
|
||
| PATCH `/contests/registrations/{id}/review` | PATCH `/api/contests/registrations/{id}/review` | ⚠️ | 路径前缀不一致 |
|
||
| DELETE `/contests/registrations/{id}` | DELETE `/api/contests/registrations/{id}` | ⚠️ | 路径前缀不一致 |
|
||
|
||
#### 1.3 团队管理 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/contests/teams/contest/{contestId}` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/contests/teams/{id}` | GET `/api/contests/teams/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/teams` | POST `/api/contests/teams` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/teams/{id}` | PUT `/api/contests/teams/{id}` | ⚠️ | 方法不同 + 路径前缀 |
|
||
| POST `/contests/teams/{teamId}/members` | POST `/api/contests/teams/{id}/members` | ⚠️ | 参数名不同 + 路径前缀 |
|
||
| DELETE `/contests/teams/{teamId}/members/{userId}` | DELETE `/api/contests/teams/{id}/members/{userId}` | ⚠️ | 参数名不同 + 路径前缀 |
|
||
| DELETE `/contests/teams/{id}` | DELETE `/api/contests/teams/{id}` | ⚠️ | 路径前缀不一致 |
|
||
|
||
#### 1.4 作品管理 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/contests/works/stats` | GET `/api/contests/works/stats` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/works` | GET `/api/contests/works/page` | ⚠️ | **路径不同** + 前缀 |
|
||
| GET `/contests/works/guided` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/contests/works/{id}` | GET `/api/contests/works/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/works/submit` | POST `/api/contests/works` | ⚠️ | **路径不同** + 前缀 |
|
||
| GET `/contests/works/registration/{id}/versions` | ❌ | ❌ | **后端缺失** |
|
||
| DELETE `/contests/works/{id}` | DELETE `/api/contests/works/{id}` | ⚠️ | 路径前缀不一致 |
|
||
|
||
#### 1.5 评审管理 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| POST `/contests/reviews/assign` | POST `/api/contests/reviews/assign` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/reviews/batch-assign` | POST `/api/contests/reviews/batch-assign` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/reviews/auto-assign` | ❌ | ❌ | **后端缺失** |
|
||
| POST `/contests/reviews/score` | POST `/api/contests/reviews/score` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/reviews/score/{scoreId}` | PUT `/api/contests/reviews/score/{scoreId}` | ⚠️ | 方法不同 + 路径前缀 |
|
||
| GET `/contests/reviews/assigned` | GET `/api/contests/reviews/my-assignments` | ⚠️ | **路径不同** + 前缀 |
|
||
| GET `/contests/reviews/progress/{contestId}` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/contests/reviews/work-status/{contestId}` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/contests/reviews/work/{workId}/scores` | GET `/api/contests/reviews/works/{workId}/scores` | ⚠️ | 路径不同 + 前缀 |
|
||
| GET `/contests/reviews/work/{workId}/final-score` | ❌ | ❌ | **后端缺失** |
|
||
| POST `/contests/reviews/replace-judge` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/contests/reviews/judge/contests` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/contests/reviews/judge/contests/{contestId}/works` | ❌ | ❌ | **后端缺失** |
|
||
|
||
#### 1.6 公告管理 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/contests/notices/contest/{contestId}` | GET `/api/contests/notices/contest/{contestId}` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/notices` | GET `/api/contests/notices` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/notices/{id}` | GET `/api/contests/notices/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/notices` | POST `/api/contests/notices` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/notices/{id}` | PUT `/api/contests/notices/{id}` | ⚠️ | 方法不同 + 路径前缀 |
|
||
| DELETE `/contests/notices/{id}` | DELETE `/api/contests/notices/{id}` | ⚠️ | 路径前缀不一致 |
|
||
|
||
#### 1.7 评委管理 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/contests/judges/contest/{contestId}` | GET `/api/contests/judges/contest/{contestId}` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/judges/{id}` | GET `/api/contests/judges/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/judges` | POST `/api/contests/judges` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/judges/{id}` | PUT `/api/contests/judges/{id}` | ⚠️ | 方法不同 + 路径前缀 |
|
||
| DELETE `/contests/judges/{id}` | DELETE `/api/contests/judges/{id}` | ⚠️ | 路径前缀不一致 |
|
||
|
||
#### 1.8 评审规则 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/contests/review-rules` | GET `/api/contests/review-rules` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/review-rules/select` | GET `/api/contests/review-rules/select` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/review-rules/{id}` | GET `/api/contests/review-rules/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/review-rules` | POST `/api/contests/review-rules` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/review-rules/{id}` | PUT `/api/contests/review-rules/{id}` | ⚠️ | 方法不同 + 路径前缀 |
|
||
| DELETE `/contests/review-rules/{id}` | DELETE `/api/contests/review-rules/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/review-rules/dimensions` | POST `/api/contests/review-rules/dimensions` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/review-rules/dimensions/{id}` | PUT `/api/contests/review-rules/dimensions/{id}` | ⚠️ | 方法不同 + 路径前缀 |
|
||
| DELETE `/contests/review-rules/dimensions/{id}` | DELETE `/api/contests/review-rules/dimensions/{id}` | ⚠️ | 路径前缀不一致 |
|
||
|
||
#### 1.9 成果管理 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| POST `/contests/results/{contestId}/calculate-scores` | POST `/api/contests/results/{contestId}/calculate-scores` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/results/{contestId}/calculate-rankings` | POST `/api/contests/results/{contestId}/calculate-rankings` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/contests/results/work/{workId}/award` | PATCH `/api/contests/results/work/{workId}/award` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/results/{contestId}/batch-set-awards` | POST `/api/contests/results/{contestId}/batch-set-awards` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/results/{contestId}/auto-set-awards` | POST `/api/contests/results/{contestId}/auto-set-awards` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/results/{contestId}/publish` | POST `/api/contests/results/{contestId}/publish` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/contests/results/{contestId}/unpublish` | POST `/api/contests/results/{contestId}/unpublish` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/results/{contestId}` | GET `/api/contests/results/{contestId}` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/contests/results/{contestId}/summary` | GET `/api/contests/results/{contestId}/summary` | ⚠️ | 路径前缀不一致 |
|
||
|
||
---
|
||
|
||
### 二、作业管理模块 (homework.ts)
|
||
|
||
#### 2.1 作业管理 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/homework/homeworks` | GET `/api/homeworks/page` | ❌ | **路径结构完全不同** |
|
||
| GET `/homework/homeworks/my` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/homework/homeworks/{id}` | GET `/api/homeworks/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/homework/homeworks` | POST `/api/homeworks` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/homework/homeworks/{id}` | PUT `/api/homeworks/{id}` | ⚠️ | 方法不同 + 路径前缀 |
|
||
| POST `/homework/homeworks/{id}/publish` | GET `/api/homeworks/{id}/publish` | ❌ | **方法不同** + 路径前缀 |
|
||
| POST `/homework/homeworks/{id}/unpublish` | ❌ | ❌ | **后端缺失** |
|
||
| DELETE `/homework/homeworks/{id}` | DELETE `/api/homeworks/{id}` | ⚠️ | 路径前缀不一致 |
|
||
|
||
#### 2.2 提交记录 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/homework/submissions` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/homework/submissions/{id}` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/homework/submissions/class-tree` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/homework/submissions/my/{homeworkId}` | ❌ | ❌ | **后端缺失** |
|
||
| POST `/homework/submissions` | POST `/api/homeworks/submit` | ❌ | **路径不同** + 前缀 |
|
||
|
||
#### 2.3 评审规则 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| GET `/homework/review-rules` | GET `/api/homeworks/review-rules` | ⚠️ | 路径前缀不一致 |
|
||
| GET `/homework/review-rules/select` | ❌ | ❌ | **后端缺失** |
|
||
| GET `/homework/review-rules/{id}` | GET `/api/homeworks/review-rules/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/homework/review-rules` | POST `/api/homeworks/review-rules` | ⚠️ | 路径前缀不一致 |
|
||
| PATCH `/homework/review-rules/{id}` | ❌ | ❌ | **后端缺失** |
|
||
| DELETE `/homework/review-rules/{id}` | ❌ | ❌ | **后端缺失** |
|
||
|
||
#### 2.4 评分 API
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| POST `/homework/scores` | POST `/api/homeworks/review` | ❌ | **路径不同** + 前缀 |
|
||
| POST `/homework/scores/{submissionId}/violation` | ❌ | ❌ | **后端缺失** |
|
||
| POST `/homework/scores/{submissionId}/reset` | ❌ | ❌ | **后端缺失** |
|
||
|
||
---
|
||
|
||
### 三、AI 3D 模块 (ai-3d.ts)
|
||
|
||
| 前端接口 | 后端接口 | 状态 | 差异说明 |
|
||
|:---------|:---------|:-----|:---------|
|
||
| POST `/ai-3d/generate` | POST `/api/ai-3d` | ❌ | **路径不同** + 前缀 |
|
||
| GET `/ai-3d/tasks` | GET `/api/ai-3d/page` | ❌ | **路径不同** + 前缀 |
|
||
| GET `/ai-3d/tasks/{id}` | GET `/api/ai-3d/{id}` | ⚠️ | 路径前缀不一致 |
|
||
| POST `/ai-3d/tasks/{id}/retry` | PUT `/api/ai-3d/{id}/retry` | ❌ | **方法不同** + 路径前缀 |
|
||
| DELETE `/ai-3d/tasks/{id}` | ❌ | ❌ | **后端缺失** |
|
||
|
||
---
|
||
|
||
## 缺失接口汇总
|
||
|
||
### 后端需要补充的接口（按优先级）
|
||
|
||
#### P0 - 核心功能缺失
|
||
|
||
1. **竞赛管理**
|
||
- `GET /api/contests/my-contests` - 我参与的活动列表
|
||
|
||
2. **作品管理**
|
||
- `GET /api/contests/works/guided` - 教师指导的作品列表
|
||
- `GET /api/contests/works/registration/{id}/versions` - 作品版本列表
|
||
|
||
3. **评审管理**
|
||
- `POST /api/contests/reviews/auto-assign` - 自动分配评委
|
||
- `GET /api/contests/reviews/progress/{contestId}` - 评审进度统计
|
||
- `GET /api/contests/reviews/work-status/{contestId}` - 作品状态统计
|
||
- `GET /api/contests/reviews/work/{workId}/final-score` - 计算最终得分
|
||
- `POST /api/contests/reviews/replace-judge` - 替换评委
|
||
- `GET /api/contests/reviews/judge/contests` - 评委参与的活动列表
|
||
- `GET /api/contests/reviews/judge/contests/{contestId}/works` - 评委的作品列表
|
||
|
||
4. **作业管理**
|
||
- `GET /api/homeworks/my` - 我的作业列表（学生端）
|
||
- `POST /api/homeworks/homeworks/{id}/unpublish` - 取消发布作业
|
||
- `GET /api/homeworks/submissions` - 提交记录列表
|
||
- `GET /api/homeworks/submissions/{id}` - 提交记录详情
|
||
- `GET /api/homeworks/submissions/class-tree` - 班级树结构
|
||
- `GET /api/homeworks/submissions/my/{homeworkId}` - 我的提交记录
|
||
- `POST /api/homeworks/scores` - 提交评分
|
||
- `POST /api/homeworks/scores/{submissionId}/violation` - 标记违规
|
||
- `POST /api/homeworks/scores/{submissionId}/reset` - 重置评分
|
||
|
||
5. **评审规则**
|
||
- `GET /api/homeworks/review-rules/select` - 获取可选的评审规则
|
||
- `PUT /api/homeworks/review-rules/{id}` - 更新评审规则
|
||
- `DELETE /api/homeworks/review-rules/{id}` - 删除评审规则
|
||
|
||
6. **AI 3D**
|
||
- `DELETE /api/ai-3d/tasks/{id}` - 删除任务
|
||
|
||
#### P1 - 重要功能缺失
|
||
|
||
1. **报名管理**
|
||
- `DELETE /api/contests/registrations/{id}/teachers/{teacherUserId}` - 移除指导老师
|
||
|
||
2. **团队管理**
|
||
- `GET /api/contests/teams/contest/{contestId}` - 按活动查询团队列表
|
||
|
||
#### P2 - 辅助功能缺失
|
||
|
||
1. **其他缺失模块**（完全未实现）
|
||
- 认证模块 (Auth)
|
||
- 文件上传模块 (Upload)
|
||
- 系统日志模块 (Logs)
|
||
- 公共接口模块 (Public)
|
||
- 评委管理模块 (Judges Management)
|
||
- 学校组织模块 (School/Grade/Class/Department/Teacher/Student)
|
||
|
||
---
|
||
|
||
## 修复方案建议
|
||
|
||
### 方案一：修改前端 API 路径（推荐）
|
||
|
||
**优点**：
|
||
- 后端遵循标准 RESTful 规范（`/api/` 前缀）
|
||
- 后端使用 PUT 进行全量更新，符合 REST 惯例
|
||
- 前端只需修改 API 客户端文件
|
||
|
||
**缺点**：
|
||
- 需要修改前端所有 API 文件
|
||
|
||
**修改内容**：
|
||
```typescript
|
||
// contests.ts - 所有路径添加 /api 前缀
|
||
- request.get("/contests/stats")
|
||
+ request.get("/api/contests/stats")
|
||
|
||
// homework.ts - 调整路径结构
|
||
- request.get("/homework/homeworks")
|
||
+ request.get("/api/homeworks/page")
|
||
|
||
- request.post("/homework/submissions")
|
||
+ request.post("/api/homeworks/submit")
|
||
|
||
// ai-3d.ts - 所有路径添加 /api 前缀
|
||
- request.post("/ai-3d/generate")
|
||
+ request.post("/api/ai-3d/generate")
|
||
```
|
||
|
||
### 方案二：修改后端 Controller
|
||
|
||
**优点**：
|
||
- 前端代码无需修改
|
||
|
||
**缺点**：
|
||
- 后端路径规范不统一
|
||
- 需要添加额外的路由映射
|
||
|
||
**修改内容**：
|
||
```java
|
||
// ContestController.java - 添加额外路由
|
||
@RequestMapping("/contests") // 新增：兼容前端路径
|
||
@RequestMapping("/api/contests") // 保留：标准路径
|
||
|
||
// HomeworkController.java - 修改路径
|
||
@RequestMapping("/homework/homeworks") // 修改为与前端一致
|
||
@RequestMapping("/api/homeworks")
|
||
|
||
// 修改 HTTP 方法
|
||
@PutMapping("/{id}") → @PatchMapping("/{id}")
|
||
```
|
||
|
||
### 方案三：双向调整（推荐）
|
||
|
||
**分阶段修复**：
|
||
|
||
1. **阶段一**：后端补充缺失接口（P0 优先级）
|
||
2. **阶段二**：前端统一添加 `/api` 前缀
|
||
3. **阶段三**：统一 HTTP 方法（更新使用 PUT）
|
||
|
||
---
|
||
|
||
## 修改清单
|
||
|
||
### 前端需要修改的文件
|
||
|
||
| 文件 | 修改内容 | 行数 |
|
||
|:------|:--------|:-----|
|
||
| `src/api/contests.ts` | 所有路径添加 `/api` 前缀，共 47 个接口 | ~1400 行 |
|
||
| `src/api/homework.ts` | 路径结构调整，共 24 个接口 | ~400 行 |
|
||
| `src/api/ai-3d.ts` | 所有路径添加 `/api` 前缀，共 5 个接口 | ~120 行 |
|
||
|
||
### 后端需要修改的 Controller
|
||
|
||
| Controller | 修改内容 |
|
||
|:----------|:--------|
|
||
| `ContestController.java` | 无需修改路径，需保持 `/api/contests` |
|
||
| `HomeworkController.java` | 无需修改路径，已使用 `/api/homeworks` |
|
||
| `AI3DTaskController.java` | 无需修改路径，已使用 `/api/ai-3d` |
|
||
|
||
### 后端需要补充的接口
|
||
|
||
共需补充 **28 个接口**，分布在以下 Controller：
|
||
|
||
| Controller | 需补充接口数 |
|
||
|:----------|:------------|
|
||
| `ContestController.java` | 1 |
|
||
| `ContestWorkController.java` | 2 |
|
||
| `ContestReviewController.java` | 7 |
|
||
| `HomeworkController.java` | 11 |
|
||
| `HomeworkReviewRuleController.java` | 3 |
|
||
| `AI3DTaskController.java` | 1 |
|
||
| `ContestRegistrationController.java` | 1 |
|
||
| `ContestTeamController.java` | 1 |
|
||
| **新增 Controller** | |
|
||
| `AuthController.java` | 认证模块（完整） |
|
||
| `UploadController.java` | 文件上传（完整） |
|
||
| `SysLogController.java` | 系统日志（完整） |
|
||
| `PublicController.java` | 公共接口（完整） |
|
||
| `SchoolController.java` | 学校组织模块（完整） |
|
||
|
||
---
|
||
|
||
## 下一步行动
|
||
|
||
1. **确认 API 规范**
|
||
- 确认前后端统一使用 `/api/` 前缀
|
||
- 确认更新接口统一使用 PUT 方法
|
||
|
||
2. **补充缺失接口**（后端）
|
||
- 按优先级分批实现缺失接口
|
||
- 优先补充 P0 核心功能接口
|
||
|
||
3. **修改前端路径**（前端）
|
||
- 统一添加 `/api` 前缀
|
||
- 调整作业模块路径结构
|
||
|
||
4. **联调测试**
|
||
- 修复后进行前后端联调
|
||
- 使用 Swagger 文档验证接口
|
||
|
||
5. **生成 API 文档**
|
||
- 使用 Swagger/OpenAPI 生成标准文档
|
||
- 作为前后端对接的标准
|