tonytech/library-picturebook-activity
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
781416dc19
library-picturebook-activity/前后端接口对齐分析.md
En b805f456a6 feat: 完善后端基础架构和登录功能 
- 添加 Lombok 配置支持
- 完善枚举类和常量定义
- 新增工具类（TraceId、限流、OSS 等）
- 添加切面（日志、限流、TraceId）
- 更新数据库索引规范（应用层防重）
- 登录页面样式优化
- 前后端项目文档补充
2026-03-31 13:58:28 +08:00

208 lines
9.2 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 前后端接口对齐分析报告
> 分析时间：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. **联调测试** - 修复后进行前后端联调测试
Reference in New Issue View Git Blame Copy Permalink