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

文档用途：作为机器人机身屏前端页面设计、交互流程、Mock 开发、后续接口联调和验收测试的统一开发基线。

文档原则：一期先完成屏幕端前端页面与交互流程，使用 Mock 数据，后续再逐步对接小主机后端、语音服务、身份识别、导航点位、访客登记等接口。

技术基线：Vue3 + Vite运行环境：Ubuntu + Chromium Kiosk屏幕基准：1024×768 横屏 8 寸交互方式：10 点触摸 + 语音指令

## 目录

## 1. 项目定位与建设目标

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

屏幕端不是运维后台，不承担素材上传、问答库维护、播放方案配置、日志查询、OTA 升级、账号管理、白名单批量维护等后台管理能力。

### 1.1 一期建设目标

展示可用
无人交互时播放广告素材、通知公告或欢迎页，形成机器人对外展示窗口。
交互清晰
通过大按钮、大字体和简洁流程完成访客登记、路线引导、通知查看等操作。
接口可替换
一期先用 Mock 数据完成前端，后续接口成熟后平滑替换为真实数据。

### 1.2 一期设计基准

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

## 2. 运行环境与技术选型

### 2.1 推荐技术路线

项目 | 建议方案 | 说明
--- | --- | ---
产品形态 | HTML5 机器人机身屏应用 | 对外可理解为 H5 屏幕端应用，运行于浏览器全屏环境。
开发框架 | Vue3 + Vite | 适合组件化开发、路由管理、状态管理和后续接口联调。
状态管理 | Pinia | 管理机器人状态、播放状态、语音指令、全局弹窗、用户输入等。
路由 | Vue Router | 管理待机页、主菜单、访客登记、路线引导、通知公告等页面。
运行方式 | Chromium Kiosk | Ubuntu 开机后自动全屏打开本地 screen 地址。
部署方式 | Nginx 托管静态文件 | Vue3 打包后生成 dist 静态文件，部署到小主机本地目录。

### 2.2 Vue3 与 HTML5 的关系

Vue3 并不是和 HTML5 二选一。Vue3 最终打包产物仍是 HTML、CSS、JavaScript 静态文件。推荐表述为：本系统采用 Vue3 开发 HTML5 机身屏应用。

### 2.3 更新部署方式

开发阶段： 编写 Vue3 源码 → npm run build → 生成 dist 静态文件 部署阶段： 上传 dist.zip → 解压覆盖 /usr/share/nginx/html/screen → 刷新或重启 Chromium → 完成更新 后续产品化： 可将 screen-ui-vX.X.X.zip 纳入运维端 OTA 升级模块，支持备份、覆盖、刷新和失败回滚。

## 3. 系统边界与职责划分

### 3.1 屏幕端负责内容

待机展示素材播放播报内容展示语音指令响应访客登记预约核验身份证读取交互人脸识别结果展示路线引导前端流程通知公告展示呼叫工作人员占位全局状态提示隐藏系统信息页

### 3.2 屏幕端不负责内容

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

### 3.3 与其他系统的关系

系统/服务 | 负责内容 | 屏幕端使用方式
--- | --- | ---
运维端 Web 管理系统 | 欢迎语、素材、播放方案、播报内容、播报任务、访客记录、预约记录、白名单、系统配置等管理。 | 屏幕端读取或消费运维端配置结果，不重复建设后台管理页面。
小主机后端服务 | 接口聚合、语音指令接收、播报任务调度、TTS 调用、身份证读卡接口、人脸识别结果转发、机器人状态接口等。 | 屏幕前端通过 HTTP 轮询或接口调用与其通信。
语音服务 | 语音识别、语音对话、TTS 播放或播报能力。 | 语音识别结果先上报小主机后端，再由屏幕端获取并执行动作。
机器人主控/导航服务 | 点位列表、导航任务、运动控制、状态采集、巡逻任务等。 | 一期路线引导先 Mock，后续接入真实点位和导航状态接口。

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

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

状态 | 触发来源 | 页面表现 | 退出条件
--- | --- | --- | ---
待机播放 | 系统启动、无操作超时、业务结束 | 播放素材广告；无素材时显示欢迎页。 | 触摸屏幕、语音唤醒、识别结果、播报任务、异常事件。
主菜单交互 | 用户触摸或语音打开菜单 | 展示访客登记、路线引导、通知公告、呼叫工作人员。 | 选择功能、返回待机、无操作超时。
业务办理 | 进入访客登记、预约核验、路线引导等流程 | 展示表单、确认页、状态页、结果页。 | 业务完成、用户取消、超时返回、异常中断。
播报插播 | 播报任务到时 | 暂停素材，显示播报内容文字，配合 TTS 语音播放。 | 播报结束后恢复原待机播放状态。
异常提示 | 低电量、故障、网络异常、服务不可用 | 全局弹窗或全屏提示，文案应面向访客，避免技术化。 | 异常解除、用户确认、系统自动恢复。

