迎宾巡逻安防机器人运维端 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
	展示主题配置	维护机器人对外展示界面的品牌与主题风格。	P1
访客管理	访客记录	查看访客登记记录，支持查询、详情、导出。	P1
	预约记录	查看主控平台同步的预约记录。	P1
	白名单管理	维护人员白名单数据，支持通过人脸照片、身份证号、手机号进行白名单匹配。	P1
监控管理	视频预览	查看机器人摄像头实时画面。	P1
	远程喊话	下发喊话内容、查看执行结果。	P1
	对话日志	查看人机交互日志。	P1
	安防告警日志	查看机器人侧安防告警记录。	P1
运维管理	设备状态	查看详细设备状态、资源占用、模块状态。	P0
	设备控制	提供一键充电、停止充电、重启、关机、服务重启等操作。	P0
	运行参数配置	动态读取参数分组与字段，支持编辑与保存。	P0
	系统诊断	查看诊断检查结果、自检结果与关键资源状态。	P1
	日志中心	统一查看系统、设备、升级、操作等日志。	P0
	软件版本 / 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 生成基础列表、查询、详情、编辑、删除接口和页面；上传素材、自动解析文件信息、缩略图/视频封面、图片/视频预览、引用状态维护、删除引用保护需要二次定制。前端只允许用户维护素材名称、启用状态和备注，文件信息由上传接口自动生成或解析。
	播放方案管理	定制开发	否	涉及主子表、素材选择、拖拽排序、播放时长、复制方案、预览方案等复杂交互，建议 Cursor 或开发人员手工实现。
	播报内容管理	RuoYi 生成后微调	适合	典型单表 CRUD，可基于 robot_ops_broadcast_content 生成，再补充测试播报按钮。
	播报任务管理	RuoYi 生成后定制	部分适合	基础 CRUD 可生成；时间段、频率、循环规则、复制任务等需要定制表单校验和交互。
	展示主题配置	RuoYi 生成后定制	部分适合	基础 CRUD 可生成；Logo/背景上传、颜色选择器、主题预览、设为启用需要定制。
访客管理	访客记录	RuoYi 生成后定制	部分适合	可基于 robot_ops_visitor_record 生成只读列表和详情页面；需去掉新增、编辑、删除，补充到访类型、登记方式、访客来源、来访事由、照片预览、时间范围查询、详情弹窗和导出字段优化。列表中访客照片前置到身份证号后，便于快速识别访客身份。
	预约记录	RuoYi 生成后微调	适合	典型查询列表和详情页面，可基于 robot_ops_appointment_record 生成，数据来源为主控平台同步。
	白名单管理	RuoYi 生成后定制	部分适合	可基于 robot_ops_whitelist 生成基础 CRUD；需补充身份证号、人脸照片上传/预览、有效期、人员类型、启用/停用、导入导出，以及手机号/身份证号/人脸照片至少填写一种的表单校验。
监控管理	视频预览	定制开发	否	实时视频播放、重连、全屏、状态提示依赖视频流接口和播放器组件，需要定制开发。
	远程喊话	半定制开发	部分适合	喊话记录列表可基于 robot_ops_shout_record 生成；喊话输入、预置短语、立即喊话操作需要定制。
	对话日志	RuoYi 生成后微调	适合	典型日志查询和详情页面，可基于 robot_ops_dialogue_log 生成，详情页需展示原始请求和原始响应。
	安防告警日志	RuoYi 生成后微调	适合	典型日志查询页面，可基于 robot_ops_alarm_log 生成，再补充确认告警、忽略告警、抓拍图预览。
运维管理	设备状态	定制开发	否	数据来自机器人侧实时接口，不落库；页面为状态面板和模块状态展示，不能按数据库表生成。
	设备控制	半定制开发	部分适合	控制记录列表可基于 robot_ops_control_record 生成；一键充电、重启、关机、服务重启等控制按钮和二次确认需要定制。
	运行参数配置	定制开发	否	虽然有 robot_ops_param 表，但页面需要根据参数分组和值类型动态渲染表单控件，不能直接按固定 CRUD 页面生成。
	系统诊断	半定制开发	部分适合	诊断项列表可基于 robot_ops_diagnosis_item 生成；立即诊断、诊断总览和诊断结果聚合需要定制。
	日志中心	RuoYi 生成后定制	部分适合	单表日志可生成，但日志中心需要整合 robot_ops_sys_log 和 robot_ops_operate_log，并通过 sourceType 区分来源，需要定制查询逻辑。
	软件版本 / 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 首页 / 工作台

