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

接口与数据模型草案

本文是后端管理系统和 App 接入前的接口草案。当前后端使用 RuoYi 默认响应格式，前端可在 service 层转换为页面使用的 camelCase。

1. 通用约定

1.1 响应格式

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

分页接口通常返回 RuoYi 表格分页结构：

{
  "code": 200,
  "msg": "查询成功",
  "rows": [],
  "total": 100
}

1.2 金额

  • 后端金额建议用分：amount_cent: 36600
  • 前端展示时格式化为 ¥366.00
  • 不建议前端自行拼最终应付金额，所有优惠、人数、服务费应由计价接口返回。

1.3 坐标

  • 建议统一使用 GCJ-02。
  • 字段：longitude、latitude。
  • 小程序当前 mock 使用字符串 "103.615097,30.995286"，后续接接口时应转换为数值字段。

2. 核心数据模型

2.1 Scenic 景区

{
  "id": "dujiangyan",
  "name": "都江堰",
  "grade": "5A",
  "city": "四川 成都",
  "address": "都江堰",
  "longitude": 103.616236,
  "latitude": 31.000747,
  "map_zoom": 16,
  "enabled": true,
  "sort": 10
}

2.2 MeetingPoint 汇合点

{
  "id": "dujiangyan-south",
  "scenic_id": "dujiangyan",
  "name": "都江堰南门",
  "longitude": 103.615097,
  "latitude": 30.995286,
  "map_zoom": 17,
  "is_primary": true,
  "guide_count": 8,
  "enabled": true,
  "sort": 10
}

2.3 GuideService 服务套餐

{
  "id": "group_quick",
  "name": "拼团 · 快讲",
  "service_type": "group",
  "duration_minutes": 30,
  "min_people": 20,
  "max_people": 25,
  "price_cent": 3600,
  "unit": "person",
  "has_counter": true,
  "enabled": true,
  "sort": 10
}

服务类型：

  • group：拼团
  • private：包团

计价单位：

  • person：按人
  • group：按团

2.4 Guide 导游

{
  "id": "guide_001",
  "name": "赵四",
  "phone": "13800000000",
  "avatar_url": "",
  "license_no": "D-000001",
  "rating": 5,
  "status": "online",
  "audit_status": "approved",
  "service_scenic_ids": ["dujiangyan"],
  "longitude": 103.6151,
  "latitude": 30.9952,
  "location_updated_at": "2026-06-13 10:00:00"
}

导游状态：

  • offline
  • online
  • busy
  • disabled

审核状态：

  • pending
  • approved
  • rejected

2.5 Order 订单

{
  "id": "MJ20260612002",
  "user_id": "user_001",
  "guide_id": "guide_001",
  "scenic_id": "dujiangyan",
  "meeting_point_id": "dujiangyan-south",
  "service_id": "group_quick",
  "status": "pending_guide",
  "family_group": {
    "number": 1,
    "color": "#278BFF"
  },
  "quantity": 4,
  "unit_price_cent": 3600,
  "discount_cent": 1800,
  "payable_amount_cent": 36600,
  "paid_amount_cent": 36600,
  "payment_status": "paid",
  "refund_status": "none",
  "created_at": "2026-06-04 11:31:02",
  "paid_at": "2026-06-04 11:31:10",
  "accepted_at": "2026-06-04 11:32:00",
  "started_at": null,
  "ended_at": null,
  "canceled_at": null
}

订单状态：

  • pending_pay
  • waiting_accept
  • pending_guide
  • serving
  • pending_review
  • completed
  • canceled

支付状态：

  • unpaid
  • paid
  • closed

退款状态：

  • none
  • refunding
  • refunded
  • failed

2.6 Review 评价

{
  "id": "review_001",
  "order_id": "MJ20260612002",
  "guide_id": "guide_001",
  "user_id": "user_001",
  "rating": 5,
  "content": "讲解很清楚",
  "images": [],
  "created_at": "2026-06-04 12:31:02"
}

3. 用户端接口

3.1 登录与用户

方法 路径 说明
POST /api/auth/wechat-phone-login 微信小程序授权手机号登录，手机号作为游客唯一识别
GET /api/user/profile 获取个人资料
PUT /api/user/profile 修改昵称、头像等
POST /api/user/logout 退出登录
POST /api/user/cancel-account 注销账号

3.2 景区与汇合点

方法 路径 说明
GET /api/cities 可用城市列表，支持 keyword 搜索
GET /api/scenics 景区列表，支持关键词和定位排序
GET /api/scenics/{id} 景区详情
GET /api/scenics/{id}/meeting-points 景区汇合点列表
GET /api/scenics/nearest 根据用户经纬度返回附近景区

3.3 服务与计价

方法 路径 说明
GET /api/scenics/{id}/services 景区可售服务套餐
POST /api/orders/quote 订单试算，返回优惠和应付金额

试算请求：

{
  "scenic_id": "dujiangyan",
  "service_id": "group_quick",
  "meeting_point_id": "dujiangyan-south",
  "quantity": 4
}

3.4 订单与支付

方法 路径 说明
POST /api/orders 创建订单
GET /api/orders 我的订单列表
GET /api/orders/current 首页进行中订单提示
GET /api/orders/{id} 订单详情
POST /api/orders/{id}/pay 创建微信支付参数
POST /api/orders/{id}/cancel 用户取消订单
GET /api/orders/{id}/accept-status 等待接单页轮询订单状态
POST /api/orders/{id}/review 提交评价
GET /api/orders/{id}/review 查看评价

微信支付参数响应建议直接返回 uni.requestPayment 所需字段：

