# H5 第三方导航改造测试报告

- 日期：2026-07-13
- 范围：H5“来馆 -> 第三方导航”百度/高德原生 Scheme 调起
- 目的地：深圳自然博物馆
- 坐标：GCJ-02 `22.692763, 114.363572`，直接复用 `MUSEUM_LOCATION`

## 实施结果

1. `navigateToMuseum` 与页面现有调用接口保持不变。
2. 点击“第三方导航”后调用 `uni.showActionSheet`，选项精确为“百度地图”“高德地图”。
3. 百度使用 `baidumap://`；高德按平台使用 iOS `iosamap://`、Android `androidamap://`。
4. 百度 URL 显式携带 `coord_type=gcj02`；高德 URL 使用 `dev=0` 表示已偏移的 GCJ-02 坐标。
5. 中文目的地名称经过 URL 编码。
6. 用户取消选择时静默返回 `false`，不显示错误提示。
7. 未使用 `uni.openLocation`，未接入腾讯路线规划插件，未使用或新增腾讯位置服务 Key，未增加中转页面，未修改 `index.vue` 或宿主小程序代码。
8. 宿主小程序原有 `openWechatHostLocation` 分支未改动。

## TDD 证据

RED 阶段按行为逐项确认失败：

- 百度 URL 测试：`buildBaiduNavigationUrl is not a function`。
- iOS 高德 URL 测试：`buildAmapNavigationUrl is not a function`。
- Android 高德 URL 测试：返回空字符串，不匹配 `androidamap://route?`。
- Action Sheet 测试：旧实现调用 `uni.openLocation`，失败为 `uni.openLocation is not a function`。
- 百度标准目的地编码测试：旧 URL 未把 `latlng:...|name:...` 合并编码到 `destination` 参数。

GREEN 阶段：

```powershell
pnpm exec vitest run tests/unit/MapNavigationService.spec.ts
```

结果：`1 file / 7 tests passed`。覆盖百度 GCJ-02、iOS/Android 高德 Scheme、中文目的地编码、百度选择跳转、iPhone 高德选择跳转、取消静默返回。

## 已自动验证

| 验证项 | 命令或方式 | 结果 |
| --- | --- | --- |
| 导航服务与页面接线单测 | `pnpm exec vitest run tests/unit/MapNavigationService.spec.ts tests/unit/ArrivalPanel.spec.ts` | 通过，`2 files / 9 tests` |
| 全量单元测试 | `pnpm test:unit` | 通过，`14 files / 81 tests` |
| TypeScript 检查 | `pnpm type-check` | 通过，退出码 0，零错误 |
| ESLint | `pnpm lint` | 通过，0 errors；1 个既有无关 warning：`src/pages/explain/list.vue:72` 的 `explainBusinessUnitItems` 未使用 |
| H5 生产构建 | `pnpm build:h5` | 通过，`DONE Build complete`，静态资源复制成功 |
| 浏览器交互 | 生产构建静态服务 `http://127.0.0.1:4173/` | 真实点击“来馆 -> 第三方导航”后显示“百度地图”“高德地图” |
| 旧选择层清理 | 浏览器 DOM 检查 | `.provider-sheet` 数量为 0 |
| 取消行为 | Vitest | 返回 `false` 且未调用 `showToast` |

构建存在既有 HarmonyOS 字体解析提示和 Sass deprecation warnings，均非错误。浏览器静态服务缺少 API 代理，出现既有 SGS 404 和腾讯地图鉴权日志，但“来馆”按钮与 Action Sheet 正常，不影响本次验证。

桌面浏览器仅验证选择框，没有选择原生 Scheme，避免在没有地图 App 的环境中把调起结果误判为真机结果。

## 需要宿主小程序真机验证

以下项目必须在承载 H5 的宿主小程序 web-view 中验证。每次测试先进入“来馆”，点击“第三方导航”，确认只显示百度和高德两项。

| 设备 | 地图 App 状态 | 操作 | 期望结果 |
| --- | --- | --- | --- |
| Android | 已安装百度地图 | 选择“百度地图” | 通过 `baidumap://` 打开百度地图，目的地为深圳自然博物馆，坐标落点为 `22.692763,114.363572` |
| Android | 未安装百度地图 | 选择“百度地图” | 系统/宿主提示无法打开或停留在 H5；返回后页面可继续操作，不应白屏或卡死 |
| Android | 已安装高德地图 | 选择“高德地图” | 通过 `androidamap://` 打开高德地图，显示到深圳自然博物馆的驾车路线 |
| Android | 未安装高德地图 | 选择“高德地图” | 系统/宿主提示无法打开或停留在 H5；返回后可改选百度地图 |
| iPhone | 已安装百度地图 | 选择“百度地图” | 通过 `baidumap://` 打开百度地图，目的地名称和 GCJ-02 落点正确 |
| iPhone | 未安装百度地图 | 选择“百度地图” | iOS/宿主提示无法打开或停留在 H5；返回后页面状态正常 |
| iPhone | 已安装高德地图 | 选择“高德地图” | 通过 `iosamap://` 打开高德地图，显示到深圳自然博物馆的驾车路线 |
| iPhone | 未安装高德地图 | 选择“高德地图” | iOS/宿主提示无法打开或停留在 H5；返回后可改选百度地图 |

每个平台还需补充验证：

1. 在 Action Sheet 上直接取消，页面无 toast、无跳转、可再次点击。
2. 从地图 App 返回宿主小程序后，H5 页面没有重载异常，来馆面板仍可操作。
3. 宿主 web-view 安全策略允许对应自定义 Scheme；若被宿主拦截，应记录手机系统、宿主版本、微信版本和拦截表现。
4. 目的地名称显示为“深圳自然博物馆”，地图落点与现有 GCJ-02 坐标一致，没有发生二次坐标转换偏移。

未安装 App 时的具体系统提示由 Android/iOS、微信和宿主 web-view 决定。本次批准范围不包含 App 安装检测、应用商店回退或中转页，因此真机验收以“页面不白屏、不锁死、返回后可重试”为最低通过条件。

## 最终修改文件

- `src/services/MapNavigationService.ts`
- `tests/unit/MapNavigationService.spec.ts`
- `src/components/navigation/ArrivalPanel.vue`
- `tests/unit/ArrivalPanel.spec.ts`
- `doc/test-reports/h5-third-party-navigation-2026-07-13.md`