迎宾巡逻安防机器人运维端 Web 管理系统详细设计开发文档（一期）

文档用途：作为运维端、机器人端、主控平台侧的统一开发基线文档，直接用于产品评审、数据库设计、接口开发、前后端开发与测试联调。

文档原则：本版以运维端需求为主导进行定义，未定事项按本文直接定版，后续由机器人侧与其他团队按本文配合实现。

技术基线：RuoYi + Vue3文档级别：详细设计开发版单机器人本地部署局域网 IP + 端口访问

1. 项目定位与约束 2. 用户角色与使用目标 3. 系统边界与设计原则 4. 总体功能架构 5. 菜单结构设计 6. 页面详细设计 7. 后端接口设计 8. 数据库表设计 9. 状态、日志与控制规则 10. 权限与账号设计 11. 开发优先级与实施顺序 12. 其他团队配合要求 13. 测试验收要点

1. 项目定位与约束

本系统为迎宾巡逻安防机器人本地运维 Web 管理系统。系统部署在单台机器人本体，运维人员通过局域网访问机器人 IP + 端口进入后台，进行机器人状态查看、内容配置、参数设置、日志诊断、版本升级与基础维护。

本系统不是云端总控平台，不承担多机器人统一调度，也不承担上级业务平台的任务编排、访客预约发起、巡逻策略制定等核心业务能力。

1.1 核心建设目标

本地可维护
不依赖云端也可完成机器人基础配置、升级、日志查看与简单控制。

内容可配置
欢迎语、问答库、多媒体、播报任务、展示主题等均在本地后台完成维护。

运维可闭环
首页看状态、模块看详情、日志可排查、版本可升级、问题可定位。

1.2 一期定版原则

凡是前期沟通中已经提到或建议过的功能，一期直接定版，不因外部团队尚未实现而弱化设计。
对机器人侧、主控平台侧、展示端存在依赖的地方，本文先定义目标能力，再要求对方配合提供接口或实现。
后续若因为硬件、算法或平台限制产生调整，应基于本文迭代版本，而不是回退为概要需求。

2. 用户角色与使用目标

角色	主要职责	核心使用模块
管理员	系统初始化、账号维护、全量配置、升级控制	全部模块
运维人员	日常维护、配置调整、排障处理、日志查看	首页、内容管理、运维管理
交付实施人员	现场交付、基础内容录入、播放方案配置、主题设置	首页、内容管理、系统设置
售后支持人员	远程辅助定位问题、指导升级、查看状态	首页、运维管理
查看人员	仅查看运行状态和记录，不执行配置和控制操作	首页、访客记录、对话日志、告警日志

2.1 典型使用目标

场景 A：现场交付初始化

接入机器人局域网
通过 IP + 端口访问后台
登录管理员账号
配置欢迎语、问答库、展示主题
上传多媒体素材并配置播放方案
配置播报内容与定时任务

场景 B：日常运维排查

查看机器人电量、运行状态、告警信息
查看摄像头画面并进行远程喊话
查看对话日志、访客记录、安防告警记录
导出需要的记录或日志
按需进行重启、充电等简单操作

3. 系统边界与设计原则

3.1 本系统负责内容

本地登录机器人状态查看设备简单控制欢迎语配置问答库管理素材管理播放方案管理播报内容管理播报任务管理展示主题配置访客记录查看导出预约记录查看白名单管理视频预览远程喊话对话日志安防告警日志参数配置运行日志版本管理与 OTA

3.2 本系统不负责内容

多机器人管理和云端总控。
建图、路径编辑、巡逻任务编排等导航管理页面。
安防算法逻辑本身，例如跌倒检测、越界检测的算法实现。
访客预约发起、被访人确认、通行权限下发等上层业务流程。

地图与路径功能虽然属于机器人能力的重要组成部分，但本期由其他团队负责，不纳入本 HTML 文档页面和表设计范围。

3.3 设计原则

页面先按清晰可开发的业务模块定型，不采用“待定”“后续再说”的写法作为主体内容。
对动态参数、动态日志等场景，采用“页面结构固定 + 数据内容动态”的设计方式。
列表页统一遵循：查询区 + 操作区 + 表格区 + 分页区 + 详情弹窗 / 编辑弹窗。
高风险动作统一弹窗二次确认，并写入操作日志。

4. 总体功能架构

首页

运行总览
设备状态
视频预览
远程喊话
设备控制
统计信息
异常告警
最近记录

内容管理

欢迎语配置
问答库管理
素材管理
播放方案管理
播报内容管理
播报任务管理
展示主题配置

访客管理

访客记录
预约记录
白名单管理

运维管理

运行参数配置
运行日志
对话日志
安防告警日志
软件版本 / OTA 升级

系统设置

账号管理
修改密码
基础设置

5. 菜单结构设计

一级菜单	二级菜单	页面职责	一期优先级
首页	首页总览	展示机器人实时状态、视频预览、远程喊话、设备快捷控制、摘要统计、异常告警与最近记录。	P0
内容管理	欢迎语配置	维护机器人默认欢迎语和触发控制参数。	P0
	问答库管理	维护 FAQ 问答数据，支持字典分类、相似问、导出；一期暂不支持导入。问答分类使用 RuoYi 字典，不单独建设问答分类管理菜单。	P0
	素材管理	维护图片、视频素材。	P0
	播放方案管理	维护素材播放编排关系、时长、顺序和当前播放方案。	P0
	播报内容管理	维护可被播报任务引用的播报文本模板。	P0
	播报任务管理	维护播报时间策略、频率、启停状态。	P0
	展示主题配置	维护机器人屏幕待机页的展示内容，包括 Logo、品牌文案、背景图、欢迎文案、按钮文案和按钮颜色。	P1
访客管理	访客记录	查看访客登记记录，支持查询、详情、导出。	P1
	预约记录	查看主控平台同步的预约记录。	P1
	白名单管理	维护人员白名单数据，支持通过人脸照片、身份证号、手机号进行白名单匹配。	P1
运维管理	运行参数配置	动态读取参数分组与字段，支持编辑与保存。	P0
	运行日志	查看机器人设备侧上报的运行日志、服务日志、异常报错日志和关键模块日志。	P0
	对话日志	查看人机交互日志。	P1
	安防告警日志	查看机器人侧安防告警记录。	P1
	软件版本 / OTA 升级	查看版本、上传安装包、执行升级、查看升级记录。	P0
系统设置	账号管理	维护后台账号、角色、状态。	P1
	修改密码	当前登录账号修改密码。	P0
	基础设置	维护系统名称、Logo、页脚信息等后台基础配置。	P2

5.1 RuoYi 代码生成与定制开发划分

本项目基于 RuoYi + Vue3 开发。RuoYi 代码生成器适合根据数据库表快速生成常规列表页、表单页、Controller、Service、Mapper 等基础 CRUD 代码；但对于首页大屏式总览、实时视频、远程控制、OTA 进度、动态参数表单、播放编排等交互复杂页面，仍需要 Cursor 或开发人员进行定制化开发。

一级菜单	页面/模块	开发方式建议	是否适合 RuoYi 代码生成	说明
首页	首页总览	定制开发	否	首页涉及机器人实时状态、设备状态、视频预览、远程喊话、设备快捷控制、统计卡片、告警摘要和最近记录，属于聚合工作台页面，不能直接按单表 CRUD 生成。
内容管理	欢迎语配置	定制开发	不建议生成前端列表页	欢迎语配置为单配置页，不是多条数据 CRUD 页面。数据库通过 config_key=default 定位默认配置；前端建议自定义表单页，直接加载和保存默认配置，不提供列表、新增、删除。
	问答库管理	RuoYi 主子表生成后定制	部分适合	可基于 robot_ops_faq、robot_ops_faq_similar 生成基础 CRUD；问题分类使用 RuoYi 字典 robot_faq_category，不单独生成问答分类管理页面；前端需将主子表明细表格调整为“相似问多行输入，一行一个”的交互方式；sortNo 作为保留字段，不在页面展示和编辑；启用/停用、导出、分类字典回显需按业务微调。一期暂不支持问答库导入，后续如运营需要批量维护再扩展。
	素材管理	RuoYi 生成后定制	部分适合	可基于 robot_ops_media_asset 生成基础列表、查询、详情、编辑、删除、导出接口和页面；当前前端已基于 RuoYi 接口和 /common/uploadMediaFile 上传接口完成定制。前端只允许用户维护素材名称、启用状态和备注，文件信息由上传接口返回或系统维护；缩略图展示、图片/视频预览、引用状态展示、删除引用保护提示均需定制。
	播放方案管理	RuoYi 主子表生成后定制	部分适合	播放方案由主表 robot_ops_play_plan 和子表 robot_ops_play_plan_item 组成，适合先使用 RuoYi 主子表生成基础列表、表单、Controller、Service、Mapper，再进行定制。前端需将原始子表表格调整为“选择素材 + 素材编排”交互，支持素材选择、顺序调整、图片停留时长、视频默认播完切换、播放状态切换、预览方案。播放状态 status=1 表示当前播放方案，status=0 表示备用方案；同一时间只允许一个播放方案处于当前播放状态，该规则需由后端事务控制。素材 quotedFlag 维护需由后端补充业务逻辑。
	播报内容管理	RuoYi 生成后微调	适合	典型单表 CRUD，可基于 robot_ops_broadcast_content 生成，再补充测试播报按钮。
	播报任务管理	RuoYi 生成后定制	部分适合	基础 CRUD 可生成；时间段、频率、循环规则、复制任务等需要定制表单校验和交互。
	展示主题配置	RuoYi 生成后改造成单配置页	部分适合	本模块一期按“待机页展示配置”设计，为单配置页，不做列表、新增、普通删除、多主题切换和启用状态；仅保留“清空配置”能力，用于删除当前 config_key=default 的运维端覆盖配置。后端可先基于 robot_ops_screen_theme_config 使用 RuoYi 生成基础 CRUD，再改造成按 config_key=default 查询和保存的接口；前端建议参考欢迎语配置页面定制为单配置表单页。页面字段包括 Logo 图片、品牌标题、品牌副标题、背景图、欢迎主标题、欢迎副标题、按钮文案、按钮颜色和备注。一期不做预览页面，后续如有需要再扩展待机页预览。
访客管理	访客记录	RuoYi 生成后定制	部分适合	可基于 robot_ops_visitor_record 生成只读列表和详情页面；需去掉新增、编辑、删除，补充到访类型、登记方式、访客来源、来访事由、照片预览、时间范围查询、详情弹窗和导出字段优化。列表中访客照片前置到身份证号后，便于快速识别访客身份。
	预约记录	RuoYi 生成后微调	适合	典型查询列表和详情页面，可基于 robot_ops_appointment_record 生成，数据来源为主控平台同步。
	白名单管理	RuoYi 生成后定制	部分适合	可基于 robot_ops_whitelist 生成基础 CRUD；需补充身份证号、人脸照片上传/预览、有效期、人员类型、启用/停用、导入导出，以及手机号/身份证号/人脸照片至少填写一种的表单校验。
运维管理	运行参数配置	定制开发	否	虽然有 robot_ops_param 表，但页面需要根据参数分组和值类型动态渲染表单控件，不能直接按固定 CRUD 页面生成。
	运行日志	RuoYi 生成后微调	适合	运行日志页面用于查看机器人设备侧上报的运行日志、服务日志、异常报错日志和关键模块日志。页面以查询、列表、详情、导出为主，不做主动诊断、立即自检和诊断项配置，可基于 robot_ops_sys_log 生成后微调。
	对话日志	RuoYi 生成后微调	适合	典型日志查询和详情页面，可基于 robot_ops_dialogue_log 生成，详情页需展示原始请求和原始响应。
	安防告警日志	RuoYi 生成后微调	适合	典型日志查询页面，可基于 robot_ops_alarm_log 生成，再补充确认告警、忽略告警、抓拍图预览。
	软件版本 / OTA 升级	定制开发	否	升级包列表和升级记录可参考生成代码，但上传安装包、执行升级、进度刷新、结果展示属于流程型页面，需要定制开发。
系统设置	账号管理	优先复用 RuoYi	视权限方案而定	如果使用 RuoYi 原生权限体系，优先复用系统用户、角色、菜单管理；如果采用本文简化账号表，可基于 robot_ops_user 生成后微调。
	修改密码	复用/定制均可	否	修改密码通常复用 RuoYi 用户中心能力，不建议按表生成单独 CRUD 页面。
	基础设置	半定制开发	部分适合	可基于 robot_ops_system_config 生成基础表单，但页面更接近单配置页，需定制保存逻辑。

开发建议：先使用 RuoYi 代码生成器生成“适合/部分适合”的基础列表、表单和后端 CRUD，再由 Cursor 或开发人员根据第 6 章页面设计、第 7 章接口设计进行二次调整。标记为“定制开发”的页面不要强行套用单表 CRUD 模板，否则后续返工成本较高。

6. 页面详细设计

6.1 登录页

项	详细设计
页面目标	本地后台登录入口，控制未授权用户访问。
展示字段	账号、密码、登录按钮、错误提示文案、系统标题、系统 Logo。
操作按钮	登录。
校验规则	账号不能为空；密码不能为空；连续输错密码 5 次锁定 10 分钟。
登录成功动作	写入 token / session，跳转首页。
登录失败动作	显示失败原因；账号或密码错误时不暴露具体哪个字段错误。

6.2 首页 / 工作台

首页按顶部状态区 + 视频预览区 + 远程喊话区 + 设备控制区 + 统计区 + 告警区 + 最近记录区进行设计。

首页中的机器人基础信息、实时运行状态、资源占用状态、模块状态等数据由机器人侧接口实时返回，运维端一期不建设机器人基础信息表和设备状态快照表。

本期将原计划作为独立菜单的“视频预览、远程喊话、设备状态、设备控制”合并到首页工作台中。首页承担机器人实时查看和高频控制入口；监控管理一级菜单已取消，对话日志和安防告警日志合并到运维管理菜单；运维管理保留参数配置、运行日志和 OTA 等维护类页面。

6.2.1 顶部状态与设备状态区字段

字段	说明	展示形式
机器人名称（robotName）	机器人名称	文本
机器人编号（robotCode）	机器人编号	文本
在线状态（onlineStatus）	在线状态：在线/离线	状态标签
工作状态（workStatus）	工作状态：空闲/接待中/播报中/充电中/异常	状态标签
电量百分比（batteryLevel）	电量百分比	进度条 + 文本
充电状态（chargeStatus）	充电状态：未充电/充电中/充满	状态标签
网络状态（networkStatus）	网络状态：正常/异常	状态标签
设备本地 IP（ipAddress）	设备本地 IP	文本
存储占用情况（storageUsed）	存储占用情况	文本，例如 18.3GB / 64GB
系统主版本号（currentVersion）	系统主版本号	文本

6.2.2 视频预览区

区域	详细设计
播放器区域	展示机器人摄像头实时画面，支持播放、刷新、全屏。视频流地址、播放状态等由机器人侧实时接口返回，运维端一期不单独建设视频配置表。
状态区域	展示视频状态：未连接、连接中、播放中、失败。播放失败时提示刷新、检查摄像头服务、检查网络。
辅助信息	显示码流类型、分辨率、最近更新时间等信息。
操作按钮	刷新、全屏、重新连接。

6.2.3 远程喊话区

区域	详细设计
页面目标	提供运维人员通过电脑麦克风对机器人进行实时远程喊话的入口。远程喊话不是文字转语音播报，不与播报内容、播报任务模块重复。
麦克风按钮	页面中心展示大号麦克风按钮。点击后开始远程喊话，再次点击结束喊话。当前前端一期可先模拟状态，后续对接浏览器麦克风采集和机器人端音频播放能力。
连接状态	展示远程喊话通道状态，包括未连接、准备就绪、正在喊话、已结束、连接失败等。
音量控制	提供扬声器音量设置，取值范围 0-100，默认 70。后续对接机器人端音量控制接口。
操作按钮	连接设备、结束喊话。连接设备用于建立远程喊话通道；结束喊话用于停止当前喊话。
业务边界	远程喊话用于实时语音对讲/喊话；播报内容和播报任务用于文本播报、定时播报和固定内容播报。两者功能边界不同，不建议在远程喊话中提供文本输入、预置短语和播放次数。

6.2.4 设备控制区

