迎宾巡逻安防机器人机身屏交互系统详细设计开发文档（一期）

目录

1. 项目定位与建设目标

本系统为迎宾巡逻安防机器人机身屏交互系统，运行在机器人本体小主机盒子中，通过 8 寸触摸屏面向访客、现场用户、前台/物业/工作人员提供迎宾展示、访客登记、预约核验、路线引导、通知公告、呼叫工作人员等交互能力。

1.1 一期建设目标

1.2 一期设计基准

• 屏幕尺寸按 1024×768 横屏 8 寸设计，支持 10 点触摸。
• 小主机系统为 Ubuntu，前端运行于 Chromium Kiosk 全屏模式。
• 语音识别、人脸识别、身份证读卡、TTS、导航等能力由小主机后端或机器人侧服务提供，屏幕端只负责展示与交互。
• 路线引导、语音指令、人脸识别、访客登记等接口可先 Mock，后续再接入真实接口。

2. 运行环境与技术选型

2.1 推荐技术路线

2.2 Vue3 与 HTML5 的关系

2.3 更新部署方式

3. 系统边界与职责划分

3.1 屏幕端负责内容

3.2 屏幕端不负责内容

• 不负责人脸采集、人脸识别算法、人脸比对。
• 不负责身份证读卡器底层驱动和 SDK 调用。
• 不负责 TTS 合成能力和语音对话能力。
• 不负责真实导航规划、路径控制、巡逻任务控制。
• 不负责运维后台管理能力，如素材上传、播放方案编辑、问答库维护、白名单导入、OTA、日志中心等。

3.3 与其他系统的关系

3.4 典型运行状态与页面状态机

屏幕端应围绕“无人待机、用户交互、业务办理、插播播报、异常提示”几个状态进行设计，避免页面之间随意跳转导致流程混乱。

4. 总体功能架构

5. 主菜单与页面结构

5.1 一期主菜单

5.1.1 当前主菜单页面设计收口说明

• 主菜单页已按“上方欢迎引导 + 下方 2×2 大触摸入口”的结构进行设计，不再采用左右 Dashboard 布局或后台卡片式布局。
• 上方欢迎引导区仅保留主标题和副标题，避免三层文案造成视觉负担。
• 四个入口统一为大按钮式服务入口，整张卡片均可点击，不再显示每张卡片右下角小箭头或“点击进入”分割栏。
• 图标采用内联 SVG 方式实现，并保留彩色渐变图标底座；后续如需统一图标规范，可替换为同一套线性图标库的 SVG。
• 左下角“返回待机”采用轻量悬浮胶囊按钮，不使用整条底部操作栏，以减少页面原型感。

5.2 页面结构建议

6. 核心业务流程设计

6.1 待机展示流程

6.2 播报内容插播流程

6.3 预约到访流程

6.4 现场登记流程

6.5 人脸识别结果进入流程

6.6 语音指令响应流程

7. 页面详细设计

7.1 待机展示页

待机页当前实现收口说明

• 待机页分为两种明确模式：默认欢迎模式与播放方案模式。
• 默认欢迎模式使用“背景图 + 前端动态文字叠加”的方式实现，机器人名称、欢迎语、副标题、按钮、时间、状态等内容均由前端或后续主题配置动态渲染。
• 默认欢迎背景图仅作为氛围底图，不包含文字、按钮、Logo 等 UI 元素，便于后续通过运维端主题配置替换。
• 播放方案模式以图片/视频素材为主视觉，状态、时间、触摸提示等仅作为轻量浮层展示。
• 播放方案模式中，图片按配置时长自动轮播，视频优先按 ended 事件切换；素材加载失败时跳过当前素材。
• 开发阶段保留欢迎模式与播放方案模式的调试切换入口，正式上线时应通过配置隐藏。

待机素材播放补充规则

