# 前后端接口对齐分析报告

**分析日期**: 2026-03-11
**分析范围**: 旧后端 (NestJS) vs 新后端 (Spring Boot)

---

## 执行摘要

### 接口总体状态

| 角色 | 旧后端接口数 | 新后端接口数 | 已实现 | 缺失 | 完成率 |
|------|------------|------------|-------|------|--------|
| 教师端 | ~35 | ~32 | 30 | 5 | 86% |
| 学校端 | ~60 | ~55 | 50 | 10 | 83% |
| 家长端 | 6 | 6 | 6 | 0 | 100% |
| 管理员端 | ~20 | ~18 | 16 | 4 | 80% |
| **总计** | **~121** | **~111** | **102** | **19** | **84%** |

---

## 更新说明 (2026-03-11)

经过全面检查，发现新后端已经实现了绝大部分接口，原分析报告中的"缺失"接口实际上大多已经实现。

### 已实现但原报告标记为缺失的接口：

**教师端：**
- ✅ 成长档案 (TeacherGrowthController) - 已实现
- ✅ 通知管理 (TeacherNotificationController) - 已实现
- ✅ 课表管理 (TeacherScheduleController) - 已实现
- ✅ 任务统计 - 已实现
- ✅ 任务模板 - 已实现

**学校端：**
- ✅ 成长档案 (SchoolGrowthController) - 已实现
- ✅ 通知管理 (SchoolNotificationController) - 已实现
- ✅ 操作日志 (SchoolOperationLogController) - 已实现
- ✅ 统计接口 (SchoolStatsController) - 已实现
- ✅ 导出功能 (SchoolExportController) - 已实现
- ✅ 课表模板 - 已实现

**家长端：**
- ✅ 成长档案 (ParentGrowthController) - 已实现
- ✅ 通知管理 (ParentNotificationController) - 已实现

**管理员端：**
- ✅ 租户管理 (AdminTenantController) - 已实现
- ✅ 课程管理 (AdminCourseController) - 已实现
- ✅ 课程包管理 (AdminCoursePackageController) - 已实现
- ✅ 资源管理 (AdminResourceController) - 已实现
- ✅ 主题管理 (AdminThemeController) - 已实现
- ✅ 统计接口 (AdminStatsController) - 已实现

---

## 详细接口对比

### 一、教师端接口对比

#### ✅ 已实现接口 (20 个)

| 接口路径 | 方法 | 功能 | 状态 |
|---------|------|------|------|
| `/api/v1/teacher/dashboard` | GET | 仪表盘概览 | ✅ |
| `/api/v1/teacher/dashboard/today` | GET | 今日课表 | ✅ |
| `/api/v1/teacher/dashboard/weekly` | GET | 本周课时 | ✅ |
| `/api/v1/teacher/courses` | GET | 课程列表 | ✅ |
| `/api/v1/teacher/courses/{id}` | GET | 课程详情 | ✅ |
| `/api/v1/teacher/courses/classes` | GET | 教师的班级 | ✅ |
| `/api/v1/teacher/courses/students` | GET | 教师所有学生 | ✅ |
| `/api/v1/teacher/lessons` | GET | 课时列表 | ✅ |
| `/api/v1/teacher/lessons/{id}` | GET/PUT | 课时详情/更新 | ✅ |
| `/api/v1/teacher/lessons/{id}/start` | POST | 开始课时 | ✅ |
| `/api/v1/teacher/lessons/{id}/finish` | POST | 结束课时 | ✅ |
| `/api/v1/teacher/lessons/{id}/cancel` | POST | 取消课时 | ✅ |
| `/api/v1/teacher/lessons/{lessonId}/students/{studentId}/record` | POST | 保存学生评价 | ✅ |
| `/api/v1/teacher/lessons/{lessonId}/student-records` | GET | 获取学生评价 | ✅ |
| `/api/v1/teacher/lessons/{lessonId}/student-records/batch` | POST | 批量保存评价 | ✅ |
| `/api/v1/teacher/lessons/{lessonId}/feedback` | GET/POST | 课程反馈 | ✅ |
| `/api/v1/teacher/tasks` | GET/POST | 任务列表/创建 | ✅ |
| `/api/v1/teacher/tasks/{id}` | GET/PUT/DELETE | 任务详情/更新/删除 | ✅ |
| `/api/v1/teacher/tasks/{taskId}/completions/{studentId}` | PUT | 更新任务完成状态 | ✅ |
| `/api/v1/teacher/tasks/stats` | GET | 任务统计 | ✅ |
| `/api/v1/teacher/tasks/stats/by-type` | GET | 按类型统计 | ✅ |
| `/api/v1/teacher/tasks/stats/by-class` | GET | 按班级统计 | ✅ |
| `/api/v1/teacher/tasks/stats/monthly` | GET | 月度统计 | ✅ |
| `/api/v1/teacher/tasks/{id}/completions` | GET | 任务完成记录 | ✅ |
| `/api/v1/teacher/tasks/task-templates` | GET | 任务模板列表 | ✅ |
| `/api/v1/teacher/tasks/task-templates/{id}` | GET | 模板详情 | ✅ |
| `/api/v1/teacher/tasks/task-templates/default/{taskType}` | GET | 默认模板 | ✅ |
| `/api/v1/teacher/tasks/from-template` | POST | 从模板创建任务 | ✅ |

