景区导游
blame | 历史 | 原始文档

导游端后端接口补充与数据映射实施计划

编制日期：2026-07-29
导游端：mingdaojingjiang_guide_app
管理后台：frontend
后端：backend

1. 目标与原则

后续以后端现有领域模型和管理后台配置为唯一数据源，逐步替换导游端 services/ 中的本地 mock。

  1. 导游端展示的数据必须可由管理后台维护、审核或查询。
  2. 导游端产生的订单状态、实时状态、反馈和提现数据必须回流管理后台。
  3. 游客端、导游端和管理后台共享业务主键、枚举和状态机，不建立重复业务表。
  4. 页面只调用 services/，不直接调用 uni.request。
  5. 金额后端统一使用 BigDecimal 元，导游端适配层可转换为 amountCent。
  6. 订单历史信息使用下单快照，不依赖后续可能变化的景区配置。

2. 数据归属

业务数据 唯一数据源 后台对应模块 导游端用途
导游账号与资料 guide_user 导游管理 登录、个人中心、接单资格
导游入驻申请 guide_application 导游审核 审核状态、驳回原因、重新提交
团队与服务景区 guide_team、guide_team_scenic_config、guide_scenic_config 讲解队、导游详情 可服务景区和服务类型
景区与价格 operation_scenic_spot、operation_scenic_pricing 运营景区 接单景区、服务时长、价格来源
汇合点 operation_scenic_meeting_point 运营景区详情 接单位置、地图、导航
导游实时状态 guide_realtime_status 后续实时监控 在线、可接单、位置
订单 tour_order 订单管理 待接、当前、历史订单和详情
订单评价 tour_order_review 评价管理 我的评分
平台抽成 平台设置服务 平台设置 导游收益计算
导游提现 guide_withdrawal 提现管理 提现申请和记录
协议 agreement_setting 协议设置 用户协议、合作协议、奖惩机制
导游反馈 user_feedback，类型 GUIDE 意见反馈 提交反馈和处理结果
通知消息 sys_notice、guide_notice_read 通知公告 消息列表、未读数、已读状态

3. 当前接入情况

3.1 已接入或后端已具备

