frontend-miniapp/docs/QA/codex-user-testing-agents-guide-2026-06-30.md

# Codex 用户测试操作指南：Lead + 专家团覆盖导览/讲解业务闭环

> 日期：2026-06-30  
> 项目：深圳自然博物馆 `frontend-miniapp`  
> 适用对象：Codex / GPT-5.4 类 coding agent  
> 默认目标：H5 用户测试与业务逻辑闭环验证  
> 推荐模式：Lead Agent + 专家团协作

---

## 1. 目标与边界

本指南用于让 Codex 以专业 agents 团队方式，为本项目执行用户测试设计、测试示例编写、H5 smoke 验证和风险汇总。

测试目标不是“证明系统已经具备真实室内导航”，而是验证当前产品能力是否闭环：

```text
导览 guide：室内 3D 展示 + 楼层切换 + POI/位置预览
讲解 explain：内容/讲解入口 + 音频状态 + 查看位置联动
```

### 1.1 必须遵守的产品真相

Codex 执行测试时必须遵守以下边界：

1. 默认只测 H5，不测 `mp-weixin`，除非用户明确要求。
2. 当前导览能力是“室内 3D 展示 + POI/位置预览”。
3. `route_graph` / `nav_data` 未验证前，不能把功能描述为“开始馆内导航”“路线导航”“到达引导”或 turn-by-turn。
4. 路线相关测试应验证 unavailable / disabled / readiness gate，而不是强行证明路线可用。
5. 讲解能力必须依赖真实内容/媒体数据；不能把 `example.com/audio.mp3` 或 placeholder 当作可用音频。
6. 页面、组件和测试应消费 domain / repository / use case 数据，不应绕过数据层直接解析静态包或后端字段。
7. 不引入 legacy nav assets service。
8. 不做无关重构、不删除旧 demo 数据、不清理历史文件，除非用户另行授权。

### 1.2 推荐测试层级

Codex 应按轻到重执行：

```text
源码审查
  -> 纯业务/adapter 单元测试示例
  -> repository/usecase 闭环测试示例
  -> H5 smoke 用户流测试
  -> 风险报告与修复建议
```

如果项目暂未引入测试框架，Codex 应先给方案或最小 Vitest 示例，不应直接引入重型 E2E 框架。

---

## 2. Lead + 专家团角色分工

### 2.1 Lead Agent：测试总负责人

职责：

- 读取任务目标和项目边界。
- 分配专家 Agent 的测试范围。
- 汇总每个专家的发现。
- 去重、排序、判定阻塞级别。
- 形成最终测试矩阵、执行结果和修复建议。

Lead Agent 不应直接跳过专家结论，也不应把假设当事实。

### 2.2 Guide Agent：导览闭环专家

关注范围：

- 首页导览入口。
- 馆外/馆内切换。
- 室内 3D 初始状态。
- 全馆/多层/单层切换。
- 楼层切换。
- POI 展示、点击、选中、聚焦。
- 位置预览卡片。
- route readiness 和不可导航状态。

重点文件：

```text
src/pages/index/index.vue
src/components/navigation/GuideMapShell.vue
src/components/map/ThreeMap.vue
src/domain/guideFloor.ts
src/domain/guideReadiness.ts
src/domain/guideModel.ts
src/usecases/guideUseCase.ts
```

### 2.3 Explain Agent：讲解闭环专家

关注范围：

- 讲解 tab 入口。
- 讲解列表加载。
- 展厅/展品/讲解项详情。
- 音频播放、暂停、关闭、错误态。
- 缺失音频 unavailable 状态。
- 讲解项“查看位置”跳回 guide location preview。
- guide/explain tab 状态保持。

重点文件：

```text
src/components/explain
src/components/audio
src/pages/index/index.vue
src/pages/exhibit
src/pages/hall
src/repositories
src/usecases
```

### 2.4 Data Agent：数据契约与 readiness 专家

关注范围：

- Provider / Adapter / Repository / UseCase 数据边界。
- static/api/sdk 模式切换。
- SGS 坐标归一化。
- 楼层 ID、label、order、floorCode 一致性。
- POI floorId 绑定。
- 展厅/space/poi/guide stop 关系。
- route graph / nav data readiness gate。

