tonytech/library-picturebook-activity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
781416dc19
library-picturebook-activity/前后端接口差异对比.md

415 lines
20 KiB
Markdown
Raw Normal View History

feat: 完善后端基础架构和登录功能 - 添加 Lombok 配置支持 - 完善枚举类和常量定义 - 新增工具类（TraceId、限流、OSS 等） - 添加切面（日志、限流、TraceId） - 更新数据库索引规范（应用层防重） - 登录页面样式优化 - 前后端项目文档补充
2026-03-31 13:58:28 +08:00
# 前后端接口差异对比报告
> 分析时间：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 生成标准文档
- 作为前后端对接的标准
Reference in New Issue Copy Permalink