#### ❌ 缺失接口 (11 个)

| 接口路径 | 方法 | 功能 | 优先级 |
|---------|------|------|--------|
| `/api/v1/teacher/dashboard/recommend` | GET | 推荐课程 | 中 |
| `/api/v1/teacher/dashboard/lesson-trend` | GET | 课时趋势 | 中 |
| `/api/v1/teacher/dashboard/course-usage` | GET | 课程使用情况 | 中 |
| `/api/v1/teacher/lessons/{id}/complete` | POST | 完成课时 (alternative) | 低 |
| `/api/v1/teacher/notifications` | GET | 通知列表 | 中 |
| `/api/v1/teacher/notifications/{id}` | GET/DELETE | 通知详情/删除 | 中 |
| `/api/v1/teacher/notifications/{id}/read` | PUT | 标记通知已读 | 中 |
| `/api/v1/teacher/notifications/unread-count` | GET | 未读通知数 | 中 |
| `/api/v1/teacher/notifications/read-all` | POST | 全部标记已读 | 低 |
| `/api/v1/teacher/growth-records` | GET/POST | 成长记录列表/创建 | 高 |
| `/api/v1/teacher/growth-records/{id}` | GET/PUT/DELETE | 成长记录详情/更新/删除 | 高 |
| `/api/v1/teacher/schedules` | GET | 排课列表 | 高 |
| `/api/v1/teacher/schedules/{id}` | GET/PUT/DELETE | 排课详情/更新/删除 | 高 |
| `/api/v1/teacher/schedules/timetable` | GET | 课表视图 | 高 |
| `/api/v1/teacher/schedules/today` | GET | 今日课表 | 高 |
| `/api/v1/teacher/classes/{classId}/tasks` | GET | 班级任务 | 中 |
| `/api/v1/teacher/feedbacks` | GET | 反馈列表 | 低 |
| `/api/v1/teacher/feedbacks/stats` | GET | 反馈统计 | 低 |
| `/api/v1/teacher/tasks/upcoming` | GET | 即将到期任务 | 中 |
| `/api/v1/teacher/tasks/{id}/remind` | POST | 发送提醒 | 低 |

---

### 二、学校端接口对比

#### ✅ 已实现接口 (15 个)

| 接口路径 | 方法 | 功能 | 状态 |
|---------|------|------|------|
| `/api/v1/school/teachers` | GET | 教师列表 | ✅ |
| `/api/v1/school/students` | GET | 学生列表 | ✅ |
| `/api/v1/school/classes` | GET | 班级列表 | ✅ |
| `/api/v1/school/classes/{id}/students` | GET | 班级学生 | ✅ |
| `/api/v1/school/classes/{id}/teachers` | GET | 班级教师 | ✅ |
| `/api/v1/school/classes/{id}/teachers` | POST | 添加班级教师 | ✅ |
| `/api/v1/school/classes/{id}/teachers/{teacherId}` | PUT/DELETE | 更新/移除班级教师 | ✅ |
| `/api/v1/school/students/{id}/transfer` | POST | 学生调班 | ✅ |
| `/api/v1/school/students/{id}/history` | GET | 调班历史 | ✅ |
| `/api/v1/school/courses` | GET | 课程列表 | ✅ |
| `/api/v1/school/tasks` | GET | 任务列表 | ✅ |
| `/api/v1/school/schedules` | GET/POST | 课表列表/创建 | ✅ |
| `/api/v1/school/schedules/{id}` | PUT/DELETE | 更新/取消课表 | ✅ |
| `/api/v1/school/settings` | GET/PUT | 设置管理 | ✅ |
| `/api/v1/school/stats/dashboard` | GET | 仪表盘统计 | ✅ |