控制项	说明	返回字段
一键充电	触发机器人进入充电流程	任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）
停止充电	停止当前充电动作	任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）
重启机器人	执行整机重启	任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）
关机	执行安全关机	任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）
控制记录	所有控制动作统一写入设备控制记录表和操作日志，便于追踪 taskId、执行结果和失败原因。	控制记录ID（controlRecordId）、任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）

6.2.5 统计区字段

字段	说明	点击跳转
今日访客登记数量（todayVisitorCount）	今日访客登记数量	访客记录
今日预约记录数量（todayAppointmentCount）	今日预约记录数量	预约记录
今日对话次数（todayDialogueCount）	今日对话次数	对话日志
今日播报次数（todayBroadcastCount）	今日播报次数	播报任务
今日安防告警数量（todayAlarmCount）	今日安防告警数量	安防告警日志
今日运维操作次数（todayOperateCount）	今日运维操作次数	运行日志

6.2.6 告警与最近记录

区块	内容
最近系统异常	最近 5 条系统异常摘要，点击跳运行日志。
最近安防告警	最近 5 条安防告警摘要，点击跳安防告警日志。
最近升级失败	最近 5 条升级失败摘要，点击跳 OTA 升级页。
最近记录与跳转入口	展示最近访客、最近对话、最近安防告警、最近升级失败等记录，点击跳转对应日志或管理页面。视频预览、远程喊话和设备控制已作为首页独立功能区展示。

6.3 内容管理

6.3.1 欢迎语配置页面

字段/功能	类型	详细设计
页面目标	-	维护机器人默认欢迎语配置。该页面为单配置页，不提供列表、新增、删除；页面打开后直接加载 config_key=default 的默认配置，保存时更新该配置。
欢迎语文本（welcomeText）	textarea	欢迎语文本，最大 200 字。
语音播报（voiceEnabled）	switch	控制欢迎语触发时是否进行语音播报。启用后，机器人检测到访客时可语音播报欢迎语；关闭后，欢迎语可仅用于屏幕展示。
语音播报冷却时间（cooldownSeconds）	number	控制语音欢迎语的重复播报间隔，单位秒，默认 30。机器人语音播报欢迎语后，在冷却时间内再次检测到访客时，不重复语音播报，可仅进行屏幕展示。
启用欢迎语（status）	switch	控制欢迎语功能整体是否启用。停用后，机器人检测到访客时不触发欢迎语。
备注（remark）	input	备注说明。
保存	button	保存当前配置（更新 config_key=default 的配置）。
恢复默认	button	前端本地恢复系统默认欢迎语配置，不直接写入数据库；用户需再次点击“保存配置”后才更新 config_key=default 的配置。
测试播报	button	下发测试播报指令，用于验证当前欢迎语文本和语音播报配置。测试播报不新增或修改配置数据。

6.3.2 问答库管理页面

模块	详细设计
页面目标	维护机器人 FAQ 问答内容，支持按问题分类管理标准问题、相似问和答案内容。页面基于 robot_ops_faq 主表和 robot_ops_faq_similar 相似问表实现，前端以一个“问答库管理”页面统一维护，不单独建设相似问管理菜单。
查询条件	问题分类（categoryType，数据来源：RuoYi 字典 robot_faq_category）、标准问题关键字、启用状态。
列表字段	问题分类、标准问题、相似问数量、答案摘要、启用状态、更新时间、操作。
操作按钮	新增、编辑、删除、批量删除、启用/停用、导出。
编辑弹窗字段	问题分类（categoryType，RuoYi 字典 robot_faq_category）、标准问题（question）、相似问（similarQuestions）、答案内容（answer）、启用状态（status）、备注（remark）。
相似问交互	相似问使用多行文本框维护，一行一个相似问；保存时前端转换为相似问列表，后端写入 robot_ops_faq_similar 表。
答案内容规则	答案内容最多 2000 字，列表中只展示答案摘要，完整答案在编辑弹窗中维护。
排序规则	sortNo / sort_no 作为保留字段，数据库继续保留；前端页面一期不展示、不编辑。新增问答时默认 sortNo=0，编辑问答时保持原值。后续如需在机器人屏幕端展示推荐问答或人工排序，再重新设计推荐/置顶/排序能力。
业务规则	同一分类下标准问题建议不重复，新增和编辑时由后端进行重复校验。删除主问答时，应同步删除其相似问数据。
导入说明	问答库一期暂不支持导入。后续如运营确实需要批量维护问答内容，再单独扩展 Excel 导入模板、问题分类匹配、相似问拆分、重复校验和失败明细回显能力。

6.3.3 素材管理页面

模块	详细设计
页面目标	维护机器人展示、播放方案等功能使用的图片和视频素材。素材管理可基于 RuoYi 生成基础列表和表单，再定制上传、缩略图展示、图片/视频预览、启用/停用、引用状态和删除保护能力。
查询条件	素材名称、素材类型、启用状态、上传时间范围。
列表字段	缩略图（thumbnailUrl）、素材名称（assetName）、素材类型（assetType）、文件格式（fileFormat）、文件大小（fileSize）、视频时长（durationSeconds）、分辨率（resolution）、上传时间（createTime）、引用状态（quotedFlag）、启用状态（status）、操作。
操作按钮	上传素材、预览、编辑、删除、启用/停用、批量删除。
编辑字段	用户只允许维护素材名称（assetName）、启用状态（status）、备注（remark）。文件地址、缩略图、文件大小、文件格式、MIME 类型、视频时长、分辨率、引用状态等信息由上传接口返回或系统维护，前端只读展示，不允许用户手动填写。
素材类型	素材类型 assetType 为业务类型，建议使用 RuoYi 字典 media_asset_type，字典项：image=图片，video=视频。素材类型可由上传接口根据文件 MIME 类型或后缀自动判断。
文件信息	fileUrl 为素材文件访问地址；thumbnailUrl 为缩略图地址，图片可等于 fileUrl，视频只有后端返回 thumbnailUrl 时才展示封面，否则前端显示默认视频图标；fileSize 为文件大小，单位字节；fileFormat 为文件格式/后缀；mimeType 为文件 MIME 类型；resolution 为分辨率；durationSeconds 为视频时长，图片素材为空。resolution、durationSeconds 允许为空。
上传规则	图片支持 jpg/png/webp；视频支持 mp4；单文件大小默认上限 500MB。当前前端实际调用 /common/uploadMediaFile 上传素材文件，上传成功后回填 fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、assetType 等字段。若部分字段为空，前端按默认图标或“-”兜底展示。
引用状态	quotedFlag 表示素材是否被播放方案引用，由系统维护，前端只读展示，不允许编辑。删除素材时，后端必须检查播放方案明细表中的实际引用关系，不应仅依赖 quotedFlag。
引用保护	被播放方案引用的素材不可直接删除，需先解除引用。接口应返回明确提示，例如“该素材已被 2 个播放方案引用，请先解除引用后再删除”。
预览规则	图片弹窗预览；视频弹窗播放器预览；视频无缩略图时，列表展示默认视频图标；无法播放时提示格式不支持。
业务规则	启用状态为启用的素材可被新播放方案选择；停用素材不可被新播放方案选择，但历史播放方案已引用的停用素材仍需支持回显。

6.3.4 播放方案管理页面

模块	详细设计
页面目标	维护机器人屏幕播放使用的素材编排方案。一个播放方案由主表信息和多个素材明细组成，素材来源于素材管理模块。
开发方式	基于 RuoYi 主子表生成基础页面和接口，主表 robot_ops_play_plan，子表 robot_ops_play_plan_item，关联字段 plan_id。生成后前端需要定制为“选择素材 + 素材编排”的交互方式。
查询条件	方案名称、循环方式（loopMode）、播放状态（status）。
列表字段	方案名称（planName）、循环方式（loopMode）、素材数量（assetCount）、播放状态（status）、更新时间（updateTime）、操作。
主表编辑字段	方案名称（planName）、循环方式（loopMode）、播放状态（status）、备注（remark）。播放状态 status=1 表示当前播放，status=0 表示备用方案。
素材明细字段	素材ID（assetId）、播放顺序（playOrder）、停留时长（staySeconds）、转场方式（transitionType，预留字段，默认 none）。素材名称、素材类型、文件地址、缩略图、视频时长、分辨率等展示字段不在明细表中冗余保存，由后端根据 assetId 关联 robot_ops_media_asset 返回。
素材选择	新增素材明细时，通过“选择素材”弹窗从素材库选择启用状态的素材。前端保存时只提交 assetId、playOrder、staySeconds、transitionType 等播放编排字段；素材名称、素材类型、文件地址、缩略图、视频时长等信息由后端查询详情或预览时关联素材表返回。
素材编排	播放方案明细支持上移、下移或拖拽排序。保存时根据当前顺序重新生成 playOrder。
图片播放规则	当 assetType=image 时，staySeconds 必填，建议默认 10 秒，取值范围 1-3600 秒。
视频播放规则	当 assetType=video 时，staySeconds 可为空，表示按视频自身播放。一期不做视频截断播放逻辑。
转场方式	transitionType 作为预留字段，一期前端不展示、不编辑，默认值为 none。后续车端屏幕支持转场效果后，再开放配置，例如 none=无转场、fade=淡入淡出。
操作按钮	新增、编辑、删除、启用播放、设为备用、预览。
播放状态规则	status=1 表示当前播放方案，status=0 表示备用方案。同一时间只允许一个播放方案 status=1。启用某个方案为当前播放时，后端应在事务中将其他方案 status 置为 0，将当前方案 status 置为 1。车端只读取 status=1 的播放方案。
删除规则	删除方案时需要同步删除其素材明细，并重新计算相关素材的 quotedFlag。如删除当前播放方案，可能导致车端无可播放方案，建议后端根据实际业务策略进行限制或提示。
素材引用规则	播放方案新增、编辑、删除后，后端需要重新计算相关素材的 quotedFlag。只要素材被任意播放方案明细引用，则 quotedFlag=1；不再被任何播放方案引用，则 quotedFlag=0。
预览规则	一期前端已基于播放方案详情接口实现预览弹窗。点击“预览”后，前端调用详情接口获取方案信息和素材明细，按 playOrder 顺序展示播放清单；左侧展示当前素材的大图或视频播放器，右侧展示播放清单，支持上一个、下一个和点击清单切换。图片按 staySeconds 展示停留时长；视频使用 fileUrl 播放，默认播完后切换到下一个素材。若后续后端提供独立 preview 接口，可仅替换预览数据源，页面结构无需大改。
业务规则	新增/编辑时至少选择一个素材。停用素材不可被新播放方案选择，但历史方案中已引用的停用素材仍需支持回显。
素材信息回显	播放方案详情、编辑回显和预览接口需要关联 robot_ops_media_asset 返回素材展示信息，包括 assetName、assetType、fileUrl、thumbnailUrl、durationSeconds、resolution、assetStatus 等。明细表本身不保存这些快照字段。

字典建议：loopMode 可使用 RuoYi 字典 play_plan_loop_mode，字典项：loop=循环播放，once=播放一次。transitionType 为预留字段，一期不开放配置。

6.3.5 播报内容管理页面

模块	详细设计
查询条件	内容名称、内容分类、启用状态。
列表字段	内容名称、内容分类、播报文本摘要、启用状态、更新时间、操作。
编辑字段	内容名称（contentName）、内容分类（contentType）、播报文本（broadcastText）、启用状态（status）、备注（remark）。
操作按钮	新增、编辑、删除、启用/停用、测试播报。
内容分类	通知、宣传、提示、安防提醒、自定义。

播报内容由运维端维护，机身屏不提供新增、编辑、删除能力。播报内容被播报任务命中后，由后端调用第三方 TTS 生成或复用 MP3 文件，并通过当前播报状态接口返回给机身屏；机身屏根据 audioUrl 播放 MP3、展示播报浮层，并暂停/恢复当前素材播放。

一期 TTS 采用非流式方案：播报文本首次使用时生成 MP3；后续相同文本和相同语音参数重复播报时复用已生成 MP3。若播报文本、音色、语速、音量、TTS 供应商或模型版本发生变化，应重新生成 MP3。

6.3.6 播报任务管理页面

模块	详细设计
查询条件	任务名称、循环类型、启用状态。
列表字段	任务名称、关联内容名称、开始时间、结束时间、播报频率（分钟）、循环类型、循环取值、启用状态、操作。
编辑字段	任务名称（taskName）、关联播报内容（contentId，页面显示内容名称）、开始时间（startTime）、结束时间（endTime）、播报频率分钟数（frequencyMinutes，单位：分钟）、循环类型（cycleType）、循环取值（cycleValue）、启用状态（status）、备注（remark）。
cycleType	使用 RuoYi 字典 `broadcast_task_cycle_type`，字典值：1=按星期，2=按日期。
cycleValue	当 cycleType=1（按星期）时，保存星期值，1=星期一、2=星期二、3=星期三、4=星期四、5=星期五、6=星期六、7=星期日，多个值用英文逗号分隔，例如 1,2,3,4,5。当 cycleType=2（按日期）时，保存指定日期，多个日期用英文逗号分隔，例如 2026-03-20,2026-03-21。
操作按钮	新增、编辑、复制、删除、启用/停用。
校验规则	结束时间必须大于开始时间；frequencyMinutes 必须大于 0，单位为分钟；当循环类型为按星期时，至少选择一个星期；当循环类型为按日期时，至少选择一个指定日期。
交互规则	关联播报内容列表显示内容名称；新增/编辑时仅允许选择启用状态的播报内容；历史任务关联的播报内容如已停用，编辑时仍需可回显，并显示“已停用”提示，但不可重新选择停用内容。

播报任务的时间判断、频率控制、循环规则和重复触发保护由后端负责。任务命中后，后端应更新当前播报运行态，并通过 /robot-ops/screen/broadcast/current 提供给机身屏前端轮询消费；机身屏只负责根据 current 接口返回的 audioUrl 播放 MP3、暂停当前素材、显示播报浮层，并在 MP3 播放结束后恢复播放。

播报任务执行时，后端优先检查播报内容是否已有可用 MP3 文件；若已存在且 Hash 未变化，则直接返回该 MP3 的 audioUrl；若不存在、文件丢失或 Hash 已变化，则先调用第三方 TTS 生成 MP3，再返回新的 audioUrl 给机身屏播放。

6.3.7 展示主题配置页面

模块	详细设计
页面目标	维护机器人屏幕端待机欢迎页的展示内容。该页面为单配置页，不提供列表、新增、普通删除、多主题切换和启用状态；仅提供“清空配置”能力，用于删除当前 config_key=default 的运维端覆盖配置。页面打开后直接加载 config_key=default 的配置。
页面形态	类似欢迎语配置页面，采用单表单配置页。页面由配置表单和操作按钮组成，一期暂不做实时预览页面。
基础说明	本模块只配置待机页中可运营维护的展示内容，包括 Logo、品牌文案、背景图、欢迎文案、按钮文案和按钮颜色。状态、电量、网络、时间日期等动态信息由屏幕端实时展示，不在后台配置。
Logo 图片（logoUrl）	用于配置待机页左上角 Logo 图片。支持上传 png、jpg、jpeg 图片，建议限制 200KB 以内。Logo 颜色由图片自身决定，后台不提供颜色配置；未配置时屏幕端使用本地默认 Logo。
品牌标题（robotName）	用于配置左上角品牌标题，例如“迎宾巡逻机器人”。选填，建议最多 50 字；未配置时屏幕端使用本地默认标题。
品牌副标题（brandSubtitle）	用于配置左上角品牌副标题，例如“智能接待 · 路线引导 · 信息服务”。选填，建议最多 100 字。
背景图（backgroundImage）	用于配置待机页整屏背景图。支持上传 jpg、png、jpeg 图片，建议使用适配屏幕比例的横图，大小建议 2MB 以内。背景适配方式由屏幕端固定处理，后台不提供选择项；未配置时屏幕端使用本地默认背景图。
欢迎主标题（welcomeTitle）	用于配置待机页中间主标题，例如“您好，欢迎光临”。选填，建议最多 50 字；未配置时屏幕端使用本地默认欢迎主标题。该字段用于屏幕展示，不等同于欢迎语配置中的语音播报文本。
欢迎副标题（welcomeSubtitle）	用于配置待机页中间说明文案，例如“我可以为您提供访客登记、路线引导、通知公告查询与现场帮助服务”。选填，建议最多 150 字。
按钮文案（touchText）	用于配置底部主按钮文案，例如“触摸屏幕进入服务”。选填，建议最多 50 字；未配置时屏幕端使用本地默认按钮文案。
按钮颜色（buttonColor）	用于配置底部主按钮颜色，默认 #2f8ee5。按钮阴影颜色不单独配置，由屏幕端根据按钮颜色自动生成。
备注（remark）	后台备注说明，选填，最多 500 字。
操作按钮	保存配置、清空配置、刷新。清空配置用于删除当前 config_key='default' 的运维端主题配置记录；删除后屏幕端将使用本地默认主题。
上传规则	Logo 图片和背景图可复用现有上传能力，例如 /common/uploadMediaFile 或通用上传接口。前端只取返回的 fileUrl / url 写入 logoUrl 或 backgroundImage。
业务规则	配置标识固定为 default。展示主题配置属于可选覆盖配置，后端数据库可以不预置默认配置。页面加载时如后端返回空数据或未查询到 config_key='default' 配置，运维端后台可展示空表单，并提示“当前未配置待机页主题，屏幕端将使用本地默认主题”。用户填写并点击“保存配置”后，后端按 config_key='default' 执行有则更新、无则新增。屏幕端必须内置本地默认主题，用于后端无配置、接口异常、网络异常或字段缺失时兜底展示。
一期不做	一期不做多主题列表、主题启用状态、主题复制、普通主题删除、实时预览、背景适配方式、柔光层开关、状态栏开关、时间日期开关、Logo 颜色、状态点颜色、标题颜色、字体大小、按钮阴影颜色和复杂布局配置。