首页按顶部状态区 + 统计区 + 告警区 + 快捷操作区 + 最近记录区进行设计。

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

6.2.1 顶部状态区字段

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

6.2.2 统计区字段

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

6.2.3 告警与快捷操作

区块	内容
最近系统异常	最近 5 条系统异常摘要，点击跳日志中心。
最近安防告警	最近 5 条安防告警摘要，点击跳安防告警日志。
最近升级失败	最近 5 条升级失败摘要，点击跳 OTA 升级页。
快捷按钮	查看摄像头、远程喊话、一键充电、停止充电、重启机器人、进入 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，视频可为视频封面图；fileSize 为文件大小，单位字节；fileFormat 为文件格式/后缀；mimeType 为文件 MIME 类型；resolution 为分辨率；durationSeconds 为视频时长，图片素材为空。
上传规则	图片支持 jpg/png/webp；视频支持 mp4；单文件大小默认上限 500MB。上传接口至少应返回 fileUrl、fileSize、fileFormat、mimeType、assetType；thumbnailUrl、resolution、durationSeconds 可根据后端解析能力逐步完善，前端需做好空值兜底展示。
引用状态	quotedFlag 表示素材是否被播放方案引用，由系统维护，前端只读展示，不允许编辑。删除素材时，后端必须检查播放方案明细表中的实际引用关系，不应仅依赖 quotedFlag。
引用保护	被播放方案引用的素材不可直接删除，需先解除引用。接口应返回明确提示，例如"该素材已被 2 个播放方案引用，请先解除引用后再删除"。
预览规则	图片弹窗预览；视频弹窗播放器预览；视频无缩略图时，列表展示默认视频图标；无法播放时提示格式不支持。
业务规则	启用状态为启用的素材可被新播放方案选择；停用素材不可被新播放方案选择，但历史播放方案已引用的停用素材仍需支持回显。

6.3.4 播放方案管理页面

模块	详细设计
查询条件	方案名称、是否默认、启用状态。
列表字段	方案名称、素材数、循环方式、默认方案、启用状态、更新时间、操作。
编辑页面字段	方案名称（planName）、循环方式（loopMode）、是否默认（isDefault）、启用状态（status）、备注（remark）、素材明细列表（itemList）。
素材明细字段	素材 ID（assetId）、素材名称（assetName，关联素材表展示字段）、素材类型（assetType，关联素材表展示字段）、播放顺序（playOrder）、停留时长（staySeconds）、转场方式（transitionType）。
操作按钮	新增、编辑、复制、删除、设为默认、启用/停用、预览。
交互规则	支持拖拽排序；图片素材必须填写停留时长；视频素材默认播完切换。

6.3.5 播报内容管理页面

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

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，单位为分钟；当循环类型为按星期时，至少选择一个星期；当循环类型为按日期时，至少选择一个指定日期。
交互规则	关联播报内容列表显示内容名称；新增/编辑时仅允许选择启用状态的播报内容；历史任务关联的播报内容如已停用，编辑时仍需可回显，并显示"已停用"提示，但不可重新选择停用内容。

6.3.7 展示主题配置页面

模块	详细设计
查询条件	主题名称、启用状态。
列表字段	主题名称、Logo、背景资源、主色、启用状态、当前启用标识、更新时间、操作。
编辑字段	主题名称（themeName）、Logo 地址（logoUrl）、背景类型（backgroundType）、背景资源地址（backgroundUrl）、主色（primaryColor）、辅助色（secondaryColor）、欢迎标题（welcomeTitle）、欢迎副标题（welcomeSubTitle）、启用状态（status）。
操作按钮	新增、编辑、删除、设为启用、预览。
业务规则	同一时刻仅允许一个主题处于“当前启用”状态。

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 视频预览页面

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

6.5.2 远程喊话页面

区域	详细设计
输入区域	喊话文本输入框，最大 500 字。
参数区域	音量（0-100）、播放次数（1-5）、是否立即打断当前播报。
预置短语	展示常用喊话语句，点击自动填充。
结果区域	显示最近 10 次喊话记录与执行结果。
操作按钮	立即喊话、清空内容。

6.5.3 对话日志页面

模块	详细设计
查询条件	时间范围、会话 ID、用户问题关键字、命中状态、来源场景。
列表字段	时间、会话 ID、用户问题、机器人回答摘要、命中方式、来源场景、状态、操作。
详情字段	会话 ID（sessionId）、提问时间（askTime）、用户问题（question）、机器人回答（answer）、命中方式（hitType）、来源场景（sceneType）、结果状态（resultStatus）、原始请求（rawRequest）、原始响应（rawResponse）。
操作按钮	查看详情、导出。

