chore: sync latest project updates

2026-07-03 14:42:38 +08:00
parent 8b2c36677e
commit 8fed715235
106 changed files with 6030 additions and 121 deletions
--- a/docs/QA/h5-guide-explain-regression-2026-07-01.md
+++ b/docs/QA/h5-guide-explain-regression-2026-07-01.md
@@ -0,0 +1,469 @@
+# 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 未验证前保持位置关系/位置预览，不作为正式室内导航
+```