6.4 访客管理

6.4.1 访客记录页面

模块	详细设计
页面目标	展示已完成登记的访客到访记录。访客记录由机器人屏幕登记流程或扫码 H5 登记流程产生，运维端仅负责查看、详情和导出，不提供新增、编辑、删除。
查询条件	访客姓名、手机号、身份证号、到访类型、登记方式、被访对象、来访时间范围。
列表字段	访客姓名、手机号、身份证号、访客照片、到访类型、登记方式、访客来源、来访事由、预约单号、被访对象、来访时间、操作。
详情字段	访客姓名（visitorName）、手机号（mobile）、身份证号（idCardNo）、到访类型（visitType）、登记方式（registerType）、访客来源（visitorSource）、来访事由（visitReason）、访客照片（visitorPhoto）、预约单号（appointmentNo）、被访对象（visitedPerson）、来访时间（visitTime）、备注（remark）。
到访类型	用于区分访客到访业务类型，建议字典项为：APPOINTMENT=预约到访，WALK_IN=现场登记。
登记方式	用于区分访客完成登记的入口，建议字典项为：SCREEN=机器人端，H5=手机端。机器人端指访客在机器人屏幕完成登记；手机端指访客扫码后在 H5 页面完成登记。身份证读卡、手机号输入、人脸拍照等可作为机器人端登记流程中的信息采集方式，不单独作为登记方式。
访客来源	用于描述访客来自哪里或属于什么来源，字段为 visitorSource / visitor_source，适配公司、酒店、小区、园区、展厅等多场景，例如公司名称、合作方、亲友、外卖、快递、供应商、施工单位、旅行团等。该字段建议选填。
来访事由	用于描述访客本次到访目的，字段为 visitReason / visit_reason，例如业务接洽、走亲访友、酒店入住、外卖配送、快递投递、设备维修、参观接待、会议拜访、施工进场等。该字段建议选填，一期采用文本输入，不强制枚举。
访客照片	由机器人端摄像头或登记流程采集上传，运维端只做展示和预览，不支持手动上传修改。列表中访客照片放在身份证号之后，便于运维人员优先查看访客身份信息；详情中可展示较大尺寸照片预览。
预约关联	预约到访记录通过 appointmentNo 关联预约记录；现场登记记录 appointmentNo 可为空。
操作按钮	查看详情、导出。
业务规则	访客记录代表已经完成登记的到访记录，不设置登记结果字段。登记失败、身份证读取失败、扫码失败、预约匹配失败等过程异常，不进入访客记录，应进入运行日志或后续扩展的登记异常日志。
与白名单关系	访客记录与白名单识别记录分开管理。命中白名单不作为访客登记结果；白名单命中属于识别或通行逻辑，可后续在识别日志、通行记录或对话/安防日志中体现。
与预约记录关系	预约记录由主控平台同步，表示计划来访；访客到现场后通过机器人屏幕或扫码 H5 完成登记确认，并生成访客记录。
导出字段	导出列表主要字段；访客照片建议导出“有照片/无照片”或照片链接，不直接导出图片文件。

6.4.2 预约记录页面

模块	详细设计
查询条件	预约单号、访客姓名、手机号、预约状态、预约时间范围。
列表字段	预约单号、访客姓名、手机号、被访人、预约时间、状态、同步时间、操作。
详情字段	预约单号（appointmentNo）、访客姓名（visitorName）、手机号（mobile）、被访人（visitedPerson）、预约时间（appointmentTime）、预约状态（status）、同步时间（syncTime）、来源平台（sourcePlatform）、备注（remark）。
操作按钮	查看详情。
数据来源	主控平台同步；本地端仅展示，不发起预约流程。

6.4.3 白名单管理页面

模块	详细设计
页面目标	维护可被机器人识别为可信人员的白名单数据，支持通过人脸照片、身份证号、手机号等信息进行白名单匹配。
查询条件	姓名、手机号、身份证号、人员类型、来源类型、启用状态。
列表字段	姓名、手机号、身份证号、人员类型、是否有人脸照片、来源类型、有效期、启用状态、更新时间、操作。
编辑字段	姓名（name）、人员类型（whitelistType，页面显示为“人员类型”）、手机号（mobile）、身份证号（idCardNo）、人脸照片（faceImageUrl）、来源类型（sourceType，只读展示，不允许人工修改）、有效开始时间（validStartTime）、有效结束时间（validEndTime）、启用状态（status）、备注（remark）。
人员类型	人员类型用于描述白名单人员身份，建议字典项为：内部人员、访客、VIP、其他。不建议将“人脸白名单”作为人员类型，因为人脸识别属于匹配方式，不属于人员身份类型。
操作按钮	新增、编辑、删除、导入、导出、启用/停用。
表单校验	姓名、人员类型、来源类型、启用状态必填；手机号、身份证号、人脸照片三者至少填写一种；手机号填写时需符合大陆手机号格式；身份证号填写时需符合 18 位身份证基础格式；有效结束时间如填写，必须大于有效开始时间。
人脸照片规则	一期仅保存人脸照片地址（faceImageUrl），不保存人脸特征ID。机器人侧按照片进行人脸比对，建议上传清晰正脸照片；前端上传限制为 2MB，支持 png/jpg/jpeg 格式。
匹配规则	白名单不设置单一识别方式字段。机器人或后端根据当前采集到的身份信息进行匹配：人脸识别时通过人脸照片比对；身份证读取或输入时匹配身份证号；手机号输入时匹配手机号。任一方式匹配到启用且在有效期内的白名单人员，即视为白名单命中。
业务规则	来源类型由系统自动识别，不允许用户手动修改。运维后台手动新增和导入的数据默认来源类型为 1=本地录入；主控平台同步数据由同步接口写入 2=平台同步；机器人端采集数据由机器人采集接口写入 3=机器人采集。列表中展示来源类型，查询区支持按来源类型筛选。
有效期规则	有效开始时间为空表示立即生效；有效结束时间为空表示长期有效。列表中根据当前时间动态展示有效期状态：有效、未生效、已过期、长期有效。一期不提供有效期状态筛选条件。

6.5 运维管理

6.5.1 运行参数配置页面

页面采用模块 Tab + 模块参数表形式。

字段	说明
参数分组编码（groupCode）	参数分组编码，例如 audio、screen、system、device、service。
参数分组名称（groupName）	参数分组名称。
参数编码（paramCode）	参数编码。
参数名称（paramName）	参数名称。
参数值（paramValue）	参数值。
值类型（valueType）	string、int、float、boolean、enum。
单位（unit）	单位。
是否可编辑（editable）	是否可编辑。
是否必填（requiredFlag）	是否必填。
数值边界（minValue / maxValue）	数值边界。
枚举项（enumOptions）	枚举项 JSON。
参数说明（remark）	参数说明。

操作按钮：刷新、保存、重置默认值。保存时需按 valueType 校验值类型和取值范围。

6.5.2 运行日志页面

模块	详细设计
页面目标	查看机器人设备侧和本地服务侧上报的运行日志、服务日志、异常报错日志、接口调用日志和关键模块日志，用于运维排查。
查询条件	日志级别、日志类型、模块名称、关键字、结果状态、时间范围。
日志类型	设备运行日志、服务日志、接口调用日志、模块日志、异常报错日志、其他日志。
列表字段	日志时间、日志级别、日志类型、模块名称、日志摘要、结果状态、追踪 ID、接收时间、操作。
详情字段	日志时间（logTime）、接收时间（receiveTime）、日志级别（logLevel）、日志类型（logType）、模块名称（moduleName）、日志摘要（contentSummary）、日志内容（content）、结果状态（resultStatus）、追踪 ID（traceId）、机器人编号（robotCode）、备注（remark）。
操作按钮	查看详情、导出。
边界说明	运行日志只展示机器人设备侧和本地服务侧上报的运行日志，不做主动诊断，不提供立即自检，不维护诊断项配置。后台用户操作日志、对话日志、安防告警日志、访客记录和 OTA 升级记录不并入运行日志。

运行日志定位为通用运维排查页面，主要用于查看机器人设备侧和本地服务侧上报的运行日志、服务日志、接口调用日志、异常报错日志和关键模块日志。

6.5.3 对话日志页面

模块	详细设计
页面目标	查看机器人与用户之间的人机对话记录，用于排查用户问题、机器人回答、命中方式、来源场景、执行结果和原始请求响应。
查询条件	会话 ID、用户问题关键字、命中方式、来源场景、结果状态、提问时间范围。
列表字段	提问时间、会话 ID、用户问题、回答摘要、命中方式、来源场景、结果状态、操作。
详情字段	机器人编号（robotCode）、会话 ID（sessionId）、提问时间（askTime）、用户问题（question）、机器人回答（answer）、回答摘要（answerSummary）、命中方式（hitType）、来源场景（sceneType）、结果状态（resultStatus）、错误信息（errorMsg）、原始请求（rawRequest）、原始响应（rawResponse）。
操作按钮	查看详情、导出。
业务规则	对话日志由机器人端或后端问答服务写入，运维端只读查看，不提供新增、编辑、删除。列表中只展示用户问题和回答摘要，完整回答、错误信息、原始请求和原始响应在详情弹窗中查看。
边界说明	对话日志只记录人机问答过程，不替代运行日志和安防告警日志。接口异常、模型调用失败、知识库未命中等可在对话日志中记录结果状态和错误信息，同时也可在运行日志中记录系统级异常。
扩展说明	一期不设计响应耗时、命中问答库 ID、命中标准问题和匹配置信度等字段；后续如问答能力、知识库命中逻辑或上位平台统计需求明确后再扩展。

6.5.4 安防告警日志页面

模块	详细设计
查询条件	告警类型、告警级别、处理状态、告警时间范围。
列表字段	告警时间、告警类型、告警级别、位置/来源、处理状态、描述摘要、操作。
详情字段	告警时间（alarmTime）、告警类型（alarmType）、告警级别（alarmLevel）、来源位置（sourcePosition）、处理状态（handleStatus）、描述（description）、抓拍图地址（snapshotUrl）、备注（remark）。
操作按钮	查看详情、确认告警、忽略告警、导出。

6.5.5 软件版本 / OTA 升级页面

区块	详细设计
软件版本列表	展示模块编码（moduleCode）、模块名称（moduleName）、当前版本（currentVersion）、安装时间（installTime）、运行状态（runStatus）。
安装包管理	展示安装包名称（packageName）、模块编码（moduleCode）、目标版本（targetVersion）、文件大小（fileSize）、上传时间（uploadTime）、上传人（uploadBy）。
升级操作	选择模块 + 安装包，执行升级，展示升级状态（resultStatus）、升级进度（progressPercent）与结果信息（resultMsg）。
升级记录	展示开始时间（startTime）、结束时间（endTime）、模块编码（moduleCode）、模块名称（moduleName）、原版本（currentVersion）、目标版本（targetVersion）、执行结果（resultStatus）、失败原因/结果信息（resultMsg）、升级进度（progressPercent）。
操作按钮	上传安装包、删除安装包、执行升级、刷新进度、查看升级详情。

6.6 系统设置

6.6.1 账号管理页面

模块	详细设计
查询条件	账号、姓名、状态。
列表字段	账号、姓名、角色、状态、最后登录时间、操作。
编辑字段	登录账号（username）、用户姓名（nickName）、登录密码（password）、角色编码（roleCode）、启用状态（status）、备注（remark）。
操作按钮	新增、编辑、重置密码、启用/停用、删除。
业务规则	admin 默认账号不可删除；可重置密码。

6.6.2 修改密码页面

字段	说明
原密码（oldPassword）	原密码。
新密码（newPassword）	新密码，建议 8-32 位。
确认新密码（confirmPassword）	确认新密码，必须与 newPassword 一致。

6.6.3 基础设置页面

字段	说明
后台系统名称（systemName）	后台系统名称。
后台 Logo（systemLogo）	后台 Logo。
页脚文案（footerText）	页脚文案。
备案号/版权信息（recordNo）	备案号/版权信息，可选。

7. 后端接口设计

说明：接口统一以 /robot-ops 为前缀，返回结构统一为 { code, msg, data, timestamp }。第 7 章接口字段采用 camelCase；第 8 章数据库字段采用 snake_case。列表接口统一支持 pageNum、pageSize。

播报插播对接补充：运维端播报内容和播报任务完成维护后，后端需提供 GET /robot-ops/screen/broadcast/current 给机身屏消费。该接口不用于运维端页面管理，而用于机身屏待机页判断是否正在播报、获取播报文字和 audioUrl，并暂停/恢复素材播放。

TTS 实现补充：一期不采用流式 TTS。后端应将第三方 TTS 封装为统一 TtsService。播报文本转换为 MP3 后保存到小主机本地目录，例如 /data/robot/audio/broadcast/，并记录音频路径、访问地址、时长、Hash、生成状态和失败原因。当前播报状态接口应返回 audioUrl，供机身屏前端播放。

7.0 通用文件上传接口

接口	方法	说明	请求参数	返回字段	适用场景
/robot-ops/common/file/upload	POST	通用文件上传	文件（file）、业务类型（bizType）	文件地址（fileUrl）、文件名称（fileName）、文件大小（fileSize）、文件格式（fileFormat）	主题Logo、主题背景资源，普通附件等。素材库文件仍优先使用素材上传接口。
/common/uploadMediaFile	POST	素材文件上传	文件（file）	文件地址（fileUrl/url）、素材类型（assetType）、缩略图地址（thumbnailUrl）、文件大小（fileSize）、文件格式（fileFormat）、MIME 类型（mimeType）、视频时长（durationSeconds）、分辨率（resolution）等；具体字段以后端实际返回为准	当前素材管理前端实际使用的上传接口。上传后前端回填文件信息，再通过素材新增/编辑接口保存素材记录。

通用文件上传接口默认不单独建设文件记录表，上传后的 fileUrl 由具体业务表保存；如后续需要统一文件管理，再扩展附件表。

当前素材管理前端实际使用 /common/uploadMediaFile 上传素材文件。上传接口负责保存文件并返回素材文件信息，前端回填 fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、assetType 等字段；用户确认后再通过 RuoYi 生成的素材新增/编辑接口保存素材记录。

开发设计中的 /robot-ops/content/media/upload 属于后续统一接口规划路径；本期前端已按当前项目实际接口 /common/uploadMediaFile 落地。

7.1 通用接口规范

7.1.1 通用返回结构

{ "code": 200, "msg": "操作成功", "data": {}, "timestamp": "2026-04-24 10:00:00" }

7.1.2 分页返回结构

{ "code": 200, "msg": "查询成功", "data": { "total": 100, "pageNum": 1, "pageSize": 10, "rows": [] }, "timestamp": "2026-04-24 10:00:00" }

