名导精讲导游端接口文档

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

1. 通用约定

1.1 基础路径

/api/guide/**

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

1.2 响应格式

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

分页响应：

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

1.3 鉴权

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

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 手机号验证码登录

POST /api/guide/auth/login

请求：

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

响应：

{
  "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 发送验证码

POST /api/guide/auth/sms-code

请求：

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

响应：

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

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

3.3 发送注册验证码

POST /api/guide/registration/sms-code

请求：

{
  "phone": "13800000000"
}

3.4 验证注册手机号

POST /api/guide/registration/verify-phone

请求：

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

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

X-Registration-Token: <registrationToken>

3.5 获取开户城市

GET /api/guide/registration/cities

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

3.6 上传注册证件

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

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

3.7 提交导游申请

POST /api/guide/registration/applications

请求：

{
  "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
}

响应数据：

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

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

4. 首页与个人中心

4.1 获取导游资料

GET /guide/profile

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

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

4.2 更新个人资料

PUT /guide/profile

请求：

{
  "avatar": "file_avatar_001"
}

响应：

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

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

4.3 更换手机号

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

旧手机号验证请求：

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

确认新手机号请求：

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

响应：

{
  "phone": "13900001111"
}

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

4.4 更新在线状态

PUT /guide/status

请求：

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

响应：

{
  "onlineStatus": "online"
}

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

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

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

4.5 可接服务类型

GET /guide/receiving/services

查询参数：

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

响应：

[
  {
    "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 首页统计

GET /guide/workbench/summary

响应：

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

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

5. 接单与订单

5.1 可服务景区与汇合点

GET /guide/scenics

响应：

[
  {
    "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 订单列表

GET /guide/orders

查询参数：

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

列表项建议字段：

{
  "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 待接订单

GET /guide/orders/pending

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

5.4 当前接单中的订单

GET /guide/orders/current-receiving

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

响应：

{
  "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 订单详情

GET /guide/orders/{orderId}

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

5.6 订单状态操作

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 收益统计与明细

GET /guide/earnings

查询参数：

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

响应：

{
  "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 评分列表

GET /api/guide/ratings

查询参数：

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

响应：

{
  "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 上传图片

POST /guide/files/upload

表单字段：

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

响应：

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

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

9. 协议、设置与反馈

9.1 协议列表

GET /guide/agreements

响应：

[
  {
    "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 提交意见反馈

POST /api/guide/feedback

请求：

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

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

响应：

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

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

9.3 注销账户

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。