470 lines
11 KiB
Markdown
470 lines
11 KiB
Markdown
# H5 导览/讲解业务闭环回归记录
|
||
|
||
> 日期：2026-07-01
|
||
> 项目：深圳自然博物馆 `frontend-miniapp`
|
||
> 范围：H5 guide / explain 业务闭环
|
||
> 验证来源：Codex 源码审查 + H5 browser smoke + 命令行质量门禁
|
||
> 测试目标：验证三轮修复后，导览位置预览、讲解音频状态、馆内楼层控件交互是否闭环。
|
||
|
||
---
|
||
|
||
## 1. 总体结论
|
||
|
||
本轮 H5 guide / explain 回归结论：**通过，发布前条件通过**。
|
||
|
||
已验证通过的闭环：
|
||
|
||
| 编号 | 闭环 | 结果 | 说明 |
|
||
|---|---|---|---|
|
||
| P1-1 | 讲解 -> guide 位置预览 | 通过 | 人类厅、展品详情均可进入位置预览 |
|
||
| P1/P2-2 | 音频可播放/不可用状态 | 通过 | 大猩猩不再误标音频讲解，播放失败后降级图文讲解 |
|
||
| P2-3 | 馆内楼层控件遮挡/误触 | 通过 | 馆内入口不再自动打开终点选择，楼层按钮可正常点击 |
|
||
| 文案边界 | 不越权宣称真实导航 | 通过 | 仍使用位置预览、位置关系、暂不提供正式室内导航等文案 |
|
||
| 质量门禁 | `pnpm type-check` / `pnpm lint` | 通过 | lint warnings 已清理 |
|
||
|
||
当前仍保留一个非阻塞发布前复测建议：在真实约 390px 宽度移动设备或 WebView 中，再做一次楼层按钮物理点击区 spot check。
|
||
|
||
---
|
||
|
||
## 2. 修复背景
|
||
|
||
Codex H5 用户测试最初发现 3 类问题：
|
||
|
||
### 2.1 P1：讲解到位置预览闭环未闭合
|
||
|
||
现象：
|
||
|
||
- 人类厅“查看展厅位置”未跳转到 guide / route preview。
|
||
- 展品详情“查看位置”未跳转到位置预览。
|
||
- toast：
|
||
- `该展厅暂无三维位置数据`
|
||
- `该讲解暂无所属展厅位置数据`
|
||
|
||
根因：
|
||
|
||
- explain 内容域 `hallId` / `poiId` 与 guide 导览域 POI ID 存在命名空间差异。
|
||
- 页面层尝试直接用 content hall id 查 guide POI，导致运行时找不到位置。
|
||
- static bridge 中已有 `hallId -> nav POI` 映射，但原点击链路没有稳定走 use case / repository 解析。
|
||
|
||
### 2.2 P1/P2：音频可播放标记与真实播放不一致
|
||
|
||
现象：
|
||
|
||
- 人类厅列表中“大猩猩”显示 `22秒 · 音频讲解`。
|
||
- 详情显示音频面板和 `23秒`。
|
||
- 点击后没有真实可播放 audio src。
|
||
- toast：`音频加载失败，当前提供图文讲解。`
|
||
- console：`详情音频不可播放`。
|
||
|
||
根因：
|
||
|
||
- 列表/详情展示层依据 `audioAvailable`、`hasAudio`、duration 等 metadata 判断“可播放”。
|
||
- 播放层需要真实 `playUrl` 或 H5 可加载 URL。
|
||
- 两套 truth source 不一致，导致 UI 宣称可播但实际不可播。
|
||
|
||
### 2.3 P2：馆内楼层控件遮挡/误触
|
||
|
||
现象：
|
||
|
||
- 点击“馆内”后自动打开 route/guide panel。
|
||
- 点击左侧 `B1` 区域打开“选择终点”，而不是切换楼层。
|
||
- 面板收起后仍遮挡 `B1/B2` 区域。
|
||
- 点击 `2F` 后进入多层加载状态，active floor 表达不稳定。
|
||
|
||
根因：
|
||
|
||
- “馆内”入口调用 route planner 打开逻辑。
|
||
- `RoutePlannerPanel` / `RoutePointPicker` z-index 高于 floor switcher，且拦截 touch。
|
||
- floor header sticky 造成点击区域覆盖。
|
||
- multi 模式下 active floor 样式被抑制，用户误以为没有当前楼层。
|
||
|
||
---
|
||
|
||
## 3. 变更范围
|
||
|
||
本轮修复涉及文件如下：
|
||
|
||
```text
|
||
src/usecases/guideUseCase.ts
|
||
src/repositories/GuideRepository.ts
|
||
src/data/adapters/backendExplainDataAdapter.ts
|
||
src/pages/hall/detail.vue
|
||
src/pages/exhibit/detail.vue
|
||
src/view-models/explainViewModels.ts
|
||
src/usecases/explainUseCase.ts
|
||
src/pages/index/index.vue
|
||
src/components/navigation/GuideMapShell.vue
|
||
src/data/providers/backendExplainContentProvider.ts
|
||
```
|
||
|
||
### 3.1 位置预览闭环修复
|
||
|
||
涉及：
|
||
|
||
```text
|
||
src/usecases/guideUseCase.ts
|
||
src/repositories/GuideRepository.ts
|
||
src/data/adapters/backendExplainDataAdapter.ts
|
||
src/pages/hall/detail.vue
|
||
src/pages/exhibit/detail.vue
|
||
```
|
||
|
||
主要变化：
|
||
|
||
- 新增/集中 explain content -> guide preview target 解析逻辑。
|
||
- 页面不再重复做 direct id / name guessing。
|
||
- 解析顺序变为：
|
||
|
||
```text
|
||
direct POI
|
||
-> bridged location.poiId
|
||
-> hall id as hall-like POI
|
||
-> hall name fallback
|
||
-> target name fallback
|
||
-> unavailable toast
|
||
```
|
||
|
||
- SDK mode 中允许 static bridge POI ID 通过 SDK POI name fallback 或 static fallback 转换成可预览目标。
|
||
- 展品详情若无 exhibit POI，可 fallback 到所属展厅位置。
|
||
- 未引入正式导航文案，仍跳转 `route/detail?...&state=preview`。
|
||
|
||
### 3.2 音频状态修复
|
||
|
||
涉及：
|
||
|
||
```text
|
||
src/view-models/explainViewModels.ts
|
||
src/data/adapters/backendExplainDataAdapter.ts
|
||
src/usecases/explainUseCase.ts
|
||
src/pages/exhibit/detail.vue
|
||
```
|
||
|
||
主要变化：
|
||
|
||
- 列表/详情 playable 状态收紧为“存在真实非空 H5 media URL / playUrl”。
|
||
- duration、`audioAvailable`、`hasAudio`、`audioStatus` 不再单独导致“音频讲解”可播放展示。
|
||
- metadata 保留为描述性信息，不再等同播放能力。
|
||
- H5 播放失败后详情页降级为图文讲解 / 音频暂不可用。
|
||
- 未添加 fake / placeholder audio。
|
||
|
||
### 3.3 楼层控件遮挡修复
|
||
|
||
涉及：
|
||
|
||
```text
|
||
src/pages/index/index.vue
|
||
src/components/navigation/GuideMapShell.vue
|
||
```
|
||
|
||
主要变化：
|
||
|
||
- “馆内”入口进入室内 3D 单层预览，不再自动打开 route planner。
|
||
- route planner 显示时隐藏 floor switcher，避免“看得见但点不到”。
|
||
- floor header 从 sticky 改为 relative，避免覆盖楼层按钮。
|
||
- multi 模式 header 显示 `多层`。
|
||
- active floor 样式在 multi/single 状态中保持可见或有明确模式提示。
|
||
|
||
### 3.4 lint 收尾清理
|
||
|
||
涉及：
|
||
|
||
```text
|
||
src/data/providers/backendExplainContentProvider.ts
|
||
```
|
||
|
||
主要变化：
|
||
|
||
- 删除未使用 type imports：
|
||
- `ExplainTrack`
|
||
- `MediaAsset`
|
||
- `MuseumHall`
|
||
- 仅 import 清理，无业务逻辑变更。
|
||
|
||
---
|
||
|
||
## 4. 命令验证
|
||
|
||
### 4.1 TypeScript 类型检查
|
||
|
||
命令：
|
||
|
||
```powershell
|
||
pnpm type-check
|
||
```
|
||
|
||
实际输出摘要：
|
||
|
||
```text
|
||
$ vue-tsc --noEmit
|
||
```
|
||
|
||
结果：通过，exit code `0`。
|
||
|
||
### 4.2 ESLint
|
||
|
||
命令：
|
||
|
||
```powershell
|
||
pnpm lint
|
||
```
|
||
|
||
实际输出摘要：
|
||
|
||
```text
|
||
$ eslint "src/**/*.{ts,vue}"
|
||
```
|
||
|
||
结果：通过，exit code `0`。
|
||
|
||
最终收尾后，之前 `src/data/providers/backendExplainContentProvider.ts` 中 3 个 unused import warnings 已清理。
|
||
|
||
### 4.3 H5 build
|
||
|
||
未运行：
|
||
|
||
```powershell
|
||
pnpm build:h5
|
||
```
|
||
|
||
原因：该命令会写入 `dist`，本轮以源码修复、type-check、lint 和 H5 smoke 为验证基线。
|
||
|
||
---
|
||
|
||
## 5. H5 smoke 验证记录
|
||
|
||
### 5.1 测试环境
|
||
|
||
URL：
|
||
|
||
```text
|
||
http://localhost:5173/#/pages/index/index?tab=guide
|
||
```
|
||
|
||
视口：
|
||
|
||
```text
|
||
请求 viewport：390x844
|
||
实际 browser CSS viewport：728x912，DPR 1
|
||
```
|
||
|
||
说明：Codex in-app browser 的 CSS viewport 与请求值不完全一致，因此发布前仍建议在真实约 390px 宽移动设备或 WebView 上 spot check。
|
||
|
||
---
|
||
|
||
## 6. Guide smoke 结果
|
||
|
||
### 6.1 操作步骤
|
||
|
||
1. 打开 guide tab。
|
||
2. 点击首页“馆内”。
|
||
3. 观察是否自动打开 route planner / 选择终点。
|
||
4. 点击可见楼层控件：
|
||
- `B2`
|
||
- `B1`
|
||
- `1F`
|
||
- `2F`
|
||
|
||
### 6.2 观察结果
|
||
|
||
- 点击“馆内”后未自动打开 route planner。
|
||
- 未出现 `选择终点` 或 `选择起点`。
|
||
- `B2`、`B1`、`1F`、`2F` 均可点击。
|
||
- 点击楼层后对应楼层成为 active floor。
|
||
- 点击楼层未触发 route panel / picker。
|
||
- 未发现室内真实导航越权文案。
|
||
|
||
### 6.3 结论
|
||
|
||
Guide smoke：通过。
|
||
|
||
---
|
||
|
||
## 7. Explain -> Guide 位置预览 smoke 结果
|
||
|
||
### 7.1 人类厅查看展厅位置
|
||
|
||
步骤：
|
||
|
||
```text
|
||
讲解 -> 人类厅 -> 查看展厅位置
|
||
```
|
||
|
||
观察结果：
|
||
|
||
- 页面跳转到：
|
||
|
||
```text
|
||
/pages/route/detail?...&state=preview
|
||
```
|
||
|
||
- 页面标题：
|
||
|
||
```text
|
||
位置预览
|
||
```
|
||
|
||
- 页面内容包含：
|
||
|
||
```text
|
||
位置预览：人类厅
|
||
```
|
||
|
||
结论：通过。
|
||
|
||
### 7.2 大猩猩 / 展品详情查看位置
|
||
|
||
步骤：
|
||
|
||
```text
|
||
讲解 -> 人类厅 -> 大猩猩 -> 查看位置
|
||
```
|
||
|
||
观察结果：
|
||
|
||
- 页面跳转到：
|
||
|
||
```text
|
||
/pages/route/detail?...&state=preview
|
||
```
|
||
|
||
- 因大猩猩展品自身无稳定 exhibit POI，fallback 到所属展厅 preview。
|
||
- 页面内容显示：
|
||
|
||
```text
|
||
位置预览：展厅5人类厅
|
||
```
|
||
|
||
- 未出现正式室内导航承诺。
|
||
|
||
结论：通过。
|
||
|
||
---
|
||
|
||
## 8. Audio smoke 结果
|
||
|
||
### 8.1 列表状态
|
||
|
||
步骤：
|
||
|
||
```text
|
||
讲解 -> 人类厅 -> 查看大猩猩列表项
|
||
```
|
||
|
||
观察结果：
|
||
|
||
- 人类厅列表包含“大猩猩”。
|
||
- 大猩猩显示为：
|
||
|
||
```text
|
||
图文讲解
|
||
```
|
||
|
||
- 人类厅列表中 `音频讲解` count 为 `0`。
|
||
|
||
结论：列表不再误标可播放音频，通过。
|
||
|
||
### 8.2 详情状态与播放失败降级
|
||
|
||
步骤：
|
||
|
||
```text
|
||
讲解 -> 人类厅 -> 大猩猩 -> 点击音频面板
|
||
```
|
||
|
||
观察结果：
|
||
|
||
- 详情初始可解析到 direct URL，因此显示 `23秒` 音频面板。
|
||
- 点击后 H5 播放失败。
|
||
- 页面降级为：
|
||
|
||
```text
|
||
图文讲解
|
||
音频加载失败，当前提供图文讲解。
|
||
```
|
||
|
||
- `23秒` 播放面板消失。
|
||
|
||
结论：播放失败后状态如实降级，通过。
|
||
|
||
---
|
||
|
||
## 9. 室内导航话术审计
|
||
|
||
本轮测试确认，guide / route preview 相关文案仍保持位置预览和 readiness 边界，没有宣称正式室内导航。
|
||
|
||
已观察到的安全文案包括：
|
||
|
||
```text
|
||
位置预览 · 查看位置关系
|
||
当前可查看位置预览和位置关系，暂不提供正式室内导航
|
||
位置关系不可用
|
||
当前不作为正式室内导航
|
||
```
|
||
|
||
说明：室外 Tencent 路线失败等文案不属于室内 certified-navigation 承诺范围。
|
||
|
||
结论：通过。
|
||
|
||
---
|
||
|
||
## 10. 剩余风险与后续建议
|
||
|
||
| 优先级 | 风险 | 状态 | 建议 |
|
||
|---|---|---|---|
|
||
| P1 | 三个已验证闭环出现阻塞回归 | 未发现 | 保持当前回归用例 |
|
||
| P2 | Codex in-app browser 实际 CSS viewport 与请求 390px 不一致 | 存在 | 发布前用真机或标准 Chrome mobile viewport spot check |
|
||
| P2 | SDK/static mixed POI fallback 掩盖后端 ID 规范缺口 | 存在 | 作为数据层迁移债记录，推动 SGS/API 提供稳定 hallId/poiId/floorId 映射 |
|
||
| P3 | preview 页个别文案略别扭 | 存在 | 后续文案 polish，例如 `无法定位，当前仅支持点位位置预览` |
|
||
| P3 | H5 build 未跑 | 有意跳过 | 如进入发布流程，再运行 `pnpm build:h5` |
|
||
|
||
---
|
||
|
||
## 11. 发布前推荐复测清单
|
||
|
||
建议在真实约 390px 宽移动设备或 WebView 中执行：
|
||
|
||
### Guide
|
||
|
||
- 打开首页。
|
||
- 点击 `馆内`。
|
||
- 点击 `B2 / B1 / 1F / 2F`。
|
||
- 确认不会打开 `选择终点`。
|
||
- 确认 active floor 稳定。
|
||
|
||
### Explain -> Guide
|
||
|
||
- `讲解 -> 人类厅 -> 查看展厅位置`。
|
||
- 确认进入 `位置预览：人类厅`。
|
||
|
||
### Exhibit -> Guide
|
||
|
||
- `讲解 -> 人类厅 -> 大猩猩 -> 查看位置`。
|
||
- 确认进入 `位置预览：展厅5人类厅`。
|
||
|
||
### Audio
|
||
|
||
- 人类厅列表查看“大猩猩”。
|
||
- 确认列表不误标 `音频讲解`。
|
||
- 打开详情并点击音频。
|
||
- 如果音频加载失败，确认降级为图文讲解并显示失败提示。
|
||
|
||
---
|
||
|
||
## 12. 最终状态
|
||
|
||
当前本轮 Codex 修复与 H5 smoke 结果可归档为：
|
||
|
||
```text
|
||
H5 guide/explain business-loop regression: PASS
|
||
Release readiness: CONDITIONAL PASS
|
||
Condition: real 390px mobile/WebView floor-control spot check before production release.
|
||
```
|
||
|
||
本轮不改变产品能力边界：
|
||
|
||
```text
|
||
guide = 室内 3D 展示 + POI/位置预览
|
||
explain = 内容/讲解 + 真实媒体可用时音频播放
|
||
route = route graph/nav data 未验证前保持位置关系/位置预览，不作为正式室内导航
|
||
```
|