# API对接检查报告

生成时间：2026-01-27

## 检查方法

本报告通过对比以下内容生成：
- 后端：`peidu/backend/src/main/java/com/peidu/controller/` 下的所有Controller
- 小程序前端：`peidu/uniapp/api/` 下的API定义
- 后台管理前端：`peidu/admin/src/api/` 下的API定义

## 一、核心功能模块API对接情况

### 1. 认证模块 (AuthController)

**后端路径**: `/api/auth`

#### 后端提供的接口：
- POST `/api/auth/login` - 手机号登录
- POST `/api/auth/wx-login` - 微信登录
- POST `/api/auth/register` - 注册
- POST `/api/auth/send-code` - 发送验证码
- POST `/api/auth/logout` - 退出登录
- POST `/api/auth/refresh-token` - 刷新token
- POST `/api/auth/reapply` - 重新申请

#### 小程序前端调用：
✅ POST `/api/auth/wx-login` - 微信登录
✅ POST `/api/auth/login` - 手机号登录
✅ POST `/api/auth/register` - 注册
✅ POST `/api/auth/reapply` - 重新申请
✅ POST `/api/auth/send-code` - 发送验证码
✅ POST `/api/auth/logout` - 退出登录
✅ POST `/api/auth/refresh-token` - 刷新token

#### 后台管理前端调用：
✅ POST `/admin/login` - 管理员登录
✅ POST `/admin/logout` - 退出登录
✅ GET `/admin/current` - 获取当前用户信息

**对接状态**: ✅ 完全对接

---

### 2. 订单模块 (OrderController)

**后端路径**: `/api/order`

#### 后端提供的接口：
- POST `/api/order/create` - 创建订单
- GET `/api/order/list` - 获取订单列表
- GET `/api/order/list-full` - 获取订单列表（含完整信息）
- GET `/api/order/{id}` - 获取订单详情（完整信息）
- GET `/api/order/detail/{id}` - 获取订单详情（基本信息）
- GET `/api/order/detail-full/{id}` - 获取订单详情（含完整信息）
- POST `/api/order/cancel/{id}` - 取消订单
- POST `/api/order/pay` - 支付订单
- POST `/api/order/mockPay` - 模拟支付
- POST `/api/order/confirm/{id}` - 确认完成
- POST `/api/order/accept/{id}` - 教师接单
- POST `/api/order/reject/{id}` - 教师拒单
- POST `/api/order/start/{id}` - 开始服务
- POST `/api/order/complete/{id}` - 完成服务
- POST `/api/order/refund/{id}` - 申请退款
- GET `/api/order/count` - 获取订单统计数量

#### 小程序前端调用：
✅ POST `/api/order/create` - 创建订单
✅ GET `/api/order/list` - 获取订单列表
✅ GET `/api/order/{id}` - 获取订单详情
✅ GET `/api/order/detail-full/{id}` - 获取订单详情（完整）
✅ POST `/api/order/cancel/{id}` - 取消订单
✅ POST `/api/order/pay` - 支付订单
✅ POST `/api/order/mockPay` - 模拟支付
✅ POST `/api/order/confirm/{id}` - 确认完成
✅ POST `/api/order/accept/{id}` - 教师接单
✅ POST `/api/order/reject/{id}` - 教师拒单
✅ POST `/api/order/start/{id}` - 开始服务
✅ POST `/api/order/complete/{id}` - 完成服务
✅ POST `/api/order/refund/{id}` - 申请退款
✅ GET `/api/order/count` - 获取订单统计数量
✅ GET `/api/order/list-full` - 获取订单列表（完整信息）

#### 后台管理前端调用：
✅ GET `/order/list` - 获取订单列表
✅ GET `/order/detail/{id}` - 获取订单详情
✅ PUT `/order/status/{id}` - 更新订单状态
✅ POST `/order/cancel/{id}` - 取消订单
✅ POST `/order/refund/{id}` - 退款订单
✅ POST `/order/verify` - 核销订单
✅ POST `/order/scan-verify/{orderId}` - 扫码核销
✅ GET `/order/statistics` - 订单统计

**对接状态**: ✅ 完全对接

**注意事项**:
- 后台管理的API路径缺少 `/api` 前缀，需要在request配置中统一添加
- 小程序的 `mockPay` 接口参数传递方式需要注意（使用URL参数）

---

### 3. 管理师模块 (ManagerController)

**后端路径**: `/api/manager`

