chore: initialize frontend miniapp repository

2026-06-09 21:08:45 +08:00
commit a90f63cef0
107 changed files with 60454 additions and 0 deletions
--- a/docs/QA/user-flow-map-2026-06-09.md
+++ b/docs/QA/user-flow-map-2026-06-09.md
@@ -0,0 +1,146 @@
+# 用户使用流程图
+
+日期：2026-06-09  
+范围：导览、讲解、搜索、详情、路线导航
+
+## 当前用户流（含断点）
+
+```mermaid
+flowchart TD
+  A["用户打开小程序/H5"] --> B["首页"]
+  B --> C{"选择一级内容"}
+
+  C -->|"导览"| D["导览页地图"]
+  D --> E{"地图模式"}
+  E -->|"室外"| F["TencentMap 室外地图"]
+  E -->|"室内 3D"| G["室内静态设计图"]
+
+  F --> H["点击 marker"]
+  H --> H1["组件内部直接跳详情"]
+  H --> H2["首页预期打开 POI 操作卡片"]
+  H2 -. "事件未接通" .-> X1["断点：无法稳定选择详情/导航/讲解"]
+
+  G -. "未接 ThreeMap/POI/路径" .-> X2["断点：室内导航只是展示图"]
+
+  D --> I["点击搜索"]
+  I --> J["搜索页"]
+  J --> J1["固定设施列表"]
+  J1 -. "关键词未驱动综合搜索" .-> X3["断点：搜索结果与用户意图不一致"]
+  J1 --> K["设施详情"]
+  K --> K1["选择起点"]
+  K1 -. "只 toast" .-> X4["断点：起点没有写入路线"]
+  K --> L["开始导航"]
+  L --> M["路线详情"]
+  M --> M1["固定目标/本地 navigationState"]
+  M1 -. "无真实路径/定位/到达判定" .-> X5["断点：导航无法完成"]
+
+  C -->|"讲解"| N["首页讲解 Tab"]
+  N --> O["讲解列表"]
+  O --> P{"用户操作"}
+  P -->|"搜索/筛选"| P1["本地 mock 列表"]
+  P1 -. "筛选未形成真实分组" .-> X6["断点：讲解发现路径不稳定"]
+  P -->|"点击展品"| Q["展品详情"]
+  Q --> Q1["默认硬编码展品"]
+  Q1 -. "路由 ID 未加载真实数据" .-> X7["断点：详情不是刚点击的对象"]
+  P -->|"播放音频"| R["底部播放器"]
+  R --> R1["audioUrl 为空时使用 example.com"]
+  R1 -. "无真实音频/无不可用状态" .-> X8["断点：讲解播放无法验收"]
+
+  Q --> S["详情页导航"]
+  S -. "navigateBack" .-> X9["断点：详情无法发起路线"]
+```
+
+## 目标闭环用户流
+
+```mermaid
+flowchart TD
+  A["用户打开小程序/H5"] --> B["首页"]
+  B --> C{"用户目标"}
+
+  C -->|"我要找位置/设施"| D["导览"]
+  D --> D1{"选择地图层"}
+  D1 -->|"室外"| D2["TencentMap 室外地图"]
+  D1 -->|"室内"| D3["ThreeMap 或真实室内平面图"]
+  D2 --> E["点击 POI"]
+  D3 --> E
+  E --> F["POI 操作卡片"]
+  F -->|"看详情"| G["对应详情页"]
+  F -->|"到这里"| H["选择起点"]
+  F -->|"听讲解"| I["打开对应讲解音频"]
+
+  C -->|"我要搜索"| J["搜索页"]
+  J --> J1["输入关键词"]
+  J1 --> J2["综合搜索：展品/展厅/设施"]
+  J2 --> J3{"选择结果类型"}
+  J3 -->|"展品"| G1["展品详情"]
+  J3 -->|"展厅"| G2["展厅详情"]
+  J3 -->|"设施"| G3["设施详情"]
+  G1 --> G
+  G2 --> G
+  G3 --> G
+
+  C -->|"我要听讲解"| K["讲解"]
+  K --> K1["按展厅/主题分组"]
+  K1 --> K2["选择展品"]
+  K2 --> K3{"音频是否可用"}
+  K3 -->|"可用"| I
+  K3 -->|"不可用"| K4["显示暂无讲解"]
+  I --> I1["播放/暂停/进度/结束"]
+  I1 --> I2["回到展品详情或讲解列表"]
+
+  G --> G4{"详情页主操作"}
+  G4 -->|"开始导航"| H
+  G4 -->|"播放讲解"| I
+  G4 -->|"收藏/分享"| G5["保存状态并反馈"]
+
+  H --> H1["确认当前位置或手动选择起点"]
+  H1 --> H2["生成起点到目标路径"]
+  H2 --> H3["路线规划页"]
+  H3 --> H4["开始导航"]
+  H4 --> H5["导航中：楼层/步骤/距离/方向"]
+  H5 --> H6{"用户中途操作"}
+  H6 -->|"查看室外"| H7["切换室外地图层并保留路线"]
+  H7 --> H5
+  H6 -->|"暂停/继续"| H8["保留当前进度"]
+  H8 --> H5
+  H6 -->|"到达"| H9["到达完成页"]
+  H9 --> H10["下一步：继续游览/返回首页/听该点讲解"]
+```
+
+## 主流程闭环标准
+
+| 流程 | 起点 | 必要中间态 | 完成态 |
+| --- | --- | --- | --- |
+| 导览找点 | 首页导览 | 地图层、POI 卡片、详情或路线选择 | 到达 POI，或返回地图继续浏览 |
+| 搜索找内容 | 搜索入口 | 关键词、综合结果、类型详情 | 进入详情，或发起导航/播放讲解 |
+| 讲解收听 | 首页讲解 | 分组/搜索、展品、音频可用性判断 | 播放结束，返回展品或讲解列表 |
+| 设施导航 | 设施详情 | 起点确认、路径生成、导航中状态 | 到达完成页，有下一步动作 |
+| 详情转导航 | 展品/展厅/设施详情 | 目标 ID、起点、路线规划 | 到达目标，不是简单返回上一页 |
+
+## 页面与数据关系
+
+```mermaid
+flowchart LR
+  DS["统一自然馆数据源"] --> S["搜索页"]
+  DS --> E["讲解列表"]
+  DS --> D["详情页"]
+  DS --> M["地图 POI"]
+  DS --> R["路线规划"]
+
+  S -->|"result.type + result.id"| D
+  E -->|"exhibit.id"| D
+  M -->|"poi.id + poi.type"| D
+  D -->|"target.id + target.type"| R
+  R -->|"routeSession"| M
+  E -->|"audioUrl"| P["播放器"]
+  D -->|"audioUrl"| P
+```
+
+## 落地顺序
+
+1. 统一自然馆数据源和 ID 规则。
+2. 搜索页、讲解页、详情页全部按统一数据源渲染。
+3. 地图 marker 只发 POI 事件，由页面统一打开操作卡片。
+4. 详情页主按钮明确进入路线页或播放器。
+5. 路线页保存 `routeSession`，覆盖起点、目标、路径、楼层、当前步骤和完成态。
+