## 4. 总体功能架构

待机展示

- 广告素材播放
- 默认欢迎页
- 通知/公告插播
- 无操作自动返回

主菜单

- 访客登记
- 路线引导
- 通知公告
- 呼叫工作人员

访客登记

- 预约到访
- 现场登记
- 身份证读取
- 手机号查询

识别结果

- 人脸识别结果
- 预约用户展示
- 白名单结果展示
- 识别失败引导

路线引导

- 目的地列表
- 目的地确认
- 模拟导航中
- 到达提示

语音响应

- 接收语音指令
- 页面跳转
- 识别文本展示
- 状态切换

全局状态

- 电量
- 网络
- 充电
- 异常提示

系统信息

- 隐藏入口
- 设备编号
- IP/版本
- 刷新页面

## 5. 主菜单与页面结构

### 5.1 一期主菜单

菜单入口 | 页面职责 | 一期处理方式 | 优先级
--- | --- | --- | ---
访客登记 | 进入预约到访或现场登记流程，支持身份证读取、手机号查询、手动填写等。 | 正式前端流程 + Mock 数据 | P0
路线引导 | 选择目的地，展示引导流程和导航状态。 | 正式前端流程 + Mock 数据 | P0
通知公告 | 展示运维端播报内容中的通知/公告类内容。 | Mock 列表与详情，后续对接播报内容接口 | P0
呼叫工作人员 | 为访客提供求助入口。 | 保留按钮和占位交互，真实方式后续确认 | P1

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

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

业务咨询模块取消，不作为主菜单入口。机器人介绍不作为一级菜单，可通过待机素材、欢迎页素材或后续主题内容体现。

### 5.2 页面结构建议

页面 | 路由建议 | 说明
--- | --- | ---
待机展示页 | /idle | 无人交互时的默认页面，播放素材或显示欢迎页。
主菜单页 | /menu | 触摸或语音唤醒后展示四个主入口。
访客登记首页 | /visitor | 选择预约到访或现场登记。
预约核验页 | /visitor/appointment | 支持身份证读取和手机号查询。
预约确认页 | /visitor/appointment-confirm | 展示预约信息，用户确认后生成访客记录。
现场登记页 | /visitor/walk-in | 身份证读取填充或手动填写访客信息。
登记成功页 | /visitor/success | 显示登记成功、欢迎语和后续指引。
识别结果页 | /recognition/result | 根据人脸识别结果展示预约用户、白名单人员或未识别结果。
路线引导页 | /navigation | 展示目的地分类和地点列表。
导航状态页 | /navigation/status | 展示模拟导航中、到达、取消等状态。
通知公告页 | /notice | 展示通知公告列表和详情。
呼叫工作人员页 | /call-staff | 保留入口，显示占位提示。
隐藏系统信息页 | /system-info | 长按 Logo 或指定区域进入，优先级低。

## 6. 核心业务流程设计

### 6.1 待机展示流程

进入屏幕系统 ↓ 加载屏幕配置、主题配置、播放方案、机器人状态 ↓ 判断是否存在启用的播放方案 ├─ 有播放方案：播放素材广告 / 图片 / 视频 └─ 无播放方案：显示默认欢迎页 ↓ 用户触摸屏幕或语音唤醒 ↓ 进入主菜单页

### 6.2 播报内容插播流程

小主机后端判断播报任务到时 ↓ 后端读取播报内容文本 ↓ 后端判断是否已有可用 MP3 ├─ 已有且未失效：复用 MP3 └─ 没有或已失效：调用第三方 TTS 生成 MP3 ↓ current 接口返回 broadcasting=true、title、content、audioUrl、audioDuration ↓ 屏幕前端轮询获取当前播报状态 ↓ 暂停当前图片轮播或视频播放 ↓ 显示播报浮层 ↓ 屏幕端播放 audioUrl 对应 MP3 ↓ audio ended 或 audio error ↓ 隐藏播报浮层 ↓ 恢复原待机播放状态

### 6.3 预约到访流程

访客登记 ↓ 选择“预约到访” ↓ 选择核验方式：身份证读取 / 手机号查询 ↓ 查询预约记录 ├─ 查询成功：展示预约信息确认页 └─ 查询失败：提示未查询到预约，可转现场登记 ↓ 访客确认预约信息 ↓ 提交登记 ↓ 登记成功

### 6.4 现场登记流程

访客登记 ↓ 选择“现场登记” ↓ 选择身份证读取或手动填写 ↓ 填写/回填访客姓名、手机号、身份证号、来访单位、被访人、来访事由 ↓ 提交登记前确认 ↓ 提交成功 ↓ 显示登记成功页
现场登记页字段顺序：访客姓名 → 手机号码 → 身份证号 → 来访单位 → 被访人 → 来访事由。被访部门不在机身屏现场登记页展示。