• 图片素材建议支持展示时长、排序、启停状态、适用屏幕方向、填充方式。
• 视频素材建议支持静音状态、音量、循环播放、播放失败跳过、播放完成自动切下一条。
• 素材填充方式建议支持 cover 与 contain：cover 适合全屏沉浸展示，contain 适合完整展示但可能留边。
• 本地网络或素材加载异常时，应自动跳过当前素材并展示下一条；全部素材不可用时回退欢迎页。
• 后续可考虑素材预缓存到小主机本地，降低网络波动对待机播放的影响。

7.2 主菜单页

主菜单页当前实现收口说明

• 主菜单页已取消左右分栏式引导区，统一改为上下结构，使页面更贴近机器人机身屏的服务选择页。
• 页面顶部保留 StatusBar，主内容区居中展示标题“请选择需要的服务”和辅助说明“触摸下方入口办理业务，也可以直接说出您的需求”。
• 四个服务入口均为大面积触摸按钮，入口本身即代表可点击，不额外展示“点击进入”文字或右下角箭头。
• 按钮图标采用彩色渐变底座 + 白色线性 SVG 图标，当前语义为：访客登记、定位导航、公告喇叭、电话呼叫。
• 若现场屏幕肉眼显示比例与系统截图不一致，应优先排查外接屏分辨率、镜像显示、浏览器缩放和屏幕硬件拉伸，不建议通过前端强行修正比例。

7.3 访客登记页面

7.3.1 现场登记页字段说明

7.3.2 预约确认页字段规则

7.3.3 登记成功页字段规则

7.4 路线引导页面

7.5 通知公告页面

7.6 呼叫工作人员页面

7.7 隐藏系统信息页

8. 播放、播报与声音控制规则

8.1 内容优先级

8.2 声音来源与职责

8.3 音量与静音控制

• 屏幕端应提供静音/取消静音和音量调节能力，优先作用于视频素材和前端提示音。
• 当播报内容或语音对话发生时，屏幕端应暂停或静音当前视频素材。
• 播报结束后，屏幕端恢复素材播放状态。
• 语音服务和浏览器同时输出到同一喇叭时，应由小主机后端协调音频抢占策略。

8.4 播报插播运行规则

• 播报内容优先级高于素材广告和默认欢迎页。
• 播报任务到时后，后端负责调用第三方 TTS 生成或复用 MP3 文件，并通过当前播报状态接口返回 audioUrl；屏幕端负责播放该 MP3，并通过 audio ended 事件感知播报结束。
• 播报开始时，屏幕端暂停当前图片轮播或视频播放，并播放播报 MP3。
• 播报播放期间，屏幕端显示播报浮层。
• 播报 MP3 播放结束后，屏幕端隐藏播报浮层，并恢复原素材播放状态。
• 播报插播不应重置当前播放方案和当前素材索引。
• 如果 MP3 播放失败，屏幕端应记录 warning 日志，并恢复素材播放。
• 一期只在待机页执行播报插播，不强制打断访客登记、路线引导等业务办理页面。

9. 语音指令与事件通信设计

9.1 一期通信链路

9.2 指令类型建议

10. 输入方式与触摸交互规范

10.1 输入策略

10.2 防误触与超时规则

• 长时间无操作自动返回待机页，建议默认 60 秒，可配置。
• 访客登记、身份证读取、手机号查询等页面超时后自动清空敏感信息。
• 退出登记流程时需弹窗确认，避免误触导致信息丢失。
• 提交登记前展示确认页，避免误提交。
• 重启、关机、开始巡逻、停止巡逻等高风险动作不在普通屏幕端开放。

10.3 触摸尺寸建议

11. UI 视觉与屏幕适配规范

11.1 视觉风格

11.2 1024×768 横屏布局建议

11.3 字号建议

11.4 竖屏适配说明

12. Mock 数据与前端开发建议

12.1 一期前端开发方式

