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 验证和风险汇总。

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

导览 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 应按轻到重执行：

源码审查
  -> 纯业务/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 和不可导航状态。

重点文件：

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 状态保持。

重点文件：

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。

重点文件：

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. 模型加载失败是否有错误和重试。

预期结果：

用户能进入馆内 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 不应长期不一致。

建议测试示例：

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. 位置预览不应宣称真实导航。

建议测试示例：

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. 如缺少位置关系，应提示无法定位，不应假装成功。

建议测试示例：

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 前必须明确：

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

测试断言建议：

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：

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。

<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 只做方案，不改代码

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 落地最小测试示例

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 测试

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.