7.1.3 通用状态码

状态码	说明	处理建议
200	成功	正常处理 data。
400	请求参数错误	前端提示 msg。
401	未登录或登录已过期	跳转登录页。
403	无权限	提示无权限。
500	服务异常	提示系统异常，并记录日志。
10001	机器人侧接口不可用	提示机器人服务异常。
10002	机器人执行失败	展示 resultMsg。

7.2 认证与系统接口

7.2.1 登录

项	内容
接口地址	POST /robot-ops/auth/login
请求参数	登录账号（username）、登录密码（password）
返回字段	访问令牌（token）、用户ID（userId）、登录账号（username）、用户姓名（nickName）、角色编码（roleCode）
数据库表	robot_ops_user
业务规则	账号停用不可登录；密码连续错误 5 次锁定 10 分钟；登录成功更新 last_login_time。

请求示例： { "username": "admin", "password": "******" } 返回示例： { "token": "xxxxxx", "userId": 1, "username": "admin", "nickName": "管理员", "roleCode": "ADMIN" }

7.2.2 退出登录

项	内容
接口地址	POST /robot-ops/auth/logout
请求参数	无
返回字段	无
业务规则	清理当前登录 token 或 session。

7.2.3 修改密码

项	内容
接口地址	POST /robot-ops/auth/change-password
请求参数	原密码（oldPassword）、新密码（newPassword）、确认新密码（confirmPassword）
返回字段	无
数据库表	robot_ops_user
业务规则	原密码校验通过后更新；新密码和确认密码必须一致。

7.2.4 当前登录用户

项	内容
接口地址	GET /robot-ops/auth/current-user
返回字段	用户ID（userId）、登录账号（username）、用户姓名（nickName）、角色编码（roleCode）、权限标识（permissions）
数据库表	robot_ops_user 或 RuoYi 原生权限表

7.2.5 基础设置查询/保存

接口	方法	说明	请求/返回字段	数据库表
/robot-ops/system/base-config	GET	获取基础设置	后台系统名称（systemName）、后台Logo（systemLogo）、页脚文案（footerText）、备案号（recordNo）	robot_ops_system_config
/robot-ops/system/base-config	PUT	保存基础设置	后台系统名称（systemName）、后台Logo（systemLogo）、页脚文案（footerText）、备案号（recordNo）	robot_ops_system_config

7.3 首页接口

7.3.1 首页总览

项	内容
接口地址	GET /robot-ops/home/overview
请求参数	无
返回字段	机器人名称（robotName）、机器人编号（robotCode）、在线状态（onlineStatus）、工作状态（workStatus）、电量百分比（batteryLevel）、充电状态（chargeStatus）、网络状态（networkStatus）、IP地址（ipAddress）、存储占用（storageUsed）、当前版本（currentVersion）、今日访客数（todayVisitorCount）、今日预约数（todayAppointmentCount）、今日对话数（todayDialogueCount）、今日播报数（todayBroadcastCount）、今日告警数（todayAlarmCount）、今日操作数（todayOperateCount）
数据来源	机器人实时接口 + 本地访客/对话/告警/操作记录聚合。
数据库表	robot_ops_visitor_record、robot_ops_appointment_record、robot_ops_dialogue_log、robot_ops_alarm_log、robot_ops_operate_log；机器人实时状态不落库。

7.3.2 首页最近告警/最近记录

接口	说明	请求参数	返回字段	数据库表
GET /robot-ops/home/alarms	获取首页最近告警	数量（limit，默认5）	告警ID（id）、告警时间（alarmTime）、告警类型（alarmType）、告警级别（alarmLevel）、描述（description）	robot_ops_alarm_log
GET /robot-ops/home/quick-records	获取首页最近记录	数量（limit，默认5）	记录类型（recordType）、时间（recordTime）、标题（title）、摘要（summary）、跳转目标（targetUrl）	robot_ops_sys_log、robot_ops_upgrade_record

视频预览、远程喊话、设备状态和设备控制已合并到首页工作台展示，但接口仍可复用原监控管理和运维管理规划接口。前端首页可调用视频流信息、视频状态、远程喊话、设备状态、设备控制等接口完成实时展示和快捷操作。

7.4 内容管理接口

7.4.1 欢迎语配置接口

接口	方法	说明	请求/返回字段	数据库表
/robot-ops/content/welcome-config	GET	获取欢迎语配置	返回：配置标识（configKey，固定 default）、欢迎语文本（welcomeText）、语音播报开关（voiceEnabled）、语音播报冷却时间（cooldownSeconds）、启用欢迎语状态（status）、备注（remark）。前端无需传参，后端以 config_key='default' 查询；如数据库暂无默认配置，可返回空数据，由前端加载默认配置。	robot_ops_welcome_config
/robot-ops/content/welcome-config	PUT	保存欢迎语配置	请求：配置标识（configKey，固定 default，可由前端传入，也可由后端默认处理）、欢迎语文本（welcomeText）、语音播报开关（voiceEnabled）、语音播报冷却时间（cooldownSeconds）、启用欢迎语状态（status）、备注（remark）。后端保存时应以 config_key='default' 作为定位条件，存在则更新，不存在则新增。	robot_ops_welcome_config
/robot-ops/content/welcome-config/test	POST	测试欢迎语播报	请求：配置标识（configKey，固定 default）、欢迎语文本（welcomeText）、启用欢迎语状态（status）、语音播报开关（voiceEnabled）。仅下发测试播报，不新增或修改配置数据。	不新增业务表，可写入 robot_ops_operate_log

欢迎语配置为单配置页，前端当前会在保存和测试播报时携带 configKey='default'；后端也应支持不传 configKey 时默认按 default 处理。

保存欢迎语配置时，后端建议按 config_key='default' 执行“有则更新，无则新增”的逻辑，避免初始化数据缺失时保存失败。

7.4.2 问答库接口

接口	方法	说明	请求参数	返回/处理字段	数据库表
/robot-ops/content/faq/page	GET	问答分页	问题分类（categoryType，字典值）、标准问题关键字（question）、启用状态（status）、pageNum、pageSize	问答ID（id）、问题分类（categoryType，按字典回显）、标准问题（question）、相似问数量（similarCount）、答案摘要（answerSummary）、启用状态（status）、更新时间（updateTime）	robot_ops_faq、robot_ops_faq_similar；分类名称通过 RuoYi 字典 robot_faq_category 回显
/robot-ops/content/faq/{id}	GET	问答详情	问答ID（id）	categoryType、question、similarQuestions 或 robotOpsFaqSimilarList、answer、sortNo、status、remark	robot_ops_faq、robot_ops_faq_similar
/robot-ops/content/faq	POST	新增问答	categoryType、question、similarQuestions 或 robotOpsFaqSimilarList、answer、status、remark；sortNo 由前端默认传 0 或后端默认写入 0	新增后的问答ID（id）	robot_ops_faq、robot_ops_faq_similar
/robot-ops/content/faq	PUT	编辑问答	id、categoryType、question、similarQuestions 或 robotOpsFaqSimilarList、answer、sortNo、status、remark；前端页面不展示 sortNo，编辑时保持原值	无	robot_ops_faq、robot_ops_faq_similar
/robot-ops/content/faq/{id}	DELETE	删除问答	问答ID（id）	无	robot_ops_faq、robot_ops_faq_similar
/robot-ops/content/faq/export	GET	导出问答	问题分类（categoryType）、标准问题关键字（question）、启用状态（status）	Excel文件；导出字段建议包括问题分类、标准问题、相似问、答案内容、启用状态、更新时间、备注，不导出 sortNo	robot_ops_faq、robot_ops_faq_similar；分类名称按 RuoYi 字典 robot_faq_category 回显

问答分类不单独建设业务表和管理页面，统一使用 RuoYi 字典维护，字典类型为 robot_faq_category。当前字典项为：1=问候寒暄，2=产品介绍，3=业务咨询，4=访客引导，5=场所引导，6=安防提示，7=设备使用，8=售后服务，9=常见问题，10=其他。

问答库前端页面使用多行文本维护相似问，一行一个；提交时可同时携带 similarQuestions 和 robotOpsFaqSimilarList，以兼容主子表接口和后续简化接口。后端保存时需写入 robot_ops_faq_similar 表。

问答库一期不提供导入接口。由于问答导入涉及分类字典匹配、标准问题重复校验、相似问拆分、主子表写入和失败明细回显，后续如运营需要批量维护，再单独扩展导入能力。

sortNo / sort_no 为保留字段，前端页面一期不展示、不编辑。新增时默认 0，编辑时保持原值。后续如需推荐、置顶或屏幕端展示排序，再重新设计排序能力。

删除问答时需同步删除 robot_ops_faq_similar 中对应 faq_id 的相似问数据；启用/停用仅影响主问答状态，相似问不单独设置状态。

7.4.3 素材管理接口

接口	方法	说明	请求参数	返回/处理字段	数据库表
/base/mediAasset/list	GET	素材分页	素材名称（assetName）、素材类型（assetType）、启用状态（status）、引用状态（quotedFlag）、上传时间范围、pageNum、pageSize	id、assetName、assetType、fileFormat、fileSize、durationSeconds、resolution、thumbnailUrl、fileUrl、quotedFlag、status、createTime	robot_ops_media_asset
/base/mediAasset/{id}	GET	素材详情	素材ID（id）	id、assetName、assetType、fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、quotedFlag、status、remark、createTime、updateTime	robot_ops_media_asset
/common/uploadMediaFile	POST	上传素材文件	文件（file）	返回文件信息：fileUrl/url、assetType、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution 等。前端上传成功后回填文件信息。	不直接等同于普通 CRUD 接口；是否直接入库以后端实现为准。当前前端兼容返回 id 或不返回 id 两种情况。
/base/mediAasset	POST	新增素材记录	assetName、assetType、fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、status、quotedFlag、remark	新增后的素材ID	robot_ops_media_asset
/base/mediAasset	PUT	编辑素材	id、assetName、assetType、fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、status、quotedFlag、remark。页面仅允许用户维护 assetName、status、remark；其他字段由上传接口回填或系统维护。	无	robot_ops_media_asset
/base/mediAasset/{ids}	DELETE	删除素材	素材ID或ID数组（ids）	无；如素材已被播放方案引用，应返回不可删除原因和引用数量	robot_ops_media_asset、robot_ops_play_plan_item
/base/mediAasset/export	GET	导出素材	同分页查询条件	Excel文件；建议导出素材名称、素材类型、文件格式、文件大小、视频时长、分辨率、引用状态、启用状态、上传时间、备注	robot_ops_media_asset

当前素材管理前端基于 RuoYi 生成接口落地，列表、详情、新增、编辑、删除、导出使用 /base/mediAasset 相关接口；素材文件上传使用 /common/uploadMediaFile。

上传接口返回素材文件信息后，前端会回填 fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、assetType 等字段；用户点击“确定”后，再通过新增或编辑接口保存素材记录。前端已兼容上传接口直接返回 id 的情况。

素材类型 assetType 是业务类型，用于页面筛选、播放方案选择和预览方式判断；mimeType 是文件 MIME 类型，用于技术校验、预览和文件响应处理；fileFormat 是文件后缀/格式，用于页面展示和导出。

thumbnailUrl 用于列表缩略图展示。图片素材没有独立缩略图时，前端可使用 fileUrl 作为缩略图；视频素材只有后端返回 thumbnailUrl 时才展示封面，否则前端展示默认视频图标，避免将 mp4 文件地址误作为图片缩略图。

durationSeconds、resolution 支持为空，前端以“-”兜底展示。若后端可解析图片/视频信息，可返回对应值；若暂时无法解析，不影响素材列表和预览功能。

quotedFlag 由后端根据播放方案明细引用关系维护，前端只读展示。删除素材时，后端必须检查 robot_ops_play_plan_item 是否存在引用，不能仅依赖 quotedFlag。

7.4.4 播放方案接口

接口	方法	说明	请求/返回字段	数据库表
/robot-ops/content/play-plan/page	GET	播放方案分页	请求：方案名称（planName）、循环方式（loopMode）、播放状态（status）、pageNum、pageSize；返回：id、planName、assetCount、loopMode、status、updateTime	robot_ops_play_plan
/robot-ops/content/play-plan/{id}	GET	播放方案详情	返回：id、planName、assetCount、loopMode、status、remark、itemList；itemList 从明细表返回 assetId、playOrder、staySeconds、transitionType，并通过关联 robot_ops_media_asset 补充 assetName、assetType、fileUrl、thumbnailUrl、durationSeconds、resolution、assetStatus 等展示字段。	robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset
/robot-ops/content/play-plan	POST	新增播放方案	请求：planName、loopMode、status、remark、itemList。itemList 只需提交 assetId、playOrder、staySeconds、transitionType；其中 transitionType 为预留字段，一期可不传，由后端默认写入 none；新增时至少包含一个素材明细；assetCount 由后端根据 itemList 数量计算。后端保存时需校验 assetId 对应素材是否存在且可用。	robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset
/robot-ops/content/play-plan	PUT	编辑播放方案	请求：id、planName、loopMode、status、remark、itemList。itemList 只需提交 assetId、playOrder、staySeconds、transitionType；其中 transitionType 为预留字段，一期可不传，由后端默认写入 none；保存时以后端接收的 itemList 为准重建或更新明细；assetCount 由后端重新计算。后端保存时需校验 assetId 对应素材是否存在。	robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset
/robot-ops/content/play-plan/{id}	DELETE	删除播放方案	方案ID（id）。删除时同步删除明细并重新计算相关素材 quotedFlag。如删除当前播放方案，可能导致车端无可播放方案，建议后端根据实际业务策略进行限制或提示。	robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset
/robot-ops/content/play-plan/{id}/status	POST	切换播放状态	方案ID（id）、播放状态（status）。当 status=1 时，后端事务中将其他方案 status 置为 0，将当前方案 status 置为 1；当 status=0 时，需根据业务策略判断是否允许将当前播放方案设为备用。	robot_ops_play_plan
/robot-ops/content/play-plan/{id}/preview	GET	预览播放方案（后续规划）	方案ID（id）。返回方案基本信息和按 playOrder 排序后的 itemList；itemList 需关联素材表返回 assetName、assetType、fileUrl、thumbnailUrl、durationSeconds、resolution、assetStatus 等字段，用于前端预览。当前前端一期已先基于详情接口 getPlan(id) 实现预览弹窗，后续可切换为该接口。	robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset

新增/编辑播放方案请求 itemList 示例： [ { "assetId": 1, "playOrder": 1, "staySeconds": 10, "transitionType": "none" }, { "assetId": 2, "playOrder": 2, "staySeconds": null, "transitionType": "none" } ] 播放方案详情/预览返回 itemList 示例： [ { "assetId": 1, "assetName": "大厅欢迎背景图", "assetType": "image", "fileUrl": "/profile/upload/media/welcome-bg.jpg", "thumbnailUrl": "/profile/upload/media/welcome-bg.jpg", "durationSeconds": null, "resolution": "1920x1080", "assetStatus": "1", "playOrder": 1, "staySeconds": 10, "transitionType": "none" }, { "assetId": 2, "assetName": "展厅轮播宣传视频", "assetType": "video", "fileUrl": "/profile/upload/media/showroom-video.mp4", "thumbnailUrl": "/profile/upload/media/showroom-video.jpg", "durationSeconds": 90, "resolution": "1920x1080", "assetStatus": "1", "playOrder": 2, "staySeconds": null, "transitionType": "none" } ]

播放方案保存时，后端应根据 itemList 数量更新主表 asset_count，并根据 itemList 顺序更新 play_order。

说明：本节播放方案接口路径为规划接口路径。若本期基于 RuoYi 主子表生成播放方案代码，实际接口路径可能采用 RuoYi 生成风格，例如 /base/playPlan/list、/base/playPlan/{id}、/base/playPlan。前端开发和联调时应以实际生成的 API 文件路径为准，并在页面开发完成后同步本文档。

播放方案明细表一期不保存素材快照字段，只保存 asset_id、play_order、stay_seconds、transition_type 等编排字段。播放方案详情、编辑回显和预览接口应根据 asset_id 关联 robot_ops_media_asset 返回 assetName、assetType、fileUrl、thumbnailUrl、durationSeconds、resolution、assetStatus 等展示字段。

