# 对标导览小程序 UX 与功能逻辑分析

## 1. 分析范围

- 对标视频：`E:\下载\导览.mp4`
- 视频信息：约 66.43 秒，448 x 960，30fps，竖屏小程序录屏。
- 本报告只抽取导览应用的功能逻辑、任务闭环、状态机和交互流程，不做 UI 视觉还原。
- 本项目对照范围：`frontend-miniapp` 的 H5 导览业务源码，重点看 `src/pages/index/index.vue`、`src/components/navigation/*`、`src/components/map/ThreeMap.vue`、`src/pages/search/index.vue`、`src/pages/route/detail.vue`、`src/domain/guideReadiness.ts`、`src/usecases/guideRouteUseCase.ts`。

## 2. 抽帧与时间线方法

已使用 ffmpeg 抽帧，并用 OpenCV 计算逐秒帧差，形成视频时间线。

分析素材：

- 抽帧拼图：`.codex-artifacts/benchmark-guide-logic/timeline_contact_sheet.jpg`
- 逐秒帧：`.codex-artifacts/benchmark-guide-logic/frames/t_001.jpg` 至 `t_066.jpg`
- 关键帧：`.codex-artifacts/benchmark-guide-logic/key_01.jpg` 至 `key_16.jpg`
- OpenCV 时间线：`.codex-artifacts/benchmark-guide-logic/opencv_timeline.json`

OpenCV 识别出的主要画面转折点为：`00:02`、`00:06`、`00:15`、`00:18`、`00:24`、`00:34`、`00:38`、`00:39`、`00:40`、`00:43`、`00:53`、`00:62`、`00:63`。这些时间点基本对应加载完成、进入分类列表、切换选点态、键盘搜索、确认起点、路线预览、开始模拟导航、退出导览等状态变化。

## 3. 视频时间线

| 时间段 | 画面 / 状态 | 用户动作 | 系统反馈 | 关键帧 |
| --- | --- | --- | --- | --- |
| 00:00-00:02 | 小程序加载页，展示馆名和加载进度 | 打开小程序 | 进入导览主页前的启动反馈 | `key_01.jpg` |
| 00:02-00:06 | 导览主页，地图为主界面，顶部搜索，右侧工具，底部功能入口 | 等待地图加载或浏览首页 | 默认落在导览地图，可直接搜索、来馆、更多或进入推荐内容 | `key_02.jpg` |
| 00:06-00:15 | 分类 / 地图列表态，展示设施分类图标、楼层切换、POI 列表 | 点击地图 / 分类入口，浏览设施 | 同屏保留地图上下文和下方列表，用户不离开导览上下文 | `key_03.jpg` |
| 00:15-00:18 | 分类无结果提示 | 点击暂无数据的分类，如饮料售卖机 | Toast 提示暂无结果，仍停留当前列表，不打断任务 | `key_04.jpg` |
| 00:18-00:24 | 路线规划选点态，顶部起终点条，下方提示选择起点，模拟导航按钮置灰 | 进入路线规划，未选起点时尝试继续 | 提示必须先选起点，主按钮保持不可用 | `key_05.jpg`、`key_06.jpg` |
| 00:24-00:34 | 搜索 / 选点态，弹出键盘，用户输入或选择点位 | 选择起点或终点 | 候选点位列表更新，地图仍作为空间参考 | `key_09.jpg`、`key_10.jpg` |
| 00:34-00:38 | 选择确认态，地图上出现选点标记，底部弹出确认或点位卡 | 确认将该点设为起点 / 终点 | 起终点条更新，进入路线可规划状态 | `key_11.jpg`、`key_12.jpg` |
| 00:38-00:43 | 路线方案态，展示推荐路线、不走楼梯、电梯等方案，显示时间 / 距离 | 查看路线方案，点击模拟导航 | 路线叠加到地图，主按钮由不可用变为可启动 | `key_08.jpg` |
| 00:43-00:53 | 导航中态，顶部转向指令卡，地图路线、当前位置箭头、语音 / 低速 / 楼层 / 缩放控件，底部目的地与退出 | 模拟导航进行中 | 给出连续导航指令和当前位置反馈，保留退出导览能力 | `key_07.jpg` |
| 00:53-00:62 | 导航中跨步骤 / 结束前状态 | 继续模拟导航或操作退出 | 当前步骤更新，路线和目的地状态持续可见 | `key_13.jpg`、`key_14.jpg` |
| 00:62-00:66 | 退出导览后回到地图 / 列表态 | 点击退出或完成导览 | 清理导航态，回到可再次搜索 / 分类 / 规划的导览首页 | `key_15.jpg`、`key_16.jpg` |

