# 名导精讲导游端开发说明

本工程是导游端 uni-app 工程，当前以页面原型和本地 mock 流程为主。后续开发需要边实现边更新本文和 `docs/接口文档.md`。

## 当前页面

- `pages/login/index.vue`：手机号验证码登录，当前为 mock 登录。
- `pages/register-phone/index.vue`：注册导游手机号验证页，验证码为本地 mock，`123456` 通过。
- `pages/register-profile/index.vue`：注册导游资料填写页，含基础资料、证件上传占位和提交审核提示。
- `pages/workbench/index.vue`：导游首页，展示今日接单、今日讲解人数，并按审核状态显示“开始接单 / 待审核 / 审核未通过”；内置个人中心抽屉。
- `pages/receiving/index.vue`：选择景区、汇合点并开启 / 停止接单。
- `pages/order-detail/index.vue`：订单详情，支持接单、确认客户到场、开始讲解、结束讲解。
- `pages/orders/index.vue`：历史订单页，按全部讲解、接单中、讲解中、已完成筛选。
- `pages/earnings/index.vue`：业绩明细页，展示今日收益、本月收益、筛选栏和收益明细列表；右上角「提现」进入导游提现。
- `pages/withdrawal/index.vue`：导游提现列表，展示当前可提、提现按钮和提现记录；按进件状态跳转进件、审核中或提现详情。
- `pages/onboarding/index.vue`：导游进件表单，支持企业/个人主体资料提交真实接口审核。
- `pages/onboarding-pending/index.vue`：进件审核中 / 审核未通过状态页；刷新时查询斗拱真实审核状态。
- `pages/withdrawal-detail/index.vue`：填写提现金额，并选择 / 更换审核通过的银行卡后提交。
- `pages/bank-card-select/index.vue`：银行卡列表，仅已通过的卡可选用，支持添加银行卡。
- `pages/bank-card-add/index.vue`：填写卡号、开户省份/城市和开户行。
- `pages/bank-branch-select/index.vue`：搜索并选择开户行。
- `pages/withdrawal-success/index.vue`：提现提交成功页。
- `pages/rating/index.vue`：我的评分页，展示综合评分、日期筛选和评价列表。
- `pages/profile/index.vue`：个人中心信息页，展示头像、手机号，并支持更换头像和进入更换手机号流程。
- `pages/change-phone-old/index.vue`：更换手机号第一步，验证旧手机号。
- `pages/change-phone-new/index.vue`：更换手机号第二步，确认新手机号。
- `pages/agreements/index.vue`：协议列表页，展示用户协议、讲解服务合作协议、平台奖惩机制。
- `pages/agreement-detail/index.vue`：协议详情页，根据协议类型展示用户协议、讲解服务合作协议、平台奖惩机制正文。
- `pages/settings/index.vue`：设置页，支持清除缓存、查看版本、退出登录和注销账户占位。
- `pages/feedback/index.vue`：意见反馈页，支持 500 字以内文本反馈提交。
- `pages/certification/index.vue`：资质认证表单，占位提交审核。

## 组件

- `components/guide-bottom-nav/guide-bottom-nav.vue`：底部四入口导航。
- `components/guide-stat-card/guide-stat-card.vue`：统计卡片。
- `components/guide-dialog/guide-dialog.vue`：统一确认弹窗，按蓝色提示标题、白色圆角面板、浅蓝取消按钮、蓝色确认按钮样式展示。

## 状态与流程

### 登录注册流程

```text
登录页
  ├─ 登录成功 -> 首页
  └─ 注册成为导游 -> 注册手机验证 -> 资料填写 -> 首页待审核状态
```

### 首页审核状态

首页不是多个审核页面，而是同一个 `pages/workbench/index.vue` 根据 `guide.auditStatus` 渲染不同内容：

- `approved`：显示“开始接单”，个人中心抽屉显示星级和完整菜单。
- `pending`：显示“资料已提交，请耐心等待审核”，个人中心抽屉只显示“设置”。
- `rejected`：显示“审核未通过，请修改资料并重新提交。”和“重新提交”按钮，个人中心抽屉只显示“设置”。