### 6.5 人脸识别结果进入流程

机器人侧完成人脸识别 ↓ 识别结果上报小主机后端 ↓ 屏幕前端轮询获取识别结果 ↓ 根据结果展示页面 ├─ 预约访客：进入预约确认页 ├─ 白名单人员：展示欢迎/通行提示 └─ 未识别人员：引导进入访客登记

### 6.6 语音指令响应流程

语音服务识别用户指令 ↓ HTTP 小主机后端接收识别结果 ↓ 屏幕前端定时轮询最新指令 ↓ 执行动作 ├─ 打开访客登记 ├─ 打开路线引导 ├─ 打开通知公告 ├─ 打开主菜单 └─ 显示提示信息

## 7. 页面详细设计

### 7.1 待机展示页

项 | 详细设计
--- | ---
页面目标 | 无人操作时作为机器人对外展示窗口，播放素材广告、公告内容或显示默认欢迎页。
主要内容 | 图片素材、视频素材、欢迎标题、欢迎副标题、Logo、当前时间、机器人简要状态。
交互方式 | 触摸任意区域或语音唤醒后进入主菜单。
兜底逻辑 | 有启用播放方案且存在可播放素材时进入播放方案模式；无播放方案、播放方案禁用或素材为空时显示默认欢迎页。
无操作规则 | 其他页面长时间无操作后自动返回待机页。

#### 待机页当前实现收口说明

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

#### 待机素材播放补充规则

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

### 7.2 主菜单页

项 | 详细设计
--- | ---
页面目标 | 提供四个核心入口，方便访客快速选择服务。
菜单入口 | 访客登记、路线引导、通知公告、呼叫工作人员。
布局建议 | 1024×768 横屏下采用“上方欢迎引导 + 下方 2×2 大触摸入口”的布局，左下角保留轻量悬浮返回待机按钮。
状态展示 | 顶部显示 Logo、时间、电量、网络、当前工作状态。
语音支持 | 语音指令“我要登记”“我要去某地”“查看通知”等可直接跳转对应页面。

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

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

### 7.3 访客登记页面

模块 | 详细设计
--- | ---
访客登记首页 | 展示预约到访、现场登记两个入口。
预约到访 | 支持身份证读取查询、手机号查询；人脸识别命中预约用户时可直接进入预约确认页。
现场登记 | 支持身份证读取自动填充和手动填写。
登记字段 | 访客姓名、手机号、身份证号、来访单位、被访人、来访事由。
输入方式 | 手机号、身份证号使用前端内置数字键盘；访客姓名、来访单位、被访人使用文本输入弹窗（依赖系统软键盘）；来访事由使用枚举选项弹窗。
超时规则 | 登记页面长时间无操作后清空敏感信息并返回待机。

#### 7.3.1 现场登记页字段说明

字段 | 类型 | 说明
--- | --- | ---
访客姓名 | 文本输入 | 依赖系统软键盘，不做枚举。
手机号码 | 数字输入 | 前端 NumericKeyboard，11 位，格式校验。
身份证号 | 数字输入 | 前端 NumericKeyboard，支持末位 X，选填。
来访单位 | 文本输入 | 依赖系统软键盘，不做枚举选择，用于填写访客来自的公司、单位、团队、施工队或客户机构等。
被访人 | 文本输入 | 依赖系统软键盘，不做枚举。被访部门不在机身屏现场登记页展示。
来访事由 | 枚举选择 | 枚举选项弹窗，不做自由文本输入。

#### 7.3.2 预约确认页字段规则

字段 | 是否可编辑 | 说明
--- | --- | ---
预约单号 | 不可修改 | 系统自动生成。
访客姓名 | 不可修改 | 来源于预约数据。
身份证号 | 不可修改 | 来源于预约数据或读取。
手机号码 | 不可修改 | 来源于预约数据。
被访人 | 可修改 | 通过蓝色标记和编辑图标提示可点击编辑。被访部门不在预约确认页展示。
预约时间 | 不可修改 | 来源于预约数据。
来访事由 | 可修改 | 通过蓝色标记和编辑图标提示可点击编辑，枚举选项弹窗。

#### 7.3.3 登记成功页字段规则

字段 | 说明
--- | ---
访客姓名 | 展示登记的访客姓名。
手机号码 | 展示登记的手机号，脱敏显示，如 138****0000。不展示完整号码。
被访人 | 展示登记的被访人。
登记时间 | 展示提交登记的时间。

登记成功页不展示身份证号，不展示来访单位（来访单位为后台登记字段，不在成功结果页展示）。成功页展示"登记成功"标题、欢迎语和后续指引文案，提供"返回待机"按钮。生产环境可 10 秒后自动返回待机页；开发环境不自动跳转，方便调试。

### 7.4 路线引导页面

