改造 H5 第三方地图导航

doc/test-reports/h5-third-party-navigation-2026-07-13.md

@@ -0,0 +1,85 @@
+# 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`
+