frontend-miniapp/docs/Benchmark/guide-video-ux-logic-analysis.md

对标导览小程序 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. 导览状态机

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. 路线规划流程

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 闭环，再在数据验证完成后逐步开放路线方案和导航中状态。