模块 | 详细设计
--- | ---
页面目标 | 让访客选择目的地，展示机器人带路或路线引导流程。
一期处理 | 正式前端版，数据使用 Mock，后续替换真实点位和导航接口。
页面内容 | 目的地分类、目的地列表、常用地点、目的地确认、导航中状态、到达提示。
操作按钮 | 开始引导、取消引导、返回首页。
异常提示 | 接口未接入或导航不可用时，提示“路线引导功能正在接入中”。

### 7.5 通知公告页面

模块 | 详细设计
--- | ---
数据来源 | 复用运维端播报内容管理中的通知、公告、提示类内容。
页面形式 | 公告列表 + 公告详情，支持大字体展示。
播放关系 | 定时播报任务触发时，可暂停素材广告并插播公告文字和语音。
一期处理 | 先使用 Mock 数据展示公告列表和详情。

### 7.6 呼叫工作人员页面

模块 | 详细设计
--- | ---
页面目标 | 为访客提供求助入口。
一期处理 | 保留入口和占位交互，真实呼叫方式后续确认。
提示文案 | 可显示“已为您通知工作人员，请稍候”或“呼叫功能正在接入中”。
后续扩展 | 可接入运维端通知、主控平台事件、语音通话或视频通话。

### 7.7 隐藏系统信息页

模块 | 详细设计
--- | ---
入口方式 | 长按 Logo 或指定区域 5 秒进入。
页面内容 | 设备编号、机器人编号、本地 IP、前端版本、后端服务状态、网络状态、当前时间。
操作按钮 | 刷新页面、返回待机。重启类操作暂不开放。
优先级 | P2，非一期核心功能。

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

### 8.1 内容优先级

优先级 | 内容类型 | 处理规则
--- | --- | ---
最高 | 紧急异常 / 告警提示 | 立即打断当前页面，展示全局异常提示。
高 | 播报内容 | 暂停素材广告，展示播报文字，后端生成 MP3，屏幕端播放。
普通 | 素材广告 | 作为待机主内容播放图片或视频。
最低 | 欢迎页 | 无播放方案时的兜底页面。

### 8.2 声音来源与职责

声音来源 | 归属 | 说明
--- | --- | ---
视频素材声音 | 屏幕端 | 视频播放时可通过喇叭输出，屏幕端需要支持静音和音量控制。
播报内容语音 | 屏幕端播放后端 MP3 | 数据库播报内容以文字为主；一期由后端调用第三方 TTS 生成并缓存 MP3 文件，屏幕端通过当前播报状态接口获取 audioUrl 后进行播放，同时展示播报文字和状态。
登记成功/导航到达/异常提示音 | 屏幕端或本地服务 | 可根据后续实现选择前端音频文件播放或后端统一播放。
语音对话声音 | 语音服务 | 不归屏幕系统控制，屏幕端只展示识别结果或跳转页面。

### 8.3 音量与静音控制

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

### 8.4 播报插播运行规则

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

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

### 9.1 一期通信链路

语音服务识别指令 ↓ HTTP 小主机后端接收并保存最新指令 ↓ 屏幕前端每 0.5 秒或 1 秒轮询 /screen/command/latest ↓ 屏幕前端执行跳转或状态切换 ↓ 屏幕前端回执 /screen/command/ack

### 9.2 指令类型建议

指令类型 | 示例 | 屏幕动作
--- | --- | ---
OPEN_PAGE | 打开访客登记 | 跳转 /visitor
OPEN_MENU | 打开菜单 | 跳转 /menu
SHOW_RECOGNITION_RESULT | 人脸识别结果 | 跳转识别结果页或预约确认页
START_BROADCAST | 开始播报通知 | 暂停素材，展示播报内容
END_BROADCAST | 播报结束 | 恢复待机播放
SHOW_ALERT | 低电量/故障 | 显示全局提示

一期采用 HTTP 轮询，后续可升级为 WebSocket 或 SSE，以减少延迟并提升实时性。

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

### 10.1 输入策略

输入内容 | 推荐方式 | 说明
--- | --- | ---
手机号 | 前端内置数字键盘 | 11 位手机号输入，支持清空、删除、确认。
身份证号 | 前端内置数字键盘 + X | 支持 18 位身份证号和末位 X，可选填。
访客姓名 | 文本输入弹窗 + 系统软键盘 | 点击字段弹出文本输入弹窗，依赖 Ubuntu 系统软键盘。
来访单位 | 文本输入弹窗 + 系统软键盘 | 文本输入弹窗，依赖系统软键盘，不做枚举选择。
被访人 | 文本输入弹窗 + 系统软键盘 | 文本输入弹窗，依赖系统软键盘。被访部门不在机身屏现场登记页展示。
来访事由 | 枚举选项弹窗 | 预置选项弹窗（商务洽谈、面试应聘、快递/外卖、设备维修、探亲访友、咨询业务、其他事宜），不做自由文本输入。