## 数据与接口替换点

当前数据集中放在：

- `constants/mock.js`
- `services/auth.js`
- `services/guide.js`
- `services/order.js`

后续接后端时优先替换 service 层，不要把接口请求散落到页面里。推荐接口边界：

- `POST /guide/auth/login`：导游登录。
- `GET /guide/profile`：导游资料。
- `PUT /guide/status`：在线 / 离线 / 忙碌状态。
- `GET /guide/scenics`：导游可服务景区和汇合点。
- `GET /guide/orders/pending`：待接订单。
- `GET /guide/orders`：订单列表。
- `GET /guide/orders/{id}`：订单详情。
- `POST /guide/orders/{id}/accept`：接单。
- `POST /guide/orders/{id}/arrive`：确认客户到场。
- `POST /guide/orders/{id}/start`：开始讲解。
- `POST /guide/orders/{id}/finish`：结束讲解。
- `GET /guide/earnings`：收益统计和明细。
- `POST /guide/certification`：提交资质认证。

完整接口草案见：`docs/接口文档.md`。

## 当前 UI 风格约定

- 登录和注册链路以首页为视觉基准：蓝色品牌主色 `#4d8fe8` / `#1685ff`、白色背景、清晰表单边框、蓝色主按钮。
- 不使用 CSS 手绘业务图标；图标统一放在 `static/icons`，当前使用 Lucide 图标资源。
- 注册类页面使用自定义蓝色顶部栏，左侧返回图标、标题居中。
- 表单控件保持轻量边框和小圆角，避免过重阴影和大面积卡片堆叠。
- 所有确认类弹窗统一使用 `components/guide-dialog/guide-dialog.vue`，不要直接调用系统 `uni.showModal`。
- 首页与审核状态页共用同一个顶部蓝色统计区域，蓝色高度保持一致。
- 个人中心是首页左侧抽屉，不是独立页面；抽屉切入使用滑动动画和遮罩渐显。

## 运行

```bash
npm install
npm run build:mp-weixin
```

微信开发者工具导入：

```text
dist/build/mp-weixin
```

HBuilderX 如果在修改 `pages.json` 前已经启动过 H5 运行，可能仍按单页面工程缓存运行，点击登录或底部导航时会提示不能执行页面跳转 API。遇到这种情况需要先停止当前运行任务，再重新运行项目；必要时清理浏览器本地缓存中的 `mingdao_guide_login_state`。

## 当前限制

- 短信验证码、资质认证和导航仍有前端占位；提现流程已接入后端和斗拱。
- 汇合点地图当前使用前端 mock 坐标，真实经纬度、地址和导航文案以后端配置为准。
- 订单数据使用本地 storage mock，会随操作改变状态。
- 真实接单提醒、声音弹窗、位置上报、后台保活需要结合 App / 小程序平台能力继续设计。
- 所有源码、配置和 Markdown 必须保持 UTF-8 编码。

## 开发记录

后续每次新增页面、调整接口或改变关键交互，都在这里追加记录。

