# 后续 Agent 接手说明

本文给后续负责后端管理系统、App 端和小程序接口化的 Agent 使用。

## 1. 当前主工程

主开发工程：

```text
C:\Users\PC\Documents\mingdaojingjiang\mingdaojingjiang_uniapp\mingdaojingjiang_uniapp
```

运行命令：

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

微信开发者工具导入：

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

当前项目是 uni-app Vue3 小程序工程，源码根目录不是传统 `src`，页面直接在 `pages/` 下。

## 2. 重要文档

- `docs/开发说明.md`：当前前端页面树、开发约定、地图说明。
- `docs/功能需求清单.md`：产品功能、后台管理系统、App 端需求。
- `docs/接口与数据模型草案.md`：接口和数据模型草案。
- `README.md`：项目入口、运行方式、关键路径。

## 3. 关键页面路径

```text
pages/home/index.vue                  首页地图与下单抽屉
pages/login/index.vue                 登录页
pages/scenic-select/index.vue         景区选择
pages/mine/index.vue                  我的
pages/profile/index.vue               个人资料
pages/customer-service/index.vue      联系客服
pages/feedback/index.vue              意见反馈
pages/orders/index.vue                订单列表
pages/order-pending-pay/index.vue     待付款详情
pages/order-waiting/index.vue         等待接单
pages/order-pending-guide/index.vue   待讲解详情
pages/order-serving/index.vue         讲解中详情
pages/order-pending-review/index.vue  待评价详情
pages/order-completed/index.vue       已完成详情
pages/order-canceled/index.vue        已取消详情
pages/order-review-detail/index.vue   查看评价
config/api.js                         后端 API 基础地址
utils/request.js                      uni.request 封装和 RuoYi 响应解包
services/city.js                      城市列表接口
services/scenic.js                    景区、汇合点、服务套餐接口
```

## 4. 关键组件

```text
components/app-nav/app-nav.vue
components/app-tabbar/app-tabbar.vue
components/service-card/service-card.vue
components/cancel-order-sheet/cancel-order-sheet.vue
```

注意：

- `app-nav` 处理微信胶囊避让和返回按钮。
- `app-tabbar` 当前只有“找导游”和“我的”，已经去掉订单 tab。
- `service-card` 承载套餐选择和拼团计数器。
- `cancel-order-sheet` 是取消订单、取消呼叫统一底部弹窗。

## 5. 当前已实现的关键交互

- 首页默认都江堰景区。
- 首页左上角点击进入景区选择。
- 切换景区后首页地图跳转到主汇合点，并且底部三步服务模块恢复默认状态。
- 首页地图使用微信原生 `map`，汇合点站牌用 `customCallout` 绘制。
- 首页服务抽屉支持展开/收起和手势吸附。
- 点击“立即呼叫讲解”后，在抽屉内横向切换到选择汇合点。
- 选择汇合点后，地图跳到对应汇合点。
- 确认订单后模拟支付，进入等待接单页。
- 等待接单页当前 5 秒自动进入待讲解详情页。
- 所有取消订单、取消呼叫确认后统一进入已取消详情页。
- 首页顶部有进行中订单提示卡，当前使用 mock。
- 个人中心“问题反馈”已接入独立页面 `/pages/feedback/index`。
- 设置页“退出登录”已实现，确认后会清理本地登录态并回首页未登录状态。
- 登录页协议提示框、意见反馈页提交按钮、评价页提交按钮已补基础禁用态 / 提交中态。

## 6. 当前 mock 数据位置

```text
constants/services.js          服务套餐和底部 tab 兜底数据
constants/scenics.js           景区列表兜底数据
constants/meeting-points.js    都江堰汇合点兜底数据
services/guide.js              服务套餐 mock 接口
pages/home/index.vue           当前进行中订单提示、下单流程状态
pages/orders/index.vue         订单列表 mock
各 order-* 页面                订单详情 mock
```

已开始接入：

```text
GET /api/cities
GET /api/scenics
GET /api/scenics/{id}/meeting-points
GET /api/scenics/{id}/services
```

后续接口化建议继续新增：

```text
services/auth.js
services/order.js
services/payment.js
services/user.js
services/review.js
services/feedback.js
```

## 7. 视觉和交互约束

- 首页是视觉基准：浅灰背景、白色面板、蓝色主色 `#278bff`、轻阴影。
- 不要照搬低保真原型的灰底按钮和粗糙排版。
- 二级页面尽量统一为：自定义导航、浅灰背景、白色圆角内容卡、轻阴影、底部蓝色主按钮。
- 图标优先使用已有资源：
  - `static/ui-icons`
  - `static/pencil-icons`