### 10.2 防误触与超时规则

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

### 10.3 触摸尺寸建议

元素 | 建议尺寸
--- | ---
主菜单卡片 | 不小于 220×150px
主按钮高度 | 72px - 96px
普通按钮高度 | 56px - 72px
图标按钮 | 不小于 64×64px
输入框高度 | 不小于 56px

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

### 11.1 视觉风格

屏幕端采用“温和迎宾风 + 轻科技感”，适配大厅、展厅、营业厅、酒店等公共接待场景。

设计项 | 建议
--- | ---
主色 | 青蓝、湖蓝、柔和科技蓝。
背景 | 浅色背景、柔和渐变、低噪点纹理。
组件 | 大按钮、圆角卡片、柔和阴影、清晰图标。
文字 | 大字号、低密度、短文案、强引导。
避免 | 后台表格风、深色监控大屏风、强安防压迫感、密集小字。

### 11.2 1024×768 横屏布局建议

顶部状态栏：Logo / 时间 / 电量 / 网络 / 状态 中部主内容：待机素材、主菜单、登记表单或路线引导内容 底部操作区：返回、确认、取消、帮助等大按钮
实机调试补充：当系统截图比例正常但肉眼观察屏幕画面存在压缩或拉伸时，应优先检查 Mac/Ubuntu 外接屏分辨率、镜像模式、浏览器缩放比例、屏幕控制板缩放方式和设备像素比。前端 CSS 中的正方形图标容器不应为适配异常显示链路而改成非标准比例。

### 11.3 字号建议

文本类型 | 建议字号
--- | ---
页面主标题 | 32px - 40px
模块标题 | 24px - 30px
正文/说明 | 18px - 22px
按钮文字 | 20px - 26px
状态文字 | 16px - 20px

### 11.4 竖屏适配说明

一期不以未知竖屏为验收目标。代码实现时避免大量写死像素和绝对定位，优先使用 flex/grid、百分比、clamp 等方式，为后续竖屏适配保留空间。

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

### 12.1 一期前端开发方式

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

### 12.2 组件拆分建议

组件 | 职责
--- | ---
ScreenLayout.vue | 统一页面布局、顶部状态栏、底部操作区。
StatusBar.vue | 展示 Logo、时间、电量、网络、机器人状态。
IdlePlayer.vue | 待机素材播放，支持图片、视频、欢迎页兜底。
BroadcastOverlay.vue | 播报内容插播展示。
MainMenu.vue | 四个主菜单入口。
NumericKeyboard.vue | 手机号、身份证号输入键盘。
VisitorForm.vue | 访客登记表单。
CameraPreview.vue | 摄像头预览窗口。
DestinationList.vue | 路线引导目的地列表。
GlobalAlert.vue | 全局异常、低电量、网络异常等提示。

### 12.3 推荐前端目录结构

src/ ├─ api/ 接口封装与 Mock 入口 ├─ assets/ 图片、图标、默认素材 ├─ components/ 通用组件 ├─ layouts/ 屏幕基础布局 ├─ mock/ Mock 数据 ├─ router/ 页面路由 ├─ stores/ Pinia 状态管理 ├─ utils/ 工具函数、时间、格式化、设备判断 ├─ views/ 页面视图 │ ├─ idle/ 待机展示 │ ├─ menu/ 主菜单 │ ├─ visitor/ 访客登记 │ ├─ navigation/ 路线引导 │ ├─ notice/ 通知公告 │ └─ system/ 系统信息 └─ App.vue

### 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. 后续接口设计建议

本章为后续接口对接建议，一期前端可先使用 Mock 数据实现。

接口 | 方法 | 说明 | 主要字段
--- | --- | --- | ---
/screen/config | GET | 获取屏幕配置 | robotName、logoUrl、idleTimeout、theme、volume、mute
/screen/status | GET | 获取机器人简要状态 | batteryLevel、networkStatus、workStatus、chargeStatus、faultFlag
/robot-ops/screen/play-plan/current | GET | 获取当前播放方案 | enabled、planId、planName、loopMode、defaultFitMode、version、items
/robot-ops/screen/broadcast/current | GET | 获取当前播报状态 | broadcasting、taskId、contentId、title、content、contentType、audioUrl、audioDuration、playMode、startTime、estimatedEndTime、version
/robot-ops/screen/broadcast/ack | POST | 播报播放完成回执 | taskId、contentId、resultStatus、resultMsg、playTime
/screen/command/latest | GET | 获取最新语音/系统指令 | commandId、type、action、payload、timestamp
/screen/command/ack | POST | 指令处理回执 | commandId、resultStatus、resultMsg
/screen/id-card/read | POST | 读取身份证 | name、idCardNo、gender、nation、address、photoUrl
/screen/appointment/query | GET | 预约查询 | mobile、idCardNo；返回 appointmentNo、visitorName、visitedPerson、appointmentTime
/screen/visitor/register | POST | 提交访客登记 | visitorName、mobile、idCardNo、visitorCompany（或 visitorSource 承接"来访单位"）、visitedPerson、visitReason、visitType、registerType、appointmentNo
/screen/recognition/latest | GET | 获取最新识别结果 | personType、matchStatus、visitorName、appointmentNo、confidence
/screen/destination/list | GET | 目的地列表 | destinationId、name、category、floor、description
/screen/navigation/start | POST | 发起导航 | destinationId
/screen/navigation/status | GET | 导航状态 | taskId、status、currentPoint、targetName、progress
/screen/notice/list | GET | 通知公告列表 | title、content、publishTime、contentType
/screen/call-staff | POST | 呼叫工作人员 | callType、pagePath、remark
/screen/camera/preview-url | GET | 获取摄像头预览地址 | streamUrl、streamType、expireTime
/screen/audio/control | POST | 音量与静音控制 | volume、mute、sourceType
/screen/event/report | POST | 屏幕事件上报 | eventType、pagePath、eventData、timestamp

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

