library-picturebook-activity/前后端接口差异对比.md

前后端接口差异对比报告

分析时间：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 文件

修改内容：

// 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

优点：

• 前端代码无需修改

缺点：

• 后端路径规范不统一
• 需要添加额外的路由映射

修改内容：

// 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 生成标准文档
   • 作为前后端对接的标准