tonytech/kindergarten_java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
6e11c874d2
kindergarten_java/docs/design/api-alignment-implementation.md

392 lines
14 KiB
Markdown
Raw Normal View History

chore: 忽略 target 目录和 .class 文件 - 添加 target/ 到 .gitignore - 从 git 暂存区移除已追踪的 target 目录 Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-14 16:50:54 +08:00
# 接口对齐实施记录
**实施日期**: 2026-03-13
**实施人**: Claude
---
## 实施概述
本次实施将新后端 (Spring Boot) 的 API 接口与旧后端 (NestJS) 进行对齐，确保前端能够无缝切换使用新后端。
---
## 已完成的接口补充
### 一、认证模块 (Auth)
**文件**: `AuthController.java`, `AuthService.java`, `AuthServiceImpl.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 登录 | POST /api/auth/login | ✅ 已有 |
| 登出 | POST /api/auth/logout | ✅ 新增 |
| 获取用户信息 | GET /api/auth/profile | ✅ 修改（/me → /profile） |
| 刷新 Token | POST /api/auth/refresh | ✅ 新增 |
| 修改密码 | POST /api/auth/change-password | ✅ 已有 |
**新增文件**:
- `TokenResponse.java` - Token 响应 DTO
---
### 二、超管端 - 租户管理 (Admin Tenant)
**文件**: `AdminTenantController.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取租户列表 | GET /api/v1/admin/tenants | ✅ 已有 |
| 获取租户详情 | GET /api/v1/admin/tenants/:id | ✅ 已有 |
| 创建租户 | POST /api/v1/admin/tenants | ✅ 已有 |
| 更新租户 | PUT /api/v1/admin/tenants/:id | ✅ 已有 |
| 更新租户配额 | PUT /api/v1/admin/tenants/:id/quota | ✅ 新增 |
| 更新租户状态 | PUT /api/v1/admin/tenants/:id/status | ✅ 新增 |
| 重置租户密码 | POST /api/v1/admin/tenants/:id/reset-password | ✅ 新增 |
| 删除租户 | DELETE /api/v1/admin/tenants/:id | ✅ 已有 |
| 租户统计 | GET /api/v1/admin/tenants/stats | ✅ 新增 |
---
### 三、超管端 - 统计管理 (Admin Stats)
**文件**: `AdminStatsController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取统计数据 | GET /api/v1/admin/stats | ✅ 新增 |
| 获取趋势数据 | GET /api/v1/admin/stats/trend | ✅ 新增 |
| 获取活跃租户 | GET /api/v1/admin/stats/tenants/active | ✅ 新增 |
| 获取热门课程 | GET /api/v1/admin/stats/courses/popular | ✅ 新增 |
| 获取最近活动 | GET /api/v1/admin/stats/activities | ✅ 新增 |
---
### 四、超管端 - 系统设置 (Admin Settings)
**文件**: `AdminSettingsController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取所有系统设置 | GET /api/v1/admin/settings | ✅ 新增 |
| 更新系统设置 | PUT /api/v1/admin/settings | ✅ 新增 |
| 获取基础设置 | GET /api/v1/admin/settings/basic | ✅ 新增 |
| 更新基础设置 | PUT /api/v1/admin/settings/basic | ✅ 新增 |
| 获取安全设置 | GET /api/v1/admin/settings/security | ✅ 新增 |
| 更新安全设置 | PUT /api/v1/admin/settings/security | ✅ 新增 |
| 获取通知设置 | GET /api/v1/admin/settings/notification | ✅ 新增 |
| 更新通知设置 | PUT /api/v1/admin/settings/notification | ✅ 新增 |
| 获取存储设置 | GET /api/v1/admin/settings/storage | ✅ 新增 |
| 更新存储设置 | PUT /api/v1/admin/settings/storage | ✅ 新增 |
| 获取租户默认设置 | GET /api/v1/admin/settings/tenant-defaults | ✅ 新增 |
---
### 五、学校端 - 套餐管理 (School Package)
**文件**: `SchoolPackageController.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取套餐信息 | GET /api/school/package | ✅ 新增 |
| 获取套餐使用 | GET /api/school/package/usage | ✅ 新增 |
| 获取套餐列表 | GET /api/school/packages | ✅ 已有 |
| 续费套餐 | POST /api/school/packages/:id/renew | ✅ 已有 |
---
### 六、学校端 - 班级管理 (School Class)
**文件**: `SchoolClassController.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取班级列表 | GET /api/school/classes | ✅ 已有 |
| 获取班级详情 | GET /api/school/classes/:id | ✅ 已有 |
| 创建班级 | POST /api/school/classes | ✅ 已有 |
| 更新班级 | PUT /api/school/classes/:id | ✅ 已有 |
| 删除班级 | DELETE /api/school/classes/:id | ✅ 已有 |
| 获取班级学生 | GET /api/school/classes/:id/students | ✅ 新增 |
| 获取班级教师 | GET /api/school/classes/:id/teachers | ✅ 新增 |
| 添加班级教师 | POST /api/school/classes/:id/teachers | ✅ 已有 |
| 更新班级教师 | PUT /api/school/classes/:id/teachers/:teacherId | ✅ 新增 |
| 移除班级教师 | DELETE /api/school/classes/:id/teachers/:teacherId | ✅ 新增 |
---
### 七、学校端 - 学生管理 (School Student)
**文件**: `SchoolStudentController.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取学生列表 | GET /api/school/students | ✅ 已有 |
| 获取学生详情 | GET /api/school/students/:id | ✅ 已有 |
| 创建学生 | POST /api/school/students | ✅ 已有 |
| 更新学生 | PUT /api/school/students/:id | ✅ 已有 |
| 删除学生 | DELETE /api/school/students/:id | ✅ 已有 |
| 导入学生 | POST /api/school/students/import | ✅ 新增 |
| 导入模板 | GET /api/school/students/import/template | ✅ 新增 |
| 学生调班 | POST /api/school/students/:id/transfer | ✅ 新增 |
| 学生调班历史 | GET /api/school/students/:id/history | ✅ 新增 |
| 重置密码 | POST /api/school/students/:id/reset-password | ✅ 新增 |
---
### 八、学校端 - 家长管理 (School Parent)
**文件**: `SchoolParentController.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取家长列表 | GET /api/school/parents | ✅ 已有 |
| 获取家长详情 | GET /api/school/parents/:id | ✅ 已有 |
| 创建家长 | POST /api/school/parents | ✅ 已有 |
| 更新家长 | PUT /api/school/parents/:id | ✅ 已有 |
| 删除家长 | DELETE /api/school/parents/:id | ✅ 已有 |
| 重置密码 | POST /api/school/parents/:id/reset-password | ✅ 已有 |
| 获取孩子列表 | GET /api/school/parents/:id/children | ✅ 新增 |
| 添加孩子 | POST /api/school/parents/:id/students/:studentId | ✅ 已有 |
| 移除孩子 | DELETE /api/school/parents/:id/students/:studentId | ✅ 已有 |
---
### 九、学校端 - 排课管理 (School Schedule)
**文件**: `SchoolScheduleController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取课程表 | GET /api/school/schedules/timetable | ✅ 新增 |
| 获取排课列表 | GET /api/school/schedules | ✅ 新增 |
| 获取排课详情 | GET /api/school/schedules/:id | ✅ 新增 |
| 创建排课 | POST /api/school/schedules | ✅ 新增 |
| 更新排课 | PUT /api/school/schedules/:id | ✅ 新增 |
| 取消排课 | DELETE /api/school/schedules/:id | ✅ 新增 |
| 批量创建 | POST /api/school/schedules/batch | ✅ 新增 |
---
### 十、学校端 - 任务模板 (School Task Template)
**文件**: `SchoolTaskTemplateController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取模板列表 | GET /api/school/task-templates | ✅ 新增 |
| 获取模板详情 | GET /api/school/task-templates/:id | ✅ 新增 |
| 获取默认模板 | GET /api/school/task-templates/default/:type | ✅ 新增 |
| 创建模板 | POST /api/school/task-templates | ✅ 新增 |
| 更新模板 | PUT /api/school/task-templates/:id | ✅ 新增 |
| 删除模板 | DELETE /api/school/task-templates/:id | ✅ 新增 |
---
### 十一、学校端 - 数据导出 (School Export)
**文件**: `SchoolExportController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 导出授课记录 | GET /api/school/export/lessons | ✅ 新增 |
| 导出教师统计 | GET /api/school/export/teacher-stats | ✅ 新增 |
| 导出学生统计 | GET /api/school/export/student-stats | ✅ 新增 |
| 导出成长记录 | GET /api/school/export/growth-records | ✅ 新增 |
---
### 十二、学校端 - 系统设置 (School Settings)
**文件**: `SchoolSettingsController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取系统设置 | GET /api/school/settings | ✅ 新增 |
| 更新系统设置 | PUT /api/school/settings | ✅ 新增 |
| 获取基础设置 | GET /api/school/settings/basic | ✅ 新增 |
| 更新基础设置 | PUT /api/school/settings/basic | ✅ 新增 |
| 获取通知设置 | GET /api/school/settings/notification | ✅ 新增 |
| 更新通知设置 | PUT /api/school/settings/notification | ✅ 新增 |
| 获取安全设置 | GET /api/school/settings/security | ✅ 新增 |
| 更新安全设置 | PUT /api/school/settings/security | ✅ 新增 |
---
### 十三、学校端 - 操作日志 (School Operation Log)
**文件**: `SchoolOperationLogController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取日志列表 | GET /api/school/operation-logs | ✅ 新增 |
| 获取日志统计 | GET /api/school/operation-logs/stats | ✅ 新增 |
| 获取日志详情 | GET /api/school/operation-logs/:id | ✅ 新增 |
---
### 十四、学校端 - 数据报告 (School Reports)
**文件**: `SchoolReportController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取报告概览 | GET /api/school/reports/overview | ✅ 新增 |
| 教师报告 | GET /api/school/reports/teachers | ✅ 新增 |
| 课程报告 | GET /api/school/reports/courses | ✅ 新增 |
| 学生报告 | GET /api/school/reports/students | ✅ 新增 |
---
### 十五、教师端 - 课程管理 (Teacher Course)
**文件**: `TeacherCourseController.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取课程列表 | GET /api/teacher/courses | ✅ 已有 |
| 获取课程详情 | GET /api/teacher/courses/:id | ✅ 已有 |
| 获取班级列表 | GET /api/teacher/classes | ✅ 已有 |
| 获取教师学生 | GET /api/teacher/students | ✅ 新增 |
| 获取班级学生 | GET /api/teacher/classes/:id/students | ✅ 新增 |
| 获取班级教师 | GET /api/teacher/classes/:id/teachers | ✅ 新增 |
---
### 十六、教师端 - 排课管理 (Teacher Schedule)
**文件**: `TeacherScheduleController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取排课列表 | GET /api/teacher/schedules | ✅ 新增 |
| 获取课程表 | GET /api/teacher/schedules/timetable | ✅ 新增 |
| 今日排课 | GET /api/teacher/schedules/today | ✅ 新增 |
| 创建排课 | POST /api/teacher/schedules | ✅ 新增 |
| 更新排课 | PUT /api/teacher/schedules/:id | ✅ 新增 |
| 取消排课 | DELETE /api/teacher/schedules/:id | ✅ 新增 |
---
### 十七、教师端 - 反馈管理 (Teacher Feedback)
**文件**: `TeacherFeedbackController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取反馈列表 | GET /api/teacher/feedbacks | ✅ 新增 |
| 获取反馈统计 | GET /api/teacher/feedbacks/stats | ✅ 新增 |
---
### 十八、教师端 - 任务模板 (Teacher Task Template)
**文件**: `TeacherTaskTemplateController.java` (新增)
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取模板列表 | GET /api/teacher/task-templates | ✅ 新增 |
| 获取模板详情 | GET /api/teacher/task-templates/:id | ✅ 新增 |
| 获取默认模板 | GET /api/teacher/task-templates/default/:type | ✅ 新增 |
| 创建模板 | POST /api/teacher/task-templates | ✅ 新增 |
| 从模板创建 | POST /api/teacher/task-templates/from-template | ✅ 新增 |
---
### 十九、家长端 - 孩子管理 (Parent Child)
**文件**: `ParentChildController.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取孩子列表 | GET /api/parent/children | ✅ 已有 |
| 获取孩子详情 | GET /api/parent/children/:id | ✅ 已有 |
| 获取成长记录 | GET /api/parent/children/:id/growth | ✅ 新增 |
---
### 二十、家长端 - 任务管理 (Parent Task)
**文件**: `ParentTaskController.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取任务列表 | GET /api/parent/tasks | ✅ 新增 |
| 获取任务详情 | GET /api/parent/tasks/:id | ✅ 已有 |
| 完成任务 | POST /api/parent/tasks/:id/complete | ✅ 已有 |
---
### 二十一、家长端 - 通知管理 (Parent Notification)
**文件**: `ParentNotificationController.java`
| 接口 | 路径 | 状态 |
|------|------|------|
| 获取通知 | GET /api/parent/notifications | ✅ 已有 |
| 获取通知详情 | GET /api/parent/notifications/:id | ✅ 已有 |
| 标记已读 | POST /api/parent/notifications/:id/read | ✅ 已有 |
| 全部已读 | POST /api/parent/notifications/read-all | ✅ 已有 |
| 未读数量 | GET /api/parent/notifications/unread-count | ✅ 已有 |
---
## 新增文件列表
### Controller (11 个)
1. `AdminStatsController.java` - 超管统计管理
2. `AdminSettingsController.java` - 超管系统设置
3. `SchoolScheduleController.java` - 学校排课管理
4. `SchoolTaskTemplateController.java` - 学校任务模板
5. `SchoolExportController.java` - 学校数据导出
6. `SchoolSettingsController.java` - 学校系统设置
7. `SchoolOperationLogController.java` - 学校操作日志
8. `SchoolReportController.java` - 学校数据报告
9. `TeacherScheduleController.java` - 教师排课管理
10. `TeacherFeedbackController.java` - 教师反馈管理
11. `TeacherTaskTemplateController.java` - 教师任务模板
### DTO/VO (1 个)
1. `TokenResponse.java` - Token 响应 DTO
---
## 修改文件列表
### Controller (7 个)
1. `AuthController.java` - 添加 logout/refresh，修改/me 为/profile
2. `AdminTenantController.java` - 添加 quota/status/reset-password/stats
3. `SchoolPackageController.java` - 添加 package/package/usage
4. `SchoolClassController.java` - 添加 students/teachers 相关接口
5. `SchoolStudentController.java` - 添加 import/transfer/history/reset-password
6. `SchoolParentController.java` - 添加 children 接口
7. `TeacherCourseController.java` - 添加 students/teachers 相关接口
### Service (2 个)
1. `AuthService.java` - 添加 logout/refreshToken 方法
2. `AuthServiceImpl.java` - 实现 logout/refreshToken 方法
---
## 注意事项
1. **待实现功能**: 本次补充的接口中，大部分使用了占位实现（TODO 标记），需要后续根据业务逻辑完善具体实现
2. **接口路径**: 所有接口路径已与旧后端对齐，前端可以无缝切换
3. **响应格式**: 所有接口统一使用 `Result<T>` 包装类返回
4. **权限控制**: 所有接口已添加相应的角色权限注解 `@RequireRole`
---
## 后续工作
1. **完善 Service 层实现**: 逐步实现各个 Controller 中 TODO 标记的业务逻辑
2. **创建 DTO/VO**: 根据具体需求创建更多数据传输对象
3. **编写单元测试**: 为各个 Controller 编写测试用例
4. **集成测试**: 前端进行完整的功能测试
---
**记录时间**: 2026-03-13
Reference in New Issue Copy Permalink