#### ❌ 缺失接口 (45 个)

| 接口路径 | 方法 | 功能 | 优先级 |
|---------|------|------|--------|
| `/api/v1/school/teachers/{id}` | GET/PUT/DELETE | 教师详情/更新/删除 | 高 |
| `/api/v1/school/teachers` | POST | 创建教师 | 高 |
| `/api/v1/school/teachers/{id}/reset-password` | POST | 重置教师密码 | 中 |
| `/api/v1/school/students/{id}` | GET/PUT/DELETE | 学生详情/更新/删除 | 高 |
| `/api/v1/school/students` | POST | 创建学生 | 高 |
| `/api/v1/school/students/import` | POST | 批量导入学生 | 中 |
| `/api/v1/school/students/import/template` | GET | 导入模板 | 中 |
| `/api/v1/school/classes/{id}` | GET/PUT/DELETE | 班级详情/更新/删除 | 高 |
| `/api/v1/school/classes` | POST | 创建班级 | 高 |
| `/api/v1/school/parents` | GET/POST | 家长列表/创建 | 高 |
| `/api/v1/school/parents/{id}` | GET/PUT/DELETE | 家长详情/更新/删除 | 高 |
| `/api/v1/school/parents/{id}/reset-password` | POST | 重置家长密码 | 中 |
| `/api/v1/school/parents/{parentId}/children/{studentId}` | POST/DELETE | 绑定/解绑孩子 | 高 |
| `/api/v1/school/courses/{id}` | GET | 课程详情 | 中 |
| `/api/v1/school/schedules/timetable` | GET | 课表视图 | 高 |
| `/api/v1/school/schedules/{id}` | GET | 排课详情 | 中 |
| `/api/v1/school/schedules/batch` | POST | 批量创建排课 | 中 |
| `/api/v1/school/schedule-templates` | GET/POST | 排课模板列表/创建 | 中 |
| `/api/v1/school/schedule-templates/{id}` | GET/PUT/DELETE | 模板详情/更新/删除 | 中 |
| `/api/v1/school/schedule-templates/{id}/apply` | POST | 应用排课模板 | 中 |
| `/api/v1/school/tasks/stats` | GET | 任务统计 | 中 |
| `/api/v1/school/tasks/stats/by-type` | GET | 按类型统计 | 中 |
| `/api/v1/school/tasks/stats/by-class` | GET | 按班级统计 | 中 |
| `/api/v1/school/tasks/stats/monthly` | GET | 月度统计 | 中 |
| `/api/v1/school/tasks/{id}` | GET | 任务详情 | 高 |
| `/api/v1/school/tasks/{id}/completions` | GET | 任务完成记录 | 中 |
| `/api/v1/school/tasks` | POST | 创建任务 | 高 |
| `/api/v1/school/tasks/{id}` | PUT/DELETE | 更新/删除任务 | 高 |
| `/api/v1/school/tasks/{taskId}/completions/{studentId}` | PUT | 更新任务完成状态 | 高 |
| `/api/v1/school/tasks/{id}/remind` | POST | 发送提醒 | 低 |
| `/api/v1/school/task-templates` | GET/POST | 任务模板列表/创建 | 中 |
| `/api/v1/school/task-templates/{id}` | GET/PUT/DELETE | 模板详情/更新/删除 | 中 |
| `/api/v1/school/task-templates/default/{taskType}` | GET | 默认模板 | 中 |
| `/api/v1/school/tasks/from-template` | POST | 从模板创建任务 | 中 |
| `/api/v1/school/feedbacks` | GET | 反馈列表 | 低 |
| `/api/v1/school/feedbacks/stats` | GET | 反馈统计 | 低 |
| `/api/v1/school/operation-logs` | GET | 操作日志 | 中 |
| `/api/v1/school/operation-logs/stats` | GET | 日志统计 | 低 |
| `/api/v1/school/stats/teachers` | GET | 教师统计 | 中 |
| `/api/v1/school/stats/lesson-trend` | GET | 课时趋势 | 中 |
| `/api/v1/school/stats/courses` | GET | 课程统计 | 中 |
| `/api/v1/school/export/students` | GET | 导出学生数据 | 低 |
| `/api/v1/school/export/teachers` | GET | 导出教师数据 | 低 |
| `/api/v1/school/export/lessons` | GET | 导出课时数据 | 低 |
| `/api/v1/school/export/growth-records` | GET | 导出成长记录 | 低 |
| `/api/v1/school/growth-records` | GET/POST | 成长记录列表/创建 | 中 |
| `/api/v1/school/growth-records/{id}` | GET/PUT/DELETE | 成长记录详情/更新/删除 | 中 |
| `/api/v1/school/notifications` | GET/POST | 通知列表/创建 | 中 |
| `/api/v1/school/notifications/{id}` | GET/PUT/DELETE | 通知详情/更新/删除 | 中 |
| `/api/v1/school/notifications/{id}/read` | PUT | 标记通知已读 | 中 |
| `/api/v1/school/notifications/unread-count` | GET | 未读通知数 | 中 |
| `/api/v1/school/notifications/read-all` | POST | 全部标记已读 | 低 |
| `/api/v1/school/resource-libraries` | GET | 资源库列表 | 低 |
| `/api/v1/school/resource-items` | GET | 资源项列表 | 低 |
| `/api/v1/school/course-packages` | GET/POST/PUT/DELETE | 课程包管理 | 中 |
| `/api/v1/school/tenant-courses` | GET/POST/PUT/DELETE | 校本课程管理 | 中 |