保存播放方案时，后端应根据 asset_id 校验素材是否存在。新增方案和新增明细时，仅允许选择启用状态的素材；历史方案中已引用的停用素材仍需支持详情回显和编辑回显，并提示素材已停用。

新增、编辑、删除播放方案后，需要重新计算相关素材的 quoted_flag，确保素材管理列表中的引用状态准确。

播放状态唯一性由后端事务控制。status=1 表示当前播放方案，同一时间只允许一个播放方案 status=1。启用某个方案为当前播放时，后端需将其他方案 status 更新为 0，将当前方案 status 更新为 1。车端只读取 status=1 的播放方案。

transitionType / transition_type 为播放转场预留字段，一期前端不展示、不编辑。保存播放方案时，如前端未传 transitionType，后端默认写入 none。后续车端屏幕支持转场效果后，再开放 fade 等配置项。

字典建议：loopMode 可使用 RuoYi 字典 play_plan_loop_mode，字典项：loop=循环播放，once=播放一次。transitionType 为预留字段，一期不开放配置。

7.4.5 播报内容与播报任务接口

接口	方法	说明	主要字段	数据库表
/robot-ops/content/broadcast-content/page	GET	播报内容分页	contentName、contentType、broadcastText、status、updateTime	robot_ops_broadcast_content
/robot-ops/content/broadcast-content/{id}	GET	播报内容详情	内容ID（id）；返回 contentName、contentType、broadcastText、status、remark	robot_ops_broadcast_content
/robot-ops/content/broadcast-content	POST	新增播报内容	contentName、contentType、broadcastText、status、remark	robot_ops_broadcast_content
/robot-ops/content/broadcast-content	PUT	编辑播报内容	id、contentName、contentType、broadcastText、status、remark	robot_ops_broadcast_content
/robot-ops/content/broadcast-content/{id}	DELETE	删除播报内容	内容ID（id）	robot_ops_broadcast_content
/robot-ops/content/broadcast-content/{id}/test	POST	测试播报内容	内容ID（id）	robot_ops_broadcast_content、robot_ops_operate_log
/robot-ops/content/broadcast-task/page	GET	播报任务分页	请求字段：任务名称（taskName）、播报内容名称（contentName）、循环类型（cycleType）、启用状态（status）、pageNum、pageSize；返回字段：任务ID（id）、任务名称（taskName）、播报内容ID（contentId）、播报内容名称（contentName）、播报内容状态（contentStatus，建议返回）、开始时间（startTime）、结束时间（endTime）、播报频率（frequencyMinutes，单位：分钟）、循环类型（cycleType：1按星期，2按日期）、循环取值（cycleValue）、启用状态（status）、更新时间（updateTime）。	robot_ops_broadcast_task、robot_ops_broadcast_content
/robot-ops/content/broadcast-task/{id}	GET	播报任务详情	任务ID（id）；返回 taskName、contentId、contentName、contentStatus、startTime、endTime、frequencyMinutes、cycleType、cycleValue、status、remark	robot_ops_broadcast_task、robot_ops_broadcast_content
/robot-ops/content/broadcast-task	POST	新增播报任务	taskName、contentId、startTime、endTime、frequencyMinutes、cycleType、cycleValue、status、remark；cycleType=1 时 cycleValue 保存星期值，cycleType=2 时 cycleValue 保存日期值	robot_ops_broadcast_task
/robot-ops/content/broadcast-task	PUT	编辑播报任务	id、taskName、contentId、startTime、endTime、frequencyMinutes、cycleType、cycleValue、status、remark；cycleType=1 时 cycleValue 保存星期值，cycleType=2 时 cycleValue 保存日期值	robot_ops_broadcast_task
/robot-ops/content/broadcast-task/{id}	DELETE	删除播报任务	任务ID（id）	robot_ops_broadcast_task
/robot-ops/content/broadcast-task/{id}/copy	POST	复制播报任务	任务ID（id）	robot_ops_broadcast_task

播报任务循环类型使用 RuoYi 字典 broadcast_task_cycle_type，字典值约定为：1=按星期，2=按日期。按星期时，cycleValue 保存 1-7 的星期值，多个值用英文逗号分隔；按日期时，cycleValue 保存 YYYY-MM-DD 日期值，多个日期用英文逗号分隔。

播报任务列表和详情接口建议返回 contentName 和 contentStatus，便于前端展示关联播报内容名称，以及识别关联内容是否已停用。新增/编辑播报任务时，前端仅允许选择启用状态的播报内容；历史任务关联的停用内容需要支持回显。

播报内容被播报任务命中后，由后端调用第三方 TTS 生成或复用 MP3 文件，并通过当前播报状态接口返回给机身屏；机身屏根据 audioUrl 播放 MP3、展示播报浮层，并暂停/恢复当前素材播放。

机身屏只负责根据 current 接口返回的 audioUrl 播放 MP3、暂停当前素材、显示播报浮层，并在 MP3 播放结束后恢复播放。

若已存在且 Hash 未变化，则直接返回该 MP3 的 audioUrl；若不存在、文件丢失或 Hash 已变化，则先调用第三方 TTS 生成 MP3，再返回新的 audioUrl 给机身屏播放。

TTS 实现补充：一期不采用流式 TTS。后端应将第三方 TTS 封装为统一 TtsService。播报文本转换为 MP3 后保存到小主机本地目录，例如 /data/robot/audio/broadcast/，并记录音频路径、访问地址、时长、Hash、生成状态和失败原因。当前播报状态接口应返回 audioUrl，供机身屏前端播放。

7.4.6 展示主题配置接口

接口	方法	说明	请求/返回字段	数据库表
/robot-ops/content/screen-theme-config	GET	获取待机页主题配置	返回：configKey（固定 default）、logoUrl、robotName、brandSubtitle、backgroundImage、welcomeTitle、welcomeSubtitle、touchText、buttonColor、remark。后端以 config_key='default' 查询；如数据库暂无 config_key='default' 配置，可返回 null、空对象或空 data；运维端后台可展示空表单并提示当前未配置，屏幕端继续使用本地默认主题。	robot_ops_screen_theme_config
/robot-ops/content/screen-theme-config	PUT	保存待机页主题配置	请求：configKey（固定 default，可由前端传入，也可由后端默认处理）、logoUrl、robotName、brandSubtitle、backgroundImage、welcomeTitle、welcomeSubtitle、touchText、buttonColor、remark。后端保存时应以 config_key='default' 作为定位条件，存在则更新，不存在则新增；因此数据库不强制要求预置默认数据。	robot_ops_screen_theme_config
/robot-ops/content/screen-theme-config/{id}	DELETE	清空待机页主题配置	配置ID（id）。删除当前 config_key='default' 的运维端主题配置记录；删除后运维端页面显示未配置状态，屏幕端使用本地默认主题。	robot_ops_screen_theme_config

规划接口路径与实际生成路径可能不同，联调以当前 API 文件 /base/opsScreenThemeConfig 为准。

展示主题配置为单配置页，前端保存时携带 configKey='default'；后端也应支持不传 configKey 时默认按 default 处理。

Logo 图片和背景图可复用现有上传能力，例如 /common/uploadMediaFile 或通用上传接口。前端只取返回的 fileUrl / url 写入 logoUrl 或 backgroundImage。

清空配置由前端调用删除接口删除当前 config_key='default' 的配置记录；删除后运维端页面显示未配置状态，屏幕端继续使用本地默认主题。

按钮颜色 buttonColor 只控制底部主按钮颜色；按钮阴影颜色由屏幕端根据 buttonColor 自动生成。Logo 颜色、状态点颜色、时间日期颜色、标题颜色一期不开放配置。

屏幕端必须内置一套本地默认待机页配置。当后端配置接口不可用、数据库未配置、返回空数据或字段缺失时，屏幕端使用本地默认配置兜底展示；后端返回配置采用覆盖合并策略，只覆盖已返回字段。

运维端后台不强制内置默认表单值。当 GET 接口未查询到 config_key='default' 配置时，页面可展示空表单，并提示“当前未配置待机页主题，屏幕端将使用本地默认主题”。用户填写并点击“保存配置”后，后端再新增 default 配置记录。

7.5 访客管理接口

接口	方法	说明	请求参数	返回/处理字段	数据库表
/robot-ops/visitor/record/page	GET	访客记录分页	visitorName、mobile、idCardNo、visitType、registerType、visitedPerson、visitTimeStart、visitTimeEnd、pageNum、pageSize	id、visitorName、mobile、idCardNo、visitorPhoto、visitType、registerType、visitorSource、visitReason、appointmentNo、visitedPerson、visitTime	robot_ops_visitor_record
/robot-ops/visitor/record/{id}	GET	访客详情	记录ID（id）	visitorName、mobile、idCardNo、visitType、registerType、visitorSource、visitReason、visitorPhoto、appointmentNo、visitedPerson、visitTime、remark	robot_ops_visitor_record
/robot-ops/visitor/record/export	GET	导出访客记录	同分页查询条件：visitorName、mobile、idCardNo、visitType、registerType、visitedPerson、visitTimeStart、visitTimeEnd	Excel文件；导出字段建议包括访客姓名、手机号、身份证号、到访类型、登记方式、访客来源、来访事由、预约单号、被访对象、来访时间、访客照片状态	robot_ops_visitor_record
/robot-ops/visitor/appointment/page	GET	预约记录分页	appointmentNo、visitorName、mobile、status、appointmentTimeStart、appointmentTimeEnd、pageNum、pageSize	appointmentNo、visitorName、mobile、visitedPerson、appointmentTime、status、syncTime	robot_ops_appointment_record
/robot-ops/visitor/appointment/{id}	GET	预约详情	预约记录ID（id）	appointmentNo、visitorName、mobile、visitedPerson、appointmentTime、status、syncTime、sourcePlatform、remark	robot_ops_appointment_record
/robot-ops/visitor/whitelist/page	GET	白名单分页	姓名（name）、手机号（mobile）、身份证号（idCardNo）、人员类型（whitelistType）、来源类型（sourceType）、启用状态（status）、pageNum、pageSize	白名单ID（id）、姓名（name）、手机号（mobile）、身份证号（idCardNo）、人员类型（whitelistType）、人脸照片地址（faceImageUrl）、是否有人脸照片（hasFaceImage）、来源类型（sourceType）、有效开始时间（validStartTime）、有效结束时间（validEndTime）、启用状态（status）、更新时间（updateTime）	robot_ops_whitelist
/robot-ops/visitor/whitelist/{id}	GET	白名单详情	白名单ID（id）	name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark	robot_ops_whitelist
/robot-ops/visitor/whitelist	POST	新增白名单	name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark；运维后台新增时 sourceType 默认传 1，表示本地录入	新增ID（id）	robot_ops_whitelist
/robot-ops/visitor/whitelist	PUT	编辑白名单	id、name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark；sourceType 由系统自动维护，前端只读展示，不允许用户手动修改	无	robot_ops_whitelist
/robot-ops/visitor/whitelist/{id}/status	PUT	启用/停用白名单	白名单ID（id）、启用状态（status）	无	robot_ops_whitelist
/robot-ops/visitor/whitelist/{id}	DELETE	删除白名单	白名单ID（id）	无	robot_ops_whitelist
/robot-ops/visitor/whitelist/import	POST	导入白名单	Excel文件（file）；导入字段包括姓名、人员类型、手机号、身份证号、人脸照片地址、有效开始时间、有效结束时间、启用状态、备注；运维后台导入的数据 sourceType 默认写入 1，表示本地录入	导入总数、成功数、失败数、失败明细；导入时需校验 mobile、idCardNo、faceImageUrl 三者至少填写一种；手机号和身份证号需校验格式	robot_ops_whitelist
/robot-ops/visitor/whitelist/export	GET	导出白名单	同分页查询条件	Excel文件；导出字段包括姓名、手机号、身份证号、人员类型、人脸照片地址、来源类型、有效开始时间、有效结束时间、启用状态、更新时间、备注	robot_ops_whitelist

访客记录不设置 resultStatus 和 sourceType 作为页面字段。访客记录代表已完成登记的到访记录；登记失败、扫码失败、读卡失败、预约匹配失败等异常应进入运行日志或后续扩展的登记异常日志。

访客记录支持两类到访类型：APPOINTMENT=预约到访，WALK_IN=现场登记；登记方式支持 SCREEN=机器人端，H5=手机端。机器人端指访客在机器人屏幕完成登记；手机端指访客扫码后在 H5 页面完成登记。

预约记录由主控平台同步；预约到访访客在现场完成登记后生成访客记录，并通过 appointmentNo 关联预约记录。现场登记访客可不关联预约单号。

白名单中的 whitelistType 字段在页面上显示为“人员类型”，用于表示人员身份，如内部人员、访客、VIP、其他。人脸识别不作为人员类型，而是白名单匹配方式之一。

白名单不单独设置识别方式字段。机器人侧可根据当前采集到的身份信息匹配白名单：人脸识别时通过 faceImageUrl 对应的人脸照片进行比对；刷身份证或输入身份证时匹配 idCardNo；输入手机号时匹配 mobile。任一方式匹配到启用且在有效期内的白名单人员，即视为白名单命中。

新增或编辑白名单时，mobile、idCardNo、faceImageUrl 三者至少填写一种；手机号填写时需符合大陆手机号格式，身份证号填写时需符合 18 位身份证基础格式；一期不保存人脸特征ID。

来源类型 sourceType 使用 RuoYi 字典 source_type，当前字典值为：1=本地录入，2=平台同步，3=机器人采集。sourceType 由系统自动赋值，运维后台新增和导入默认写入 1；主控平台同步写入 2；机器人采集写入 3。前端新增/编辑弹窗中只读展示来源类型，不允许人工选择。

有效期状态由前端根据 validStartTime、validEndTime 和当前时间动态展示，不作为一期分页查询参数。

7.6 运维日志与监控接口

接口	方法	说明	请求参数	返回/处理字段	数据库表
/robot-ops/monitor/video/stream-info	GET	获取视频流信息	无	视频地址（streamUrl）、播放协议（streamProtocol）、码流类型（streamType）、分辨率（resolution）、过期时间（expireTime）	实时接口返回，不落库
/robot-ops/monitor/video/status	GET	获取视频状态	无	播放状态（videoStatus）、错误码（errorCode）、错误信息（errorMsg）、更新时间（updateTime）	实时接口返回，不落库
/robot-ops/monitor/voice/connect	POST	建立远程喊话通道	音量（volume）	会话ID（sessionId）、连接状态（connectStatus）、结果信息（resultMsg）	robot_ops_shout_record、robot_ops_operate_log
/robot-ops/monitor/voice/start	POST	开始远程喊话	会话ID（sessionId）、音量（volume）	执行状态（resultStatus）、结果信息（resultMsg）	robot_ops_shout_record、robot_ops_operate_log
/robot-ops/monitor/voice/stop	POST	结束远程喊话	会话ID（sessionId）	执行状态（resultStatus）、结果信息（resultMsg）、开始时间（startTime）、结束时间（endTime）	robot_ops_shout_record、robot_ops_operate_log
/robot-ops/monitor/voice/shout-record/page	GET	喊话记录分页	sessionId、resultStatus、startTimeStart、startTimeEnd、pageNum、pageSize	id、sessionId、volume、connectStatus、resultStatus、resultMsg、operateBy、startTime、endTime、durationSeconds	robot_ops_shout_record

远程喊话为麦克风实时语音喊话，不是文本转语音播报。浏览器端后续需要对接麦克风采集能力，机器人端需要提供音频通道建立、音频推送、播放和结束能力。文本播报、定时播报和固定内容播报仍由播报内容与播报任务模块负责。

接口	方法	说明	请求参数	返回/处理字段	数据库表
/robot-ops/monitor/dialogue/page	GET	对话日志分页	sessionId、keyword、hitType、sceneType、resultStatus、askTimeStart、askTimeEnd、pageNum、pageSize	id、sessionId、askTime、question、answerSummary、hitType、sceneType、resultStatus	robot_ops_dialogue_log
/robot-ops/monitor/dialogue/{id}	GET	对话详情	日志ID（id）	id、robotCode、sessionId、askTime、question、answer、answerSummary、hitType、sceneType、resultStatus、errorMsg、rawRequest、rawResponse	robot_ops_dialogue_log
/robot-ops/monitor/dialogue/export	GET	导出对话日志	同分页查询条件	Excel文件；建议导出提问时间、机器人编号、会话ID、用户问题、回答摘要、命中方式、来源场景、结果状态、错误信息	robot_ops_dialogue_log

