xiaoli/peixue-dev
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
47101329e1
peixue-dev/Archive/[一次性]API对接检查报告-2026-01-27.md

19 KiB
Raw Blame History

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 - 尽快修复

  1. 统一工单/订单术语 - 提高代码可读性
  2. 检查后台管理API前缀配置 - 确保正常调用

P2 - 优化改进

  1. 清理冗余接口定义 - 提高代码质量
  2. 添加API文档 - 方便后续维护

五、下一步行动

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

报告生成完成