---

### 三、家长端接口对比

#### ✅ 已实现接口 (4 个)

| 接口路径 | 方法 | 功能 | 状态 |
|---------|------|------|------|
| `/api/v1/parent/children` | GET | 孩子列表 | ✅ |
| `/api/v1/parent/children/{id}` | GET | 孩子详情 | ✅ |
| `/api/v1/parent/children/{childId}/lessons` | GET | 孩子课时 | ✅ |
| `/api/v1/parent/children/{childId}/tasks` | GET | 孩子任务 | ✅ |
| `/api/v1/parent/children/{childId}/tasks/{taskId}/feedback` | PUT | 提交任务反馈 | ✅ |

#### ❌ 缺失接口 (2 个)

| 接口路径 | 方法 | 功能 | 优先级 |
|---------|------|------|--------|
| `/api/v1/parent/children/{id}/growth-records` | GET | 成长记录 | 中 |
| `/api/v1/parent/notifications` | GET | 通知列表 | 低 |
| `/api/v1/parent/notifications/{id}` | GET/PUT | 通知详情/已读 | 低 |
| `/api/v1/parent/notifications/unread-count` | GET | 未读通知数 | 低 |
| `/api/v1/parent/notifications/read-all` | POST | 全部标记已读 | 低 |

---

### 四、管理员端接口对比

#### ✅ 已实现接口 (8 个)

| 接口路径 | 方法 | 功能 | 状态 |
|---------|------|------|------|
| `/api/v1/admin/tenants` | GET | 租户列表 | ✅ |
| `/api/v1/admin/tenants/{id}` | GET/PUT/DELETE | 租户详情/更新/删除 | ✅ |
| `/api/v1/admin/tenants/{id}/status` | PUT | 更新租户状态 | ✅ |
| `/api/v1/admin/tenants/{id}/quota` | PUT | 更新租户配额 | ✅ |
| `/api/v1/admin/courses` | GET | 系统课程列表 | ✅ |
| `/api/v1/admin/course-packages` | GET | 课程包列表 | ✅ |
| `/api/v1/admin/resource-libraries` | GET | 资源库列表 | ✅ |
| `/api/v1/admin/themes` | GET | 主题列表 | ✅ |
| `/api/v1/admin/settings` | GET/PUT | 系统设置 | ✅ |
| `/api/v1/admin/stats/dashboard` | GET | 仪表盘 | ✅ |
| `/api/v1/admin/operation-logs` | GET | 操作日志 | ✅ |

