library-picturebook-activity/前后端接口对齐分析.md

前后端接口对齐分析报告

分析时间：2026-03-30（最后更新：2026-03-30） 前端目录：java-frontend/src/api/ 后端目录：java-backend/src/main/java/com/lesingle/creation/controller/

---

总体概况

模块	前端 API	后端 Controller	对齐状态	备注
认证 Auth	✅ auth.ts	✅ AuthController	✅ 已实现	新增
租户 Tenants	✅ tenants.ts	✅ TenantController	⚠️ 需检查
用户 Users	✅ users.ts	✅ UserController	⚠️ 需检查
角色 Roles	✅ roles.ts	✅ RoleController	⚠️ 需检查
权限 Permissions	✅ permissions.ts	✅ PermissionController	⚠️ 需检查
菜单 Menus	✅ menus.ts	✅ MenuController	⚠️ 需检查
字典 Dict	✅ dict.ts	✅ DictController	⚠️ 需检查
配置 Config	✅ config.ts	✅ ConfigController	⚠️ 需检查
竞赛 Contests	✅ contests.ts	✅ ContestController	✅ 已对齐	已补充 my-contests
报名 Registrations	✅ contests.ts	✅ ContestRegistrationController	✅ 已对齐
团队 Teams	✅ contests.ts	✅ ContestTeamController	✅ 已对齐	已补充 listByContest
作品 Works	✅ contests.ts	✅ ContestWorkController	✅ 已对齐	已补充 guided、versions
评审 Reviews	✅ contests.ts	✅ ContestReviewController	✅ 已对齐	已补充 progress、auto-assign 等
评委 Judges	✅ contests.ts	✅ ContestJudgeController	✅ 已对齐	补充 freeze/unfreeze/batch-delete
公告 Notices	✅ contests.ts	✅ ContestNoticeController	✅ 基本对齐
成果 Results	✅ contests.ts	✅ ContestResultController	⚠️ 部分对齐
评审规则 ReviewRules	✅ contests.ts	✅ ContestReviewRuleController	⚠️ 部分对齐
预设评语 PresetComments	✅ preset-comments.ts	✅ ContestPresetCommentController	⚠️ 部分对齐
作业 Homework	✅ homework.ts	✅ HomeworkController	✅ 已对齐	已补充 submission、score 等
AI 3D	✅ ai-3d.ts	✅ AI3DTaskController	✅ 已对齐	已补充 delete
学校 Schools	✅ schools.ts	✅ SchoolController	✅ 已实现
年级 Grades	✅ grades.ts	✅ GradeController	✅ 已实现	新增
班级 Classes	✅ classes.ts	✅ SchoolClassController	✅ 已实现	新增
部门 Departments	✅ departments.ts	✅ DepartmentController	✅ 已实现	新增
教师 Teachers	✅ teachers.ts	✅ TeacherController	✅ 已实现	新增
学生 Students	✅ students.ts	✅ StudentController	✅ 已实现	新增
上传 Upload	✅ upload.ts	✅ UploadController	✅ 已实现	新增
日志 Logs	✅ logs.ts	✅ SysLogController	✅ 已实现	新增
公共 Public	✅ public.ts	✅ PublicController	✅ 已实现	新增核心接口
评委管理 JudgesMgmt	✅ judges-management.ts	✅ ContestJudgeController	✅ 已实现	freeze/unfreeze/batch-delete

---

本次完成的工作

第一阶段：补充竞赛管理模块缺失接口

接口	状态	说明
GET /api/contests/my-contests	✅	我参与的活动列表
GET /api/contests/teams/contest/:contestId	✅	按竞赛查询团队列表
GET /api/contests/works/guided	✅	教师指导的作品列表
GET /api/contests/works/registration/:id/versions	✅	作品版本列表

第一阶段：补充评审管理模块缺失接口

接口	状态	说明
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	✅	评委的作品列表

第一阶段：补充作业管理模块缺失接口

接口	状态	说明
GET /api/homeworks/my	✅	我的作业列表
POST /api/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	✅	重置评分
GET /api/homeworks/review-rules/select	✅	可选评审规则
PUT /api/homeworks/review-rules/:id	✅	更新评审规则
DELETE /api/homeworks/review-rules/:id	✅	删除评审规则

第一阶段：补充其他模块缺失接口

模块	接口	状态
AI 3D	DELETE /api/ai-3d/:id	✅ 删除任务

第二阶段：统一 HTTP 方法

将以下更新接口统一为 PUT 方法：