本接口为机身屏待机页播放方案模式的一期核心接口。运维 Web 前端、机身屏前端和后端服务共用同一套数据库与同一个后端服务；运维端负责素材上传和播放方案配置，机身屏前端只读取当前播放方案并播放素材。

#### 13.1.1 接口基本信息

项 | 设计内容
--- | ---
接口地址 | `GET /robot-ops/screen/play-plan/current`
接口用途 | 供机身屏 `/idle` 待机页读取当前启用播放方案。前端根据返回结果决定进入播放方案模式或回退默认欢迎页。
部署关系 | 运维 Web 前端、机身屏前端和后端服务部署在同一台小主机，共用同一套数据库和同一个后端服务。
素材访问地址 | 屏幕端访问素材统一使用完整 URL，例如 `http://192.168.0.30/profile/upload/xxx.mp4`。
是否允许多个当前方案 | 不允许。播放方案主表中同一时间只允许一个方案为当前播放方案。

#### 13.1.2 数据来源与字段映射

数据表 | 主要字段 | 接口字段 | 说明
--- | --- | --- | ---
robot_ops_play_plan | id | planId | 播放方案 ID。
robot_ops_play_plan | plan_name | planName | 播放方案名称。
robot_ops_play_plan | loop_mode | loopMode | 循环方式，建议支持 loop、once；一期默认 loop。
robot_ops_play_plan | status | enabled 判断依据 | status=1 表示当前播放方案。
robot_ops_play_plan | update_time | version | 可使用更新时间生成版本号，用于前端判断播放方案是否变化。
robot_ops_play_plan_item | id | itemId / id | 播放方案明细 ID。
robot_ops_play_plan_item | asset_id | assetId | 关联素材 ID。
robot_ops_play_plan_item | play_order | sort | 播放顺序，按升序返回。
robot_ops_play_plan_item | stay_seconds | staySeconds / duration | 图片停留秒数；duration = staySeconds × 1000。
robot_ops_media_asset | asset_name | title | 素材名称。
robot_ops_media_asset | asset_type | type | 素材类型，转换为 image 或 video。
robot_ops_media_asset | file_url | url | 素材文件地址，后端需补全为屏幕端可直接访问的完整 URL。
robot_ops_media_asset | thumbnail_url | thumbnailUrl | 缩略图地址，可为空。
robot_ops_media_asset | status | 过滤依据 | 只有启用状态素材可被屏幕端播放。

#### 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`。

数据库 file_url 示例 | 接口返回 url 示例 | 处理规则
--- | --- | ---
`http://192.168.0.30/profile/upload/a.mp4` | `http://192.168.0.30/profile/upload/a.mp4` | 已是完整 URL，原样返回。
`/profile/upload/a.mp4` | `http://192.168.0.30/profile/upload/a.mp4` | 使用资源访问前缀拼接。
`profile/upload/a.mp4` | `http://192.168.0.30/profile/upload/a.mp4` | 补充斜杠后再拼接。

建议后端将资源访问前缀配置化，例如 `screen.resource-base-url=http://192.168.0.30`，避免硬编码到业务代码中。

#### 13.1.5 返回示例

{ "code": 200, "msg": "查询成功", "data": { "enabled": true, "planId": 1, "planName": "默认播放方案", "loopMode": "loop", "defaultFitMode": "cover", "version": "20260513153000", "items": [ { "id": 1001, "itemId": 1001, "assetId": 501, "type": "image", "title": "欢迎宣传图", "url": "http://192.168.0.30/profile/upload/2026/05/welcome.png", "thumbnailUrl": "http://192.168.0.30/profile/upload/2026/05/welcome.png", "duration": 8000, "staySeconds": 8, "fitMode": "cover", "showTitle": false, "sort": 1 }, { "id": 1002, "itemId": 1002, "assetId": 502, "type": "video", "title": "机器人介绍视频", "url": "http://192.168.0.30/profile/upload/2026/05/robot-intro.mp4", "thumbnailUrl": "http://192.168.0.30/profile/upload/2026/05/robot-intro-cover.jpg", "duration": null, "staySeconds": null, "fitMode": "cover", "muted": false, "showTitle": false, "sort": 2 } ] }, "timestamp": "2026-05-13 15:30:00" }

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

