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

## 目标

后续以 `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。