对话日志为只读日志，不提供新增、编辑、删除接口。robotCode 用于后续上传上位平台或多机器人汇聚识别；本地运维端当前不作为主要查询条件和列表字段展示。

接口	方法	说明	请求参数	返回/处理字段	数据库表
/robot-ops/monitor/alarm/page	GET	安防告警分页	alarmType、alarmLevel、handleStatus、alarmTimeStart、alarmTimeEnd、pageNum、pageSize	id、alarmTime、alarmType、alarmLevel、sourcePosition、handleStatus、description	robot_ops_alarm_log
/robot-ops/monitor/alarm/{id}	GET	安防告警详情	告警ID（id）	alarmTime、alarmType、alarmLevel、sourcePosition、handleStatus、description、snapshotUrl、remark	robot_ops_alarm_log
/robot-ops/monitor/alarm/{id}/confirm	PUT	确认告警	告警ID（id）、备注（remark）	无	robot_ops_alarm_log
/robot-ops/monitor/alarm/{id}/ignore	PUT	忽略告警	告警ID（id）、备注（remark）	无	robot_ops_alarm_log
/robot-ops/monitor/alarm/export	GET	导出告警日志	同分页查询条件	Excel文件	robot_ops_alarm_log

视频预览和远程喊话接口当前由首页工作台调用，不再单独作为左侧菜单页面；对话日志和安防告警日志已合并到运维管理菜单，作为独立日志页面保留。

7.7 运维管理接口

设备状态和设备控制接口当前由首页工作台调用，不再单独作为左侧菜单页面；运行参数配置、运行日志、对话日志、安防告警日志和 OTA 升级属于运维管理菜单。

7.7.1 设备状态与设备控制接口

接口	方法	说明	请求参数	返回/处理字段	数据库表
/robot-ops/ops/device-status/detail	GET	设备状态详情	无	robotName、robotCode、serialNo、ipAddress、macAddress、uptime、onlineStatus、workStatus、batteryLevel、chargeStatus、networkStatus、cpuUsage、memoryUsage、diskUsage、temperature、cameraStatus、micStatus、speakerStatus、screenStatus、mainServiceStatus、serverTime、lastHeartbeatTime	实时接口返回，不落库
/robot-ops/ops/control/charge-start	POST	一键充电	无或扩展参数	taskId、resultStatus、resultMsg	robot_ops_control_record、robot_ops_operate_log
/robot-ops/ops/control/charge-stop	POST	停止充电	无或扩展参数	taskId、resultStatus、resultMsg	robot_ops_control_record、robot_ops_operate_log
/robot-ops/ops/control/reboot	POST	重启机器人	确认标识（confirmFlag）	taskId、resultStatus、resultMsg	robot_ops_control_record、robot_ops_operate_log
/robot-ops/ops/control/shutdown	POST	关机	确认标识（confirmFlag）	taskId、resultStatus、resultMsg	robot_ops_control_record、robot_ops_operate_log
/robot-ops/ops/control/record/page	GET	设备控制记录分页	controlType、resultStatus、createTimeStart、createTimeEnd、pageNum、pageSize	id、controlType、controlName、taskId、resultStatus、resultMsg、operateBy、createTime、finishTime	robot_ops_control_record
/robot-ops/ops/control/record/{id}	GET	设备控制记录详情	控制记录ID（id）	controlType、controlName、taskId、requestParam、resultStatus、resultMsg、operateBy、createTime、finishTime	robot_ops_control_record

7.7.2 运行参数接口

接口	方法	说明	请求/返回字段	数据库表
/robot-ops/ops/param/groups	GET	参数分组列表	groupCode、groupName、sortNo、status	robot_ops_param_group
/robot-ops/ops/param/page	GET	参数分页/分组参数	groupCode、keyword、pageNum、pageSize；返回 paramCode、paramName、paramValue、valueType、unit、editable、requiredFlag、minValue、maxValue、enumOptions、remark	robot_ops_param
/robot-ops/ops/param	PUT	保存参数	参数列表（params：paramCode、paramValue）	robot_ops_param、robot_ops_operate_log
/robot-ops/ops/param/reset	POST	重置参数	groupCode 或 paramCodes	robot_ops_param、robot_ops_operate_log

参数保存时必须根据 valueType、requiredFlag、minValue、maxValue、enumOptions 做后端校验。

7.7.3 运行日志接口

接口	方法	说明	请求参数	返回字段	数据库表
/robot-ops/ops/sys-log/page	GET	运行日志分页	logLevel、logType、moduleName、keyword、resultStatus、logTimeStart、logTimeEnd、pageNum、pageSize	id、logTime、receiveTime、logLevel、logType、moduleName、contentSummary、resultStatus、traceId、robotCode	robot_ops_sys_log
/robot-ops/ops/sys-log/{id}	GET	运行日志详情	日志ID（id）	id、logTime、receiveTime、logLevel、logType、moduleName、contentSummary、content、resultStatus、traceId、robotCode、remark	robot_ops_sys_log
/robot-ops/ops/sys-log/export	GET	导出运行日志	同运行日志分页查询条件	Excel文件	robot_ops_sys_log

运行日志接口仅用于查询机器人设备侧和本地服务侧上报的运行日志、服务日志、接口调用日志、异常报错日志和关键模块日志；不提供主动诊断和立即自检能力。

7.7.4 软件版本与 OTA 升级接口

接口	方法	说明	请求/返回字段	数据库表
/robot-ops/ops/version/page	GET	软件版本分页	moduleCode、moduleName、runStatus、pageNum、pageSize；返回 moduleCode、moduleName、currentVersion、installTime、runStatus	robot_ops_version_info
/robot-ops/ops/upgrade/package/upload	POST	上传升级包	文件（file）、模块编码（moduleCode）、目标版本（targetVersion）、安装包名称（packageName）	packageId、packageName、moduleCode、targetVersion、fileUrl、fileSize、uploadBy、uploadTime	robot_ops_upgrade_package
/robot-ops/ops/upgrade/package/page	GET	升级包分页	packageName、moduleCode、targetVersion、pageNum、pageSize	packageId、packageName、moduleCode、targetVersion、fileSize、uploadBy、uploadTime	robot_ops_upgrade_package
/robot-ops/ops/upgrade/package/{id}	DELETE	删除升级包	升级包ID（id）	无	robot_ops_upgrade_package
/robot-ops/ops/upgrade/execute	POST	执行升级	模块编码（moduleCode）、升级包ID（packageId）、确认标识（confirmFlag）	升级记录ID（recordId）、升级状态（resultStatus）、升级进度（progressPercent）、结果信息（resultMsg）	robot_ops_upgrade_record、robot_ops_operate_log
/robot-ops/ops/upgrade/record/page	GET	升级记录分页	moduleCode、resultStatus、startTimeStart、startTimeEnd、pageNum、pageSize	recordId、moduleCode、moduleName、currentVersion、targetVersion、startTime、endTime、resultStatus、resultMsg、progressPercent	robot_ops_upgrade_record
/robot-ops/ops/upgrade/record/{id}	GET	升级详情	升级记录ID（id）	moduleCode、moduleName、currentVersion、targetVersion、packageId、executeBy、startTime、endTime、resultStatus、resultMsg、progressPercent	robot_ops_upgrade_record

7.8 账号管理接口

接口	方法	说明	请求/返回字段	数据库表
/robot-ops/system/user/page	GET	账号分页	username、nickName、status、pageNum、pageSize；返回 userId、username、nickName、roleCode、status、lastLoginTime	robot_ops_user
/robot-ops/system/user/{id}	GET	账号详情	用户ID（id）	userId、username、nickName、roleCode、status、remark、lastLoginTime	robot_ops_user
/robot-ops/system/user	POST	新增账号	username、nickName、password、roleCode、status、remark	新增用户ID（userId）	robot_ops_user
/robot-ops/system/user	PUT	编辑账号	userId、nickName、roleCode、status、remark	无	robot_ops_user
/robot-ops/system/user/{id}	DELETE	删除账号	用户ID（id）	无	robot_ops_user
/robot-ops/system/user/{id}/reset-password	POST	重置密码	用户ID（id）、新密码（newPassword）	无	robot_ops_user

admin 默认账号不可删除；账号停用后不可登录；所有账号新增、编辑、删除、重置密码操作均需写入操作日志。

8. 数据库表设计

说明：以下表结构按运维端主库设计，命名采用 robot_ops_ 前缀。第 6 章括号内字段为前端/接口字段，采用 camelCase；第 8 章字段为数据库字段，采用 snake_case，例如 robotName 对应 robot_name。机器人基础信息、实时运行状态、资源占用状态、模块状态、视频流状态等由机器人侧实时接口提供，一期不建设 robot_ops_robot_info 和 robot_ops_device_status_snapshot 两张表。

数据库建表语句以 MySQL 8.x 为基线，字段中文说明通过 COMMENT 标注。若项目实际使用 RuoYi 默认字段规范，可在开发时结合 create_by、create_time、update_by、update_time 等公共字段做统一封装；remark 作为业务备注字段，不要求所有表强制具备。

公共字段约定：除日志流水类表外，内容管理类、访客管理类、运维配置类、系统配置类等业务表统一包含 create_by、create_time、update_by、update_time 四个公共字段，用于记录创建人、创建时间、更新人和更新时间。remark 为业务备注字段，不属于所有表强制必备字段；原则上用于后台可维护的主表、配置表和业务记录表。子表、明细表、日志流水表不强制添加 remark。日志类如需记录处理说明，应优先使用 result_msg、error_msg、handle_remark、description 等具备业务含义的字段。

问答分类使用 RuoYi 系统字典能力维护，不单独建设 robot_ops_faq_category 表。RuoYi 字典类型为 robot_faq_category，当前字典项为：1=问候寒暄，2=产品介绍，3=业务咨询，4=访客引导，5=场所引导，6=安防提示，7=设备使用，8=售后服务，9=常见问题，10=其他。

8.1 基础与权限表

8.1.1 本地账号表 robot_ops_user