{ "code": 200, "msg": "暂无当前播放方案", "data": { "enabled": false, "planId": null, "planName": "", "loopMode": "loop", "defaultFitMode": "cover", "version": "", "items": [] }, "timestamp": "2026-05-13 15:30:00" }

#### 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 播放方案更新检查策略

场景 | 处理策略 | 说明
--- | --- | ---
进入待机页 | 立即请求当前播放方案接口 | 确保屏幕端启动或从业务页面返回待机时读取最新播放配置。
待机播放中 | 每 60 秒请求一次 `/robot-ops/screen/play-plan/current` | 一期不单独增加 version 接口，直接轮询 current 接口即可。
version 未变化 | 不重置播放进度 | 避免图片/视频被无意义重播或闪烁。
version 变化 | 当前素材结束后切换新方案 | 图片在本次 duration 结束后切换；视频在 ended 后切换。
方案被取消或素材为空 | 当前素材结束后回退默认欢迎页 | 避免播放过程中突兀黑屏或直接中断。

后续如需降低接口数据量，可扩展轻量版本检查接口 `GET /robot-ops/screen/play-plan/version`。屏幕端每 30-60 秒请求 version，只有版本变化时再请求 current 完整播放方案。一期建议先使用 current 接口轮询，降低前后端联调复杂度。

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

本接口供机身屏 `/idle` 待机页获取当前播报状态。前端根据 broadcasting 判断是否显示播报浮层，并暂停或恢复当前素材播放。

#### 13.2.1 接口基本信息

项 | 设计内容
--- | ---
接口地址 | `GET /robot-ops/screen/broadcast/current`
接口用途 | 供机身屏 `/idle` 待机页获取当前播报状态。前端根据 broadcasting 判断是否显示播报浮层、播放 MP3，并暂停或恢复当前素材播放。
数据来源 | 运维端播报内容管理与播报任务管理。后端关联播报任务和播报内容后，生成 MP3 并返回当前播报文本和音频地址。
轮询频率 | 一期建议待机页每 2 秒轮询一次。
TTS 职责 | 后端负责播报文本转 MP3、音频缓存、任务命中判断和音频地址返回；屏幕端负责根据 audioUrl 播放 MP3、展示播报浮层、暂停和恢复当前素材播放。
生效范围 | 一期优先只在 `/idle` 待机页执行播报插播；访客登记、路线引导等业务办理页面暂不强制打断。

#### 13.2.2 数据来源与字段映射

来源表 | 来源字段 | 接口字段 | 说明
--- | --- | --- | ---
robot_ops_broadcast_task | id | taskId | 播报任务 ID。
robot_ops_broadcast_task | task_name | taskName | 播报任务名称。
robot_ops_broadcast_task | content_id | contentId | 关联播报内容 ID。
robot_ops_broadcast_task | start_time | startTime | 本次播报开始时间。
robot_ops_broadcast_task | end_time、frequency_minutes、cycle_type、cycle_value、status | 后端判断依据 | 由后端根据任务规则判断是否命中当前播报，前端不参与计算。
robot_ops_broadcast_content | content_name | title | 播报标题。
robot_ops_broadcast_content | content_type | contentType | 播报分类，例如通知、宣传、提示、安防提醒、自定义。
robot_ops_broadcast_content | broadcast_text | content | 播报文本，用于屏幕展示，并由后端调用第三方 TTS 生成 MP3。
robot_ops_broadcast_content | status | 过滤依据 | 只有启用状态的播报内容可被任务触发。

#### 13.2.3 有播报返回示例

{ "code": 200, "msg": "查询成功", "data": { "broadcasting": true, "taskId": 12, "contentId": 35, "taskName": "大厅整点提醒", "title": "参观提醒", "content": "欢迎各位来宾参观，请按照现场工作人员引导有序通行。", "contentType": "notice", "level": "normal", "audioUrl": "http://192.168.0.30/profile/audio/broadcast/35_abc123.mp3", "audioDuration": 20.5, "playMode": "once", "startTime": "2026-05-18 16:30:00", "estimatedEndTime": "2026-05-18 16:30:20", "version": "20260518163000" }, "timestamp": "2026-05-18 16:30:01" }

#### 13.2.4 无播报返回示例