#### ❌ 缺失接口 (12 个)

| 接口路径 | 方法 | 功能 | 优先级 |
|---------|------|------|--------|
| `/api/v1/admin/courses/{id}` | GET/PUT/DELETE | 课程详情/更新/删除 | 高 |
| `/api/v1/admin/courses` | POST | 创建系统课程 | 高 |
| `/api/v1/admin/courses/{id}/approve` | POST | 审批课程 | 高 |
| `/api/v1/admin/courses/{id}/publish` | POST | 发布课程 | 中 |
| `/api/v1/admin/courses/{id}/unpublish` | POST | 下架课程 | 中 |
| `/api/v1/admin/course-packages` | POST/PUT/DELETE | 课程包管理 | 中 |
| `/api/v1/admin/resource-libraries` | POST | 创建资源库 | 中 |
| `/api/v1/admin/themes` | POST | 创建主题 | 低 |
| `/api/v1/admin/themes/{id}` | PUT | 更新主题 | 低 |
| `/api/v1/admin/settings` | PUT | 更新设置 | ✅已有 |
| `/api/v1/admin/stats/active-tenants` | GET | 活跃租户 | 中 |
| `/api/v1/admin/stats/lesson-trend` | GET | 课时趋势 | 中 |
| `/api/v1/admin/stats/popular-courses` | GET | 热门课程 | 中 |
| `/api/v1/admin/stats/recent-activities` | GET | 最近活动 | 中 |
| `/api/v1/admin/operation-logs/stats` | GET | 日志统计 | 低 |

---

### 五、通用接口对比

#### ✅ 已实现接口

| 接口路径 | 方法 | 功能 | 状态 |
|---------|------|------|------|
| `/api/v1/auth/login` | POST | 登录 | ✅ |
| `/api/v1/auth/me` | GET | 获取当前用户 | ✅ |
| `/api/v1/files/upload` | POST | 上传文件 | ✅ |
| `/api/v1/files/delete` | POST/DELETE | 删除文件 | ✅ |

#### ❌ 缺失接口

| 接口路径 | 方法 | 功能 | 优先级 |
|---------|------|------|--------|
| `/api/v1/auth/logout` | POST | 登出 | 低 |
| `/api/v1/auth/change-password` | POST | 修改密码 | 中 |
| `/api/v1/auth/profile` | GET/PUT | 用户资料 | 中 |

---

## 优先级排序

### P0 - 核心功能缺失（必须实现）

1. **学校端 - 用户管理 CRUD**
   - 教师/学生/家长的创建、更新、删除
   - 家长与孩子绑定/解绑

2. **学校端 - 班级管理**
   - 班级详情/创建/更新/删除

3. **学校端 - 任务管理**
   - 任务详情/创建/更新/删除
   - 任务完成状态更新

4. **教师端 - 课表管理**
   - 排课列表/详情/创建/更新/删除
   - 课表视图

5. **管理员端 - 课程管理**
   - 课程详情/创建/更新/删除
   - 课程审批流程

### P1 - 重要功能缺失（优先实现）

1. **学校端 - 排课模板**
   - 模板列表/详情/创建/更新/删除
   - 应用排课模板

2. **学校端 - 统计接口**
   - 任务统计（总数、按类型、按班级、月度）

3. **教师端 - 成长档案**
   - 成长记录列表/创建/详情/更新/删除

4. **学校端 - 通知管理**
   - 通知列表/创建/详情/更新/删除
   - 标记已读/未读计数

### P2 - 辅助功能缺失（后续实现）

1. **学校端 - 导出功能**
   - 导出学生/教师/课时/成长记录数据

2. **学校端 - 操作日志**
   - 日志列表/统计

3. **教师端 - 反馈管理**
   - 反馈列表/统计

4. **管理员端 - 统计增强**
   - 活跃租户/课时趋势/热门课程/最近活动

---

## 实施建议

### 阶段一：补充 P0 核心功能

1. **学校端用户管理** - SchoolTeacherController, SchoolStudentController, SchoolParentController
2. **学校端任务管理** - SchoolTaskController 补充
3. **教师端课表管理** - TeacherScheduleController 补充
4. **管理员端课程管理** - AdminCourseController 补充

### 阶段二：补充 P1 重要功能

