# 名导精讲导游端接口文档

本文记录导游端前端所需接口。登录模块已经接入后端，其他业务模块仍按功能逐步替换 `services/` 层中的本地 mock，不要在页面中直接写请求。

## 1. 通用约定

### 1.1 基础路径

```text
/api/guide/**
```

前端请求层通过 `VITE_API_BASE_URL` 配置后端地址，默认值为 `https://www.mingdao123.com/api`。

### 1.2 响应格式

```json
{
  "code": 0,
  "message": "success",
  "data": {}
}
```

分页响应：

```json
{
  "list": [],
  "pageNum": 1,
  "pageSize": 20,
  "total": 0
}
```

### 1.3 鉴权

登录后前端保存后端返回 token。后续请求通过请求头携带：

```text
Authorization: Bearer <token>
```

当前 mock 登录态保存在本地 storage：`mingdao_guide_login_state`。

## 2. 枚举

### 2.1 导游审核状态

| 值 | 说明 | 首页表现 |
| --- | --- | --- |
| `pending` | 资料已提交，等待平台审核 | 首页显示“资料已提交，请耐心等待审核”；抽屉只显示设置 |
| `approved` | 审核通过 | 首页显示“开始接单”；抽屉显示完整菜单 |
| `rejected` | 审核未通过 | 首页显示“审核未通过，请修改资料并重新提交。”和重新提交按钮；抽屉只显示设置 |

### 2.2 导游在线状态

| 值 | 说明 |
| --- | --- |
| `offline` | 离线 |
| `online` | 在线接单 |
| `serving` | 讲解中 |
| `busy` | 忙碌 |
| `disabled` | 禁用 |

### 2.3 订单状态

| 值 | 说明 | 前端操作 |
| --- | --- | --- |
| `pending` | 待接单 | 接单 |
| `accepted` | 已接单，待确认客户 | 确认客户到场 |
| `arrived` | 客户已到场 | 开始讲解 |
| `serving` | 讲解中 | 结束讲解 |
| `completed` | 已完成 | 查看详情 |
| `canceled` | 已取消 | 查看详情 |

## 3. 登录与注册

### 3.1 手机号验证码登录

```text
POST /api/guide/auth/login
```

请求：

```json
{
  "phone": "13800000000",
  "code": "123456"
}
```