6.5.4 安防告警日志页面

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

6.6 运维管理

6.6.1 设备状态页面

区域	字段
基础信息	机器人名称（robotName）、机器人编号（robotCode）、序列号（serialNo）、IP 地址（ipAddress）、MAC 地址（macAddress）、运行时长（uptime）。
运行信息	在线状态（onlineStatus）、工作状态（workStatus）、电量百分比（batteryLevel）、充电状态（chargeStatus）、网络状态（networkStatus）。
系统资源	CPU 使用率（cpuUsage）、内存使用率（memoryUsage）、磁盘使用率（diskUsage）、温度（temperature）。
模块状态	摄像头状态（cameraStatus）、麦克风状态（micStatus）、扬声器状态（speakerStatus）、屏幕状态（screenStatus）、主服务状态（mainServiceStatus）。
时间信息	系统时间（serverTime）、最近心跳时间（lastHeartbeatTime）。

以上设备状态字段均由机器人侧实时接口返回，运维端一期不做本地数据库持久化。

6.6.2 设备控制页面

控制项	说明	返回字段
一键充电	触发机器人进入充电流程	任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）
停止充电	停止当前充电动作	任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）
重启机器人	执行整机重启	任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）
关机	执行安全关机	任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）
重启应用服务	重启指定服务	任务ID（taskId）、服务名称（serviceName）、执行状态（resultStatus）
音频测试	播放测试音频或测试播报	执行状态（resultStatus）
屏幕测试	切换测试画面	执行状态（resultStatus）
控制记录	所有控制动作统一写入设备控制记录表和操作日志，便于追踪 taskId、执行结果和失败原因。	控制记录ID（controlRecordId）、任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）

6.6.3 运行参数配置页面

页面采用模块 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.6.4 系统诊断页面

模块	设计说明
诊断总览	显示诊断结果汇总：正常项数量、告警项数量、失败项数量。
诊断列表	项目名称、检查结果、详情描述、最后检查时间。
检查项	网络检查、摄像头检查、麦克风检查、扬声器检查、磁盘空间检查、服务状态检查。
操作按钮	立即诊断、刷新结果、导出诊断结果。

6.6.5 日志中心页面

模块	详细设计
查询条件	日志类型、关键字、时间范围、结果状态。
日志类型	系统日志、设备日志、操作日志、升级日志、服务日志。
列表字段	日志时间、日志类型、日志级别、模块名称、摘要、结果状态、操作。
详情字段	日志时间（logTime）、日志类型（logType）、日志级别（logLevel）、模块名称（moduleName）、日志内容（content）、结果状态（resultStatus）、追踪 ID（traceId）、备注（remark）。
操作按钮	查看详情、导出。

6.6.6 软件版本 / 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.7 系统设置

6.7.1 账号管理页面

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

6.7.2 修改密码页面

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

6.7.3 基础设置页面

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

7. 后端接口设计

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

7.0 通用文件上传接口

接口	方法	说明	请求参数	返回字段	适用场景
/robot-ops/common/file/upload	POST	通用文件上传	文件（file）、业务类型（bizType）	文件地址（fileUrl）、文件名称（fileName）、文件大小（fileSize）、文件格式（fileFormat）	主题Logo、主题背景资源，普通附件等。素材库文件仍优先使用素材上传接口。

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

素材库文件上传优先使用素材管理专用上传接口 /robot-ops/content/media/upload。素材上传接口除保存文件外，还需要生成或解析 assetType、fileSize、fileFormat、mimeType、thumbnailUrl、durationSeconds、resolution 等素材字段；通用文件上传接口不承担素材入库和素材元数据解析职责。

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_operate_log、robot_ops_upgrade_record、robot_ops_sys_log

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' 执行"有则更新，无则新增"的逻辑，避免初始化数据缺失时保存失败。

恢复默认由前端本地重置表单完成，不单独调用后端恢复默认接口；用户点击“保存配置”后才真正写入数据库。

status 控制欢迎语功能整体是否启用；voiceEnabled 控制欢迎语触发时是否进行语音播报；cooldownSeconds 表示语音播报冷却时间，用于避免短时间内重复语音播报。

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 素材管理接口