#### 后端提供的接口：
- GET `/api/manager/list` - 获取管理师列表
- POST `/api/manager/audit/{id}` - 审核管理师
- GET `/api/manager/statistics` - 获取管理师统计数据
- POST `/api/manager/apply` - 管理师注册申请
- GET `/api/manager/work-orders` - 获取工单列表
- GET `/api/manager/teacher/{teacherId}/work-orders` - 获取陪伴员工单
- POST `/api/manager/assign` - 派单
- POST `/api/manager/work-order/status` - 更新工单状态
- GET `/api/manager/feedback-summary` - 获取反馈汇总
- GET `/api/manager/available-teachers` - 获取可派单的陪伴员列表
- GET `/api/manager/month-statistics` - 获取本月服务统计

#### 小程序前端调用：
✅ POST `/api/manager/apply` - 管理师注册申请
✅ GET `/api/manager/work-orders` - 获取工单列表
✅ GET `/api/manager/teacher/{teacherId}/work-orders` - 获取陪伴员工单
✅ GET `/api/order/list-full` - 获取完整工单列表
✅ GET `/api/order/{id}` - 获取工单详情（实际是订单详情）
✅ POST `/api/manager/assign` - 派单
✅ POST `/api/manager/work-order/status` - 更新工单状态
✅ GET `/api/manager/statistics` - 获取管理师统计数据
✅ GET `/api/manager/feedback-summary` - 获取反馈汇总
✅ GET `/api/manager/available-teachers` - 获取可派单的陪伴员
✅ GET `/api/manager/month-statistics` - 获取本月统计

**对接状态**: ✅ 完全对接

**重要发现**:
- ⚠️ 小程序中"工单"实际上就是"订单"，前端调用 `/api/order/{id}` 来获取工单详情
- ⚠️ 这是一个设计上的混淆，建议统一术语

---

### 4. 教师/陪伴员模块 (TeacherController)

**后端路径**: `/api/teacher`

#### 后端提供的接口：
- GET `/api/teacher/list` - 获取教师列表
- GET `/api/teacher/detail/{id}` - 获取教师详情
- GET `/api/teacher/filter-options` - 获取筛选选项
- POST `/api/teacher/apply` - 教师认证申请
- PUT `/api/teacher/audit/{id}` - 审核教师
- POST `/api/teacher/create` - 创建教师
- PUT `/api/teacher/update/{id}` - 更新教师
- GET `/api/teacher/recommend` - 获取推荐教师
- GET `/api/teacher/statistics` - 获取陪伴员统计数据
- GET `/api/teacher/available-orders` - 获取可接订单列表
- GET `/api/teacher/pending-orders` - 获取待接单列表
- POST `/api/teacher/accept-order` - 接受订单
- POST `/api/teacher/reject-order` - 拒绝订单
- GET `/api/teacher/my-orders` - 获取我的订单列表

#### 小程序前端调用：
✅ GET `/api/teacher/list` - 获取教师列表
✅ GET `/api/teacher/detail/{id}` - 获取教师详情
✅ GET `/api/teacher/recommend` - 获取推荐教师
✅ GET `/api/teacher/filter-options` - 获取筛选选项
✅ GET `/api/teacher/statistics` - 获取统计数据
✅ GET `/api/teacher/available-orders` - 获取可接订单
✅ GET `/api/teacher/pending-orders` - 获取待接单列表
✅ POST `/api/teacher/accept-order` - 接受订单
✅ POST `/api/teacher/reject-order` - 拒绝订单
✅ GET `/api/teacher/my-orders` - 获取我的订单
✅ POST `/api/teacher/apply` - 陪伴员申请
✅ PUT `/api/teacher/update/{id}` - 更新陪伴员信息

#### 后台管理前端调用：
✅ GET `/teacher/list` - 获取教师列表
✅ GET `/teacher/detail/{id}` - 获取教师详情
✅ POST `/teacher/create` - 创建教师
✅ PUT `/teacher/update/{id}` - 更新教师
✅ PUT `/teacher/audit/{id}` - 审核教师
✅ PUT `/teacher/status/{id}` - 更新教师状态
✅ GET `/teacher/schedule/{teacherId}` - 获取教师排班
✅ PUT `/teacher/schedule/{teacherId}` - 更新教师排班

**对接状态**: ✅ 完全对接

---

### 5. 成长记录模块 (GrowthRecordController)