| 日期 | 记录 |
| --- | --- |
| 2026-06-17 | 初始化导游端页面骨架：登录、注册手机验证、资料填写、首页、接单、订单、收益等。 |
| 2026-06-17 | 登录页改为蓝色景区插画头图 + 白色表单卡，图标改为本地 Lucide 资源。 |
| 2026-06-17 | 注册流程拆为手机验证页和资料填写页，资料提交后首页进入 `pending` 审核状态。 |
| 2026-06-17 | 首页按审核状态渲染：审核通过、审核中、审核未通过；个人中心抽屉按状态展示不同菜单。 |
| 2026-06-17 | 新增 `docs/接口文档.md`，后续后端联调以 service 层替换为准。 |
| 2026-06-17 | 重构 `pages/receiving/index.vue` 为接单选择页：景区/汇合点下拉、汇合点地图占位、接单类型多选、平台奖惩机制入口和确认开始接单。 |
| 2026-06-17 | 优化接单选择页精讲锁定态，锁定文案为“总接单数≥10团，总平均评分 ≥4.5分，可解锁精讲”，其中接单数和评分阈值后续由后台配置。 |
| 2026-06-17 | 首页新增在线接单状态：接单选择确认后保存接单配置，首页显示“接单中”、当前汇合点、暂无订单提示和取消接单按钮。 |
| 2026-06-17 | 首页接单中状态新增已有订单样式：服务类型、开讲时间、游客分组列表、电话联系和开始讲解按钮。 |
| 2026-06-17 | 首页新增讲解中状态：开始讲解后切换为“讲解中”，底部按钮改为“结束讲解”，点击结束时弹确认提示。 |
| 2026-06-17 | 首页接单中、讲解中状态增加倒计时展示，格式为“分钟数:秒数”；当前 mock 接单中默认 15 分钟，讲解中按订单时长倒计时。 |
| 2026-06-17 | 重做业绩明细页：蓝色导航、今日/本月收益、订单类型/景区/日期筛选和明细列表，贴近当前原型样式。 |
| 2026-06-17 | 重做历史订单页：蓝色导航、四项状态筛选、讲解类型/景区/接单时间/人数列表，贴近当前原型样式。 |
| 2026-06-17 | 新增我的评分页：综合评分、日期筛选、评价星级、文字反馈和图片占位，并接入个人中心抽屉入口。 |
| 2026-06-17 | 业绩明细、历史订单、我的评分统一改为自定义蓝色顶部栏，并补充左侧返回入口。 |
| 2026-06-17 | 修复个人中心进入业绩明细、历史订单、我的评分后无法返回的问题：入口改为保留页面栈，返回按钮无上一页时回首页。 |
| 2026-06-17 | 业绩明细、历史订单、我的评分增加页面进入/退出动画：进入右侧轻滑入，返回时轻滑出后再执行返回。 |
| 2026-06-17 | 重做个人中心信息页，新增头像本地选择预览保存、更换手机号旧号验证和新号确认两步页面。 |
| 2026-06-17 | 增强二级页返回动画可感知度：退出位移和时长加大，并延后实际返回到动画完成后执行。 |
| 2026-06-17 | 新增用户协议、设置、意见反馈页面，并接入个人中心抽屉入口；设置页支持清缓存和退出登录，反馈页支持字数统计和提交校验。 |
| 2026-06-17 | 新增统一弹窗组件 `guide-dialog`，替换登录协议提示、退出登录、取消接单、结束讲解、联系游客、提交成功等确认类弹窗。 |
| 2026-06-17 | 新增协议详情页，协议列表支持进入用户协议、讲解服务合作协议、平台奖惩机制正文。 |
| 2026-06-17 | 登录页协议文字和接单选择页平台奖惩机制入口接入协议详情页跳转。 |
| 2026-06-17 | 优化历史订单页列表设计：订单状态改为彩色标签，接单中/讲解中/已完成用不同颜色区分，并增强订单信息层级。 |
| 2026-07-28 | 汇合点接入地图展示：为景区汇合点补充经纬度与地址，接单选择页改为真地图预览，首页/订单详情/接单页点击“查看汇合点”后直接拉起系统地图导航。 |
| 2026-07-29 | 导游意见反馈接入 `POST /api/guide/feedback`，提交人身份从 GUIDE Token 获取，反馈统一进入后台意见反馈管理。 |
| 2026-08-14 | 业绩明细右上角增加「提现」入口，复用商户端提现静态流程：列表、填写金额、提交成功；当前为 App 本地 mock。 |
| 2026-08-14 | 补齐提现完整静态流程：导游进件、审核状态、选择/填写银行卡、选择开户行；提现详情支持选择或更换已通过银行卡。 |
| 2026-08-14 | 提现复用页顶栏改为浅色（灰底深色标题），与原商户端一致；业绩明细等导游主流程页仍用蓝底导航。 |
| 2026-08-14 | 提现模块接入真实接口：区分个人/企业进件，审核通过后绑定结算卡，并支持余额、提现记录、提现申请、后台受理和斗拱到账回调。 |