接口	方法	说明	请求参数	返回/处理字段	数据库表
/robot-ops/content/media/page	GET	素材分页	素材名称（assetName）、素材类型（assetType）、启用状态（status）、上传时间范围、pageNum、pageSize	id、assetName、assetType、fileFormat、fileSize、durationSeconds、resolution、thumbnailUrl、quotedFlag、status、createTime	robot_ops_media_asset
/robot-ops/content/media/{id}	GET	素材详情	素材ID（id）	id、assetName、assetType、fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、quotedFlag、status、remark、createTime、updateTime	robot_ops_media_asset
/robot-ops/content/media/upload	POST	上传素材	文件（file）、素材名称（assetName，可选，未填写时默认使用文件名）、启用状态（status，可选，默认启用）、备注（remark，可选）	素材ID（id）、素材名称（assetName）、素材类型（assetType）、文件地址（fileUrl）、缩略图地址（thumbnailUrl）、文件大小（fileSize）、文件格式（fileFormat）、MIME类型（mimeType）、视频时长（durationSeconds）、分辨率（resolution）、启用状态（status）	robot_ops_media_asset
/robot-ops/content/media	PUT	编辑素材	素材ID（id）、素材名称（assetName）、启用状态（status）、备注（remark）	无	robot_ops_media_asset
/robot-ops/content/media/{id}	DELETE	删除素材	素材ID（id）	无；如素材已被播放方案引用，应返回不可删除原因和引用数量	robot_ops_media_asset、robot_ops_play_plan_item
/robot-ops/content/media/export	GET	导出素材	同分页查询条件	Excel文件；建议导出素材名称、素材类型、文件格式、文件大小、视频时长、分辨率、引用状态、启用状态、上传时间、备注	robot_ops_media_asset

素材上传接口需要在 RuoYi 生成的基础 CRUD 之外进行二次开发。RuoYi 生成器可生成列表、详情、编辑、删除等基础接口，但不会自动解析上传文件信息、生成视频封面、解析视频时长和分辨率。

上传接口一期至少应返回 fileUrl、fileSize、fileFormat、mimeType、assetType。thumbnailUrl、resolution、durationSeconds 可根据后端解析能力逐步完善；前端需对这些字段为空的情况做兜底展示。

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

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

7.4.4 播放方案接口

接口	方法	说明	请求/返回字段	数据库表
/robot-ops/content/play-plan/page	GET	播放方案分页	方案名称（planName）、是否默认（isDefault）、启用状态（status）、pageNum、pageSize；返回 id、planName、assetCount、loopMode、isDefault、status、updateTime	robot_ops_play_plan、robot_ops_play_plan_item
/robot-ops/content/play-plan/{id}	GET	播放方案详情	返回 planName、loopMode、isDefault、status、remark、itemList	robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset
/robot-ops/content/play-plan	POST	新增播放方案	planName、loopMode、isDefault、status、remark、itemList	robot_ops_play_plan、robot_ops_play_plan_item
/robot-ops/content/play-plan	PUT	编辑播放方案	id、planName、loopMode、isDefault、status、remark、itemList	robot_ops_play_plan、robot_ops_play_plan_item
/robot-ops/content/play-plan/{id}	DELETE	删除播放方案	方案ID（id）	robot_ops_play_plan、robot_ops_play_plan_item
/robot-ops/content/play-plan/{id}/set-default	POST	设为默认方案	方案ID（id）	robot_ops_play_plan
/robot-ops/content/play-plan/{id}/copy	POST	复制播放方案	方案ID（id）	robot_ops_play_plan、robot_ops_play_plan_item
/robot-ops/content/play-plan/{id}/preview	GET	预览播放方案	方案ID（id）	robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset

itemList 字段示例： [ { "assetId": 1, "playOrder": 1, "staySeconds": 10, "transitionType": "fade" } ]

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，便于前端展示关联播报内容名称，以及识别关联内容是否已停用。新增/编辑播报任务时，前端仅允许选择启用状态的播报内容；历史任务关联的停用内容需要支持回显。

7.4.6 展示主题接口