重点文件：

```text
src/config/dataSource.ts
src/data/providers
src/data/adapters
src/repositories/GuideRepository.ts
src/repositories/GuideModelRepository.ts
src/domain/museum.ts
src/domain/guideModel.ts
```

### 2.5 UX Agent：移动端用户流与遮挡专家

关注范围：

- 手机 viewport 下顶部/底部/楼层控件是否可点击。
- 3D canvas 是否遮挡 search、floor switcher、POI card、tab、audio player。
- 返回、关闭、取消、重试是否形成闭环。
- 搜索、定位、讲解、查看位置之间是否有死路。
- 加载/错误/空状态是否可理解。

### 2.6 QA Agent：测试矩阵与执行记录专家

职责：

- 把 Guide / Explain / Data / UX 结论转换成测试矩阵。
- 明确每条测试：前置条件、操作步骤、期望结果、证据类型。
- 区分源码审核、单元测试、H5 smoke、人工复核。
- 记录命令输出。

### 2.7 Risk Agent：风险与反误导专家

职责：

- 检查是否误称真实导航。
- 检查是否使用 placeholder 音频。
- 检查是否混用 legacy demo 数据。
- 检查是否绕过数据层。
- 检查是否把 SDK/API/static 数据混在一起。
- 检查是否做了无关重构或破坏 H5 边界。

---

## 3. 导览 guide 用户测试闭环

### 3.1 导览入口闭环

测试目标：用户从首页进入馆内导览后，能理解当前状态。

检查点：

1. 首页是否展示 `馆内` 入口。
2. 点击后是否进入 guide 业务而不是 explain。
3. 初始状态是否清楚表达是馆外、全馆、单层还是多层。
4. 如果进入室内 3D，是否有加载状态。
5. 模型加载失败是否有错误和重试。

预期结果：

```text
用户能进入馆内 3D/位置预览体验，且不会看到“已开始导航”等误导文案。
```

### 3.2 楼层切换闭环

测试目标：楼层切换后模型、POI 和 UI 楼层状态一致。

检查点：

1. 楼层列表只展示室内可导览楼层。
2. 楼层顺序符合 B2/B1/1F/2F/3F 等语义。
3. 点击某一楼层后，UI 显示 loading 或状态变化。
4. 模型切换到目标楼层。
5. POI 只展示目标楼层点位。
6. 切换失败时保留旧状态或给出明确错误。
7. 父组件 active floor 与 ThreeMap rendered floor 不应长期不一致。

建议测试示例：

```text
Given 当前在 1F
When 点击 2F
Then 楼层按钮高亮 2F
And ThreeMap 渲染 2F 模型
And POI 列表只包含 floorId=2F/L2 对应点位
And 不出现 B1/1F POI
```

### 3.3 POI 展示与位置预览闭环

测试目标：用户点击 POI 后能看懂“这是什么、在哪层、如何查看位置”。

检查点：

1. POI 有稳定 id、name、category、floorId。
2. POI 坐标可用于渲染。
3. SGS 模式下 `position.y` 不应误作单层 marker 高度。
4. 点击 POI 后弹出卡片。
5. 卡片展示名称、楼层、类型或展厅信息。
6. 展厅类 POI 可进入“查看展厅”或“相关讲解”。
7. 位置预览不应宣称真实导航。

建议测试示例：

```text
Given 当前楼层有展厅 POI
When 点击该 POI
Then POI card 展示展厅名和所在楼层
And 相机聚焦到该 POI
And 文案使用“查看位置/查看展厅/相关讲解”
And 不出现“开始导航/到达引导”
```

### 3.4 route readiness 闭环

测试目标：没有 route graph/nav data 时，路线能力被正确阻断。

检查点：

1. `NAV_ROUTE_GRAPH_READY` 为 false 时，不应展示已可用导航。
2. route panel 或按钮应显示未开放、位置预览、不可用等状态。
3. 测试中不能断言路线规划成功。
4. 如 SDK/API 返回路线失败，应有错误处理。

---

## 4. 讲解 explain 用户测试闭环

### 4.1 讲解入口闭环

测试目标：用户能从首页进入讲解业务，且不会污染导览状态。

检查点：