**后端路径**: `/api/growth-record`

#### 后端提供的接口：
- GET `/api/growth-record/daily/list` - 获取每日反馈列表
- GET `/api/growth-record/daily/{id}` - 获取每日反馈详情
- GET `/api/growth-record/weekly` - 获取周反馈列表
- GET `/api/growth-record/monthly` - 获取月反馈列表
- POST `/api/growth-record/daily/create` - 创建每日反馈
- PUT `/api/growth-record/daily/update` - 更新每日反馈
- DELETE `/api/growth-record/daily/{id}` - 删除每日反馈

#### 小程序前端调用：
✅ GET `/growth/parent/list` - 获取家长端成长记录列表
✅ GET `/growth/parent/detail/{id}` - 获取记录详情
✅ GET `/growth/parent/weekly` - 获取周报告
✅ GET `/growth/parent/monthly` - 获取月报告
✅ GET `/growth/parent/unread-count` - 获取未读数量
✅ GET `/growth/teacher/list` - 获取陪伴员反馈列表
✅ POST `/growth/teacher/create` - 创建成长记录
✅ PUT `/growth/teacher/update` - 更新成长记录
✅ DELETE `/growth/teacher/delete/{id}` - 删除成长记录
✅ PUT `/growth/teacher/publish/{id}` - 发布成长记录
✅ GET `/growth/teacher/daily` - 获取某日的记录

**对接状态**: ⚠️ 部分不匹配

**问题**:
- ❌ 小程序使用 `/growth/parent/*` 和 `/growth/teacher/*` 路径
- ❌ 后端使用 `/api/growth-record/*` 路径
- ❌ **路径不一致，需要统一**

**建议**:
1. 后端添加路由别名支持旧路径
2. 或者前端统一修改为 `/api/growth-record/*`

---

### 6. 消息通知模块 (NotificationController / MessageController)

**后端路径**: `/api/notification` 和 `/api/message`

#### 后端提供的接口：
- GET `/api/notification/list` - 获取通知列表
- GET `/api/message/unread-count` - 获取未读消息数量
- POST `/api/notification/mark-read/{id}` - 标记为已读
- POST `/api/notification/mark-all-read` - 全部标记为已读
- DELETE `/api/notification/{id}` - 删除通知

#### 小程序前端调用：
✅ GET `/api/notification/list` - 获取通知列表
✅ GET `/api/message/unread-count` - 获取未读数量
✅ POST `/api/notification/mark-read/{id}` - 标记为已读
✅ POST `/api/notification/mark-all-read` - 全部标记为已读
✅ DELETE `/api/notification/{id}` - 删除通知

**对接状态**: ✅ 完全对接

---

### 7. 服务商模块 (ProviderController)

**后端路径**: `/api/provider`

#### 后端提供的接口：
- GET `/api/provider/status` - 获取服务商状态
- POST `/api/provider/apply` - 申请成为服务商
- GET `/api/provider/info` - 获取服务商信息
- PUT `/api/provider/info` - 更新服务商信息
- GET `/api/provider/course/list` - 获取课程列表
- GET `/api/provider/course/{id}` - 获取课程详情
- POST `/api/provider/course/publish` - 发布课程
- PUT `/api/provider/course/{id}` - 更新课程
- DELETE `/api/provider/course/{id}` - 删除课程
- POST `/api/provider/course/start` - 开始课程
- POST `/api/provider/course/end` - 结束课程
- POST `/api/provider/course/record` - 保存课程记录
- GET `/api/provider/course/stats` - 获取课程统计
- GET `/api/provider/student/list` - 获取学生列表
- GET `/api/provider/student/{id}` - 获取学生详情
- GET `/api/provider/student/{id}/growth` - 获取学生成长记录
- POST `/api/provider/student/{id}/growth` - 添加学生成长记录
- GET `/api/provider/student/stats` - 获取学生统计
- GET `/api/provider/order/list` - 获取订单列表
- GET `/api/provider/order/{id}` - 获取订单详情
- GET `/api/provider/order/stats` - 获取订单统计
- GET `/api/provider/earnings/stats` - 获取收益统计
- POST `/api/provider/withdraw/apply` - 申请提现