CREATE TABLE `robot_ops_user` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `username` VARCHAR(50) NOT NULL COMMENT '登录账号', `password` VARCHAR(100) NOT NULL COMMENT '登录密码，加密存储', `nick_name` VARCHAR(50) DEFAULT NULL COMMENT '用户姓名/昵称', `role_code` VARCHAR(50) DEFAULT NULL COMMENT '角色编码：ADMIN、OPS、VIEWER', `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '账号状态：0停用，1启用', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `last_login_time` DATETIME DEFAULT NULL COMMENT '最近登录时间', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_robot_ops_user_username` (`username`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='本地后台账号表';

8.1.2 系统基础配置表 robot_ops_system_config

CREATE TABLE `robot_ops_system_config` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `system_name` VARCHAR(100) DEFAULT NULL COMMENT '后台系统名称', `system_logo` VARCHAR(255) DEFAULT NULL COMMENT '后台系统Logo地址', `footer_text` VARCHAR(255) DEFAULT NULL COMMENT '页脚文案', `record_no` VARCHAR(100) DEFAULT NULL COMMENT '备案号/版权信息', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统基础配置表';

8.2 内容管理表

8.2.1 欢迎语配置表 robot_ops_welcome_config

CREATE TABLE `robot_ops_welcome_config` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `config_key` VARCHAR(50) NOT NULL DEFAULT 'default' COMMENT '配置标识，默认配置固定为default', `welcome_text` VARCHAR(500) NOT NULL COMMENT '欢迎语文本，前端限制最大200字，数据库预留500字', `voice_enabled` CHAR(1) NOT NULL DEFAULT '1' COMMENT '是否启用语音播报：0否，1是', `cooldown_seconds` INT NOT NULL DEFAULT 30 COMMENT '语音播报冷却时间，单位秒', `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用欢迎语状态：0停用，1启用', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_robot_ops_welcome_config_key` (`config_key`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='欢迎语配置表';

说明：欢迎语配置一期为单配置页，不作为多条数据列表管理。config_key 用于标识固定配置项，默认配置固定为 default；后端查询和保存时应以 config_key='default' 作为业务定位条件，避免因误插入多条数据导致无法判断当前配置。建议数据库初始化时预置一条 config_key='default' 的默认配置，同时保存接口应支持“有则更新，无则新增”。

说明：welcome_text 数据库预留 500 字长度，前端页面按产品规则限制最大 200 字，便于后续扩展欢迎语内容。

说明：status 控制欢迎语功能整体是否启用；voice_enabled 控制欢迎语触发后是否语音播报；cooldown_seconds 控制语音欢迎语的重复播报间隔。冷却期内再次检测到访客时，可仅做屏幕展示，不重复语音播报。

INSERT INTO `robot_ops_welcome_config` (`config_key`, `welcome_text`, `voice_enabled`, `cooldown_seconds`, `status`, `remark`, `create_by`, `create_time`, `update_by`, `update_time`) VALUES ('default', '您好，欢迎光临！我是迎宾巡逻安防机器人，很高兴为您服务。', '1', 30, '1', '系统默认欢迎语配置', 'system', NOW(), 'system', NOW());

8.2.2 问答库表 robot_ops_faq

CREATE TABLE `robot_ops_faq` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `category_type` VARCHAR(50) DEFAULT NULL COMMENT '问题分类字典值，字典类型：robot_faq_category', `question` VARCHAR(500) NOT NULL COMMENT '标准问题', `answer` TEXT NOT NULL COMMENT '答案内容', `sort_no` INT DEFAULT 0 COMMENT '排序号，数字越小越靠前', `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_faq_category_type` (`category_type`), KEY `idx_robot_ops_faq_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='问答库主表';

说明：sort_no 为保留字段，前端页面一期不展示、不编辑。新增问答默认写入 0，编辑问答时保持原值。后续如果需要推荐问答、置顶问答或机器人屏幕端展示排序，再重新设计排序和推荐能力。

8.2.3 相似问表 robot_ops_faq_similar

CREATE TABLE `robot_ops_faq_similar` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `faq_id` BIGINT NOT NULL COMMENT '问答ID，关联robot_ops_faq.id', `similar_question` VARCHAR(500) NOT NULL COMMENT '相似问文本', `sort_no` INT DEFAULT 0 COMMENT '排序号，数字越小越靠前', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_faq_similar_faq_id` (`faq_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='问答相似问表';

8.2.4 素材资源表 robot_ops_media_asset

CREATE TABLE `robot_ops_media_asset` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `asset_name` VARCHAR(100) NOT NULL COMMENT '素材名称', `asset_type` VARCHAR(20) NOT NULL COMMENT '素材类型：image图片，video视频', `file_url` VARCHAR(500) NOT NULL COMMENT '素材文件地址', `thumbnail_url` VARCHAR(500) DEFAULT NULL COMMENT '缩略图地址，图片可等于file_url，视频可为封面图', `file_size` BIGINT DEFAULT NULL COMMENT '文件大小，单位字节', `file_format` VARCHAR(20) DEFAULT NULL COMMENT '文件格式，如jpg、png、webp、mp4', `mime_type` VARCHAR(100) DEFAULT NULL COMMENT '文件MIME类型，如image/jpeg、video/mp4', `duration_seconds` INT DEFAULT NULL COMMENT '视频时长，单位秒；图片为空', `resolution` VARCHAR(50) DEFAULT NULL COMMENT '分辨率，如1920x1080', `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用', `quoted_flag` CHAR(1) NOT NULL DEFAULT '0' COMMENT '是否被播放方案引用：0否，1是，由系统维护', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间/上传时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_media_asset_type` (`asset_type`), KEY `idx_robot_ops_media_asset_status` (`status`), KEY `idx_robot_ops_media_asset_quoted_flag` (`quoted_flag`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='素材资源表';

说明：asset_type 为业务素材类型，用于页面筛选、播放方案选择和预览方式判断；mime_type 为文件标准 MIME 类型，用于文件校验、响应和预览处理；file_format 为文件后缀/格式，用于页面展示和导出。

说明：file_url、thumbnail_url、file_size、file_format、mime_type、duration_seconds、resolution 等字段由上传接口返回或后端解析生成，前端只读展示，不允许用户手动填写。duration_seconds 仅视频素材需要，图片素材为空；duration_seconds、resolution 允许为空，前端以“-”兜底展示。

说明：thumbnail_url 用于列表缩略图和视频封面展示。图片素材如未单独生成缩略图，可使用 file_url；视频素材只有后端返回 thumbnail_url 时才展示封面图，否则前端展示默认视频图标。

说明：quoted_flag 由系统维护，表示素材是否被播放方案引用。删除素材时，应以后端检查 robot_ops_play_plan_item 的实际引用关系为准。

8.2.5 播放方案表 robot_ops_play_plan

CREATE TABLE `robot_ops_play_plan` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `plan_name` VARCHAR(100) NOT NULL COMMENT '播放方案名称', `loop_mode` VARCHAR(20) NOT NULL DEFAULT 'loop' COMMENT '循环方式：loop循环播放，once播放一次', `asset_count` INT NOT NULL DEFAULT 0 COMMENT '素材数量', `status` CHAR(1) NOT NULL DEFAULT '0' COMMENT '播放状态：0备用方案，1当前播放', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_play_plan_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播放方案主表';

说明：status 表示播放状态，0=备用方案，1=当前播放。车端只读取 status=1 的播放方案。

说明：asset_count 为素材数量，由后端根据播放方案明细 itemList 数量维护，前端不允许手动填写。

说明：同一时间仅允许一个播放方案 status=1，唯一性由后端事务控制，不依赖数据库唯一索引。

8.2.6 播放方案素材明细表 robot_ops_play_plan_item

CREATE TABLE `robot_ops_play_plan_item` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `plan_id` BIGINT NOT NULL COMMENT '播放方案ID，关联robot_ops_play_plan.id', `asset_id` BIGINT NOT NULL COMMENT '素材ID，关联robot_ops_media_asset.id', `play_order` INT NOT NULL DEFAULT 0 COMMENT '播放顺序，数字越小越靠前', `stay_seconds` INT DEFAULT NULL COMMENT '停留时长，图片必填，视频可为空', `transition_type` VARCHAR(50) NOT NULL DEFAULT 'none' COMMENT '转场方式，预留字段：none无转场，fade淡入淡出', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_play_plan_item_plan_id` (`plan_id`), KEY `idx_robot_ops_play_plan_item_asset_id` (`asset_id`), KEY `idx_robot_ops_play_plan_item_order` (`plan_id`, `play_order`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播放方案素材明细表';

说明：播放方案明细表一期只保存素材引用关系和播放编排字段，不保存素材名称、类型、文件地址、缩略图、视频时长等快照字段。

说明：asset_id 为素材真实关联字段；播放方案详情、编辑回显、预览接口需要通过 asset_id 关联 robot_ops_media_asset 返回素材名称、素材类型、文件地址、缩略图、视频时长、分辨率、素材状态等展示信息。

说明：图片素材 stay_seconds 必填；视频素材 stay_seconds 可为空，表示按视频自身播放。一期不做视频截断播放逻辑。

说明：transition_type 为预留字段，一期前端不展示、不编辑，默认值为 none。后续车端屏幕支持转场动画后，再开放 fade 等转场配置。

设计取舍：一期不做播放方案发布版本冻结，不要求保存素材快照。这样表结构更简单，后端维护成本更低；后续如果需要"方案发布后素材内容不随素材库变更而变化"，再扩展素材快照字段或播放方案发布版本表。

8.2.7 播报内容表 robot_ops_broadcast_content

CREATE TABLE `robot_ops_broadcast_content` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `content_name` VARCHAR(100) NOT NULL COMMENT '播报内容名称', `content_type` VARCHAR(50) DEFAULT NULL COMMENT '内容分类：通知、宣传、提示、安防提醒、自定义', `broadcast_text` VARCHAR(2000) NOT NULL COMMENT '播报文本', `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用', `audio_file_url` VARCHAR(500) DEFAULT NULL COMMENT 'MP3文件访问地址，供机身屏前端播放，例如 http://192.168.0.30/profile/audio/broadcast/xxx.mp3', `audio_local_path` VARCHAR(500) DEFAULT NULL COMMENT 'MP3文件在小主机本地的保存路径', `audio_duration` DECIMAL(10,2) DEFAULT NULL COMMENT 'MP3音频时长，单位秒', `audio_hash` VARCHAR(64) DEFAULT NULL COMMENT 'MP3生成Hash，用于判断是否需要重新生成', `tts_status` CHAR(1) DEFAULT '0' COMMENT 'TTS生成状态：0待生成，1生成成功，2生成失败', `tts_error_msg` VARCHAR(500) DEFAULT NULL COMMENT 'TTS生成失败错误信息', `tts_update_time` DATETIME DEFAULT NULL COMMENT 'TTS生成或更新时间', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_broadcast_content_type` (`content_type`), KEY `idx_robot_ops_broadcast_content_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播报内容表';

说明：audio_file_url 字段用于返回 MP3 访问地址，供机身屏前端播放；audio_local_path 字段记录本地保存路径；audio_duration 记录音频时长；audio_hash 用于判断播报文本和语音参数变化后是否需要重新生成 MP3；tts_status、tts_error_msg、tts_update_time 用于记录 TTS 生成状态和失败原因。建议 Hash 计算口径为：md5(播报文本 + 音色 + 语速 + 音量 + TTS供应商 + 模型版本)。

8.2.8 播报任务表 robot_ops_broadcast_task

CREATE TABLE `robot_ops_broadcast_task` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `task_name` VARCHAR(100) NOT NULL COMMENT '播报任务名称', `content_id` BIGINT NOT NULL COMMENT '播报内容ID，关联robot_ops_broadcast_content.id', `start_time` VARCHAR(8) DEFAULT NULL COMMENT '开始时间，格式HH:mm:ss', `end_time` VARCHAR(8) DEFAULT NULL COMMENT '结束时间，格式HH:mm:ss', `frequency_minutes` INT DEFAULT NULL COMMENT '播报频率，单位分钟', `cycle_type` VARCHAR(20) DEFAULT NULL COMMENT '循环类型字典值，字典类型：broadcast_task_cycle_type，1按星期，2按日期', `cycle_value` VARCHAR(255) DEFAULT NULL COMMENT '循环取值：cycle_type=1时保存星期值，如1,2,3,4,5；cycle_type=2时保存日期值，如2026-03-20,2026-03-21', `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_broadcast_task_content_id` (`content_id`), KEY `idx_robot_ops_broadcast_task_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播报任务表';

播报任务循环类型使用 RuoYi 字典 broadcast_task_cycle_type，字典项建议配置为：1=按星期，2=按日期。按星期时，cycle_value 中 1-7 分别代表星期一到星期日。

8.2.9 屏幕待机页主题配置表 robot_ops_screen_theme_config

CREATE TABLE `robot_ops_screen_theme_config` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `config_key` VARCHAR(50) NOT NULL DEFAULT 'default' COMMENT '配置标识，默认配置固定为default', `logo_url` VARCHAR(500) DEFAULT NULL COMMENT 'Logo图片地址', `robot_name` VARCHAR(100) DEFAULT '迎宾巡逻机器人' COMMENT '品牌标题/机器人名称', `brand_subtitle` VARCHAR(200) DEFAULT '智能接待 · 路线引导 · 信息服务' COMMENT '品牌副标题', `background_image` VARCHAR(500) DEFAULT NULL COMMENT '待机页背景图地址', `welcome_title` VARCHAR(100) DEFAULT '您好，欢迎光临' COMMENT '欢迎主标题', `welcome_subtitle` VARCHAR(300) DEFAULT '我可以为您提供访客登记、路线引导、通知公告查询与现场帮助服务' COMMENT '欢迎副标题', `touch_text` VARCHAR(100) DEFAULT '触摸屏幕进入服务' COMMENT '主按钮文案', `button_color` VARCHAR(20) DEFAULT '#2f8ee5' COMMENT '主按钮颜色', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_robot_ops_screen_theme_config_key` (`config_key`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='屏幕待机页主题配置表';

说明：展示主题配置一期为单配置页，不作为多条数据列表管理。config_key 用于标识固定配置项，默认配置固定为 default；后端查询和保存时应以 config_key='default' 作为业务定位条件。数据库可以不预置默认记录，保存接口需支持有则更新、无则新增。未配置时不视为异常，屏幕端使用本地默认主题展示。

说明：本表仅保存待机页可运营维护的展示内容。背景适配方式、柔光层、状态栏、时间日期、标题颜色、按钮阴影等由屏幕端固定规则处理，不在后台配置。

说明：button_color 仅用于控制主按钮颜色，按钮阴影颜色由屏幕端根据 button_color 自动生成。

可选初始化数据：以下 INSERT 语句不是必须执行项。若希望数据库中预置一套默认主题配置，可执行该初始化 SQL；若不执行，运维端后台在未查询到配置时可显示空表单并提示当前未配置，屏幕端继续使用本地默认主题。用户首次保存后，后端再写入 config_key='default' 的配置记录。

INSERT INTO `robot_ops_screen_theme_config` (`config_key`, `robot_name`, `brand_subtitle`, `welcome_title`, `welcome_subtitle`, `touch_text`, `button_color`, `remark`, `create_by`, `create_time`, `update_by`, `update_time`) VALUES ('default', '迎宾巡逻机器人', '智能接待 · 路线引导 · 信息服务', '您好，欢迎光临', '我可以为您提供访客登记、路线引导、通知公告查询与现场帮助服务', '触摸屏幕进入服务', '#2f8ee5', '系统默认待机页主题配置', 'system', NOW(), 'system', NOW());

8.3 访客管理表

8.3.1 访客记录表 robot_ops_visitor_record

CREATE TABLE `robot_ops_visitor_record` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `visitor_name` VARCHAR(100) NOT NULL COMMENT '访客姓名', `mobile` VARCHAR(20) DEFAULT NULL COMMENT '手机号', `id_card_no` VARCHAR(50) DEFAULT NULL COMMENT '身份证号', `visit_type` VARCHAR(50) NOT NULL COMMENT '到访类型：APPOINTMENT预约到访，WALK_IN现场登记', `register_type` VARCHAR(50) NOT NULL COMMENT '登记方式：SCREEN机器人端，H5手机端', `visitor_source` VARCHAR(100) DEFAULT NULL COMMENT '访客来源，如公司、单位、亲友、外卖、快递、供应商等', `visit_reason` VARCHAR(200) DEFAULT NULL COMMENT '来访事由，如业务接洽、走亲访友、酒店入住、配送、维修、参观等', `visitor_photo` VARCHAR(255) DEFAULT NULL COMMENT '访客照片地址，由机器人端采集上传', `appointment_no` VARCHAR(100) DEFAULT NULL COMMENT '关联预约单号，现场登记可为空', `visited_person` VARCHAR(100) DEFAULT NULL COMMENT '被访对象，可为被访人、房号、部门、接待单位等', `visit_time` DATETIME NOT NULL COMMENT '来访/登记时间', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_visitor_record_name` (`visitor_name`), KEY `idx_robot_ops_visitor_record_mobile` (`mobile`), KEY `idx_robot_ops_visitor_record_id_card_no` (`id_card_no`), KEY `idx_robot_ops_visitor_record_visit_type` (`visit_type`), KEY `idx_robot_ops_visitor_record_register_type` (`register_type`), KEY `idx_robot_ops_visitor_record_appointment_no` (`appointment_no`), KEY `idx_robot_ops_visitor_record_visit_time` (`visit_time`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='访客记录表';

说明：访客记录表只保存已完成登记的到访记录，不保存登记失败结果。登记失败、扫码失败、身份证读取失败、预约匹配失败等异常，进入运行日志或后续扩展的登记异常日志。

说明：visit_type 建议使用 RuoYi 字典 visitor_visit_type，字典项为 APPOINTMENT=预约到访，WALK_IN=现场登记。

说明：register_type 建议使用 RuoYi 字典 visitor_register_type，字典项为 SCREEN=机器人端，H5=手机端。机器人端指访客在机器人屏幕完成登记；手机端指访客扫码后在 H5 页面完成登记。

说明：visitor_source 和 visit_reason 为通用文本字段，用于适配公司、酒店、小区、园区、展厅等多种场景，不强制做枚举。

8.3.2 预约记录表 robot_ops_appointment_record

CREATE TABLE `robot_ops_appointment_record` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `appointment_no` VARCHAR(50) NOT NULL COMMENT '预约单号', `visitor_name` VARCHAR(100) DEFAULT NULL COMMENT '访客姓名', `mobile` VARCHAR(20) DEFAULT NULL COMMENT '访客手机号', `visited_person` VARCHAR(100) DEFAULT NULL COMMENT '被访人/被访对象', `appointment_time` DATETIME DEFAULT NULL COMMENT '预约到访时间', `status` VARCHAR(20) DEFAULT NULL COMMENT '预约状态：待到访、已到访、已取消、已过期', `sync_time` DATETIME DEFAULT NULL COMMENT '同步到本地时间', `source_platform` VARCHAR(50) DEFAULT NULL COMMENT '来源平台', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_robot_ops_appointment_no` (`appointment_no`), KEY `idx_robot_ops_appointment_time` (`appointment_time`), KEY `idx_robot_ops_appointment_mobile` (`mobile`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='访客预约记录表';

8.3.3 白名单表 robot_ops_whitelist

CREATE TABLE `robot_ops_whitelist` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `name` VARCHAR(100) NOT NULL COMMENT '姓名', `mobile` VARCHAR(20) DEFAULT NULL COMMENT '手机号', `id_card_no` VARCHAR(50) DEFAULT NULL COMMENT '身份证号', `whitelist_type` VARCHAR(50) DEFAULT NULL COMMENT '人员类型字典值，如internal内部人员、visitor访客、vip VIP、other其他', `face_image_url` VARCHAR(255) DEFAULT NULL COMMENT '人脸照片地址，用于机器人侧照片比对', `source_type` VARCHAR(50) DEFAULT NULL COMMENT '来源类型字典值：1本地录入，2平台同步，3机器人采集', `valid_start_time` DATETIME DEFAULT NULL COMMENT '有效开始时间，不填表示立即生效', `valid_end_time` DATETIME DEFAULT NULL COMMENT '有效结束时间，不填表示长期有效', `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_whitelist_mobile` (`mobile`), KEY `idx_robot_ops_whitelist_id_card_no` (`id_card_no`), KEY `idx_robot_ops_whitelist_type` (`whitelist_type`), KEY `idx_robot_ops_whitelist_source_type` (`source_type`), KEY `idx_robot_ops_whitelist_status` (`status`), KEY `idx_robot_ops_whitelist_valid_time` (`valid_start_time`, `valid_end_time`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='白名单表';

说明：whitelist_type 当前页面显示为“人员类型”，用于描述人员身份，不表示识别方式。建议字典项为 internal=内部人员、visitor=访客、vip=VIP、other=其他。

说明：白名单不设置 recognition_type / auth_type 字段，因为同一人员可同时支持人脸照片、身份证号、手机号多种匹配方式。机器人侧根据实际采集到的信息选择对应字段进行匹配。

说明：一期不建设 face_feature_id 字段。当前人脸白名单采用照片比对方式，仅保存 face_image_url。

说明：source_type 使用 RuoYi 字典 source_type，当前字典项为 1=本地录入、2=平台同步、3=机器人采集。运维后台新增和导入的数据默认写入 1，平台同步和机器人采集数据由对应接口写入。

8.4 监控与日志表

8.4.1 远程喊话记录表 robot_ops_shout_record

CREATE TABLE `robot_ops_shout_record` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `shout_text` VARCHAR(1000) NOT NULL COMMENT '喊话文本', `volume` INT DEFAULT NULL COMMENT '音量，0-100', `play_times` INT DEFAULT 1 COMMENT '播放次数', `interrupt_flag` CHAR(1) DEFAULT '0' COMMENT '是否打断当前播报：0否，1是', `result_status` VARCHAR(20) DEFAULT NULL COMMENT '执行状态：SUCCESS成功，FAIL失败，RUNNING执行中', `result_msg` VARCHAR(500) DEFAULT NULL COMMENT '执行结果信息/失败原因', `operate_by` VARCHAR(64) DEFAULT NULL COMMENT '操作人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间/喊话时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_shout_record_create_time` (`create_time`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='远程喊话记录表';

8.4.2 对话日志表 robot_ops_dialogue_log

CREATE TABLE `robot_ops_dialogue_log` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `robot_code` VARCHAR(64) DEFAULT NULL COMMENT '机器人编号，用于后续上传上位平台或多机器人汇聚识别', `session_id` VARCHAR(100) DEFAULT NULL COMMENT '会话ID', `ask_time` DATETIME DEFAULT NULL COMMENT '提问时间', `question` VARCHAR(1000) DEFAULT NULL COMMENT '用户问题', `answer` TEXT COMMENT '机器人回答', `answer_summary` VARCHAR(500) DEFAULT NULL COMMENT '回答摘要', `hit_type` VARCHAR(50) DEFAULT NULL COMMENT '命中方式：FAQ/AI/NONE/ERROR', `scene_type` VARCHAR(50) DEFAULT NULL COMMENT '来源场景：SCREEN/VOICE/H5/OTHER', `result_status` VARCHAR(20) DEFAULT NULL COMMENT '结果状态：SUCCESS/FAIL/UNKNOWN', `error_msg` VARCHAR(1000) DEFAULT NULL COMMENT '失败原因或错误信息', `raw_request` TEXT COMMENT '原始请求', `raw_response` TEXT COMMENT '原始响应', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', PRIMARY KEY (`id`), KEY `idx_dialogue_robot` (`robot_code`), KEY `idx_dialogue_session` (`session_id`), KEY `idx_dialogue_ask_time` (`ask_time`), KEY `idx_dialogue_hit_type` (`hit_type`), KEY `idx_dialogue_scene_type` (`scene_type`), KEY `idx_dialogue_result` (`result_status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='对话日志表';

说明：对话日志表用于保存机器人端或后端问答服务产生的人机对话记录。robot_code 用于后续日志上传上位平台或多机器人汇聚识别；本地端当前仍按单机器人后台使用。

字典建议：hitType 使用 dialogue_hit_type，字典项 FAQ=命中问答库、AI=AI生成、NONE=未命中、ERROR=异常；sceneType 使用 dialogue_scene_type，字典项 SCREEN=机器人屏幕、VOICE=语音交互、H5=扫码H5、OTHER=其他；resultStatus 复用 common_result_status。

8.4.3 安防告警日志表 robot_ops_alarm_log

CREATE TABLE `robot_ops_alarm_log` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `alarm_time` DATETIME DEFAULT NULL COMMENT '告警时间', `alarm_type` VARCHAR(50) DEFAULT NULL COMMENT '告警类型', `alarm_level` VARCHAR(20) DEFAULT NULL COMMENT '告警级别：LOW低，MEDIUM中，HIGH高，CRITICAL紧急', `source_position` VARCHAR(100) DEFAULT NULL COMMENT '来源位置/区域/模块', `handle_status` VARCHAR(20) DEFAULT 'UNHANDLED' COMMENT '处理状态：UNHANDLED未处理，CONFIRMED已确认，IGNORED已忽略', `description` VARCHAR(1000) DEFAULT NULL COMMENT '告警描述', `snapshot_url` VARCHAR(255) DEFAULT NULL COMMENT '抓拍图地址', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_alarm_log_time` (`alarm_time`), KEY `idx_robot_ops_alarm_log_level` (`alarm_level`), KEY `idx_robot_ops_alarm_log_status` (`handle_status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='安防告警日志表';

8.4.4 系统日志表 robot_ops_sys_log

CREATE TABLE `robot_ops_sys_log` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `robot_code` VARCHAR(64) DEFAULT NULL COMMENT '机器人编号', `log_time` DATETIME DEFAULT NULL COMMENT '日志时间，设备侧或服务侧日志发生时间', `receive_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '日志接收时间', `log_type` VARCHAR(50) DEFAULT NULL COMMENT '日志类型：DEVICE设备运行、SERVICE服务、API接口调用、MODULE模块、ERROR异常、OTHER其他', `log_level` VARCHAR(20) DEFAULT NULL COMMENT '日志级别：DEBUG、INFO、WARN、ERROR、FATAL', `module_name` VARCHAR(100) DEFAULT NULL COMMENT '模块名称，如 screen、audio、camera、network、ota', `content_summary` VARCHAR(500) DEFAULT NULL COMMENT '日志摘要', `content` TEXT COMMENT '日志内容', `result_status` VARCHAR(20) DEFAULT NULL COMMENT '结果状态：SUCCESS、FAIL、WARN、UNKNOWN', `trace_id` VARCHAR(100) DEFAULT NULL COMMENT '链路追踪ID', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_sys_log_time` (`log_time`), KEY `idx_robot_ops_sys_log_receive_time` (`receive_time`), KEY `idx_robot_ops_sys_log_type` (`log_type`), KEY `idx_robot_ops_sys_log_level` (`log_level`), KEY `idx_robot_ops_sys_log_module` (`module_name`), KEY `idx_robot_ops_sys_log_trace` (`trace_id`), KEY `idx_robot_ops_sys_log_robot` (`robot_code`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统运行日志表';

说明：robot_ops_sys_log 用于保存机器人设备侧和本地服务侧上报的运行日志、异常日志、接口调用日志、服务日志和关键模块日志，不用于保存后台用户操作日志。后台用户操作、配置变更、删除、重启等审计类日志应写入 robot_ops_operate_log。

字典建议：logLevel 使用 robot_log_level，字典项 DEBUG、INFO、WARN、ERROR、FATAL；logType 使用 robot_log_type，字典项 DEVICE、SERVICE、API、MODULE、ERROR、OTHER；resultStatus 使用 common_result_status，字典项 SUCCESS、FAIL、WARN、UNKNOWN。

8.4.5 操作日志表 robot_ops_operate_log

CREATE TABLE `robot_ops_operate_log` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `operate_time` DATETIME DEFAULT NULL COMMENT '操作时间', `operate_user` VARCHAR(64) DEFAULT NULL COMMENT '操作人', `module_name` VARCHAR(100) DEFAULT NULL COMMENT '操作模块', `operate_type` VARCHAR(50) DEFAULT NULL COMMENT '操作类型：新增、编辑、删除、控制、升级等', `operate_content` VARCHAR(1000) DEFAULT NULL COMMENT '操作内容', `result_status` VARCHAR(20) DEFAULT NULL COMMENT '操作结果：SUCCESS成功，FAIL失败', `result_msg` VARCHAR(500) DEFAULT NULL COMMENT '结果信息/失败原因', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_operate_log_time` (`operate_time`), KEY `idx_robot_ops_operate_log_user` (`operate_user`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='后台操作日志表';

8.5 运维与升级表

8.5.1 参数分组表 robot_ops_param_group

CREATE TABLE `robot_ops_param_group` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `group_code` VARCHAR(50) NOT NULL COMMENT '参数分组编码', `group_name` VARCHAR(100) NOT NULL COMMENT '参数分组名称', `sort_no` INT DEFAULT 0 COMMENT '排序号，数字越小越靠前', `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用', `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_robot_ops_param_group_code` (`group_code`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运行参数分组表';

8.5.2 设备控制记录表 robot_ops_control_record

CREATE TABLE `robot_ops_control_record` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `control_type` VARCHAR(50) NOT NULL COMMENT '控制类型：充电、停止充电、重启、关机等', `control_name` VARCHAR(100) DEFAULT NULL COMMENT '控制名称', `task_id` VARCHAR(100) DEFAULT NULL COMMENT '机器人侧返回的任务ID', `request_param` TEXT COMMENT '请求参数JSON', `result_status` VARCHAR(20) DEFAULT NULL COMMENT '执行状态：SUCCESS成功，FAIL失败，RUNNING执行中，PENDING等待中', `result_msg` VARCHAR(500) DEFAULT NULL COMMENT '执行结果信息/失败原因', `operate_by` VARCHAR(64) DEFAULT NULL COMMENT '操作人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间/下发时间', `finish_time` DATETIME DEFAULT NULL COMMENT '完成时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_control_record_task_id` (`task_id`), KEY `idx_robot_ops_control_record_type` (`control_type`), KEY `idx_robot_ops_control_record_time` (`create_time`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='设备控制记录表';

8.5.3 运行参数表 robot_ops_param

CREATE TABLE `robot_ops_param` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `group_code` VARCHAR(50) NOT NULL COMMENT '参数分组编码，关联robot_ops_param_group.group_code', `param_code` VARCHAR(100) NOT NULL COMMENT '参数编码', `param_name` VARCHAR(100) NOT NULL COMMENT '参数名称', `param_value` VARCHAR(2000) DEFAULT NULL COMMENT '参数值', `value_type` VARCHAR(20) DEFAULT NULL COMMENT '值类型：string、int、float、boolean、enum、json', `unit` VARCHAR(20) DEFAULT NULL COMMENT '单位', `editable` CHAR(1) NOT NULL DEFAULT '1' COMMENT '是否可编辑：0否，1是', `required_flag` CHAR(1) NOT NULL DEFAULT '0' COMMENT '是否必填：0否，1是', `min_value` VARCHAR(50) DEFAULT NULL COMMENT '最小值', `max_value` VARCHAR(50) DEFAULT NULL COMMENT '最大值', `enum_options` VARCHAR(2000) DEFAULT NULL COMMENT '枚举项JSON', `remark` VARCHAR(500) DEFAULT NULL COMMENT '参数说明/备注', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_robot_ops_param_code` (`group_code`,`param_code`), KEY `idx_robot_ops_param_group_code` (`group_code`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运行参数配置表';

说明：系统诊断项表 robot_ops_diagnosis_item 和诊断相关能力（立即诊断、诊断项配置）一期不建设，属于后续规划。运行日志通过设备侧上报的日志数据进行查询，不做主动诊断触发。如后续需要主动诊断能力，再扩展诊断项表和诊断触发接口。

8.5.5 软件版本信息表 robot_ops_version_info

CREATE TABLE `robot_ops_version_info` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `module_code` VARCHAR(50) NOT NULL COMMENT '模块编码', `module_name` VARCHAR(100) NOT NULL COMMENT '模块名称', `current_version` VARCHAR(50) DEFAULT NULL COMMENT '当前版本号', `install_time` DATETIME DEFAULT NULL COMMENT '安装时间', `run_status` VARCHAR(20) DEFAULT NULL COMMENT '运行状态：RUNNING运行中，STOPPED已停止，ERROR异常', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), UNIQUE KEY `uk_robot_ops_version_module_code` (`module_code`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='软件版本信息表';

8.5.6 升级包表 robot_ops_upgrade_package

CREATE TABLE `robot_ops_upgrade_package` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `package_name` VARCHAR(100) NOT NULL COMMENT '安装包名称', `module_code` VARCHAR(50) NOT NULL COMMENT '升级模块编码', `target_version` VARCHAR(50) NOT NULL COMMENT '目标版本号', `file_url` VARCHAR(255) NOT NULL COMMENT '升级包文件地址', `file_size` BIGINT DEFAULT NULL COMMENT '文件大小，单位字节', `upload_by` VARCHAR(64) DEFAULT NULL COMMENT '上传人', `upload_time` DATETIME DEFAULT NULL COMMENT '上传完成时间', `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_upgrade_package_module` (`module_code`), KEY `idx_robot_ops_upgrade_package_version` (`target_version`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='OTA升级包表';

8.5.7 升级记录表 robot_ops_upgrade_record

CREATE TABLE `robot_ops_upgrade_record` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `module_code` VARCHAR(50) NOT NULL COMMENT '模块编码', `module_name` VARCHAR(100) DEFAULT NULL COMMENT '模块名称', `current_version` VARCHAR(50) DEFAULT NULL COMMENT '原版本号', `target_version` VARCHAR(50) DEFAULT NULL COMMENT '目标版本号', `package_id` BIGINT DEFAULT NULL COMMENT '升级包ID，关联robot_ops_upgrade_package.id', `execute_by` VARCHAR(64) DEFAULT NULL COMMENT '执行人', `start_time` DATETIME DEFAULT NULL COMMENT '升级开始时间', `end_time` DATETIME DEFAULT NULL COMMENT '升级结束时间', `result_status` VARCHAR(20) DEFAULT NULL COMMENT '升级状态：SUCCESS成功，FAIL失败，RUNNING升级中，PENDING等待中', `result_msg` VARCHAR(1000) DEFAULT NULL COMMENT '升级结果信息/失败原因', `progress_percent` INT DEFAULT 0 COMMENT '升级进度百分比，0-100', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_upgrade_record_module` (`module_code`), KEY `idx_robot_ops_upgrade_record_status` (`result_status`), KEY `idx_robot_ops_upgrade_record_start_time` (`start_time`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='OTA升级记录表';

一期不建设机器人基础信息表和设备状态快照表。首页总览、设备状态页、视频预览页的数据以机器人侧实时接口为准；如二期需要状态历史趋势、离线查看最近状态、故障追溯统计，再扩展设备状态快照表。

9. 状态、日志与控制规则

9.1 状态枚举建议

字段	建议值
onlineStatus	ONLINE / OFFLINE
workStatus	IDLE / RECEIVING / BROADCASTING / CHARGING / ERROR
chargeStatus	NOT_CHARGING / CHARGING / FULL
resultStatus	SUCCESS / FAIL / RUNNING / PENDING
alarmLevel	LOW / MEDIUM / HIGH / CRITICAL
status	0 停用 / 1 启用

9.2 控制规则

重启、关机、充电、停止充电、升级等操作必须记录操作日志。
重启、关机、升级操作必须弹窗二次确认。
当机器人处于升级中时，除查看类操作外，禁止执行关机、重启、参数保存等高风险动作。
当设备离线时，控制按钮置灰并显示“设备离线，无法执行”。

9.3 日志规则

所有关键业务操作必须写入操作日志。
机器人端回传的异常和运行日志，统一映射到运行日志页面展示。
日志保留时长一期默认 180 天，可由系统参数配置。

10. 权限与账号设计

角色	默认权限
ADMIN	全量权限，包括账号管理、参数配置、设备控制、OTA 升级。
OPS	首页、内容管理、访客管理、运维管理（除账号管理）。
VIEWER	仅查看权限，不可执行新增、编辑、删除、升级、控制等动作。

RuoYi 菜单权限与按钮权限均需保留，避免后期返工。即使一期只有 admin，也要按标准权限框架开发。

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

阶段	模块	说明
阶段一	登录、首页（含视频预览/远程喊话/设备控制）、运行日志、参数配置、版本/OTA	先打通基础运维闭环。视频预览、远程喊话、设备状态、设备控制合并到首页工作台；运行日志为纯读取页面；系统诊断一期不做。
阶段二	欢迎语、问答库、素材管理、播放方案、播报内容、播报任务、主题配置（单配置页）	打通内容配置闭环。
阶段三	访客记录、预约记录、白名单、对话日志、安防告警日志	补齐业务查询和日志能力。对话日志、安防告警日志作为运维管理下独立日志页面保留。
阶段四	优化、导入导出、性能提升、操作审计完善	稳定化阶段。

12. 对其他团队的配合要求

以下内容不再作为“待定事项”，而是作为其他团队必须按本文配合实现的内容。

机器人侧：需提供首页状态接口、设备状态接口、控制接口、视频流信息接口、喊话接口、参数接口、日志接口、版本与升级接口。
主控平台侧：需提供预约记录同步接口、可选白名单同步接口。
展示端：需支持欢迎语、播放方案、播报任务、展示主题配置的读取与应用。
算法 / 安防侧：需向运维端提供安防告警记录标准数据结构。

结论：本文件已经作为一期开发基线文档定版。后续若有调整，应基于本文迭代版本，而不是推翻本文重新回到需求澄清阶段。

13. 测试验收要点

模块	验收要点
登录	正确账号可登录，错误账号提示，退出后不可访问后台页面。
首页	状态、统计、告警、快捷入口可正常展示和跳转。
内容管理	欢迎语、问答库、素材、方案、播报任务、主题均可增删改查。
访客管理	访客记录、预约记录、白名单可查询，导出结果正确。
运维管理	设备状态、控制、运行日志、对话日志、告警日志可查看，OTA 升级流程完整。
运维管理	设备状态可展示，控制操作有确认弹窗和结果反馈，参数保存有效，OTA 流程完整。
日志与权限	关键操作写入操作日志，不同角色权限生效。