• 先完成 Vue3 前端工程、页面路由、组件拆分和 Mock 数据。
• 所有接口封装统一走 api 层，即使一期使用本地 Mock，也保留后续替换真实接口的结构。
• 播放状态、机器人状态、语音指令、访客登记信息等统一由 Pinia 管理。
• 待机播放器、数字键盘、状态栏、全局弹窗、登记表单、目的地卡片等应封装为可复用组件。

12.2 组件拆分建议

12.3 推荐前端目录结构

12.4 Mock 数据范围

12.5 访客登记 Mock 开发说明

• 开发环境允许现场登记提交失败时使用 Mock 成功数据跳转 /visitor/success，便于前端调试登记成功页。
• 正式生产环境不启用 Mock 提交兜底，接口失败时正常提示"登记失败，请重试"。
• 登记成功页（Success.vue）支持开发环境无 registrationInfo 时使用 Mock 数据展示，Mock 数据包含访客姓名、手机号、被访人、登记时间。
• 预约确认页（AppointmentConfirm.vue）可在开发环境通过 setMockAppointment() 方法注入 Mock 预约数据进行调试。
• 开发阶段所有 Mock 数据仅在前端内存中，不持久化，不上报真实后端接口。

本地播放素材 Mock 约定

• 开发阶段播放方案素材放置于 src/assets/media/play-plan/images/ 与 src/assets/media/play-plan/videos/ 目录。
• Mock 播放方案通过 Vite 的 import.meta.glob 自动扫描本地图片与视频文件，不再手动逐个 import 固定素材。
• 本地素材仅用于模拟后端播放方案返回结果，组件仅消费 playPlan.items 中的 url、type、duration、fitMode 等字段。
• 后续对接真实接口时，应保持数据结构一致，由后端返回素材 URL 与播放参数，前端不再依赖本地素材目录。

13. 后续接口设计建议

13.1 当前播放方案接口详细设计

13.1.1 接口基本信息

13.1.2 数据来源与字段映射

13.1.3 后端取数规则

1. 查询 robot_ops_play_plan 中 status=1 的当前播放方案。
2. 如果不存在当前播放方案，返回 enabled=false 和空 items。
3. 如果存在当前播放方案，查询该方案下的 robot_ops_play_plan_item 明细，并按 play_order 升序排序。
4. 关联 robot_ops_media_asset 素材表，获取素材名称、类型、文件地址、缩略图、视频时长、启用状态等。
5. 过滤不可播放素材：素材不存在、素材停用、file_url 为空、asset_type 不是 image/video。
6. 如果过滤后素材列表为空，也返回 enabled=false 和空 items。
7. 如果存在可播放素材，返回 enabled=true 和已排序的素材列表。

13.1.4 素材 URL 补全规则

后端返回给屏幕端的 url 和 thumbnailUrl 必须是浏览器可直接访问的地址。屏幕端当前约定素材访问前缀为 http://192.168.0.30。

13.1.5 返回示例

13.1.6 无播放方案或无可播放素材返回示例

13.1.7 前端播放规则

• enabled=false 或 items 为空时，机身屏回退默认欢迎页。
• enabled=true 且 items 有数据时，机身屏进入播放方案模式。
• 图片素材按 staySeconds 控制停留时长，前端使用 duration 毫秒值进行定时切换。
• 视频素材默认完整播放，前端监听 ended 事件后切换下一条，不使用 staySeconds 强制截断。
• fitMode 默认 cover，后续可扩展 contain、stretch。
• showTitle 默认 false，避免和素材自带文字冲突。
• 屏幕端进入 /idle 待机页时，应立即请求一次 /robot-ops/screen/play-plan/current 当前播放方案接口。
• 待机播放期间，屏幕端应每 60 秒重新请求一次当前播放方案接口，用于检查运维端是否更新了播放方案或素材配置。
• 前端应通过接口返回的 version 字段判断播放方案是否变化；如果 version 未变化，不应重置当前播放进度。
• 如果 version 发生变化，前端应标记新方案待生效，并在当前图片展示结束或当前视频播放结束后切换到新播放方案，不建议直接打断正在播放的视频。
• 如果重新请求后发现无当前播放方案、播放方案禁用或素材为空，前端应在当前素材播放结束后回退默认欢迎页。