接口	方法	说明	请求/返回字段	数据库表
/robot-ops/content/theme/page	GET	主题分页	themeName、status、pageNum、pageSize；返回 logoUrl、backgroundType、backgroundUrl、primaryColor、currentEnabled、updateTime	robot_ops_theme
/robot-ops/content/theme/{id}	GET	主题详情	id、themeName、logoUrl、backgroundType、backgroundUrl、primaryColor、secondaryColor、welcomeTitle、welcomeSubTitle、status、currentEnabled	robot_ops_theme
/robot-ops/content/theme	POST	新增主题	themeName、logoUrl、backgroundType、backgroundUrl、primaryColor、secondaryColor、welcomeTitle、welcomeSubTitle、status	robot_ops_theme
/robot-ops/content/theme	PUT	编辑主题	id、themeName、logoUrl、backgroundType、backgroundUrl、primaryColor、secondaryColor、welcomeTitle、welcomeSubTitle、status	robot_ops_theme
/robot-ops/content/theme/{id}	DELETE	删除主题	主题ID（id）	robot_ops_theme
/robot-ops/content/theme/{id}/enable	POST	启用主题	主题ID（id）	robot_ops_theme

主题 Logo、背景资源可通过通用文件上传接口获取 fileUrl 后，再写入 logoUrl、backgroundUrl；也可根据项目实现复用素材上传接口。

启用主题时需要将其他主题 current_enabled 置为 0，当前主题置为 1，保证同一时间只有一个主题生效。

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/shout	POST	执行远程喊话	喊话文本（shoutText）、音量（volume）、播放次数（playTimes）、是否打断（interruptFlag）	记录ID（id）、执行状态（resultStatus）、结果信息（resultMsg）	robot_ops_shout_record、robot_ops_operate_log
/robot-ops/monitor/voice/shout-record/page	GET	喊话记录分页	shoutText、resultStatus、createTimeStart、createTimeEnd、pageNum、pageSize	id、shoutText、volume、playTimes、interruptFlag、resultStatus、resultMsg、operateBy、createTime	robot_ops_shout_record
/robot-ops/monitor/dialogue/page	GET	对话日志分页	sessionId、keyword、hitType、sceneType、askTimeStart、askTimeEnd、pageNum、pageSize	id、sessionId、askTime、question、answerSummary、hitType、sceneType、resultStatus	robot_ops_dialogue_log
/robot-ops/monitor/dialogue/{id}	GET	对话详情	日志ID（id）	sessionId、askTime、question、answer、hitType、sceneType、resultStatus、rawRequest、rawResponse	robot_ops_dialogue_log
/robot-ops/monitor/dialogue/export	GET	导出对话日志	同分页查询条件	Excel文件	robot_ops_dialogue_log
/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 运维管理接口

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/restart-service	POST	重启服务	服务名称（serviceName）	taskId、serviceName、resultStatus、resultMsg	robot_ops_control_record、robot_ops_operate_log
/robot-ops/ops/control/audio-test	POST	音频测试	测试文本（testText，可选）	resultStatus、resultMsg	robot_ops_control_record、robot_ops_operate_log
/robot-ops/ops/control/screen-test	POST	屏幕测试	测试类型（testType，可选）	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/diagnosis/overview	GET	诊断总览	normalCount、warnCount、failCount、lastCheckTime	robot_ops_diagnosis_item
/robot-ops/ops/diagnosis/page	GET	诊断项分页	itemName、resultStatus、pageNum、pageSize；返回 itemCode、itemName、resultStatus、detailMsg、lastCheckTime	robot_ops_diagnosis_item
/robot-ops/ops/diagnosis/run	POST	执行诊断	诊断项编码（itemCodes，可选）	normalCount、warnCount、failCount、itemList	robot_ops_diagnosis_item、robot_ops_sys_log
/robot-ops/ops/diagnosis/export	GET	导出诊断结果	resultStatus	Excel文件	robot_ops_diagnosis_item
/robot-ops/ops/log/page	GET	日志分页	日志来源类型（sourceType：SYS/OPERATE，可选）、logType、logLevel、keyword、resultStatus、logTimeStart、logTimeEnd、pageNum、pageSize	id、日志来源类型（sourceType）、logTime、logType、logLevel、moduleName、contentSummary、resultStatus、traceId	robot_ops_sys_log、robot_ops_operate_log
/robot-ops/ops/log/{id}	GET	日志详情	日志ID（id）、日志来源类型（sourceType）	logTime、logType、logLevel、moduleName、content、resultStatus、traceId、remark	robot_ops_sys_log、robot_ops_operate_log
/robot-ops/ops/log/export	GET	导出日志	同日志分页查询条件	Excel文件	robot_ops_sys_log、robot_ops_operate_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 四个公共字段，用于记录创建人、创建时间、更新人和更新时间。日志流水类表以业务时间、操作人、处理人等字段为主，不强制补齐全部公共字段。

问答分类使用 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 仅视频素材需要，图片素材为空。