1. 顶部或首页入口使用 `讲解`。
2. 点击后加载讲解列表。
3. 返回 `馆内` 时，导览基本状态不异常丢失。
4. 讲解列表空状态或加载失败有提示。

### 4.2 讲解内容与音频状态闭环

测试目标：讲解项的内容、音频和 unavailable 状态可信。

检查点：

1. 讲解项有稳定 id、标题、所属展厅/展品。
2. 音频 URL 来自真实媒体数据。
3. 缺失音频时显示 unavailable，不自动使用 placeholder。
4. 播放、暂停、关闭不泄漏状态。
5. 页面返回后 player 状态符合产品预期。

### 4.3 讲解查看位置闭环

测试目标：用户从讲解项能回到对应导览位置预览。

检查点：

1. 讲解项具备 `poiId`、`floorId`、`hallId` 或 `exhibitId` 中至少一种可解析关系。
2. 点击“查看位置”后切回 guide。
3. guide 切到目标楼层。
4. 目标 POI 被聚焦或显示 preview card。
5. 如缺少位置关系，应提示无法定位，不应假装成功。

建议测试示例：

```text
Given 一个讲解项绑定 poiId 和 floorId
When 点击“查看位置”
Then 当前 tab 切换到馆内
And active floor 等于讲解项 floorId
And target focus 指向对应 poiId
And 显示位置预览卡片
```

---

## 5. 数据与状态核对规则

### 5.1 楼层数据

必须核对：

- `floorId` 是否稳定。
- `label` 是否仅用于显示。
- `order/ordinal` 是否用于排序。
- 外立面、馆外、建筑外观是否被过滤。
- API / static / SDK 模式下楼层语义是否一致。

### 5.2 POI 数据

必须核对：

- POI 必须有 `id`、`name`、`floorId`、`category`。
- 渲染 POI 必须有可用 display coordinate。
- 缺坐标 POI 不应进入 3D marker 渲染。
- 展厅 space center 不应直接等同 route destination。
- route destination 应未来使用 entrance / route node。

### 5.3 SGS 坐标归一化

SGS 坐标进入 ThreeMap 前必须明确：

```text
source.x -> render x
source.z -> render z
source.y -> 原始高度/绝对高程，不直接作为单层 marker y
```

测试断言建议：

```text
Given SGS position = { x: 10, y: 99, z: 20 }
When 转换成 ThreeMap render POI
Then render position 应使用水平坐标 10/20
And marker 高度不应等于 99
```

### 5.4 route readiness

必须核对：

- route graph/nav data 未 ready 时，route planning 不应被视为通过。
- 所有测试报告中应使用“位置预览”或“路线未开放”。
- 不把 SDK mode 当作真实导航 ready 的证据。

---

## 6. H5 smoke 用户测试建议

当 Codex 需要执行浏览器级 H5 smoke 时，按以下顺序：

1. 启动 H5 dev server：

```powershell
pnpm dev:h5
```

2. 在移动 viewport 打开本地 URL。
3. 执行以下用户流：

### 6.1 导览 smoke

- 打开首页。
- 点击 `馆内`。
- 等待 3D 加载。
- 切换全馆/单层/多层。
- 点击 1F、2F、B1 等楼层。
- 点击一个 POI。
- 检查卡片是否出现。
- 检查楼层控件、搜索、卡片、底部导航是否仍可点击。

### 6.2 讲解 smoke

- 点击 `讲解`。
- 查看讲解列表。
- 点击讲解项。
- 尝试播放音频。
- 如无音频，检查 unavailable 状态。
- 点击“查看位置”。
- 检查是否回到馆内并显示目标位置预览。

### 6.3 异常 smoke

- 模拟模型加载失败。
- 模拟 POI 空列表。
- 模拟音频缺失。
- 模拟 route unavailable。
- 检查是否有重试、返回、关闭或明确提示。

---

## 7. 验收标准

### 7.1 通过标准

一次 Codex 测试任务可判定为通过，必须满足：

1. 明确列出测试范围。
2. 明确说明 guide 只是位置预览，不是认证导航。
3. 至少覆盖 guide 楼层切换和 POI 点击闭环。
4. 至少覆盖 explain 查看位置或音频 unavailable 闭环。
5. 输出测试矩阵。
6. 输出命令结果或说明为何未执行。
7. 标记 source-only、unit、H5 smoke、manual 的证据类型。
8. 不做无关重构。