- 不要随手用字符图标替代。
- 地图上的内容尽量用 `cover-view` / `cover-image`，不要用普通 `view` 覆盖 `map`。
- 微信小程序 `map` 底图实际是腾讯地图；高德 SDK 当前只用于定位逆地理解析。
- 在实机和开发者工具中地图覆盖层表现可能不同，涉及 `cover-view` 的样式要真机复查。

## 8. 小程序能力注意事项

- 微信小程序网络请求必须配置合法域名。
- `config/api.js` 当前本地为 `http://127.0.0.1:8080`，真机预览要改成电脑局域网 IP 或线上 HTTPS 域名。
- 高德接口域名：`https://restapi.amap.com`
- 定位需要 `scope.userLocation` 和 `requiredPrivateInfos: ["getLocation"]`。
- 开发者工具中部分地图 API 可能不支持，真机预览为准。
- 本地 HBuilder/uni 调试可能出现 websocket 域名校验错误，开发环境可以关 `urlCheck`，发布前必须配置合法域名。

## 9. 编码规则

项目有大量中文内容，所有源码、配置和 Markdown 必须保持 UTF-8 编码。

PowerShell 读写中文时显式指定：

```powershell
Get-Content -Encoding UTF8
Set-Content -Encoding UTF8
Add-Content -Encoding UTF8
```

不要用默认 ANSI/GBK 编码重写文件。

## 10. 后端接入优先建议

第一步先让小程序核心链路跑通：

1. 登录和用户资料。
2. 景区列表、汇合点列表、服务套餐。
3. 订单试算、创建订单。
4. 微信支付和支付回调。
5. 等待接单状态接口。
6. 导游接单后进入待讲解。
7. 订单列表和订单详情。
8. 取消订单和退款。

第二步补齐：

1. 评价提交和查看。
2. 售后。
3. 协议内容。
4. 用户资料修改。
5. 发票。
6. 消息订阅通知。

建议补充顺序：

1. 首页和景区选择页已开始接城市 / 景区 / 汇合点 / 服务套餐接口，继续补真实异常态和 loading 即可。
2. 再接订单试算、创建订单、支付、等待接单状态。
3. 然后替换订单列表和各详情页 mock。
4. 最后接评价提交、意见反馈、资料修改等次级表单。

## 11. 管理后台开发建议

后台建议优先做这些模块：

1. 登录、角色权限。
2. 景区和汇合点管理。
3. 服务套餐和价格管理。
4. 导游档案和审核。
5. 订单管理和订单详情。
6. 派单 / 改派 / 接单日志。
7. 支付流水、退款流水。
8. 评价和售后。
9. 协议内容管理。
10. 操作日志。

管理后台 UI 风格建议走工作台风格：信息密度高、表格筛选清晰、操作可追溯，不要做营销页式大卡片。

## 12. App 端开发建议

如果 App 是游客端：

- 可复用小程序业务链路，但地图、定位、支付、分享、订阅通知都需要 App 平台适配。
- 建议将订单、景区、套餐接口和状态枚举与小程序共用。

如果 App 是导游端：

- 核心是接单、位置上报、导航、开始/结束讲解。
- 位置上报、电量、后台保活、消息推送是关键技术点。
- 导游端需要独立权限和审核流程，不建议直接复用游客账号体系。

## 13. 已知技术债

- 工程仍保留 hello-uniapp 大量示例页面目录，如 `pages/API`、`pages/component`、`pages/extUI`、`pages/template`。`pages.json` 未注册它们，不影响当前小程序，但后续可清理以减小项目体积。
- 当前多数订单详情页是重复样式，后续可抽 `OrderGuideCard`、`OrderSummaryCard`、`OrderDetailRows` 等组件。
- 订单状态枚举前端当前为 camelCase mock，后端建议 snake_case；需要统一转换层。
- 等待接单页当前 5 秒自动跳转只是演示行为，正式必须由后端订单状态驱动。
- 当前已有本地登录态和页面鉴权，但未接真实用户资料接口和 token 生命周期。
- 首页进行中订单提示、订单详情仍以本地 mock 为主；景区、汇合点、服务套餐已改为接口优先、本地 mock 兜底。
- 意见反馈页、评价页只有前端提交成功态，尚未接真实提交接口。