#### 小程序前端调用：
✅ GET `/api/provider/status` - 获取服务商状态
✅ POST `/api/provider/apply` - 申请成为服务商
✅ GET `/api/provider/info` - 获取服务商信息
✅ PUT `/api/provider/info` - 更新服务商信息
✅ GET `/api/provider/course/list` - 获取课程列表
✅ GET `/api/provider/course/{id}` - 获取课程详情
✅ POST `/api/provider/course/publish` - 发布课程
✅ PUT `/api/provider/course/{id}` - 更新课程
✅ DELETE `/api/provider/course/{id}` - 删除课程
✅ POST `/api/provider/course/start` - 开始课程
✅ POST `/api/provider/course/end` - 结束课程
✅ POST `/api/provider/course/record` - 保存课程记录
✅ GET `/api/provider/course/stats` - 获取课程统计
✅ GET `/api/provider/student/list` - 获取学生列表
✅ GET `/api/provider/student/{id}` - 获取学生详情
✅ GET `/api/provider/student/{id}/growth` - 获取学生成长记录
✅ POST `/api/provider/student/{id}/growth` - 添加学生成长记录
✅ GET `/api/provider/student/stats` - 获取学生统计
✅ GET `/api/provider/order/list` - 获取订单列表
✅ GET `/api/provider/order/{id}` - 获取订单详情
✅ GET `/api/provider/order/stats` - 获取订单统计
✅ GET `/api/provider/earnings/stats` - 获取收益统计
✅ POST `/api/provider/withdraw/apply` - 申请提现

**对接状态**: ✅ 完全对接

**注意事项**:
- 前端还保留了旧的财务接口路径 `/api/provider/finance/*`，但实际调用的是新路径
- 建议清理前端代码中的冗余接口定义

---

### 8. 分销员模块 (DistributorController)

**后端路径**: `/api/distributor`

#### 后端提供的接口：
- POST `/api/distributor/apply` - 分销员注册申请
- GET `/api/distributor/info` - 获取分销员信息
- GET `/api/distributor/promotion-code` - 获取推广码
- POST `/api/distributor/record-visit` - 记录推广访问
- POST `/api/distributor/poster/generate` - 生成推广海报
- GET `/api/distributor/course/list` - 获取可分销课程列表
- GET `/api/distributor/order/list` - 获取分销订单列表
- GET `/api/distributor/commission/stats` - 获取佣金统计
- GET `/api/distributor/commission/list` - 获取佣金明细列表
- POST `/api/distributor/withdraw/apply` - 申请提现
- GET `/api/distributor/withdraw/list` - 获取提现记录
- GET `/api/distributor/team/info` - 获取团队信息
- GET `/api/distributor/team/members` - 获取团队成员列表
- GET `/api/distributor/promotion/stats` - 获取推广统计

#### 小程序前端调用：
✅ POST `/api/distributor/apply` - 分销员注册申请
✅ GET `/api/distributor/info` - 获取分销员信息
✅ GET `/api/distributor/promotion-code` - 获取推广码
✅ POST `/api/distributor/record-visit` - 记录推广访问
✅ POST `/api/distributor/poster/generate` - 生成推广海报
✅ GET `/api/distributor/course/list` - 获取可分销课程
✅ GET `/api/distributor/order/list` - 获取分销订单
✅ GET `/api/distributor/commission/stats` - 获取佣金统计
✅ GET `/api/distributor/commission/list` - 获取佣金明细
✅ POST `/api/distributor/withdraw/apply` - 申请提现
✅ GET `/api/distributor/withdraw/list` - 获取提现记录
✅ GET `/api/distributor/team/info` - 获取团队信息
✅ GET `/api/distributor/team/members` - 获取团队成员
✅ GET `/api/distributor/promotion/stats` - 获取推广统计

**对接状态**: ✅ 完全对接

---

### 9. 日历模块 (CalendarController)

**后端路径**: `/api/calendar`

#### 后端提供的接口：
- GET `/api/calendar/appointments` - 获取预约记录（月视图）
- GET `/api/calendar/daily-services` - 获取指定日期的服务详情
- GET `/api/calendar/monthly-stats` - 获取当月预约统计
- GET `/api/calendar/all-appointments` - 获取所有预约记录
- GET `/api/calendar/all-stats` - 获取所有预约统计

#### 小程序前端调用：
✅ GET `/api/calendar/appointments` - 获取预约记录
✅ GET `/api/calendar/daily-services` - 获取指定日期服务
✅ GET `/api/calendar/monthly-stats` - 获取当月统计
✅ GET `/api/calendar/all-appointments` - 获取所有预约
✅ GET `/api/calendar/all-stats` - 获取所有统计