13.1.8 播放方案更新检查策略

13.2 当前播报状态接口详细设计

13.2.1 接口基本信息

13.2.2 数据来源与字段映射

13.2.3 有播报返回示例

13.2.4 无播报返回示例

13.2.5 屏幕端处理规则

• 屏幕端进入 /idle 后立即请求一次当前播报状态接口，并每 2 秒轮询一次。
• 当 broadcasting=true 且 audioUrl 不为空时，屏幕端显示播报浮层，展示播报标题、播报正文和"正在播报"状态。
• 当前为图片素材时，播报开始后暂停图片轮播定时器，并播放 audioUrl 对应 MP3；播报结束后恢复图片轮播。
• 当前为视频素材时，播报开始后暂停视频播放，并播放 audioUrl 对应 MP3；播报结束后继续播放视频。
• 当前为默认欢迎页时，播报开始后显示播报浮层并播放 MP3；播报结束后隐藏播报浮层。
• 屏幕端应通过 audio ended 事件判断播报播放完成。
• 播报插播不应重置当前播放方案和当前素材索引。
• 如果 audioUrl 为空、MP3 加载失败或播放失败，屏幕端应记录 warning 日志，并恢复原素材播放状态。
• 接口请求失败或后端播报服务异常时，不影响当前素材播放。

13.2.6 后端与 TTS 处理建议

• 一期 TTS 不采用流式 TTS，统一采用"第三方 TTS 生成 MP3 文件 + 屏幕端播放 MP3"的方式实现。
• 后端根据播报任务的开始时间、结束时间、频率、循环类型和循环取值判断当前是否命中播报。
• 后端应避免同一任务在同一时间窗口内重复触发。
• 播报任务命中后，后端读取播报内容文本，判断该内容是否已有可用 MP3 文件；如果已有且未失效，则直接复用；如果没有或内容已修改，则调用第三方 TTS 重新生成 MP3。
• MP3 文件建议保存到小主机本地目录，例如 /data/robot/audio/broadcast/，并通过静态资源服务暴露为屏幕端可访问的 audioUrl，例如 http://192.168.0.30/profile/audio/broadcast/35_abc123.mp3。
• MP3 是否需要重新生成，应根据播报文本、音色、语速、音量、TTS 供应商和模型版本等生成 Hash 进行判断；Hash 不一致或本地文件不存在时重新生成。
• 后端在 current 接口中返回 broadcasting=true、audioUrl、audioDuration、title、content 等字段。
• 屏幕端负责播放 MP3。后端不直接控制浏览器音频播放，也不直接负责暂停/恢复素材。
• 后端可根据任务命中状态和播放窗口维护当前播报状态；如增加播放完成回执接口，则以后端收到 ack 后结束本次播报状态。
• 如果 TTS 生成失败，应记录失败原因，并避免影响素材播放；current 接口可返回 broadcasting=false 或返回错误状态，具体按后端实现处理。
• 后端应封装统一 TtsService，不要将第三方 TTS API 直接写死在播报任务逻辑中。

13.2.7 MP3 文件生成与复用规则

建议 Hash 计算口径为：md5(播报文本 + 音色 + 语速 + 音量 + TTS供应商 + 模型版本)

后端应封装统一 TtsService。屏幕端应封装统一音频播放逻辑，用于播放播报 MP3、监听 ended/error 事件，并在播放完成或失败后恢复素材播放。

14. 开发优先级与实施顺序

15. 测试验收要点

15.1 页面与交互验收