{
  "timeStamp": "1718180000",
  "nonceStr": "abc",
  "package": "prepay_id=xxx",
  "signType": "RSA",
  "paySign": "xxx"
}

3.5 协议、设置、反馈

方法 路径 说明
GET /api/agreements 协议列表
GET /api/agreements/{type} 协议详情
POST /api/feedback 问题反馈
POST /api/invoices/apply 申请发票

4. 导游 App 接口

方法 路径 说明
POST /api/guide/auth/login 导游登录
GET /api/guide/profile 导游资料
PUT /api/guide/status 在线 / 离线 / 忙碌
POST /api/guide/location 上报位置
GET /api/guide/orders/pending 待接订单
POST /api/guide/orders/{id}/accept 接单
POST /api/guide/orders/{id}/reject 拒单
GET /api/guide/orders 导游订单列表
POST /api/guide/orders/{id}/start 开始讲解
POST /api/guide/orders/{id}/finish 结束讲解
GET /api/guide/earnings 收益明细

5. 管理后台接口模块

管理后台可按资源 REST 风格拆分：

  • /admin/scenics
  • /admin/meeting-points
  • /admin/services
  • /admin/guides
  • /admin/orders
  • /admin/reviews
  • /admin/refunds
  • /admin/feedback
  • /admin/agreements
  • /admin/users
  • /admin/roles
  • /admin/logs

后台订单详情建议包含完整时间线：

{
  "timeline": [
    { "status": "pending_pay", "text": "订单创建", "time": "2026-06-04 11:31:02" },
    { "status": "paid", "text": "支付成功", "time": "2026-06-04 11:31:10" },
    { "status": "pending_guide", "text": "导游接单", "time": "2026-06-04 11:32:00" }
  ]
}

6. 当前前端接入点

  • 新建 API 封装建议放在 services/ 目录。
  • 现有 services/guide.js 只有 getGuideServices() mock，可扩展为真实服务接口。
  • 首页景区与汇合点数据目前来自 constants/scenics.js、constants/meeting-points.js。
  • 订单 mock 散落在各订单页面，接后端时建议先抽 services/order.js，再逐页替换。
  • 登录态目前保存在本地 LOGIN_STORAGE_KEY = mingdao_login_state。
  • “问题反馈”页面路径是 /pages/feedback/index，当前只做前端提交成功态。
  • “联系客服”页面路径是 /pages/customer-service/index，当前为静态联系方式展示。

6.1 页面与接口映射建议

页面 推荐接口
/pages/home/index /api/scenics /api/scenics/{id}/meeting-points /api/scenics/{id}/services /api/orders/current /api/orders/quote /api/orders /api/orders/{id}/pay
/pages/scenic-select/index /api/cities /api/scenics /api/scenics/nearest
/pages/login/index /api/auth/wechat-phone-login
/pages/mine/index /api/user/profile /api/orders
/pages/orders/index /api/orders
/pages/order-pending-pay/index /api/orders/{id} /api/orders/{id}/pay /api/orders/{id}/cancel
/pages/order-waiting/index /api/orders/{id}/accept-status
/pages/order-pending-guide/index /api/orders/{id}
/pages/order-serving/index /api/orders/{id}
/pages/order-pending-review/index /api/orders/{id} /api/orders/{id}/review
/pages/order-completed/index /api/orders/{id} /api/orders/{id}/review
/pages/order-review-detail/index /api/orders/{id}/review
/pages/agreement-list/index /api/agreements
/pages/agreement-detail/index /api/agreements/{type}
/pages/feedback/index /api/feedback
/pages/customer-service/index 可静态配置，也可做 /api/settings/contact
/pages/settings/index /api/user/logout /api/user/cancel-account

7. 状态流转建议

pending_pay
  ├─ 支付成功 -> waiting_accept
  ├─ 支付超时 -> canceled
  └─ 用户取消 -> canceled

waiting_accept
  ├─ 导游接单 -> pending_guide
  ├─ 等待超时 -> canceled + refunding
  └─ 用户取消 -> canceled + refunding

pending_guide
  ├─ 导游开始讲解 -> serving
  └─ 用户/后台取消 -> canceled + refunding

serving
  └─ 导游结束讲解 -> pending_review

pending_review
  ├─ 用户提交评价 -> completed
  └─ 超过评价期 -> completed

7.1 小程序当前前端状态流转实现

这是当前前端已经存在的页面跳转逻辑，后端接入时建议保持兼容：

首页选择服务
  -> 选择汇合点
  -> 确认订单
  -> 确认支付
  -> /pages/order-waiting/index
  -> 当前前端 5 秒后自动跳 /pages/order-pending-guide/index

订单列表
  pendingPay       -> /pages/order-pending-pay/index
  pendingGuide     -> /pages/order-pending-guide/index
  serving          -> /pages/order-serving/index
  pendingReview    -> /pages/order-pending-review/index
  completed        -> /pages/order-completed/index
  canceled         -> /pages/order-canceled/index

评价提交流程
  /pages/order-pending-review/index
  -> 提交评价
  -> 正式接入后建议返回 /pages/order-completed/index

取消流程
  待付款 / 待讲解 / 等待接单
  -> 底部取消弹窗确认
  -> /pages/order-canceled/index

8. 管理后台权限建议

权限 说明
scenic:* 景区和汇合点管理
service:* 套餐和价格管理
guide:* 导游审核、启停、排班
order:read 查看订单
order:operate 取消、改派、备注
refund:* 退款审核和处理
review:* 评价管理
agreement:* 协议内容管理
system:* 用户、角色、日志、系统配置