tonytech/kindergarten_java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
1a79fef30f
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

14 KiB
Raw Blame History

接口对齐实施记录

实施日期: 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