### 7.2 阻塞问题

以下问题应标为 P1：

- 切换楼层后模型和 POI 楼层不一致。
- 点击 POI 后卡片展示错误楼层或错误对象。
- route 未 ready 但 UI 宣称可导航。
- 讲解项缺真实音频却显示可播放。
- 点击“查看位置”后进入死路或白屏。
- 3D canvas 遮挡关键控件。

### 7.3 P2 问题

- 楼层 label 不清晰。
- POI 分类图标不一致。
- 搜索结果没有按楼层表达。
- 讲解返回后状态丢失。
- 错误提示不够明确。

### 7.4 P3 问题

- 视觉 polish。
- 动效不顺。
- 非核心文案优化。
- 后续 E2E 覆盖建议。

---

## 8. 可直接复制给 Codex 的 XML Prompt

> 使用方式：将以下 prompt 复制给 Codex。若希望 Codex 只出方案不改代码，将 `<write_policy>` 改为 `read_only`。若希望 Codex 落地最小测试示例，将 `<write_policy>` 改为 `minimal_test_examples`。

```xml
<task>
You are operating in the Shenzhen Natural Museum frontend-miniapp repository:
E:\MyWork\深圳国际艺术馆\museum-guide\museum-guide-v4.0\frontend-miniapp

Create a professional user-testing operation plan and, if allowed by write_policy, minimal test examples for closing the guide/explain business logic loops.
Use a Lead Agent + specialist agents mental model. Do not spawn real external agents unless the runtime supports it; simulate the team by producing separate role findings.
</task>

<write_policy>
read_only
</write_policy>

<product_truth>
- Target platform is H5 only. Do not test mp-weixin unless explicitly requested.
- The guide business currently supports indoor 3D display plus POI/location preview.
- Do not claim certified indoor navigation, turn-by-turn guidance, arrival guidance, or route planning unless route_graph/nav_data and runtime behavior are verified.
- Route-related UI should be tested as route readiness / unavailable / location preview.
- The explain business is content/audio explanation only when real media exists.
- Missing audio/transcript must show unavailable state. Do not treat example.com or placeholder media as working capability.
- Keep data and presentation decoupled: Provider -> Adapter -> Repository -> UseCase -> ViewModel/Component.
- Do not reintroduce retired legacy nav assets service.
- Do not delete historical demo data or perform broad cleanup.
</product_truth>

<agent_team>
<lead_agent>
Own scope, sequencing, final synthesis, risk ranking, and the final test matrix.
</lead_agent>

<guide_agent>
Inspect guide entry, indoor/outdoor switch, full-building/multi-floor/single-floor switching, floor state, POI display, POI click, target focus, location preview card, and route readiness gates.
Primary files:
- src/pages/index/index.vue
- src/components/navigation/GuideMapShell.vue
- src/components/map/ThreeMap.vue
- src/domain/guideFloor.ts
- src/domain/guideReadiness.ts
- src/domain/guideModel.ts
- src/usecases/guideUseCase.ts
</guide_agent>

<explain_agent>
Inspect explain tab/list/detail, audio play/unavailable state, guide-location linkage, top-tab preservation, and missing media behavior.
Primary files:
- src/components/explain
- src/components/audio
- src/pages/index/index.vue
- src/pages/exhibit
- src/pages/hall
- src/repositories
- src/usecases
</explain_agent>

<data_agent>
Inspect provider/adapter/repository/usecase contracts, data-source mode handling, SGS coordinate normalization, floorId/label/order consistency, POI floor binding, and route readiness.
Primary files:
- src/config/dataSource.ts
- src/data/providers
- src/data/adapters
- src/repositories/GuideRepository.ts
- src/repositories/GuideModelRepository.ts
- src/domain/museum.ts
- src/domain/guideModel.ts
</data_agent>

<ux_agent>
Inspect mobile H5 user flows, canvas/overlay hit areas, loading/error/empty states, return/close/cancel/retry paths, and dead-end risks.
</ux_agent>

<qa_agent>
Convert findings into a test matrix with preconditions, steps, expected result, evidence type, and priority.
</qa_agent>

<risk_agent>
Check for false navigation claims, placeholder audio, legacy demo pollution, direct raw-data coupling, static/api/sdk mixing, and unrelated refactors.
</risk_agent>
</agent_team>

<required_test_loops>
<guide_loop>
- Home -> guide/馆内 entry.
- Indoor 3D loading state.
- Overview/multi-floor/single-floor switching.
- Floor switch: requested floor, rendered model, active UI floor, loaded POIs.
- POI click -> focus -> preview card.
- Route graph not ready -> location preview/unavailable, not real navigation.
</guide_loop>

<explain_loop>
- Home -> explain/讲解 entry.
- Explain list load/empty/error.
- Explain item detail.
- Audio play/pause/close or unavailable if missing real media.
- Explain item 查看位置 -> guide tab -> target floor -> target POI/location preview.
- Back/top-tab state preservation.
</explain_loop>

<data_loop>
- Floor filtering and sorting.
- POI floor binding.
- SGS position normalization: source x/z become horizontal render coordinates; source y must not be misused as single-floor marker height.
- Missing position POIs do not enter render marker set.
- Route readiness stays false unless graph/nav data are loaded and verified.
</data_loop>
</required_test_loops>

<execution_plan>
1. Inspect package.json and identify available scripts.
2. Inspect the primary files listed by each specialist agent.
3. Build a source-based test matrix first.
4. If write_policy is minimal_test_examples, add the smallest test framework or test scripts needed, preferably Vitest, without breaking H5 build.
5. Prefer domain/adapter/repository/usecase tests before component or E2E tests.
6. If H5 smoke is requested and feasible, run pnpm dev:h5 and browser-test mobile viewport flows.
7. Run the smallest meaningful verification commands available, such as pnpm type-check and pnpm lint. Do not run build:h5 unless explicitly approved because it writes dist.
</execution_plan>

<action_safety>
- Keep changes narrow.
- Do not perform broad refactors.
- Do not delete files.
- Do not modify unrelated UI styling.
- Do not install dependencies unless the plan explains why and the user allowed write-capable execution.
- If a test requires browser automation that is unavailable, mark it manual/H5-smoke-pending rather than inventing results.
</action_safety>

<grounding_rules>
- Every finding must cite file path and line number when source-based.
- Every browser finding must include the tested URL, viewport, steps, and observed result.
- Distinguish confirmed behavior from hypothesis.
- If data is missing, say data insufficient instead of guessing.
</grounding_rules>

<structured_output_contract>
Return in this order:
1. Codex setup assumptions and scripts discovered.
2. Agent-by-agent findings.
3. Business-loop test matrix.
4. Recommended minimal automated tests.
5. H5 smoke/manual test script.
6. P1/P2/P3 risks.
7. Commands run and exact results.
8. Files changed, or state "no files changed".
9. Follow-up recommendations.
</structured_output_contract>

<completion_criteria>
The task is complete only when:
- Guide loop and explain loop are both covered.
- Route readiness is not misrepresented as real navigation.
- Audio placeholder risk is checked.
- Floor/POI/SGS coordinate risks are checked.
- Output includes an actionable test matrix.
</completion_criteria>
```

---

## 9. 推荐 Codex 分阶段执行命令

### 9.1 只做方案，不改代码

```text
Use the XML prompt in docs/QA/codex-user-testing-agents-guide-2026-06-30.md with write_policy=read_only. Produce a professional Lead+specialist-agents user-testing operation plan for the guide/explain H5 business loops. Do not modify files.
```

### 9.2 落地最小测试示例

```text
Use the XML prompt in docs/QA/codex-user-testing-agents-guide-2026-06-30.md with write_policy=minimal_test_examples. Add the smallest unit-test examples needed to cover guideFloor, route readiness, SGS coordinate normalization, POI floor binding, and explain 查看位置/unavailable audio behavior. Keep changes narrow and run pnpm type-check and pnpm lint.
```

### 9.3 做 H5 smoke 测试

```text
Use the XML prompt in docs/QA/codex-user-testing-agents-guide-2026-06-30.md with write_policy=read_only. Start or use the H5 dev server if available, test mobile viewport guide/explain loops, and return a browser-observed test report. Do not change code.
```