# 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 未验证前保持位置关系/位置预览，不作为正式室内导航
```