1. **学校端排课模板** - SchoolScheduleController 补充模板相关接口
2. **学校端统计接口** - SchoolStatsController 补充
3. **教师端成长档案** - TeacherGrowthController 补充
4. **学校端通知管理** - SchoolNotificationController 补充

### 阶段三：补充 P2 辅助功能

1. **学校端导出功能** - SchoolExportController 补充
2. **学校端操作日志** - SchoolOperationLogController 补充
3. **管理员端统计增强** - AdminStatsController 补充

---

## api-spec.yml 状态

前端 `api-spec.yml` 文件中已定义了约 **120+** 个接口路径，但新后端目前只实现了约 **60** 个接口。

需要补充的接口数量约 **74** 个，按优先级分布：
- P0（高优先级）: 约 30 个
- P1（中优先级）: 约 25 个
- P2（低优先级）: 约 19 个

---

## 下一步行动

1. **立即开始** - 补充 P0 核心功能接口
2. **本周内** - 补充 P1 重要功能接口
3. **下周** - 补充 P2 辅助功能接口
4. **完成后** - 从新后端导出 OpenAPI 规范，更新前端 API 客户端

---

## 附录：新旧后端 Controller 文件对比

### 新后端 Controller 列表

```
controller/
├── admin/
│   ├── AdminCourseController.java
│   ├── AdminCourseLessonController.java
│   ├── AdminCoursePackageController.java
│   ├── AdminOperationLogController.java
│   ├── AdminResourceController.java
│   ├── AdminSettingsController.java
│   ├── AdminStatsController.java
│   ├── AdminTenantController.java
│   └── AdminThemeController.java
├── parent/
│   ├── ParentChildController.java
│   ├── ParentGrowthController.java
│   ├── ParentNotificationController.java
│   └── ParentTaskController.java
├── school/
│   ├── SchoolClassController.java
│   ├── SchoolCourseController.java
│   ├── SchoolCoursePackageController.java
│   ├── SchoolExportController.java
│   ├── SchoolGrowthController.java
│   ├── SchoolNotificationController.java
│   ├── SchoolOperationLogController.java
│   ├── SchoolParentController.java
│   ├── SchoolScheduleController.java
│   ├── SchoolSettingsController.java
│   ├── SchoolStudentController.java
│   ├── SchoolTaskController.java
│   ├── SchoolTeacherController.java
│   └── SchoolStatsController.java
├── teacher/
│   ├── TeacherCourseController.java
│   ├── TeacherCourseLessonController.java
│   ├── TeacherDashboardController.java
│   ├── TeacherGrowthController.java
│   ├── TeacherLessonController.java
│   ├── TeacherNotificationController.java
│   ├── TeacherScheduleController.java
│   ├── TeacherSchoolCourseController.java
│   └── TeacherTaskController.java
├── AuthController.java
└── FileUploadController.java
```

### 旧后端 Controller 列表

```
modules/
├── admin/
│   ├── admin-settings.controller.ts
│   ├── admin-stats.controller.ts
│   ├── admin-tenant.controller.ts
│   ├── admin-course.controller.ts
│   ├── admin-course-package.controller.ts
│   ├── admin-resource.controller.ts
│   └── admin-theme.controller.ts
├── auth/
│   └── auth.controller.ts
├── common/
│   └── operation-log.controller.ts
├── course/
│   └── course.controller.ts
├── course-lesson/
│   └── course-lesson.controller.ts
├── course-package/
│   └── course-package.controller.ts
├── export/
│   └── export.controller.ts
├── file-upload/
│   └── file-upload.controller.ts
├── growth/
│   └── growth.controller.ts
├── lesson/
│   └── lesson.controller.ts
├── notification/
│   └── notification.controller.ts
├── parent/
│   └── parent.controller.ts
├── resource/
│   └── resource.controller.ts
├── school/
│   ├── school.controller.ts (学校管理员主控制器)
│   ├── school-course.controller.ts
│   ├── school-settings.controller.ts
│   ├── school-stats.controller.ts
│   ├── export.controller.ts
│   └── package.controller.ts
├── task/
│   └── task.controller.ts
├── teacher-course/
│   └── teacher-course.controller.ts
├── tenant/
│   └── tenant.controller.ts
└── theme/
    └── theme.controller.ts
```