响应：

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "token": "xxx",
    "expiresIn": 604800,
    "user": {
      "id": 1,
      "username": "13800000000",
      "realName": "赵明",
      "mobile": "13800000000",
      "rating": 4.9,
      "acceptedOrderCount": 286,
      "teamName": "都江堰精讲一团"
    }
  }
}
```

前端对接：`services/auth.js` 的 `loginByPhone()`。

### 3.2 发送验证码

```text
POST /api/guide/auth/sms-code
```

请求：

```json
{
  "phone": "13800000000",
  "scene": "login"
}
```

响应：

```json
{
  "expireSeconds": 300,
  "resendSeconds": 30
}
```

开发环境固定验证码为 `123456`，无需先发送即可登录；生产环境接入短信供应商后必须清空固定验证码配置，恢复验证码发送、校验和一次性消费流程。

### 3.3 发送注册验证码

```text
POST /api/guide/registration/sms-code
```

请求：

```json
{
  "phone": "13800000000"
}
```

### 3.4 验证注册手机号

```text
POST /api/guide/registration/verify-phone
```

请求：

```json
{
  "phone": "13800000000",
  "code": "123456"
}
```

成功后返回有效期 30 分钟的 `registrationToken`，后续上传和提交通过请求头携带：

```text
X-Registration-Token: <registrationToken>
```

### 3.5 获取开户城市

```text
GET /api/guide/registration/cities
```

仅返回后台已启用的运营城市。

### 3.6 上传注册证件

```text
POST /api/guide/registration/documents
Content-Type: multipart/form-data
```

表单文件字段名为 `file`，支持 JPG、PNG、WebP，单张不超过 5MB。身份证等注册证件仅允许后台管理员鉴权访问。

### 3.7 提交导游申请

```text
POST /api/guide/registration/applications
```

请求：

```json
{
  "realName": "赵明",
  "gender": 1,
  "ageRange": "26-35岁",
  "workYearRange": "3-5年",
  "guideType": "personal",
  "idCardNo": "11010519491231002X",
  "idCardFrontUrl": "/uploads/guide-applications/front.jpg",
  "idCardBackUrl": "/uploads/guide-applications/back.jpg",
  "guideCertificateUrl": "/uploads/guide-applications/guide.jpg",
  "qualificationCertificateUrl": "/uploads/guide-applications/qualification.jpg",
  "certificateValidUntil": "2027-12-31",
  "bankCardNo": "6222021234567890123",
  "bankCityId": 1
}
```

响应数据：

```json
{
  "id": 10,
  "applicationNo": "GA20260729143000ABC123",
  "auditStatus": "pending"
}
```

手机号或身份证存在待审核/已通过申请时会拒绝重复提交。审核通过后后台创建正式导游账号，申请人再使用手机号验证码登录。

## 4. 首页与个人中心

### 4.1 获取导游资料

```text
GET /guide/profile
```

响应字段参考 3.1 登录响应中的 `guide`。

当前 mock：`services/guide.js` 的 `getGuideProfile()`。

### 4.2 更新个人资料

```text
PUT /guide/profile
```

请求：

```json
{
  "avatar": "file_avatar_001"
}
```

响应：

```json
{
  "id": "guide_001",
  "name": "赵明",
  "phone": "13600004562",
  "avatar": "https://..."
}
```

当前 mock：`services/guide.js` 的 `updateGuideProfile()`，头像使用 `uni.chooseImage()` 本地临时路径保存。

### 4.3 更换手机号

```text
POST /guide/profile/change-phone/verify-old
POST /guide/profile/change-phone/confirm-new
```

旧手机号验证请求：

```json
{
  "phone": "13600004562",
  "code": "123456"
}
```

确认新手机号请求：

```json
{
  "phone": "13900001111",
  "code": "123456"
}
```

响应：

```json
{
  "phone": "13900001111"
}
```

当前 mock：页面内验证码倒计时和本地资料更新。

### 4.4 更新在线状态

```text
PUT /guide/status
```

请求：

```json
{
  "onlineStatus": "online",
  "scenicId": "dujiangyan",
  "meetingPointId": "south_gate",
  "meetingPointLatitude": 31.001472,
  "meetingPointLongitude": 103.648278,
  "meetingPointAddress": "四川省成都市都江堰市公园路都江堰景区南门",
  "serviceIds": ["quick"]
}
```

响应：

```json
{
  "onlineStatus": "online"
}
```

当前 mock：`services/guide.js` 的 `updateGuideOnlineStatus()`。

当 `onlineStatus=online` 时，前端首页展示接单中状态，读取 `receivingConfig.meetingPointName` 作为右侧汇合点名称；当 `onlineStatus=serving` 时，首页展示讲解中状态；当 `onlineStatus=offline` 时，首页恢复“开始接单”。

首页接单中和讲解中状态需要展示倒计时，前端展示格式为“分钟数:秒数”。正式接口建议由后端返回 `countdownSeconds` 或基于服务端时间的开始 / 结束时间，避免前端刷新后重置倒计时。

### 4.5 可接服务类型

```text
GET /guide/receiving/services
```

查询参数：

| 参数 | 说明 |
| --- | --- |
| `scenicId` | 景区 ID |
| `meetingPointId` | 汇合点 ID |

响应：

```json
[
  {
    "id": "quick",
    "title": "快讲",
    "duration": "30分钟",
    "groupPeople": "20-25人",
    "groupPrice": "¥36/人",
    "privatePeople": "6人(含)内",
    "privatePrice": "¥536/团",
    "enabled": true
  },
  {
    "id": "deep",
    "title": "精讲",
    "duration": "30分钟",
    "enabled": false,
    "unlockOrderCount": 10,
    "unlockRating": 4.5,
    "unlockText": "总接单数≥10团，总平均评分 ≥4.5分，可解锁精讲"
  }
]
```

`unlockOrderCount`、`unlockRating` 和 `unlockText` 由后台配置，前端只负责展示；若后端只返回数字，前端可按统一模板拼接文案。

当前 mock：`pages/receiving/index.vue` 内本地服务类型数组，后续建议下沉到 `services/guide.js`。

### 4.6 首页统计

```text
GET /guide/workbench/summary
```

响应：

```json
{
  "todayOrderCount": 6,
  "todayPeopleCount": 156,
  "pendingCount": 1,
  "activeCount": 1,
  "completedCount": 1,
  "todayIncomeCent": 10080
}
```

当前 mock：`services/order.js` 的 `getWorkbenchSummary()`，页面会按本地订单数量兜底展示。

## 5. 接单与订单

### 5.1 可服务景区与汇合点

```text
GET /guide/scenics
```

响应：

```json
[
  {
    "id": "dujiangyan",
    "name": "都江堰景区",
    "city": "成都",
    "meetingPoints": [
      {
        "id": "south_gate",
        "name": "都江堰南门",
        "guideCount": 6,
        "latitude": 31.001472,
        "longitude": 103.648278,
        "address": "四川省成都市都江堰市公园路都江堰景区南门"
      }
    ]
  }
]
```

当前 mock：`services/guide.js` 的 `getScenics()`。

正式接口建议在汇合点配置中始终返回 `latitude`、`longitude`、`address`，前端接单选择页和汇合点详情页都直接依赖这组字段进行地图展示。

### 5.2 订单列表

```text
GET /guide/orders
```

查询参数：

| 参数 | 说明 |
| --- | --- |
| `status` | 可选，订单状态；历史订单页使用 `all` / `accepted` / `serving` / `completed` 对应全部讲解、接单中、讲解中、已完成 |
| `pageNum` | 页码 |
| `pageSize` | 每页数量 |

列表项建议字段：

```json
{
  "id": "MJ20260608001",
  "serviceName": "精讲",
  "durationMinutes": 30,
  "scenicName": "青城山",
  "receiveTime": "2026-06-08 16:34:33",
  "quantity": 14,
  "status": "accepted"
}
```

当前 mock：`services/order.js` 的 `getGuideOrders(filter)`。

### 5.3 待接订单

```text
GET /guide/orders/pending
```

当前 mock：`services/order.js` 的 `getPendingOrders()`。

### 5.4 当前接单中的订单

```text
GET /guide/orders/current-receiving
```

用于首页接单中状态展示游客/家庭列表。

响应：

```json
{
  "serviceName": "精讲",
  "durationMinutes": 30,
  "meetingPointName": "青城山-前门",
  "lectureStartTime": "15:00",
  "countdownSeconds": 900,
  "serverTime": "2026-06-17 10:15:00",
  "lectureStartAt": "2026-06-17 10:30:00",
  "lectureEndAt": "2026-06-17 11:00:00",
  "customers": [
    {
      "groupNo": 1,
      "phone": "13600004568",
      "peopleCount": 3
    }
  ]
}
```

字段说明：

| 字段 | 说明 |
| --- | --- |
| `countdownSeconds` | 当前状态剩余秒数；接单中表示距离开始讲解的剩余时间，讲解中表示距离讲解结束的剩余时间。 |
| `serverTime` | 后端当前时间，用于前端做时间差校准。 |
| `lectureStartAt` | 预计开始讲解时间。 |
| `lectureEndAt` | 预计结束讲解时间。 |

当前 mock：`pages/workbench/index.vue` 从 `getGuideOrders('all')` 中临时组装展示数据；正式联调后建议替换为本接口。

### 5.5 订单详情

```text
GET /guide/orders/{orderId}
```

当前 mock：`services/order.js` 的 `getOrderDetail(orderId)`。

### 5.6 订单状态操作

```text
POST /guide/orders/{orderId}/accept
POST /guide/orders/{orderId}/arrive
POST /guide/orders/{orderId}/start
POST /guide/orders/{orderId}/finish
```

当前 mock：`services/order.js` 的 `updateOrderStatus(orderId, status)`。

首页当前讲解中状态暂由 `services/guide.js` 的 `updateGuideOnlineStatus('serving')` 驱动；正式联调时应由订单开始 / 结束接口返回最新订单与导游状态。

## 6. 收益

### 6.1 收益统计与明细

```text
GET /guide/earnings
```

查询参数：

| 参数 | 说明 |
| --- | --- |
| `orderType` | 可选，订单类型，如 `quick` / `deep`。 |
| `scenicId` | 可选，景区 ID。 |
| `date` | 可选，日期，格式 `YYYY-MM-DD`。 |

响应：

```json
{
  "todayIncomeCent": 10080,
  "monthIncomeCent": 69000,
  "withdrawableCent": 59080,
  "rows": [
    {
      "id": "E20260617001",
      "scenicName": "青城山",
      "serviceName": "精讲",
      "orderNo": "MJ20260617001",
      "amountCent": 10080,
      "status": "待结算",
      "time": "2026-06-08 16:43:42"
    }
  ]
}
```

当前 mock：`services/order.js` 的 `getEarnings()`，页面内临时补齐为原型所需展示字段。

## 7. 我的评分

### 7.1 评分列表

```text
GET /api/guide/ratings
```

查询参数：

| 参数 | 说明 |
| --- | --- |
| `date` | 可选，日期，格式 `YYYY-MM-DD`。 |
| `pageNum` | 页码。 |
| `pageSize` | 每页数量。 |

响应：

```json
{
  "score": 5.0,
  "total": 1,
  "pageNum": 1,
  "pageSize": 20,
  "rows": [
    {
      "id": "R20260608001",
      "dateText": "2026年6月8日",
      "score": 5,
      "comment": "感觉导游很不错",
      "images": ["https://..."]
    }
  ]
}
```

当前实现：`services/rating.js` 调用导游评分接口，页面按接口返回的综合评分、评价日期、单条评分、评价内容和图片列表展示。评价图片字段当前返回空数组，待游客端评价图片完成上传及持久化后复用该字段。

## 8. 文件上传

### 8.1 上传图片

```text
POST /guide/files/upload
```

表单字段：

| 字段 | 说明 |
| --- | --- |
| `file` | 图片文件 |
| `bizType` | `id_front` / `id_back` / `guide_license` / `guide_cert` |

响应：

```json
{
  "fileId": "file_001",
  "url": "https://..."
}
```

当前 mock：注册资料页使用 `uni.chooseImage()` 本地临时路径预览，未上传。

## 9. 协议、设置与反馈

### 9.1 协议列表

```text
GET /guide/agreements
```

响应：

```json
[
  {
    "type": "user",
    "title": "用户协议",
    "url": "https://...",
    "content": ""
  },
  {
    "type": "service",
    "title": "讲解服务合作协议",
    "url": "https://..."
  },
  {
    "type": "reward",
    "title": "平台奖惩机制",
    "url": "https://..."
  }
]
```

协议内容可由后端返回 `content` 富文本 / Markdown，或返回 `url` 由前端打开 H5/PDF 页面。当前 mock：`pages/agreement-detail/index.vue` 内本地协议正文。

### 9.2 提交意见反馈

```text
POST /api/guide/feedback
```

请求：

```json
{
  "content": "希望增加订单消息声音提醒"
}
```

反馈提交人 ID、姓名和手机号从当前 GUIDE Token 对应的导游账号读取，前端不传用户身份字段。反馈保存到 `user_feedback`，`feedbackType` 固定为 `GUIDE`，可在管理后台意见反馈中查询和处理。

响应：

```json
{
  "id": 1,
  "feedbackNo": "FB20260729143000123ABCDE",
  "feedbackType": "GUIDE",
  "content": "希望增加订单消息声音提醒",
  "status": 0,
  "feedbackAt": "2026-07-29T14:30:00"
}
```

当前 mock：`pages/feedback/index.vue` 做本地空内容校验和提交提示。

### 9.3 注销账户

```text
POST /guide/account/cancel
```

当前 mock：设置页仅 Toast 占位；退出登录复用本地 `services/auth.js` 的 `logout()`。

## 10. 后续记录

接口变更时在本节追加，保留日期和变更原因。

| 日期 | 变更 |
| --- | --- |
| 2026-06-17 | 建立导游端接口文档初版，按当前 mock service 和页面状态整理。 |
| 2026-06-17 | 首页当前接单接口补充倒计时字段，支持接单中 / 讲解中以“分钟数:秒数”展示剩余时间。 |
| 2026-06-17 | 收益接口补充订单类型、景区、日期筛选参数和业绩明细展示字段。 |
| 2026-06-17 | 订单列表接口补充历史订单页筛选值和列表展示字段。 |
| 2026-06-17 | 新增我的评分接口草案，支持综合评分、日期筛选、评价文字和图片列表。 |
| 2026-06-17 | 新增个人资料更新和更换手机号接口草案，支持头像更新和旧号/新号两步验证。 |
| 2026-06-17 | 新增协议列表、意见反馈、注销账户接口草案，对应个人中心抽屉入口。 |
| 2026-06-17 | 协议接口补充正文内容说明，前端新增本地协议详情 mock。 |