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
En 6e11c874d2 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

392 lines
14 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-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 View Git Blame Copy Permalink