{ "code": 200, "msg": "当前无播报", "data": { "broadcasting": false, "taskId": null, "contentId": null, "taskName": "", "title": "", "content": "", "contentType": "", "level": "normal", "audioUrl": "", "audioDuration": null, "playMode": "once", "startTime": null, "estimatedEndTime": null, "version": "20260518163100" }, "timestamp": "2026-05-18 16:31:00" }

#### 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 文件生成与复用规则

场景 | 处理规则 | 说明
--- | --- | ---
首次播报 | 调用第三方 TTS 生成 MP3 | 生成完成后保存本地文件，并记录音频路径、访问 URL、时长、Hash 和生成状态。
重复播报相同内容 | 复用已生成 MP3 | 避免每次播报都请求第三方 TTS，降低成本和延迟。
播报文本修改 | 重新生成 MP3 | 文本变化后 Hash 变化，旧音频失效。
音色/语速/音量/供应商参数修改 | 重新生成 MP3 | 同一文本在不同语音参数下应视为不同音频。
本地音频文件丢失 | 重新生成 MP3 | 数据库有记录但文件不存在时应自动补偿生成。
MP3 播放失败 | 屏幕端记录失败并恢复素材播放 | 不应阻塞待机素材播放，后续可通过事件上报或运行日志记录。
TTS 生成失败 | 后端记录失败状态和错误信息 | 不返回可播放 audioUrl，屏幕端不进入播报播放状态。

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

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

一期如后端需要确认屏幕端实际播放完成，可提供 POST `/robot-ops/screen/broadcast/ack`。屏幕端在 audio ended 后上报 success，在 audio error 后上报 failed。若一期暂不做 ack，后端可根据播报窗口或 estimatedEndTime 结束播报状态。

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

阶段 | 开发内容 | 目标
--- | --- | ---
第一阶段 | Vue3 工程、路由、布局、状态栏、全局样式、Mock 数据框架 | 建立屏幕端前端基础工程。
第二阶段 | 待机展示页、默认欢迎模式、播放方案模式、本地素材 Mock、图片/视频播放器、当前播放方案接口、欢迎页兜底、无操作返回待机 | 前端已收口；下一步由后端提供 `/robot-ops/screen/play-plan/current` 接口，跑通运维端素材与播放方案到机身屏播放链路。
第三阶段 | 主菜单页、上方欢迎引导、2×2 大触摸入口、返回待机按钮、图标与文案优化 | 已完成前端收口，后续重点进入访客登记流程开发。
第四阶段 | 访客登记、预约核验、身份证读取 Mock、数字键盘 | 完成核心登记流程。
第五阶段 | 路线引导正式前端流程、目的地 Mock、导航状态 Mock | 完成路线引导演示闭环。
第六阶段 | 当前播报状态接口、播报浮层、素材暂停/恢复、通知公告列表、声音/静音控制 | 优先跑通运维端播报内容与播报任务到机身屏插播展示链路。
第七阶段 | 语音指令轮询 Mock、人脸识别结果 Mock、全局异常提示 | 完成事件驱动页面跳转能力。
第八阶段 | 隐藏系统信息页、屏幕刷新、版本展示 | 补充现场维护辅助能力。

## 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 启动建议

chromium-browser \ --kiosk \ --noerrdialogs \ --disable-infobars \ --disable-session-crashed-bubble \ http://127.0.0.1/screen

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

### 17.2 开机自启建议

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

### 17.3 前端包更新建议

上传 screen-ui-vX.X.X.zip ↓ 备份旧版本目录 ↓ 解压覆盖新版本 dist ↓ 刷新 Chromium 页面或重启 Chromium ↓ 异常时回滚旧版本

### 17.4 现场维护信息建议

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

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

事项 | 当前处理 | 后续方向
--- | --- | ---
呼叫工作人员真实方式 | 一期保留按钮和占位交互。 | 可接入运维端消息、主控平台通知、语音/视频通话。
真实导航接口 | 一期使用 Mock 数据。 | 对接点位列表、导航开始、导航状态、取消导航接口。
Ubuntu 中文输入体验 | 一期数字输入内置键盘，中文输入暂依赖系统软键盘或预置选项。 | 结合现场系统环境优化软键盘或减少自由文本输入。
WebSocket/SSE 推送 | 一期 HTTP 轮询。 | 后续升级为 WebSocket 或 SSE。
竖屏适配 | 一期按 1024×768 横屏开发。 | 屏幕选型确定后专项适配。
屏幕端 OTA | 一期可手动部署 dist 包。 | 后续纳入运维端 OTA 升级模块。
播报 TTS 实现方式 | 文档建议由小主机后端调用 TTS/语音服务。 | 后续确认 TTS 服务地址、播放完成回调、音频抢占规则。
摄像头预览流格式 | 文档建议仅在识别相关页面展示。 | 后续确认 RTSP、HTTP-FLV、WebRTC 或 MJPEG 等实现方式。
呼叫工作人员闭环 | 一期占位。 | 后续确认是通知运维端、现场终端、语音通话还是视频通话。