功能 前端服务 后端接口 状态
手机验证码登录 services/auth.js POST /api/guide/auth/login 已接入
登录验证码 services/auth.js POST /api/guide/auth/sms-code 已接入
退出登录 services/auth.js POST /api/guide/auth/logout 已接入
注册与资料提交 services/registration.js /api/guide/registration/** 已接入
首页聚合数据 services/workbench.js GET /api/guide/workbench 已接入，页面仍混用 mock 订单
消息与已读 services/message.js /api/guide/notifications/** 已接入
个人资料 services/guide.js GET/PUT /api/guide/profile 后端已有，前端未接入
实时接单状态 暂无真实调用 GET/PUT /api/guide/realtime-status 后端已有，前端未接入

3.2 仍使用 mock 或缺少接口

页面/功能 当前实现 主要缺口
接单选择 constants/mock.js 景区数据 可服务景区、汇合点、服务类型、精讲权限
首页订单卡片 本地 storage 订单 待接订单和当前订单
历史订单 本地 storage 订单 导游本人订单分页与筛选
订单详情 本地 mock 拼装 订单快照、地图字段、时间线
订单操作 本地修改状态 并发安全的接单和服务状态流转
收益明细 固定 earningRows 收益汇总、结算状态、可提现余额
我的评分 页面静态数据 评分汇总和评价分页
个人资料 本地登录态 头像上传、资料更新、手机号变更
资质重提 调用不存在的接口 驳回后重提与后台审核联动
协议、反馈、注销 页面占位 导游端业务接口

4. 页面—接口—后台映射

4.1 工作台与接单

页面动作 建议接口 数据与约束 后台对应
打开首页 GET /api/guide/workbench 资料、今日统计、未读数、审核状态、客服配置 导游、订单、平台设置、通知
获取可接配置 GET /api/guide/receiving/options 聚合导游权限、启用景区、汇合点和价格配置 导游详情、团队详情、运营景区
获取实时状态 GET /api/guide/realtime-status 当前在线、可接单、景区、汇合点和定位 实时监控
开始/取消接单 PUT /api/guide/realtime-status 写入在线状态、可接状态和位置 实时监控
获取待接订单 GET /api/guide/orders/pending 仅返回当前导游有资格接取的订单 订单管理
获取当前订单 GET /api/guide/orders/current 返回本人已接但未完成订单 订单管理

receiving/options 必须从后台配置聚合生成。团队导游使用团队景区配置，个人导游使用个人景区配置，最终过滤已禁用景区、汇合点和服务类型。

4.2 订单

页面动作 建议接口 核心约束
历史订单分页 GET /api/guide/orders 强制按登录导游查询
订单详情 GET /api/guide/orders/{id} 仅允许查看本人订单
接单 POST /api/guide/orders/{id}/accept 条件更新，避免多人抢同一订单
确认到场 POST /api/guide/orders/{id}/arrive 仅允许 ACCEPTED -> ARRIVED
开始讲解 POST /api/guide/orders/{id}/start 仅允许 ARRIVED -> SERVING
结束讲解 POST /api/guide/orders/{id}/finish 仅允许 SERVING -> COMPLETED

订单接口直接复用 tour_order。三端必须共用后端 OrderStatus，前端只做显示映射。订单详情中的景区、汇合点、套餐、游客、金额和时间节点优先读取订单快照。

4.3 收益与提现

页面动作 建议接口 数据来源
收益汇总 GET /api/guide/earnings/summary 已完成订单、退款状态、平台抽成
收益明细 GET /api/guide/earnings 当前导游订单收益分页
提现记录 GET /api/guide/withdrawals guide_withdrawal
提交提现 POST /api/guide/withdrawals 可提现余额校验后写入申请

导游收益不得由前端传入。后端统一计算并明确 待结算、可提现、提现中、已提现 的口径。结算规则未确定前只实现查询，不提前引入复杂钱包模型。

4.4 评分、协议、反馈与账号

页面动作 建议接口 后台对应
评分汇总和列表 GET /api/guide/ratings 评价管理
协议列表/详情 GET /api/guide/agreements、GET /api/guide/agreements/{code} 协议设置
提交反馈 POST /api/guide/feedback 意见反馈，固定类型 GUIDE
查询/修改资料 GET/PUT /api/guide/profile 导游详情
上传头像 POST /api/guide/profile/avatar 导游详情
更换手机号 /api/guide/profile/change-phone/** 导游详情
重新提交资质 PUT /api/guide/applications/latest 导游审核
注销账号 DELETE /api/guide/account 导游管理

评分、接单数、团队归属、白名单、账号状态和景区权限属于后台维护字段，导游端不得修改。

5. 已发现的一致性问题

  1. mingdaojingjiang_guide_app/docs/接口文档.md 部分路径缺少 /api 前缀。
  2. 文档使用 PUT /guide/status，实际后端为 PUT /api/guide/realtime-status。
  3. services/guide.js 的个人资料和在线状态仍写本地 storage，未调用已有后端接口。
  4. 资质重提调用 /guide/application/resubmit，后端当前不存在该接口。
  5. 前端景区和汇合点使用字符串主键，后端使用 Long 主键，联调时需统一。
  6. 前端需要汇合点 address，当前汇合点表只有名称和坐标；建议增加后台可维护地址字段。
  7. 前端订单需要汇合点坐标、地址、服务时长、备注和导游收益，当前 tour_order 快照字段不足。
  8. 实时状态前端使用 offline/online/serving/busy/disabled，后端当前只有在线和可接两个数值状态，需要统一映射。
  9. UserFeedbackService 只有游客反馈创建方法，需要复用该服务增加导游反馈。
  10. 后台已有提现管理，导游端尚无申请与查询接口，需先确认余额口径。

6. 推荐实施顺序

第一阶段：接单闭环

  1. 统一订单、实时状态和服务类型枚举。
  2. 实现可接景区、汇合点和服务类型聚合接口。
  3. 导游端实时状态切换为真实接口。
  4. 实现待接订单、当前订单、订单详情和状态操作。
  5. 替换工作台、接单页、订单页和详情页 mock。

第二阶段：个人中心闭环

  1. 接入个人资料查询和修改。
  2. 实现头像上传、手机号变更和资质重提。
  3. 接入协议、反馈和账号注销。

第三阶段：评价与财务闭环

  1. 实现评分汇总和评价分页。
  2. 明确结算与平台抽成口径。
  3. 实现收益、提现申请和提现记录。
  4. 校验后台财务流水与导游端金额一致。

7. 接口完成标准

每次补充接口必须同时完成：

  1. 后端 Controller、DTO、Service、Mapper 或数据库迁移。
  2. 导游端 services/ 请求与响应适配，页面不感知后端内部字段。
  3. 管理后台可查询或配置对应数据；没有入口时记录维护方式。
  4. 使用登录导游主键鉴权，禁止信任请求中的 guideId。
  5. 校验前置状态并处理重复提交、越权访问和并发竞争。
  6. 增加后端测试并更新接口文档和开发记录。

8. 首批建议接口

GET  /api/guide/receiving/options
GET  /api/guide/realtime-status
PUT  /api/guide/realtime-status
GET  /api/guide/orders/pending
GET  /api/guide/orders/current
GET  /api/guide/orders
GET  /api/guide/orders/{id}
POST /api/guide/orders/{id}/accept
POST /api/guide/orders/{id}/arrive
POST /api/guide/orders/{id}/start
POST /api/guide/orders/{id}/finish

完成后，首页、接单页、历史订单页和订单详情页可停止使用本地订单 storage，管理后台订单状态与导游端保持实时一致。