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. **联调测试** - 修复后进行前后端联调测试