## 4. 对标应用的用户任务闭环

对标应用的核心闭环不是单个“搜索结果页”，而是围绕地图持续完成任务：

1. 进入导览首页：地图即工作台，用户先获得空间上下文。
2. 找目标：通过搜索、分类、楼层列表或地图点选定位目标。
3. 定起终点：路线规划需要明确起点和终点，未满足条件时主动作禁用并给出原因。
4. 看方案：系统生成推荐路线，并提供偏好方案，如不走楼梯、电梯。
5. 开始导览：从路线方案进入导航中，地图、路线、位置、转向指令同步变化。
6. 导航中纠偏：持续显示当前指令、楼层、缩放、语音等控制，用户可以退出。
7. 结束 / 退出：退出后清理导航态，返回导览主页，可继续搜索或重新规划。

这个闭环的 UX 关键点是“上下文不断裂”：搜索、分类、选点、路线、导航都嵌在地图任务里，用户很少被推到孤立页面。

## 5. 导览状态机

```mermaid
stateDiagram-v2
  [*] --> Loading
  Loading --> MapHome
  MapHome --> CategoryList: 打开地图/分类
  MapHome --> SearchSelecting: 搜索或选点
  MapHome --> RoutePointPicking: 进入路线规划
  CategoryList --> EmptyCategory: 分类无结果
  EmptyCategory --> CategoryList: Toast 后停留
  CategoryList --> PoiSelected: 点击 POI
  SearchSelecting --> PoiSelected: 选择候选点
  PoiSelected --> RoutePointPicking: 设为起点/终点
  RoutePointPicking --> RoutePointPicking: 起终点不完整/提示
  RoutePointPicking --> RoutePreview: 起终点完整并规划
  RoutePreview --> Navigating: 开始/模拟导航
  Navigating --> Navigating: 步进/转向/楼层变化
  Navigating --> MapHome: 退出导览
  RoutePreview --> RoutePointPicking: 返回修改起终点
  RoutePointPicking --> MapHome: 取消/清除
```

状态机说明：

- `MapHome` 是中心状态，不只是入口页；其它状态多数都能回到它。
- `RoutePointPicking` 对起点 / 终点完整性有强校验，防止用户在条件不足时进入导航。
- `RoutePreview` 与 `Navigating` 是两个不同状态：前者看方案，后者进入指令驱动。
- `Navigating` 必须有退出路径，否则用户进入沉浸态后会失控。

## 6. 路线规划流程

```mermaid
flowchart TD
  A[进入路线规划] --> B{是否已有起点}
  B -- 否 --> C[提示选择起点并禁用主按钮]
  C --> D[搜索/地图点选/列表选择起点]
  B -- 是 --> E{是否已有终点}
  D --> E
  E -- 否 --> F[提示选择终点并禁用主按钮]
  F --> G[搜索/地图点选/列表选择终点]
  E -- 是 --> H[展示路线偏好]
  G --> H
  H --> I[请求路线规划]
  I --> J{是否有可用路线}
  J -- 否 --> K[展示无路线/能力不可用原因]
  J -- 是 --> L[展示推荐路线、距离、时间、跨层信息]
  L --> M[开始模拟/正式导航]
  M --> N[导航中指令、定位、楼层、退出]
  N --> O[结束或退出，清理导航态]
```

对标流程里的路线偏好包含“推荐路线 / 不走楼梯 / 电梯”。这不只是三个按钮，而是路线规划输入条件的一部分：它们应改变路径权重、可通行边、垂直交通工具偏好，不能只改变文案。

## 7. 搜索 / 选点 / 楼层 / 导航中 / 结束逻辑

### 搜索逻辑

- 搜索框始终贴近地图主场景，搜索不是脱离地图的单独任务。
- 输入时可出现键盘与候选列表；确认后应回填到起点或终点，而不是只跳详情。
- 搜索结果应可被用于三类动作：查看位置、设为起点、设为终点。
- 空结果使用轻量 Toast 或空态，不破坏当前选点任务。

### 选点逻辑

- 路线规划明确区分起点和终点。
- 当前正在选起点还是终点，需要有持续提示。
- 未选起点 / 终点时，模拟导航等主动作应禁用。
- 选点后需要地图标记、文本条和底部确认态同步更新。

### 楼层逻辑

- 楼层既是浏览过滤条件，也是路线语义的一部分。
- 分类 / POI 列表与楼层选择联动，用户可以按楼层缩小范围。
- 跨层路线需要展示跨层提示，并在导航中支持楼层切换或自动跟随。
- 电梯、扶梯、楼梯不只是设施 POI；在正式路线里应作为垂直连接器参与拓扑。