• 待机页应支持默认欢迎模式与播放方案模式两种状态，并能通过播放方案是否启用和素材是否为空进行自动切换。
• 主菜单页应采用上方欢迎引导与下方 2×2 大触摸入口结构，四个入口整体可点击，不依赖小箭头或“点击进入”文字传达可操作性。
• 1024×768 分辨率下所有页面无横向滚动、无明显遮挡。
• 主菜单四个入口清晰可点击，按钮尺寸适合 8 寸触摸屏。
• 长时间无操作可自动返回待机。
• 访客登记流程完整，支持预约到访和现场登记。
• 手机号和身份证号输入使用内置数字键盘。
• 路线引导页面流程完整，可从目的地选择到模拟到达。
• 通知公告列表和详情可正常展示。
• 呼叫工作人员入口有明确占位反馈。

15.2 播放与声音验收

• 待机状态有播放方案时播放素材，无播放方案时显示欢迎页。
• 视频素材可播放声音，支持静音和音量调节。
• 播报内容插播时可暂停当前图片轮播或视频播放，播报结束后恢复原素材播放状态。
• 屏幕端在待机页应每 2 秒轮询一次 /robot-ops/screen/broadcast/current，当返回 broadcasting=true 时显示播报浮层。
• 播报期间不应重置当前播放方案和当前素材索引。
• 异常提示优先级高于播报和素材广告。

15.3 Mock 与接口替换验收

• 运维端上传图片/视频素材并创建播放方案后，机身屏应可通过 /robot-ops/screen/play-plan/current 获取当前播放方案并播放素材。
• 当运维端未设置当前播放方案、播放方案被禁用或所有素材不可播放时，机身屏应自动回退默认欢迎页。
• 接口返回的素材 url 必须是屏幕端浏览器可直接访问的完整地址，例如 http://192.168.0.30/profile/upload/xxx.mp4。
• 屏幕端在待机播放期间应每 60 秒检查一次当前播放方案；当接口返回的 version 变化时，应在当前图片展示结束或当前视频播放结束后切换到新播放方案。
• 当播放方案更新为无可播放素材或取消当前播放方案时，屏幕端应自动回退默认欢迎页。
• 所有 Mock 数据均通过统一 api 层获取，后续可替换真实接口。
• 语音指令、识别结果、预约查询、身份证读取、导航状态均有 Mock 数据和页面响应。
• 关键用户操作可预留事件上报接口。

16. 安全、隐私与异常兜底

16.1 隐私与敏感信息处理

• 访客手机号、身份证号、访客照片等敏感信息不应长时间停留在屏幕上。
• 登记成功或流程超时后，应自动清空本地表单数据和临时识别结果。
• 身份证号展示时可考虑脱敏，例如仅展示前 6 位和后 4 位。
• 摄像头预览只在识别、核验、登记等明确业务场景展示，不在待机页长期展示。
• 屏幕端不应在本地持久化敏感访客信息，确需缓存时应由小主机后端统一处理。

16.2 异常兜底文案

16.3 操作安全边界

17. 运行部署与现场维护建议

17.1 Chromium Kiosk 启动建议

实际命令需根据 Ubuntu 版本、Chromium 安装路径、是否启用硬件加速等情况调整。

17.2 开机自启建议

• 小主机启动后应先启动 Nginx、小主机后端、语音服务等基础服务。
• Chromium Kiosk 建议在本地服务启动完成后再打开，避免首屏接口异常。
• 可使用 systemd 或桌面自启动脚本管理 Chromium 启动。
• 现场断电重启后，屏幕应自动恢复到待机展示页。

17.3 前端包更新建议

17.4 现场维护信息建议

• 隐藏系统信息页应展示前端版本、后端服务连接状态、本机 IP、机器人编号、屏幕分辨率、当前音量、网络状态。
• 系统信息页可提供刷新页面、重新加载配置、返回待机等低风险操作。
• 错误日志、接口异常、识别失败等详细排查信息建议上报后端或运维端，不直接展示给访客。

18. 待确认与后续扩展事项