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

导游端接口与后台数据对齐基线

目标

后续以 mingdaojingjiang_guide_app 的页面交互补充导游端接口，同时复用后台管理端已有的数据表、实体、枚举和业务规则。导游端、游客端和后台管理端必须读取同一份业务数据，禁止为导游端建立含义重复的订单、景区、评价、收益或导游档案模型。

单一数据源

导游端功能 后端数据源 后台模块
注册、认证、审核 guide_application、guide_user 导游审核、导游管理
个人资料、所属团队 guide_user、guide_team 导游详情、讲解队管理
可服务景区 guide_scenic_config、operation_scenic_spot 导游详情、景区管理
服务类型、价格 operation_scenic_pricing 景区详情
汇合点、地图坐标 operation_scenic_meeting_point 景区详情
在线、接单、定位 guide_realtime_status 导游管理
待接、当前、历史订单 tour_order 订单管理
评价、综合评分 tour_order_review、guide_user.rating 评价管理、导游管理
收益、结算、提现 tour_order、guide_withdrawal 财务流水、提现管理
消息 sys_notice、guide_notice_read 系统通知
协议、反馈、平台规则 agreement_setting、user_feedback、sys_config 协议、反馈、平台设置

当前状态

已有真实接口

  • 登录与退出：/api/guide/auth/**
  • 注册与证件上传：/api/guide/registration/**
  • 工作台：GET /api/guide/workbench
  • 导游资料：GET/PUT /api/guide/profile
  • 在线与定位：GET/PUT /api/guide/realtime-status
  • 消息与已读：GET /api/guide/notifications、PUT /api/guide/notifications/{id}/read

仍使用本地数据

  • services/guide.js 中的资料、在线状态、景区、汇合点和资质提交仍以本地数据为主。
  • services/order.js 中的订单、状态流转、统计和收益全部为本地数据。
  • 评分页已接入 GET /api/guide/ratings；协议、反馈、更换手机号、注销和通用上传尚未真实接入。

已发现的问题

  • 后端尚无导游订单、收益和服务范围 controller。
  • GuideRealtimeStatusRequest 使用整数状态，导游端使用 offline/online/serving/busy/disabled 字符串。
  • 后端订单状态为 PENDING_PAYMENT/PENDING_ACCEPT/PENDING_MEETING/IN_SERVICE/COMPLETED/CANCELLED/REFUNDED，页面使用另一套小写状态。
  • 页面仍存在日期、人数、手机号、景区和时长硬编码，联调时必须由响应数据替换。

推荐接口

第一优先级：接单闭环

接口 用途
GET /api/guide/service-scope 返回本人可服务景区、启用汇合点、坐标和服务类型
GET /api/guide/orders?scope=pending 返回符合本人服务范围的待接订单
GET /api/guide/orders?scope=current 返回本人待汇合或服务中的订单
PUT /api/guide/orders/{id}/accept 原子绑定导游并进入待汇合状态
PUT /api/guide/orders/{id}/arrive 记录到场时间
PUT /api/guide/orders/{id}/start 记录开讲时间并进入服务中
PUT /api/guide/orders/{id}/complete 记录结束时间并完成订单
PUT /api/guide/realtime-status 保存景区、汇合点、定位和可接单状态

第二优先级：订单、收益、评分

接口 用途
GET /api/guide/orders 本人历史订单，支持状态、日期和分页
GET /api/guide/orders/{id} 本人订单详情，聚合景区、汇合点、服务时长和游客信息
GET /api/guide/earnings/summary 今日、本月和可提现金额
GET /api/guide/earnings/records 与后台财务口径一致的本人收益明细
GET /api/guide/reviews 本人评价列表
GET /api/guide/reviews/summary 与 guide_user.rating 一致的评分汇总

第三优先级：个人中心

接口 用途
POST /api/guide/profile/avatar 安全上传头像并更新导游资料
POST /api/guide/security/change-phone/** 旧号验证、新号验证和最终换绑
POST /api/guide/applications/resubmit 重提资质并进入后台审核
GET /api/guide/agreements 读取后台发布的协议
POST /api/guide/feedback 写入反馈并关联当前导游
POST /api/guide/account/cancellation 提交注销申请，不物理删除历史数据

字段与状态约束

  • 页面 serviceName 对应订单 packageName，时长对应景区价格配置 durationMinutes。
  • 页面人数统一使用订单 peopleCount；如需游客分组，必须建立真实分组模型，禁止从总人数虚构明细。
  • 接单、开讲、结束时间分别对应 acceptedAt、serviceStartedAt、completedAt。
  • 汇合点 ID、名称和经纬度来自 operation_scenic_meeting_point，不得依赖前端 mock 反查。
  • 导游收入由后端结算规则计算并可追溯，前端不得自行按订单金额推算。
  • API 返回后端标准订单枚举；导游端仅在 service 层转换为 pending/accepted/arrived/serving/completed/canceled。
  • 实时状态应增加后端枚举或集中转换器，禁止在多层分别维护魔法数字。

权限规则

  • 所有 /api/guide/** 接口从登录主体取得 guideId，不得信任前端传入的导游 ID。
  • 待接订单按景区服务范围、在线状态、可接状态和订单状态过滤。
  • 接单使用数据库条件更新或事务锁，防止多个导游重复接取。
  • 游客手机号按场景脱敏，仅服务中的订单提供必要联系能力。
  • 身份证、证件图片和银行卡不得通过普通资料接口返回。
  • 删除遵循现有逻辑删除规范，订单、评价和财务记录不得物理删除。

实施顺序

  1. 将资料和实时状态切换到现有真实接口。
  2. 增加服务范围接口，替换景区和汇合点 mock。
  3. 增加导游订单查询和状态流转，完成接单闭环。
  4. 替换历史订单和订单详情本地数据。
  5. 增加收益、评分并对齐后台财务与评价口径。
  6. 补齐协议、反馈、换绑、资质重提和注销申请。
  7. 删除对应 mock 和硬编码，并补充数据权限及状态流转测试。

开发规则

  • 页面只调用 services/，不直接写 uni.request。
  • 优先复用现有 entity、mapper、service 和 DTO，仅为必要聚合新增导游端 response DTO。
  • 每增加一个导游字段，先确认后台是否已经维护或展示该字段。
  • 每增加一个状态操作，先定义前置状态、目标状态、操作者、时间字段和并发保护。
  • 接口文档、前端适配和后端测试同步更新，不长期保留双轨 mock。