### 导航中逻辑

- 导航中要从“看路线”切换到“执行指令”：顶部当前动作、地图路线、当前位置、目的地、退出按钮是最小闭环。
- 语音、低速、楼层、缩放等控制属于导航运行态控制，不应和路线方案态混淆。
- 模拟导航可以作为无真实定位时的演示模式，但需要和正式导航文案区分。

### 结束导览逻辑

- 结束或退出要清理路线、当前位置模拟、转向指令和目的地卡片。
- 退出后应回到地图主页或路线方案可编辑态，而不是落到空白或无法继续的状态。
- 对“已到达”与“用户主动退出”应分别处理：前者可给到到达反馈，后者保持可重规划。

## 8. 本项目当前逻辑对照

| 模块 | 当前状态 | 源码证据 | 与对标逻辑的差距 |
| --- | --- | --- | --- |
| 导览主页地图工作台 | 部分实现 | `src/pages/index/index.vue` 已有 `is3DMode`、`guideOutdoorState`、`indoorView`、`activeGuideFloor`、`selectedGuidePoi` 等状态；`GuideMapShell` 统一承载馆内 / 馆外、搜索、楼层、工具事件 | 已具备地图主页骨架，但搜索 / 分类 / 选点 / 路线的“同一任务上下文”还不如对标视频连贯 |
| “来馆”入口 | 已实现 | `src/pages/index/index.vue` 更多菜单标题已为“来馆”，并通过 `openOutdoorNavPanel()` 切到馆外 2D 地图 | 与对标里的“来馆/馆外参考”接近，继续保持与馆内导航解耦 |
| 馆外导航 / 来馆 | 已实现 | `src/components/navigation/OutdoorNavigationPanel.vue` 支持 GPS、手动起点、地址搜索、出行方式、路线结果、开始导航 / 清除 | 与对标导览里的馆内路线逻辑是两条业务线，不能混成馆内导航能力 |
| 馆内 3D 和楼层 | 部分实现 | `src/components/map/ThreeMap.vue` 和 `GuideMapShell` 已有馆内模型、楼层、POI 聚焦、路线预览渲染入口 | 具备位置预览和楼层浏览基础；正式跨层导航还缺经验证的拓扑与连接器 |
| POI 选择与卡片 | 部分实现 | `src/pages/index/index.vue` 有 `selectedGuidePoi`、POI 卡片、设起点 / 终点相关处理 | 对标视频中选点和路线起终点绑定更强；本项目仍偏“点位预览 + 路线面板” |
| 搜索 | 部分实现 | `src/pages/search/index.vue` 有搜索输入、筛选 chip、结果列表、点击详情、结果动作跳 `route/detail` | 已有搜索基础，但不是对标那种地图内分类面板 + 楼层 POI 列表 + 选起终点一体化流程 |
| 路线规划面板 | 部分实现 | `src/components/navigation/RoutePlannerPanel.vue` 有起点、终点、交换、清除、收起、推荐路线 / 少走楼梯 / 电梯优先、主按钮 | 面板结构接近对标，但路线偏好大多禁用；主流程受路线数据门禁限制 |
| 起终点搜索 / 选择 | 已实现基础 | `RoutePointPicker.vue` 被 `RoutePlannerPanel.vue` 使用，支持起点 / 终点 picker 与搜索 | 可继续吸收对标的“地图点选确认”和“当前选择角色持续提示” |
| 路线可用性门禁 | 已实现且必须保留 | `src/domain/guideReadiness.ts` 中 `NAV_ROUTE_GRAPH_READY = false`，不可用文案为“当前暂不支持正式导航，可查看位置预览、路线示意和馆外参考” | 当前不能对外宣称正式馆内导航，这是正确边界 |
| 真正路线规划 | 缺失 / 被门禁关闭 | `src/usecases/guideRouteUseCase.ts` 的 `planRoute()` 先读 readiness；未 ready 直接返回 error；`GuideRouteRepository` 也经过 `applyRouteReadinessGate` | 对标视频可进入路线方案和导航中，本项目当前只能做位置预览或能力不可用提示 |
| 导航中 turn-by-turn | 缺失 | `src/pages/index/index.vue` 有 `isSimulatingRoute` 和模拟态 UI 变量，但由于 `routeReady=false` 通常无法获得真实 `activeRoutePreview` | 缺真实路线、实时 / 模拟位置步进、转向指令、到达判断、偏航处理 |
| 路线偏好 | 缺失 / 占位 | `RoutePlannerPanel.vue` 中“少走楼梯”“电梯优先”均 `disabled: true`，提示待路线数据验证 | 需要真实 graph 边权、垂直连接器、无障碍属性后才可启用 |
| 结束导览 | 部分实现 | `handleRouteBack()`、`handleRouteClear()`、`handleRouteSimulate()` 可切换 / 清理部分路线状态 | 对标中的“导航中退出 -> 回到地图 / 方案态”闭环可借鉴，但需先有稳定导航中状态 |