说明：thumbnail_url 用于列表缩略图和视频封面展示。图片素材如未单独生成缩略图，可使用 file_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) DEFAULT 'loop' COMMENT '循环方式：loop循环播放，once播放一次', `is_default` CHAR(1) NOT NULL DEFAULT '0' COMMENT '是否默认方案：0否，1是', `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_play_plan_default` (`is_default`), KEY `idx_robot_ops_play_plan_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播放方案主表';

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 DEFAULT 0 COMMENT '播放顺序，数字越小越靠前', `stay_seconds` INT DEFAULT NULL COMMENT '停留时长，图片必填，视频可为空', `transition_type` VARCHAR(50) 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_item_plan_id` (`plan_id`), KEY `idx_robot_ops_play_plan_item_asset_id` (`asset_id`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播放方案素材明细表';

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启用', `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='播报内容表';

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_theme

CREATE TABLE `robot_ops_theme` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `theme_name` VARCHAR(100) NOT NULL COMMENT '主题名称', `logo_url` VARCHAR(255) DEFAULT NULL COMMENT 'Logo地址', `background_type` VARCHAR(20) DEFAULT NULL COMMENT '背景类型：image图片，video视频，color纯色', `background_url` VARCHAR(255) DEFAULT NULL COMMENT '背景资源地址', `primary_color` VARCHAR(20) DEFAULT NULL COMMENT '主题主色', `secondary_color` VARCHAR(20) DEFAULT NULL COMMENT '辅助色', `welcome_title` VARCHAR(200) DEFAULT NULL COMMENT '欢迎标题', `welcome_sub_title` VARCHAR(500) DEFAULT NULL COMMENT '欢迎副标题', `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用', `current_enabled` CHAR(1) NOT NULL DEFAULT '0' COMMENT '是否当前启用主题：0否，1是', `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_theme_current_enabled` (`current_enabled`), KEY `idx_robot_ops_theme_status` (`status`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='机器人展示主题表';

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', `session_id` VARCHAR(100) DEFAULT NULL COMMENT '会话ID', `ask_time` DATETIME DEFAULT NULL COMMENT '提问时间', `question` VARCHAR(1000) DEFAULT NULL COMMENT '用户问题', `answer` TEXT COMMENT '机器人回答', `hit_type` VARCHAR(50) DEFAULT NULL COMMENT '命中方式：FAQ命中、未命中、其他', `scene_type` VARCHAR(50) DEFAULT NULL COMMENT '来源场景：欢迎接待、咨询问答、其他', `result_status` VARCHAR(20) DEFAULT NULL COMMENT '结果状态：SUCCESS成功，FAIL失败，TIMEOUT超时', `raw_request` TEXT COMMENT '原始请求内容', `raw_response` TEXT COMMENT '原始响应内容', `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间', PRIMARY KEY (`id`), KEY `idx_robot_ops_dialogue_log_session_id` (`session_id`), KEY `idx_robot_ops_dialogue_log_ask_time` (`ask_time`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='人机对话日志表';

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', `log_time` DATETIME DEFAULT NULL COMMENT '日志时间', `log_type` VARCHAR(50) DEFAULT NULL COMMENT '日志类型：系统日志、设备日志、升级日志、服务日志', `log_level` VARCHAR(20) DEFAULT NULL COMMENT '日志级别：INFO、WARN、ERROR', `module_name` VARCHAR(100) DEFAULT NULL COMMENT '模块名称', `content` TEXT COMMENT '日志内容', `result_status` VARCHAR(20) DEFAULT NULL COMMENT '结果状态', `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_type` (`log_type`), KEY `idx_robot_ops_sys_log_level` (`log_level`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统日志表';

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='运行参数配置表';

8.5.4 系统诊断项表 robot_ops_diagnosis_item

CREATE TABLE `robot_ops_diagnosis_item` ( `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID', `item_code` VARCHAR(50) NOT NULL COMMENT '诊断项编码', `item_name` VARCHAR(100) NOT NULL COMMENT '诊断项名称', `result_status` VARCHAR(20) DEFAULT NULL COMMENT '检查结果：NORMAL正常，WARN告警，FAIL失败', `detail_msg` VARCHAR(1000) DEFAULT NULL COMMENT '详情描述', `last_check_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_diagnosis_item_code` (`item_code`) ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统诊断项表';

说明：一期仅保留各诊断项的最新诊断结果；如后续需要追踪每次诊断历史，可在二期扩展诊断记录表和诊断明细表。

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 流程完整。
日志与权限	关键操作写入操作日志，不同角色权限生效。