• PATCH /contests/:id → PUT /api/contests/:id
• PATCH /teams/:id → PUT /api/teams/:id
• PATCH /homeworks/:id → PUT /api/homeworks/:id
• PATCH /ai-3d/:id/retry → PUT /api/ai-3d/:id/retry

第三阶段：修改前端 API 路径

将前端 API 路径统一添加 /api 前缀：

• /contests/* → /api/contests/*
• /homework/homeworks/* → /api/homeworks/*
• /ai-3d/* → /api/ai-3d/*

第四阶段：新增模块

4.1 认证模块 (Auth)

• POST /api/auth/login - 用户登录
• GET /api/auth/user-info - 获取用户信息
• POST /api/auth/logout - 用户登出
• POST /api/auth/refresh-token - 刷新 Token

4.2 文件上传模块 (Upload)

• POST /api/upload - 上传文件
• DELETE /api/upload?url= - 删除文件

4.3 系统日志模块 (Logs)

• GET /api/sys-log/page - 分页查询日志
• GET /api/sys-log/:id - 日志详情
• GET /api/sys-log/statistics - 日志统计
• DELETE /api/sys-log?ids= - 批量删除日志
• POST /api/sys-log/clean - 清理过期日志

4.4 年级管理模块 (Grades)

• GET /api/grades - 分页查询年级列表
• GET /api/grades/:id - 年级详情
• POST /api/grades - 创建年级
• PUT /api/grades/:id - 更新年级
• DELETE /api/grades/:id - 删除年级

4.5 班级管理模块 (Classes)

• GET /api/classes - 分页查询班级列表
• GET /api/classes/:id - 班级详情
• POST /api/classes - 创建班级
• PUT /api/classes/:id - 更新班级
• DELETE /api/classes/:id - 删除班级

4.6 部门管理模块 (Departments)

• GET /api/departments - 部门列表
• GET /api/departments/tree - 部门树形结构
• GET /api/departments/:id - 部门详情
• POST /api/departments - 创建部门
• PUT /api/departments/:id - 更新部门
• DELETE /api/departments/:id - 删除部门

4.7 教师管理模块 (Teachers)

• GET /api/teachers - 教师列表
• GET /api/teachers/:id - 教师详情
• GET /api/teachers/user/:userId - 根据用户 ID 查询教师
• POST /api/teachers - 创建教师
• PUT /api/teachers/:id - 更新教师
• DELETE /api/teachers/:id - 删除教师

4.8 学生管理模块 (Students)

• GET /api/students - 分页查询学生列表
• GET /api/students/:id - 学生详情
• GET /api/students/user/:userId - 根据用户 ID 查询学生
• POST /api/students - 创建学生
• PUT /api/students/:id - 更新学生
• DELETE /api/students/:id - 删除学生

4.9 评委管理模块 (Contest Judges)

• GET /api/contests/judges/contest/:contestId - 活动评委列表
• GET /api/contests/judges/:id - 评委详情
• POST /api/contests/judges - 创建评委
• PUT /api/contests/judges/:id - 更新评委
• DELETE /api/contests/judges/:id - 删除评委
• POST /api/contests/judges/freeze - 冻结评委
• POST /api/contests/judges/unfreeze - 解冻评委
• POST /api/contests/judges/batch-delete - 批量删除评委

---

待实现模块

P0 - 高优先级

1. 公共接口模块 (Public) - 涉及用户注册、登录、个人信息、子女管理、活动、作品、AI 创作、标签、广场等（40+ 端点，功能复杂）

P1 - 中优先级

1. 学校管理模块完善 - 学校信息 CRUD（已有基础，需补充完整接口）
2. 结果管理模块完善 - ContestResult 相关接口
3. 评审规则模块完善 - ContestReviewRule 相关接口
4. 预设评语模块完善 - ContestPresetComment 相关接口

---

主要问题总结

1. 路径前缀不一致

• 前端大多使用 /contests、/homework/homeworks
• 后端统一使用 /api/contests、/api/homeworks
• 修复方案：已修改前端 API 路径，添加 /api 前缀

2. HTTP 方法不一致

• 多处更新接口前端使用 PATCH，后端使用 PUT
• 修复方案：已统一修改前端使用 PUT 方法

---

下一步行动

1. 实现公共接口模块 - 这是最大的模块，涉及用户端所有功能
2. 实现学校组织模块 - 部门、教师、学生管理
3. 实现评委管理模块 - 评委邀请、审核、管理
4. 联调测试 - 修复后进行前后端联调测试