## 9. 已有能力、缺失能力与优先级

### 已有，可继续打磨

- 地图作为导览主页：本项目已通过 `GuideMapShell`、`ThreeMap`、`TencentMap` 分离馆内 / 馆外渲染。
- POI / 楼层 / 位置预览：已有基础数据流和 UI 状态。
- 起终点面板：已有起点、终点、交换、清除、picker 搜索等基础能力。
- 路线能力门禁：当前 `NAV_ROUTE_GRAPH_READY=false`，避免误导用户，这是上线前必须保留的保护。
- 来馆：馆外导航面板已存在，适合承接对标视频里的“来馆”任务。

### 部分已有，建议按 UX 闭环补齐

- 地图内分类列表：当前搜索页是独立页面样式，建议未来改为地图上下文内的分类 / 楼层 / POI 列表，不打断导览。
- 点位到路线的动作：搜索结果、POI 卡片、地图点选应统一提供“查看位置 / 设为起点 / 设为终点”。
- 路线方案态：可先在 route graph 未就绪时展示“位置关系 / 路线示意不可用原因”，路线就绪后再切换到推荐路线。
- 导航退出闭环：现有清理函数可复用，但应明确区分取消规划、退出模拟、到达结束。

### 缺失，需数据和算法支撑

- 经验证的 `route_graph` / `nav_data` 加载、校验和冒烟测试。
- 馆内路径规划算法或 SDK 路线规划结果适配。
- 楼层连接器：楼梯、扶梯、电梯与图节点 / 边的关联。
- 路线偏好：推荐、不走楼梯、电梯优先对应不同权重和约束。
- 导航中 turn-by-turn：分步指令、当前位置更新、下一步提示、到达判断、偏航 / 重规划。
- 正式导航和模拟导航的文案与状态区分。

## 10. 建议吸收的 UX 逻辑

P1：先补齐不依赖真实路线的闭环。

- 将搜索、分类、楼层、POI 列表尽量保持在导览地图上下文内。
- 统一点位动作模型：`preview`、`setStart`、`setEnd`、`clear`。
- 路线未就绪时，主按钮和状态文案只表达“查看位置 / 位置关系 / 能力不可用原因”，不出现正式导航承诺。
- 空结果、未选起点、未选终点用即时反馈，不跳离当前任务。

P2：在 route graph 就绪后启用路线方案态。

- 接入真实 `route_graph`、`nav_data`、楼层连接器和 POI 到可行走节点映射。
- 将推荐路线、不走楼梯、电梯优先从 UI 占位变成规划输入。
- 路线方案卡展示距离、预计时间、跨层信息、关键连接器。

P3：再启用导航中状态。

- 明确模拟导航与正式导航两条状态。
- 导航中提供当前指令、下一步、楼层跟随、缩放、语音开关、退出。
- 结束导览后清理导航态并回到地图主页或路线方案态。

## 11. 风险边界

本项目当前不能按对标视频完整复刻“正式馆内导航”。原因不是 UI 缺按钮，而是路线能力被明确门禁：

- `src/domain/guideReadiness.ts` 将 `NAV_ROUTE_GRAPH_READY` 固定为 `false`。
- `guideRouteUseCase.planRoute()` 在 readiness 未就绪时直接返回错误，不进入真实路线规划。
- “少走楼梯 / 电梯优先”在路线面板中仍是禁用占位。

因此，对标视频中的路线方案、转向指令、模拟导航、到达结束等逻辑可以作为产品目标和状态机设计参考，但在本项目中必须等 `route_graph`、`nav_data`、楼层连接器和路线冒烟测试完成后才能启用。短期应继续使用“位置预览 / 查看位置关系 / 馆外参考 / 来馆”作为真实能力表述。

## 12. 结论

对标小程序的核心优势是把导览任务组织成一个连续地图工作流：找点、选点、看路线、开始导航、退出导览都在同一空间上下文中完成。本项目已经具备地图 shell、馆内 3D、楼层、POI、路线面板、来馆面板和路线能力门禁，基础方向正确。

当前最大差距在于真实馆内路线数据和导航运行态：对标视频已经展示路线方案与导航中指令，本项目仍应停留在位置预览和能力不可用提示。建议先吸收不依赖路线数据的 UX 闭环，再在数据验证完成后逐步开放路线方案和导航中状态。