frontend-miniapp/docs/QA/h5-guide-explain-regression-2026-07-01.md

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. 变更范围

本轮修复涉及文件如下：

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 位置预览闭环修复

涉及：

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。
• 解析顺序变为：

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 音频状态修复

涉及：

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 楼层控件遮挡修复

涉及：

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 收尾清理

涉及：

src/data/providers/backendExplainContentProvider.ts

主要变化：

• 删除未使用 type imports：
  • ExplainTrack
  • MediaAsset
  • MuseumHall
• 仅 import 清理，无业务逻辑变更。

---

4. 命令验证

4.1 TypeScript 类型检查

命令：

pnpm type-check

实际输出摘要：

$ vue-tsc --noEmit

结果：通过，exit code 0。

4.2 ESLint

命令：

pnpm lint

实际输出摘要：

$ eslint "src/**/*.{ts,vue}"

结果：通过，exit code 0。

最终收尾后，之前 src/data/providers/backendExplainContentProvider.ts 中 3 个 unused import warnings 已清理。

4.3 H5 build

未运行：

pnpm build:h5

原因：该命令会写入 dist，本轮以源码修复、type-check、lint 和 H5 smoke 为验证基线。

---

5. H5 smoke 验证记录

5.1 测试环境

URL：

http://localhost:5173/#/pages/index/index?tab=guide

视口：

请求 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 人类厅查看展厅位置

步骤：

讲解 -> 人类厅 -> 查看展厅位置

观察结果：

• 页面跳转到：

/pages/route/detail?...&state=preview

• 页面标题：

位置预览

• 页面内容包含：

位置预览：人类厅

结论：通过。

7.2 大猩猩 / 展品详情查看位置

步骤：

讲解 -> 人类厅 -> 大猩猩 -> 查看位置

观察结果：

• 页面跳转到：

/pages/route/detail?...&state=preview

• 因大猩猩展品自身无稳定 exhibit POI，fallback 到所属展厅 preview。
• 页面内容显示：

位置预览：展厅5人类厅

• 未出现正式室内导航承诺。

结论：通过。

---

8. Audio smoke 结果

8.1 列表状态

步骤：

讲解 -> 人类厅 -> 查看大猩猩列表项

观察结果：

• 人类厅列表包含“大猩猩”。
• 大猩猩显示为：

图文讲解

• 人类厅列表中 音频讲解 count 为 0。

结论：列表不再误标可播放音频，通过。

8.2 详情状态与播放失败降级

步骤：

讲解 -> 人类厅 -> 大猩猩 -> 点击音频面板

观察结果：

• 详情初始可解析到 direct URL，因此显示 23秒 音频面板。
• 点击后 H5 播放失败。
• 页面降级为：

图文讲解
音频加载失败，当前提供图文讲解。

• 23秒 播放面板消失。

结论：播放失败后状态如实降级，通过。

---

9. 室内导航话术审计

本轮测试确认，guide / route preview 相关文案仍保持位置预览和 readiness 边界，没有宣称正式室内导航。

已观察到的安全文案包括：

位置预览 · 查看位置关系
当前可查看位置预览和位置关系，暂不提供正式室内导航
位置关系不可用
当前不作为正式室内导航

说明：室外 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 结果可归档为：

H5 guide/explain business-loop regression: PASS
Release readiness: CONDITIONAL PASS
Condition: real 390px mobile/WebView floor-control spot check before production release.

本轮不改变产品能力边界：

guide = 室内 3D 展示 + POI/位置预览
explain = 内容/讲解 + 真实媒体可用时音频播放
route = route graph/nav data 未验证前保持位置关系/位置预览，不作为正式室内导航