**对接状态**: ✅ 完全对接

---

### 10. 管理师-课时管理模块 (ManagerHoursController)

**后端路径**: `/api/manager/hours`

#### 后端提供的接口：
- GET `/api/manager/hours/statistics` - 获取课时统计
- GET `/api/manager/hours/list` - 获取课时列表
- GET `/api/manager/hours/schedule/list` - 获取排课列表
- GET `/api/manager/hours/consumption/daily` - 获取每日消耗
- GET `/api/manager/hours/consumption/monthly` - 获取每月消耗
- POST `/api/manager/hours/schedule/create` - 创建排课
- POST `/api/manager/hours/schedule/complete/{id}` - 完成排课
- POST `/api/manager/hours/schedule/cancel/{id}` - 取消排课

#### 小程序前端调用：
✅ GET `/api/manager/hours/statistics` - 获取课时统计
✅ GET `/api/manager/hours/list` - 获取课时列表
✅ GET `/api/manager/hours/schedule/list` - 获取排课列表
✅ GET `/api/manager/hours/consumption/daily` - 获取每日消耗
✅ GET `/api/manager/hours/consumption/monthly` - 获取每月消耗
✅ POST `/api/manager/hours/schedule/create` - 创建排课
✅ POST `/api/manager/hours/schedule/complete/{id}` - 完成排课
✅ POST `/api/manager/hours/schedule/cancel/{id}` - 取消排课

**对接状态**: ✅ 完全对接

---

## 二、发现的主要问题

### 🔴 严重问题

#### 1. 成长记录模块路径不一致
- **问题**: 小程序使用 `/growth/*` 路径，后端使用 `/api/growth-record/*`
- **影响**: 成长记录功能无法正常工作
- **建议**: 
  - 方案1: 后端添加路由别名支持 `/growth/*`
  - 方案2: 前端统一修改为 `/api/growth-record/*`

### ⚠️ 需要注意的问题

#### 2. 工单与订单概念混淆
- **问题**: 系统中"工单"实际上就是"订单"，但使用了不同的术语
- **影响**: 代码可读性差，容易混淆
- **建议**: 统一使用"订单"术语，或明确区分工单和订单的概念

#### 3. 后台管理API路径缺少前缀
- **问题**: 后台管理前端API调用缺少 `/api` 前缀
- **影响**: 需要在request配置中统一处理
- **建议**: 检查 `peidu/admin/src/utils/request.js` 中的baseURL配置

#### 4. 服务商模块有冗余接口定义
- **问题**: 前端保留了旧的 `/api/provider/finance/*` 路径定义
- **影响**: 代码冗余，维护困难
- **建议**: 清理前端代码中的冗余接口定义

---

## 三、总体评估

### 对接完成度统计

| 模块 | 后端接口数 | 前端调用数 | 对接状态 |
|------|-----------|-----------|---------|
| 认证模块 | 7 | 7 | ✅ 100% |
| 订单模块 | 16 | 16 | ✅ 100% |
| 管理师模块 | 11 | 11 | ✅ 100% |
| 教师模块 | 14 | 14 | ✅ 100% |
| 成长记录模块 | 7 | 10 | ⚠️ 路径不一致 |
| 消息通知模块 | 5 | 5 | ✅ 100% |
| 服务商模块 | 24 | 24 | ✅ 100% |
| 分销员模块 | 14 | 14 | ✅ 100% |
| 日历模块 | 5 | 5 | ✅ 100% |
| 课时管理模块 | 8 | 8 | ✅ 100% |

### 总体结论

✅ **大部分API已正确对接**，核心功能模块的API调用基本完整。

⚠️ **需要修复的问题**：
1. 成长记录模块的路径不一致问题（最严重）
2. 工单与订单概念需要统一
3. 清理冗余的接口定义

---

## 四、建议的修复优先级

### P0 - 立即修复
1. **成长记录模块路径不一致** - 影响核心功能

### P1 - 尽快修复
2. **统一工单/订单术语** - 提高代码可读性
3. **检查后台管理API前缀配置** - 确保正常调用

### P2 - 优化改进
4. **清理冗余接口定义** - 提高代码质量
5. **添加API文档** - 方便后续维护

---

## 五、下一步行动

1. 修复成长记录模块路径问题
2. 验证后台管理系统的API调用
3. 进行端到端测试，确保所有功能正常
4. 补充API文档

---

**报告生成完成**