Strona główna Odkrywaj Pomoc
Zaloguj się
gebadi
/
RobotSpineWeb
4
0
Forkuj 0
Pliki Problemy 0 Oczekujące zmiany 0 Wiki
Drzewo: 6c73a8bcd3
Gałęzie Tagi
RobotSpineWeb
/
迎宾巡逻安防机器人运维端Web管理系统详细设计开发文档_V2.1.html

迎宾巡逻安防机器人运维端Web管理系统详细设计开发文档_V2.1.html 144 KB
Historia Czysty

12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970717273747576777879808182838485868788899091929394959697989910010110210310410510610710810911011111211311411511611711811912012112212312412512612712812913013113213313413513613713813914014114214314414514614714814915015115215315415515615715815916016116216316416516616716816917017117217317417517617717817918018118218318418518618718818919019119219319419519619719819920020120220320420520620720820921021121221321421521621721821922022122222322422522622722822923023123223323423523623723823924024124224324424524624724824925025125225325425525625725825926026126226326426526626726826927027127227327427527627727827928028128228328428528628728828929029129229329429529629729829930030130230330430530630730830931031131231331431531631731831932032132232332432532632732832933033133233333433533633733833934034134234334434534634734834935035135235335435535635735835936036136236336436536636736836937037137237337437537637737837938038138238338438538638738838939039139239339439539639739839940040140240340440540640740840941041141241341441541641741841942042142242342442542642742842943043143243343443543643743843944044144244344444544644744844945045145245345445545645745845946046146246346446546646746846947047147247347447547647747847948048148248348448548648748848949049149249349449549649749849950050150250350450550650750850951051151251351451551651751851952052152252352452552652752852953053153253353453553653753853954054154254354454554654754854955055155255355455555655755855956056156256356456556656756856957057157257357457557657757857958058158258358458558658758858959059159259359459559659759859960060160260360460560660760860961061161261361461561661761861962062162262362462562662762862963063163263363463563663763863964064164264364464564664764864965065165265365465565665765865966066166266366466566666766866967067167267367467567667767867968068168268368468568668768868969069169269369469569669769869970070170270370470570670770870971071171271371471571671771871972072172272372472572672772872973073173273373473573673773873974074174274374474574674774874975075175275375475575675775875976076176276376476576676776876977077177277377477577677777877978078178278378478578678778878979079179279379479579679779879980080180280380480580680780880981081181281381481581681781881982082182282382482582682782882983083183283383483583683783883984084184284384484584684784884985085185285385485585685785885986086186286386486586686786886987087187287387487587687787887988088188288388488588688788888989089189289389489589689789889990090190290390490590690790890991091191291391491591691791891992092192292392492592692792892993093193293393493593693793893994094194294394494594694794894995095195295395495595695795895996096196296396496596696796896997097197297397497597697797897998098198298398498598698798898999099199299399499599699799899910001001100210031004100510061007100810091010101110121013101410151016101710181019102010211022102310241025102610271028102910301031103210331034103510361037103810391040104110421043104410451046104710481049105010511052105310541055105610571058105910601061106210631064106510661067106810691070107110721073107410751076107710781079108010811082 
  1. <!DOCTYPE html>
    2. 

  2. <html lang="zh-CN">
    3. 

  3. <head>
    4. 

  4.   <meta charset="UTF-8" />
    5. 

  5.   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    6. 

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

  7.   <style>
    8. 

  8.     :root{--primary:#1f7aec;--green:#10b981;--orange:#f59e0b;--red:#ef4444;--purple:#7c3aed;--text:#1f2937;--sub:#4b5563;--line:#e5e7eb;--bg:#f6f8fb;--card:#fff;--tag:#eef4ff;--code:#f8fafc}
    9. 

  9.     *{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;font-family:"PingFang SC","Microsoft YaHei",Arial,sans-serif;color:var(--text);background:var(--bg);line-height:1.72}
    10. 

  10.     .container{width:1240px;max-width:calc(100vw - 48px);margin:24px auto 60px}.hero{background:linear-gradient(135deg,#0f172a 0%,#1d4ed8 52%,#0ea5e9 100%);color:#fff;border-radius:22px;padding:38px 42px;box-shadow:0 18px 50px rgba(17,24,39,.16)}
    11. 

  11.     .hero h1{margin:0 0 12px;font-size:34px;line-height:1.25}.hero p{margin:8px 0;opacity:.96;font-size:15px}.meta{display:flex;gap:12px;flex-wrap:wrap;margin-top:18px}.chip{padding:6px 12px;border-radius:999px;background:rgba(255,255,255,.14);border:1px solid rgba(255,255,255,.18);font-size:13px}
    12. 

  12.     .section{background:var(--card);border-radius:18px;padding:28px 30px;margin-top:20px;box-shadow:0 10px 30px rgba(15,23,42,.06)}h2{margin:0 0 14px;font-size:24px;color:#111827;padding-left:14px;border-left:5px solid var(--primary)}h3{margin:26px 0 10px;font-size:18px;color:#111827}h4{margin:20px 0 8px;font-size:16px;color:#111827}p,li{font-size:14px;color:var(--sub)}ul,ol{margin:8px 0 8px 22px;padding:0}
    13. 

  13.     .grid-2{display:grid;grid-template-columns:1fr 1fr;gap:24px}.grid-3{display:grid;grid-template-columns:repeat(3,1fr);gap:16px}.card{border:1px solid var(--line);border-radius:14px;padding:16px 18px;background:#fff}.card strong{color:#111827}.scenario-grid{display:grid;grid-template-columns:1fr 1fr;gap:24px;margin-top:14px}.scenario-card{border:1px solid #d9dee7;border-radius:16px;padding:20px 24px 22px;background:#fff;min-height:210px}.scenario-card h4{margin:0 0 12px;font-size:16px;line-height:1.4;color:#111827}.scenario-card ul{margin:0 0 0 20px;padding:0}.scenario-card li{font-size:14px;line-height:1.75;color:#4b5563;margin:2px 0}.tag{display:inline-block;padding:3px 10px;margin-right:8px;margin-bottom:8px;border-radius:999px;background:var(--tag);color:var(--primary);font-size:12px;border:1px solid #dbeafe}
    14. 

  14.     .warn{border-left:5px solid var(--orange);background:#fffaf0;padding:16px 18px;border-radius:12px;color:#7c5a10;font-size:14px}.danger{border-left:5px solid var(--red);background:#fff5f5;padding:16px 18px;border-radius:12px;color:#8f1d1d;font-size:14px}.ok{border-left:5px solid var(--green);background:#f0fdf4;padding:16px 18px;border-radius:12px;color:#166534;font-size:14px}.note{border-left:5px solid var(--purple);background:#faf5ff;padding:16px 18px;border-radius:12px;color:#6b21a8;font-size:14px}
    15. 

  15.     table{width:100%;border-collapse:collapse;margin-top:10px;background:#fff;border:1px solid var(--line);table-layout:fixed}th,td{border:1px solid var(--line);padding:10px 12px;text-align:left;vertical-align:top;font-size:13px;color:var(--sub);word-break:break-word}th{background:#f8fafc;color:#111827;font-weight:600}
    16. 

  16.     .toc{columns:2;gap:30px}.toc a{display:block;text-decoration:none;color:var(--primary);padding:3px 0;font-size:14px}.code{background:var(--code);border:1px solid var(--line);border-radius:12px;padding:14px 16px;font-family:Consolas,Monaco,monospace;font-size:12px;line-height:1.6;color:#0f172a;white-space:pre-wrap;overflow:auto}.footer{text-align:center;color:#94a3b8;margin-top:20px;font-size:12px}code.inline{background:#eff6ff;color:#1d4ed8;border:1px solid #dbeafe;padding:2px 6px;border-radius:6px;font-size:12px}
    17. 

  17.     @media(max-width:900px){.grid-2,.grid-3,.scenario-grid{grid-template-columns:1fr}.scenario-card{padding:18px 20px}.scenario-card h4{font-size:16px}.scenario-card li{font-size:14px}.toc{columns:1}.container{max-width:calc(100vw - 24px)}.hero{padding:24px}.section{padding:22px}table{display:block;overflow:auto}}
    18. 

  18.   </style>
    19. 

  19. </head>
    20. 

  20. <body>
    21. 

  21. <div class="container">
    22. 

  22.   <div class="hero">
    23. 

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

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

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

  26.     <div class="meta"><span class="chip">技术基线：RuoYi + Vue3</span><span class="chip">文档级别：详细设计开发版</span><span class="chip">单机器人本地部署</span><span class="chip">局域网 IP + 端口访问</span></div>
    27. 

  27.   </div>
    28. 

  28. 

  29.   <div class="section"><h2>目录</h2><div class="toc">
    30. 

  30.     <a href="#s1">1. 项目定位与约束</a><a href="#s2">2. 用户角色与使用目标</a><a href="#s3">3. 系统边界与设计原则</a><a href="#s4">4. 总体功能架构</a><a href="#s5">5. 菜单结构设计</a><a href="#s6">6. 页面详细设计</a><a href="#s7">7. 后端接口设计</a><a href="#s8">8. 数据库表设计</a><a href="#s9">9. 状态、日志与控制规则</a><a href="#s10">10. 权限与账号设计</a><a href="#s11">11. 开发优先级与实施顺序</a><a href="#s12">12. 其他团队配合要求</a><a href="#s13">13. 测试验收要点</a>
    31. 

  31.   </div></div>
    32. 

  32. 

  33.   <div class="section" id="s1"><h2>1. 项目定位与约束</h2>
    34. 

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

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

  36.     <h3>1.1 核心建设目标</h3><div class="grid-3"><div class="card"><strong>本地可维护</strong><br>不依赖云端也可完成机器人基础配置、升级、日志查看与简单控制。</div><div class="card"><strong>内容可配置</strong><br>欢迎语、问答库、多媒体、播报任务、展示主题等均在本地后台完成维护。</div><div class="card"><strong>运维可闭环</strong><br>首页看状态、模块看详情、日志可排查、版本可升级、问题可定位。</div></div>
    37. 

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

  38.   </div>
    39. 

  39. 

  40.   <div class="section" id="s2"><h2>2. 用户角色与使用目标</h2>
    41. 

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

  42.     <h3>2.1 典型使用目标</h3>
    43. 

  43.     <div class="scenario-grid">
    44. 

  44.       <div class="scenario-card">
    45. 

  45.         <h4>场景 A：现场交付初始化</h4>
    46. 

  46.         <ul>
    47. 

  47.           <li>接入机器人局域网</li>
    48. 

  48.           <li>通过 IP + 端口访问后台</li>
    49. 

  49.           <li>登录管理员账号</li>
    50. 

  50.           <li>配置欢迎语、问答库、展示主题</li>
    51. 

  51.           <li>上传多媒体素材并配置播放方案</li>
    52. 

  52.           <li>配置播报内容与定时任务</li>
    53. 

  53.         </ul>
    54. 

  54.       </div>
    55. 

  55.       <div class="scenario-card">
    56. 

  56.         <h4>场景 B：日常运维排查</h4>
    57. 

  57.         <ul>
    58. 

  58.           <li>查看机器人电量、运行状态、告警信息</li>
    59. 

  59.           <li>查看摄像头画面并进行远程喊话</li>
    60. 

  60.           <li>查看对话日志、访客记录、安防告警记录</li>
    61. 

  61.           <li>导出需要的记录或日志</li>
    62. 

  62.           <li>按需进行重启、充电等简单操作</li>
    63. 

  63.         </ul>
    64. 

  64.       </div>
    65. 

  65.     </div>
    66. 

  66.   </div>
    67. 

  67. 

  68.   <div class="section" id="s3"><h2>3. 系统边界与设计原则</h2>
    69. 

  69.     <h3>3.1 本系统负责内容</h3><div><span class="tag">本地登录</span><span class="tag">机器人状态查看</span><span class="tag">设备简单控制</span><span class="tag">欢迎语配置</span><span class="tag">问答库管理</span><span class="tag">素材管理</span><span class="tag">播放方案管理</span><span class="tag">播报内容管理</span><span class="tag">播报任务管理</span><span class="tag">展示主题配置</span><span class="tag">访客记录查看导出</span><span class="tag">预约记录查看</span><span class="tag">白名单管理</span><span class="tag">视频预览</span><span class="tag">远程喊话</span><span class="tag">对话日志</span><span class="tag">安防告警日志</span><span class="tag">参数配置</span><span class="tag">日志中心</span><span class="tag">系统诊断</span><span class="tag">版本管理与 OTA</span></div>
    70. 

  70.     <h3>3.2 本系统不负责内容</h3><ul><li>多机器人管理和云端总控。</li><li>建图、路径编辑、巡逻任务编排等导航管理页面。</li><li>安防算法逻辑本身，例如跌倒检测、越界检测的算法实现。</li><li>访客预约发起、被访人确认、通行权限下发等上层业务流程。</li></ul><div class="warn">地图与路径功能虽然属于机器人能力的重要组成部分，但本期由其他团队负责，不纳入本 HTML 文档页面和表设计范围。</div>
    71. 

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

  72.   </div>
    73. 

  73. 

  74.   <div class="section" id="s4"><h2>4. 总体功能架构</h2><div class="grid-3">
    75. 

  75.     <div class="card"><strong>首页</strong><ul><li>运行总览</li><li>统计信息</li><li>异常告警</li><li>快捷操作</li></ul></div><div class="card"><strong>内容管理</strong><ul><li>欢迎语配置</li><li>问答库管理</li><li>素材管理</li><li>播放方案管理</li><li>播报内容管理</li><li>播报任务管理</li><li>展示主题配置</li></ul></div><div class="card"><strong>访客管理</strong><ul><li>访客记录</li><li>预约记录</li><li>白名单管理</li></ul></div><div class="card"><strong>监控管理</strong><ul><li>视频预览</li><li>远程喊话</li><li>对话日志</li><li>安防告警日志</li></ul></div><div class="card"><strong>运维管理</strong><ul><li>设备状态</li><li>设备控制</li><li>运行参数配置</li><li>系统诊断</li><li>日志中心</li><li>软件版本 / OTA 升级</li></ul></div><div class="card"><strong>系统设置</strong><ul><li>账号管理</li><li>修改密码</li><li>基础设置</li></ul></div>
    76. 

  76.   </div></div>
    77. 

  77. 

  78.   <div class="section" id="s5"><h2>5. 菜单结构设计</h2>
    79. 

  79.     <table><thead><tr><th>一级菜单</th><th>二级菜单</th><th>页面职责</th><th>一期优先级</th></tr></thead><tbody>
    80. 

  80.       <tr><td>首页</td><td>首页总览</td><td>展示机器人实时状态、摘要统计、异常告警与快捷操作入口。</td><td>P0</td></tr>
    81. 

  81.       <tr><td rowspan="7">内容管理</td><td>欢迎语配置</td><td>维护机器人默认欢迎语和触发控制参数。</td><td>P0</td></tr><tr><td>问答库管理</td><td>维护 FAQ 问答数据，支持字典分类、相似问、导入导出；问答分类使用 RuoYi 字典，不单独建设问答分类管理菜单。</td><td>P0</td></tr><tr><td>素材管理</td><td>维护图片、视频素材。</td><td>P0</td></tr><tr><td>播放方案管理</td><td>维护素材播放编排关系、时长、顺序、默认方案。</td><td>P0</td></tr><tr><td>播报内容管理</td><td>维护可被播报任务引用的播报文本模板。</td><td>P0</td></tr><tr><td>播报任务管理</td><td>维护播报时间策略、频率、启停状态。</td><td>P0</td></tr><tr><td>展示主题配置</td><td>维护机器人对外展示界面的品牌与主题风格。</td><td>P1</td></tr>
    82. 

  82.       <tr><td rowspan="3">访客管理</td><td>访客记录</td><td>查看访客登记记录，支持查询、详情、导出。</td><td>P1</td></tr><tr><td>预约记录</td><td>查看主控平台同步的预约记录。</td><td>P1</td></tr><tr><td>白名单管理</td><td>维护人员白名单数据，支持通过人脸照片、身份证号、手机号进行白名单匹配。</td><td>P1</td></tr>
    83. 

  83.       <tr><td rowspan="4">监控管理</td><td>视频预览</td><td>查看机器人摄像头实时画面。</td><td>P1</td></tr><tr><td>远程喊话</td><td>下发喊话内容、查看执行结果。</td><td>P1</td></tr><tr><td>对话日志</td><td>查看人机交互日志。</td><td>P1</td></tr><tr><td>安防告警日志</td><td>查看机器人侧安防告警记录。</td><td>P1</td></tr>
    84. 

  84.       <tr><td rowspan="6">运维管理</td><td>设备状态</td><td>查看详细设备状态、资源占用、模块状态。</td><td>P0</td></tr><tr><td>设备控制</td><td>提供一键充电、停止充电、重启、关机、服务重启等操作。</td><td>P0</td></tr><tr><td>运行参数配置</td><td>动态读取参数分组与字段，支持编辑与保存。</td><td>P0</td></tr><tr><td>系统诊断</td><td>查看诊断检查结果、自检结果与关键资源状态。</td><td>P1</td></tr><tr><td>日志中心</td><td>统一查看系统、设备、升级、操作等日志。</td><td>P0</td></tr><tr><td>软件版本 / OTA 升级</td><td>查看版本、上传安装包、执行升级、查看升级记录。</td><td>P0</td></tr>
    85. 

  85.       <tr><td rowspan="3">系统设置</td><td>账号管理</td><td>维护后台账号、角色、状态。</td><td>P1</td></tr><tr><td>修改密码</td><td>当前登录账号修改密码。</td><td>P0</td></tr><tr><td>基础设置</td><td>维护系统名称、Logo、页脚信息等后台基础配置。</td><td>P2</td></tr>
    86. 

  86.     </tbody></table>
    87. 

  87. 

  88.     <h3>5.1 RuoYi 代码生成与定制开发划分</h3>
    89. 

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

  90.     <table>
    91. 

  91.       <thead>
    92. 

  92.         <tr>
    93. 

  93.           <th>一级菜单</th>
    94. 

  94.           <th>页面/模块</th>
    95. 

  95.           <th>开发方式建议</th>
    96. 

  96.           <th>是否适合 RuoYi 代码生成</th>
    97. 

  97.           <th>说明</th>
    98. 

  98.         </tr>
    99. 

  99.       </thead>
    100. 

  100.       <tbody>
    101. 

  101.         <tr><td>首页</td><td>首页总览</td><td>定制开发</td><td>否</td><td>首页涉及机器人实时状态、统计卡片、告警摘要、快捷操作入口，属于聚合看板页面，不能直接按单表 CRUD 生成。</td></tr>
    102. 

  102.         <tr><td rowspan="7">内容管理</td><td>欢迎语配置</td><td>定制开发</td><td>不建议生成前端列表页</td><td>欢迎语配置为单配置页，不是多条数据 CRUD 页面。数据库通过 config_key=default 定位默认配置；前端建议自定义表单页，直接加载和保存默认配置，不提供列表、新增、删除。</td></tr>
    103. 

  103.         <tr><td>问答库管理</td><td>RuoYi 主子表生成后定制</td><td>部分适合</td><td>可基于 robot_ops_faq、robot_ops_faq_similar 生成基础 CRUD；问题分类使用 RuoYi 字典 robot_faq_category，不单独生成问答分类管理页面；前端需将主子表明细表格调整为"相似问多行输入，一行一个"的交互方式；sortNo 作为保留字段，不在页面展示和编辑；启用/停用、导出、分类字典回显需按业务微调。一期暂不支持问答库导入，后续如运营需要批量维护再扩展。</td></tr>
    104. 

  104.         <tr><td>素材管理</td><td>RuoYi 生成后定制</td><td>部分适合</td><td>可基于 robot_ops_media_asset 生成基础列表、查询、详情、编辑、删除接口和页面；上传素材、自动解析文件信息、缩略图/视频封面、图片/视频预览、引用状态维护、删除引用保护需要二次定制。前端只允许用户维护素材名称、启用状态和备注，文件信息由上传接口自动生成或解析。</td></tr>
    105. 

  105.         <tr><td>播放方案管理</td><td>定制开发</td><td>否</td><td>涉及主子表、素材选择、拖拽排序、播放时长、复制方案、预览方案等复杂交互，建议 Cursor 或开发人员手工实现。</td></tr>
    106. 

  106.         <tr><td>播报内容管理</td><td>RuoYi 生成后微调</td><td>适合</td><td>典型单表 CRUD，可基于 robot_ops_broadcast_content 生成，再补充测试播报按钮。</td></tr>
    107. 

  107.         <tr><td>播报任务管理</td><td>RuoYi 生成后定制</td><td>部分适合</td><td>基础 CRUD 可生成；时间段、频率、循环规则、复制任务等需要定制表单校验和交互。</td></tr>
    108. 

  108.         <tr><td>展示主题配置</td><td>RuoYi 生成后定制</td><td>部分适合</td><td>基础 CRUD 可生成；Logo/背景上传、颜色选择器、主题预览、设为启用需要定制。</td></tr>
    109. 

  109.         <tr><td rowspan="3">访客管理</td><td>访客记录</td><td>RuoYi 生成后定制</td><td>部分适合</td><td>可基于 robot_ops_visitor_record 生成只读列表和详情页面；需去掉新增、编辑、删除，补充到访类型、登记方式、访客来源、来访事由、照片预览、时间范围查询、详情弹窗和导出字段优化。列表中访客照片前置到身份证号后，便于快速识别访客身份。</td></tr>
    110. 

  110.         <tr><td>预约记录</td><td>RuoYi 生成后微调</td><td>适合</td><td>典型查询列表和详情页面，可基于 robot_ops_appointment_record 生成，数据来源为主控平台同步。</td></tr>
    111. 

  111.         <tr><td>白名单管理</td><td>RuoYi 生成后定制</td><td>部分适合</td><td>可基于 robot_ops_whitelist 生成基础 CRUD；需补充身份证号、人脸照片上传/预览、有效期、人员类型、启用/停用、导入导出，以及手机号/身份证号/人脸照片至少填写一种的表单校验。</td></tr>
    112. 

  112.         <tr><td rowspan="4">监控管理</td><td>视频预览</td><td>定制开发</td><td>否</td><td>实时视频播放、重连、全屏、状态提示依赖视频流接口和播放器组件，需要定制开发。</td></tr>
    113. 

  113.         <tr><td>远程喊话</td><td>半定制开发</td><td>部分适合</td><td>喊话记录列表可基于 robot_ops_shout_record 生成；喊话输入、预置短语、立即喊话操作需要定制。</td></tr>
    114. 

  114.         <tr><td>对话日志</td><td>RuoYi 生成后微调</td><td>适合</td><td>典型日志查询和详情页面，可基于 robot_ops_dialogue_log 生成，详情页需展示原始请求和原始响应。</td></tr>
    115. 

  115.         <tr><td>安防告警日志</td><td>RuoYi 生成后微调</td><td>适合</td><td>典型日志查询页面，可基于 robot_ops_alarm_log 生成，再补充确认告警、忽略告警、抓拍图预览。</td></tr>
    116. 

  116.         <tr><td rowspan="6">运维管理</td><td>设备状态</td><td>定制开发</td><td>否</td><td>数据来自机器人侧实时接口，不落库；页面为状态面板和模块状态展示，不能按数据库表生成。</td></tr>
    117. 

  117.         <tr><td>设备控制</td><td>半定制开发</td><td>部分适合</td><td>控制记录列表可基于 robot_ops_control_record 生成；一键充电、重启、关机、服务重启等控制按钮和二次确认需要定制。</td></tr>
    118. 

  118.         <tr><td>运行参数配置</td><td>定制开发</td><td>否</td><td>虽然有 robot_ops_param 表，但页面需要根据参数分组和值类型动态渲染表单控件，不能直接按固定 CRUD 页面生成。</td></tr>
    119. 

  119.         <tr><td>系统诊断</td><td>半定制开发</td><td>部分适合</td><td>诊断项列表可基于 robot_ops_diagnosis_item 生成；立即诊断、诊断总览和诊断结果聚合需要定制。</td></tr>
    120. 

  120.         <tr><td>日志中心</td><td>RuoYi 生成后定制</td><td>部分适合</td><td>单表日志可生成，但日志中心需要整合 robot_ops_sys_log 和 robot_ops_operate_log，并通过 sourceType 区分来源，需要定制查询逻辑。</td></tr>
    121. 

  121.         <tr><td>软件版本 / OTA 升级</td><td>定制开发</td><td>否</td><td>升级包列表和升级记录可参考生成代码，但上传安装包、执行升级、进度刷新、结果展示属于流程型页面，需要定制开发。</td></tr>
    122. 

  122.         <tr><td rowspan="3">系统设置</td><td>账号管理</td><td>优先复用 RuoYi</td><td>视权限方案而定</td><td>如果使用 RuoYi 原生权限体系，优先复用系统用户、角色、菜单管理；如果采用本文简化账号表，可基于 robot_ops_user 生成后微调。</td></tr>
    123. 

  123.         <tr><td>修改密码</td><td>复用/定制均可</td><td>否</td><td>修改密码通常复用 RuoYi 用户中心能力，不建议按表生成单独 CRUD 页面。</td></tr>
    124. 

  124.         <tr><td>基础设置</td><td>半定制开发</td><td>部分适合</td><td>可基于 robot_ops_system_config 生成基础表单，但页面更接近单配置页，需定制保存逻辑。</td></tr>
    125. 

  125.       </tbody>
    126. 

  126.     </table>
    127. 

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

  128.   </div>
    129. 

  129. 

  130.   <div class="section" id="s6"><h2>6. 页面详细设计</h2>
    131. 

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

  132. 

  133.     <h3>6.2 首页 / 工作台</h3><p>首页按<strong>顶部状态区 + 统计区 + 告警区 + 快捷操作区 + 最近记录区</strong>进行设计。</p><div class="note">首页中的机器人基础信息、实时运行状态、资源占用状态、模块状态等数据由机器人侧接口实时返回，运维端一期不建设机器人基础信息表和设备状态快照表。</div>
    134. 

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

  135.     <h4>6.2.2 统计区字段</h4><table><thead><tr><th>字段</th><th>说明</th><th>点击跳转</th></tr></thead><tbody><tr><td>今日访客登记数量（todayVisitorCount）</td><td>今日访客登记数量</td><td>访客记录</td></tr><tr><td>今日预约记录数量（todayAppointmentCount）</td><td>今日预约记录数量</td><td>预约记录</td></tr><tr><td>今日对话次数（todayDialogueCount）</td><td>今日对话次数</td><td>对话日志</td></tr><tr><td>今日播报次数（todayBroadcastCount）</td><td>今日播报次数</td><td>播报任务</td></tr><tr><td>今日安防告警数量（todayAlarmCount）</td><td>今日安防告警数量</td><td>安防告警日志</td></tr><tr><td>今日运维操作次数（todayOperateCount）</td><td>今日运维操作次数</td><td>日志中心</td></tr></tbody></table>
    136. 

  136.     <h4>6.2.3 告警与快捷操作</h4><table><thead><tr><th>区块</th><th>内容</th></tr></thead><tbody><tr><td>最近系统异常</td><td>最近 5 条系统异常摘要，点击跳日志中心。</td></tr><tr><td>最近安防告警</td><td>最近 5 条安防告警摘要，点击跳安防告警日志。</td></tr><tr><td>最近升级失败</td><td>最近 5 条升级失败摘要，点击跳 OTA 升级页。</td></tr><tr><td>快捷按钮</td><td>查看摄像头、远程喊话、一键充电、停止充电、重启机器人、进入 OTA。</td></tr></tbody></table>
    137. 

  137. 

  138.     <h3>6.3 内容管理</h3>
    139. 

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

  140.     <h4>6.3.2 问答库管理页面</h4>
    141. 

  141. <table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody>
    142. 

  142. <tr><td>页面目标</td><td>维护机器人 FAQ 问答内容，支持按问题分类管理标准问题、相似问和答案内容。页面基于 robot_ops_faq 主表和 robot_ops_faq_similar 相似问表实现，前端以一个"问答库管理"页面统一维护，不单独建设相似问管理菜单。</td></tr>
    143. 

  143. <tr><td>查询条件</td><td>问题分类（categoryType，数据来源：RuoYi 字典 robot_faq_category）、标准问题关键字、启用状态。</td></tr>
    144. 

  144. <tr><td>列表字段</td><td>问题分类、标准问题、相似问数量、答案摘要、启用状态、更新时间、操作。</td></tr>
    145. 

  145. <tr><td>操作按钮</td><td>新增、编辑、删除、批量删除、启用/停用、导出。</td></tr>
    146. 

  146. <tr><td>编辑弹窗字段</td><td>问题分类（categoryType，RuoYi 字典 robot_faq_category）、标准问题（question）、相似问（similarQuestions）、答案内容（answer）、启用状态（status）、备注（remark）。</td></tr>
    147. 

  147. <tr><td>相似问交互</td><td>相似问使用多行文本框维护，一行一个相似问；保存时前端转换为相似问列表，后端写入 robot_ops_faq_similar 表。</td></tr>
    148. 

  148. <tr><td>答案内容规则</td><td>答案内容最多 2000 字，列表中只展示答案摘要，完整答案在编辑弹窗中维护。</td></tr>
    149. 

  149. <tr><td>排序规则</td><td>sortNo / sort_no 作为保留字段，数据库继续保留；前端页面一期不展示、不编辑。新增问答时默认 sortNo=0，编辑问答时保持原值。后续如需在机器人屏幕端展示推荐问答或人工排序，再重新设计推荐/置顶/排序能力。</td></tr>
    150. 

  150. <tr><td>业务规则</td><td>同一分类下标准问题建议不重复，新增和编辑时由后端进行重复校验。删除主问答时，应同步删除其相似问数据。</td></tr>
    151. 

  151. <tr><td>导入说明</td><td>问答库一期暂不支持导入。后续如运营确实需要批量维护问答内容，再单独扩展 Excel 导入模板、问题分类匹配、相似问拆分、重复校验和失败明细回显能力。</td></tr>
    152. 

  152. </tbody></table>
    153. 

  153.     <h4>6.3.3 素材管理页面</h4>
    154. 

  154. <table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody>
    155. 

  155. <tr><td>页面目标</td><td>维护机器人展示、播放方案等功能使用的图片和视频素材。素材管理可基于 RuoYi 生成基础列表和表单，再定制上传、缩略图展示、图片/视频预览、启用/停用、引用状态和删除保护能力。</td></tr>
    156. 

  156. <tr><td>查询条件</td><td>素材名称、素材类型、启用状态、上传时间范围。</td></tr>
    157. 

  157. <tr><td>列表字段</td><td>缩略图（thumbnailUrl）、素材名称（assetName）、素材类型（assetType）、文件格式（fileFormat）、文件大小（fileSize）、视频时长（durationSeconds）、分辨率（resolution）、上传时间（createTime）、引用状态（quotedFlag）、启用状态（status）、操作。</td></tr>
    158. 

  158. <tr><td>操作按钮</td><td>上传素材、预览、编辑、删除、启用/停用、批量删除。</td></tr>
    159. 

  159. <tr><td>编辑字段</td><td>素材名称（assetName）、启用状态（status）、备注（remark）。文件地址、缩略图、文件大小、文件格式、MIME 类型、视频时长、分辨率等信息由上传接口自动生成或解析，前端只读展示，不允许用户手动填写。</td></tr>
    160. 

  160. <tr><td>素材类型</td><td>素材类型 assetType 为业务类型，建议使用 RuoYi 字典 media_asset_type，字典项：image=图片，video=视频。素材类型可由上传接口根据文件 MIME 类型或后缀自动判断。</td></tr>
    161. 

  161. <tr><td>文件信息</td><td>fileUrl 为素材文件访问地址；thumbnailUrl 为缩略图地址，图片可等于 fileUrl，视频可为视频封面图；fileSize 为文件大小，单位字节；fileFormat 为文件格式/后缀；mimeType 为文件 MIME 类型；resolution 为分辨率；durationSeconds 为视频时长，图片素材为空。</td></tr>
    162. 

  162. <tr><td>上传规则</td><td>图片支持 jpg/png/webp；视频支持 mp4；单文件大小默认上限 500MB。上传接口至少应返回 fileUrl、fileSize、fileFormat、mimeType、assetType；thumbnailUrl、resolution、durationSeconds 可根据后端解析能力逐步完善，前端需做好空值兜底展示。</td></tr>
    163. 

  163. <tr><td>引用状态</td><td>quotedFlag 表示素材是否被播放方案引用，由系统维护，前端只读展示，不允许编辑。删除素材时，后端必须检查播放方案明细表中的实际引用关系，不应仅依赖 quotedFlag。</td></tr>
    164. 

  164. <tr><td>引用保护</td><td>被播放方案引用的素材不可直接删除，需先解除引用。接口应返回明确提示，例如"该素材已被 2 个播放方案引用，请先解除引用后再删除"。</td></tr>
    165. 

  165. <tr><td>预览规则</td><td>图片弹窗预览；视频弹窗播放器预览；视频无缩略图时，列表展示默认视频图标；无法播放时提示格式不支持。</td></tr>
    166. 

  166. <tr><td>业务规则</td><td>启用状态为启用的素材可被新播放方案选择；停用素材不可被新播放方案选择，但历史播放方案已引用的停用素材仍需支持回显。</td></tr>
    167. 

  167. </tbody></table>
    168. 

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

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

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

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

  172. 

  173.     <h3>6.4 访客管理</h3>
    174. 

  174.     <h4>6.4.1 访客记录页面</h4>
    175. 

  175. <table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody>
    176. 

  176. <tr><td>页面目标</td><td>展示已完成登记的访客到访记录。访客记录由机器人屏幕登记流程或扫码 H5 登记流程产生，运维端仅负责查看、详情和导出，不提供新增、编辑、删除。</td></tr>
    177. 

  177. <tr><td>查询条件</td><td>访客姓名、手机号、身份证号、到访类型、登记方式、被访对象、来访时间范围。</td></tr>
    178. 

  178. <tr><td>列表字段</td><td>访客姓名、手机号、身份证号、访客照片、到访类型、登记方式、访客来源、来访事由、预约单号、被访对象、来访时间、操作。</td></tr>
    179. 

  179. <tr><td>详情字段</td><td>访客姓名（visitorName）、手机号（mobile）、身份证号（idCardNo）、到访类型（visitType）、登记方式（registerType）、访客来源（visitorSource）、来访事由（visitReason）、访客照片（visitorPhoto）、预约单号（appointmentNo）、被访对象（visitedPerson）、来访时间（visitTime）、备注（remark）。</td></tr>
    180. 

  180. <tr><td>到访类型</td><td>用于区分访客到访业务类型，建议字典项为：APPOINTMENT=预约到访，WALK_IN=现场登记。</td></tr>
    181. 

  181. <tr><td>登记方式</td><td>用于区分访客完成登记的入口，建议字典项为：SCREEN=机器人端，H5=手机端。机器人端指访客在机器人屏幕完成登记；手机端指访客扫码后在 H5 页面完成登记。身份证读卡、手机号输入、人脸拍照等可作为机器人端登记流程中的信息采集方式，不单独作为登记方式。</td></tr>
    182. 

  182. <tr><td>访客来源</td><td>用于描述访客来自哪里或属于什么来源，字段为 visitorSource / visitor_source，适配公司、酒店、小区、园区、展厅等多场景，例如公司名称、合作方、亲友、外卖、快递、供应商、施工单位、旅行团等。该字段建议选填。</td></tr>
    183. 

  183. <tr><td>来访事由</td><td>用于描述访客本次到访目的，字段为 visitReason / visit_reason，例如业务接洽、走亲访友、酒店入住、外卖配送、快递投递、设备维修、参观接待、会议拜访、施工进场等。该字段建议选填，一期采用文本输入，不强制枚举。</td></tr>
    184. 

  184. <tr><td>访客照片</td><td>由机器人端摄像头或登记流程采集上传，运维端只做展示和预览，不支持手动上传修改。列表中访客照片放在身份证号之后，便于运维人员优先查看访客身份信息；详情中可展示较大尺寸照片预览。</td></tr>
    185. 

  185. <tr><td>预约关联</td><td>预约到访记录通过 appointmentNo 关联预约记录；现场登记记录 appointmentNo 可为空。</td></tr>
    186. 

  186. <tr><td>操作按钮</td><td>查看详情、导出。</td></tr>
    187. 

  187. <tr><td>业务规则</td><td>访客记录代表已经完成登记的到访记录，不设置登记结果字段。登记失败、身份证读取失败、扫码失败、预约匹配失败等过程异常，不进入访客记录，应进入日志中心或后续扩展的登记异常日志。</td></tr>
    188. 

  188. <tr><td>与白名单关系</td><td>访客记录与白名单识别记录分开管理。命中白名单不作为访客登记结果；白名单命中属于识别或通行逻辑，可后续在识别日志、通行记录或对话/安防日志中体现。</td></tr>
    189. 

  189. <tr><td>与预约记录关系</td><td>预约记录由主控平台同步，表示计划来访；访客到现场后通过机器人屏幕或扫码 H5 完成登记确认，并生成访客记录。</td></tr>
    190. 

  190. <tr><td>导出字段</td><td>导出列表主要字段；访客照片建议导出"有照片/无照片"或照片链接，不直接导出图片文件。</td></tr>
    191. 

  191. </tbody></table>
    192. 

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

  193.     <h4>6.4.3 白名单管理页面</h4>
    194. 

  194. <table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody>
    195. 

  195. <tr><td>页面目标</td><td>维护可被机器人识别为可信人员的白名单数据，支持通过人脸照片、身份证号、手机号等信息进行白名单匹配。</td></tr>
    196. 

  196. <tr><td>查询条件</td><td>姓名、手机号、身份证号、人员类型、来源类型、启用状态。</td></tr>
    197. 

  197. <tr><td>列表字段</td><td>姓名、手机号、身份证号、人员类型、是否有人脸照片、来源类型、有效期、启用状态、更新时间、操作。</td></tr>
    198. 

  198. <tr><td>编辑字段</td><td>姓名（name）、人员类型（whitelistType，页面显示为"人员类型"）、手机号（mobile）、身份证号（idCardNo）、人脸照片（faceImageUrl）、来源类型（sourceType，只读展示，不允许人工修改）、有效开始时间（validStartTime）、有效结束时间（validEndTime）、启用状态（status）、备注（remark）。</td></tr>
    199. 

  199. <tr><td>人员类型</td><td>人员类型用于描述白名单人员身份，建议字典项为：内部人员、访客、VIP、其他。不建议将"人脸白名单"作为人员类型，因为人脸识别属于匹配方式，不属于人员身份类型。</td></tr>
    200. 

  200. <tr><td>操作按钮</td><td>新增、编辑、删除、导入、导出、启用/停用。</td></tr>
    201. 

  201. <tr><td>表单校验</td><td>姓名、人员类型、来源类型、启用状态必填；手机号、身份证号、人脸照片三者至少填写一种；手机号填写时需符合大陆手机号格式；身份证号填写时需符合 18 位身份证基础格式；有效结束时间如填写，必须大于有效开始时间。</td></tr>
    202. 

  202. <tr><td>人脸照片规则</td><td>一期仅保存人脸照片地址（faceImageUrl），不保存人脸特征ID。机器人侧按照片进行人脸比对，建议上传清晰正脸照片；前端上传限制为 2MB，支持 png/jpg/jpeg 格式。</td></tr>
    203. 

  203. <tr><td>匹配规则</td><td>白名单不设置单一识别方式字段。机器人或后端根据当前采集到的身份信息进行匹配：人脸识别时通过人脸照片比对；身份证读取或输入时匹配身份证号；手机号输入时匹配手机号。任一方式匹配到启用且在有效期内的白名单人员，即视为白名单命中。</td></tr>
    204. 

  204. <tr><td>业务规则</td><td>来源类型由系统自动识别，不允许用户手动修改。运维后台手动新增和导入的数据默认来源类型为 1=本地录入；主控平台同步数据由同步接口写入 2=平台同步；机器人端采集数据由机器人采集接口写入 3=机器人采集。列表中展示来源类型，查询区支持按来源类型筛选。</td></tr>
    205. 

  205. <tr><td>有效期规则</td><td>有效开始时间为空表示立即生效；有效结束时间为空表示长期有效。列表中根据当前时间动态展示有效期状态：有效、未生效、已过期、长期有效。一期不提供有效期状态筛选条件。</td></tr>
    206. 

  206. </tbody></table>
    207. 

  207. 

  208.     <h3>6.5 监控管理</h3>
    209. 

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

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

  211.     <h4>6.5.3 对话日志页面</h4><table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody><tr><td>查询条件</td><td>时间范围、会话 ID、用户问题关键字、命中状态、来源场景。</td></tr><tr><td>列表字段</td><td>时间、会话 ID、用户问题、机器人回答摘要、命中方式、来源场景、状态、操作。</td></tr><tr><td>详情字段</td><td>会话 ID（sessionId）、提问时间（askTime）、用户问题（question）、机器人回答（answer）、命中方式（hitType）、来源场景（sceneType）、结果状态（resultStatus）、原始请求（rawRequest）、原始响应（rawResponse）。</td></tr><tr><td>操作按钮</td><td>查看详情、导出。</td></tr></tbody></table>
    212. 

  212.     <h4>6.5.4 安防告警日志页面</h4><table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody><tr><td>查询条件</td><td>告警类型、告警级别、处理状态、告警时间范围。</td></tr><tr><td>列表字段</td><td>告警时间、告警类型、告警级别、位置/来源、处理状态、描述摘要、操作。</td></tr><tr><td>详情字段</td><td>告警时间（alarmTime）、告警类型（alarmType）、告警级别（alarmLevel）、来源位置（sourcePosition）、处理状态（handleStatus）、描述（description）、抓拍图地址（snapshotUrl）、备注（remark）。</td></tr><tr><td>操作按钮</td><td>查看详情、确认告警、忽略告警、导出。</td></tr></tbody></table>
    213. 

  213. 

  214.     <h3>6.6 运维管理</h3>
    215. 

  215.     <h4>6.6.1 设备状态页面</h4><table><thead><tr><th>区域</th><th>字段</th></tr></thead><tbody><tr><td>基础信息</td><td>机器人名称（robotName）、机器人编号（robotCode）、序列号（serialNo）、IP 地址（ipAddress）、MAC 地址（macAddress）、运行时长（uptime）。</td></tr><tr><td>运行信息</td><td>在线状态（onlineStatus）、工作状态（workStatus）、电量百分比（batteryLevel）、充电状态（chargeStatus）、网络状态（networkStatus）。</td></tr><tr><td>系统资源</td><td>CPU 使用率（cpuUsage）、内存使用率（memoryUsage）、磁盘使用率（diskUsage）、温度（temperature）。</td></tr><tr><td>模块状态</td><td>摄像头状态（cameraStatus）、麦克风状态（micStatus）、扬声器状态（speakerStatus）、屏幕状态（screenStatus）、主服务状态（mainServiceStatus）。</td></tr><tr><td>时间信息</td><td>系统时间（serverTime）、最近心跳时间（lastHeartbeatTime）。</td></tr></tbody></table><p>以上设备状态字段均由机器人侧实时接口返回，运维端一期不做本地数据库持久化。</p>
    216. 

  216.     <h4>6.6.2 设备控制页面</h4><table><thead><tr><th>控制项</th><th>说明</th><th>返回字段</th></tr></thead><tbody><tr><td>一键充电</td><td>触发机器人进入充电流程</td><td>任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）</td></tr>
    217. 

  217. <tr><td>停止充电</td><td>停止当前充电动作</td><td>任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）</td></tr>
    218. 

  218. <tr><td>重启机器人</td><td>执行整机重启</td><td>任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）</td></tr>
    219. 

  219. <tr><td>关机</td><td>执行安全关机</td><td>任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）</td></tr>
    220. 

  220. <tr><td>重启应用服务</td><td>重启指定服务</td><td>任务ID（taskId）、服务名称（serviceName）、执行状态（resultStatus）</td></tr>
    221. 

  221. <tr><td>音频测试</td><td>播放测试音频或测试播报</td><td>执行状态（resultStatus）</td></tr>
    222. 

  222. <tr><td>屏幕测试</td><td>切换测试画面</td><td>执行状态（resultStatus）</td></tr>
    223. 

  223. <tr><td>控制记录</td><td>所有控制动作统一写入设备控制记录表和操作日志，便于追踪 taskId、执行结果和失败原因。</td><td>控制记录ID（controlRecordId）、任务ID（taskId）、执行状态（resultStatus）、结果信息（resultMsg）</td></tr></tbody></table>
    224. 

  224.     <h4>6.6.3 运行参数配置页面</h4><p>页面采用<strong>模块 Tab + 模块参数表</strong>形式。</p><table><thead><tr><th>字段</th><th>说明</th></tr></thead><tbody><tr><td>参数分组编码（groupCode）</td><td>参数分组编码，例如 audio、screen、system、device、service。</td></tr><tr><td>参数分组名称（groupName）</td><td>参数分组名称。</td></tr><tr><td>参数编码（paramCode）</td><td>参数编码。</td></tr><tr><td>参数名称（paramName）</td><td>参数名称。</td></tr><tr><td>参数值（paramValue）</td><td>参数值。</td></tr><tr><td>值类型（valueType）</td><td>string、int、float、boolean、enum。</td></tr><tr><td>单位（unit）</td><td>单位。</td></tr><tr><td>是否可编辑（editable）</td><td>是否可编辑。</td></tr><tr><td>是否必填（requiredFlag）</td><td>是否必填。</td></tr><tr><td>数值边界（minValue / maxValue）</td><td>数值边界。</td></tr><tr><td>枚举项（enumOptions）</td><td>枚举项 JSON。</td></tr><tr><td>参数说明（remark）</td><td>参数说明。</td></tr></tbody></table><p>操作按钮：刷新、保存、重置默认值。保存时需按 valueType 校验值类型和取值范围。</p>
    225. 

  225.     <h4>6.6.4 系统诊断页面</h4><table><thead><tr><th>模块</th><th>设计说明</th></tr></thead><tbody><tr><td>诊断总览</td><td>显示诊断结果汇总：正常项数量、告警项数量、失败项数量。</td></tr><tr><td>诊断列表</td><td>项目名称、检查结果、详情描述、最后检查时间。</td></tr><tr><td>检查项</td><td>网络检查、摄像头检查、麦克风检查、扬声器检查、磁盘空间检查、服务状态检查。</td></tr><tr><td>操作按钮</td><td>立即诊断、刷新结果、导出诊断结果。</td></tr></tbody></table>
    226. 

  226.     <h4>6.6.5 日志中心页面</h4><table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody><tr><td>查询条件</td><td>日志类型、关键字、时间范围、结果状态。</td></tr><tr><td>日志类型</td><td>系统日志、设备日志、操作日志、升级日志、服务日志。</td></tr><tr><td>列表字段</td><td>日志时间、日志类型、日志级别、模块名称、摘要、结果状态、操作。</td></tr><tr><td>详情字段</td><td>日志时间（logTime）、日志类型（logType）、日志级别（logLevel）、模块名称（moduleName）、日志内容（content）、结果状态（resultStatus）、追踪 ID（traceId）、备注（remark）。</td></tr><tr><td>操作按钮</td><td>查看详情、导出。</td></tr></tbody></table>
    227. 

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

  228. 

  229.     <h3>6.7 系统设置</h3>
    230. 

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

  231.     <h4>6.7.2 修改密码页面</h4><table><thead><tr><th>字段</th><th>说明</th></tr></thead><tbody><tr><td>原密码（oldPassword）</td><td>原密码。</td></tr><tr><td>新密码（newPassword）</td><td>新密码，建议 8-32 位。</td></tr><tr><td>确认新密码（confirmPassword）</td><td>确认新密码，必须与 newPassword 一致。</td></tr></tbody></table>
    232. 

  232.     <h4>6.7.3 基础设置页面</h4><table><thead><tr><th>字段</th><th>说明</th></tr></thead><tbody><tr><td>后台系统名称（systemName）</td><td>后台系统名称。</td></tr><tr><td>后台 Logo（systemLogo）</td><td>后台 Logo。</td></tr><tr><td>页脚文案（footerText）</td><td>页脚文案。</td></tr><tr><td>备案号/版权信息（recordNo）</td><td>备案号/版权信息，可选。</td></tr></tbody></table>
    233. 

  233.   </div>
    234. 

  234. 

  235.   <div class="section" id="s7"><h2>7. 后端接口设计</h2>
    236. 

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

  237.     <h3>7.0 通用文件上传接口</h3>
    238. 

  238.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求参数</th><th>返回字段</th><th>适用场景</th></tr></thead><tbody>
    239. 

  239.       <tr><td>/robot-ops/common/file/upload</td><td>POST</td><td>通用文件上传</td><td>文件（file）、业务类型（bizType）</td><td>文件地址（fileUrl）、文件名称（fileName）、文件大小（fileSize）、文件格式（fileFormat）</td><td>主题Logo、主题背景资源，普通附件等。素材库文件仍优先使用素材上传接口。</td></tr>
    240. 

  240.     </tbody></table>
    241. 

  241.     <div class="note">通用文件上传接口默认不单独建设文件记录表，上传后的 fileUrl 由具体业务表保存；如后续需要统一文件管理，再扩展附件表。</div>
    242. 

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

  243. 

  244. 

  245.     <h3>7.1 通用接口规范</h3>
    246. 

  246.     <h4>7.1.1 通用返回结构</h4>
    247. 

  247.     <div class="code">{
    248. 

  248.   "code": 200,
    249. 

  249.   "msg": "操作成功",
    250. 

  250.   "data": {},
    251. 

  251.   "timestamp": "2026-04-24 10:00:00"
    252. 

  252. }</div>
    253. 

  253.     <h4>7.1.2 分页返回结构</h4>
    254. 

  254.     <div class="code">{
    255. 

  255.   "code": 200,
    256. 

  256.   "msg": "查询成功",
    257. 

  257.   "data": {
    258. 

  258.     "total": 100,
    259. 

  259.     "pageNum": 1,
    260. 

  260.     "pageSize": 10,
    261. 

  261.     "rows": []
    262. 

  262.   },
    263. 

  263.   "timestamp": "2026-04-24 10:00:00"
    264. 

  264. }</div>
    265. 

  265.     <h4>7.1.3 通用状态码</h4>
    266. 

  266.     <table><thead><tr><th>状态码</th><th>说明</th><th>处理建议</th></tr></thead><tbody>
    267. 

  267.       <tr><td>200</td><td>成功</td><td>正常处理 data。</td></tr>
    268. 

  268.       <tr><td>400</td><td>请求参数错误</td><td>前端提示 msg。</td></tr>
    269. 

  269.       <tr><td>401</td><td>未登录或登录已过期</td><td>跳转登录页。</td></tr>
    270. 

  270.       <tr><td>403</td><td>无权限</td><td>提示无权限。</td></tr>
    271. 

  271.       <tr><td>500</td><td>服务异常</td><td>提示系统异常，并记录日志。</td></tr>
    272. 

  272.       <tr><td>10001</td><td>机器人侧接口不可用</td><td>提示机器人服务异常。</td></tr>
    273. 

  273.       <tr><td>10002</td><td>机器人执行失败</td><td>展示 resultMsg。</td></tr>
    274. 

  274.     </tbody></table>
    275. 

  275. 

  276.     <h3>7.2 认证与系统接口</h3>
    277. 

  277.     <h4>7.2.1 登录</h4>
    278. 

  278.     <table><thead><tr><th>项</th><th>内容</th></tr></thead><tbody>
    279. 

  279.       <tr><td>接口地址</td><td>POST /robot-ops/auth/login</td></tr>
    280. 

  280.       <tr><td>请求参数</td><td>登录账号（username）、登录密码（password）</td></tr>
    281. 

  281.       <tr><td>返回字段</td><td>访问令牌（token）、用户ID（userId）、登录账号（username）、用户姓名（nickName）、角色编码（roleCode）</td></tr>
    282. 

  282.       <tr><td>数据库表</td><td>robot_ops_user</td></tr>
    283. 

  283.       <tr><td>业务规则</td><td>账号停用不可登录；密码连续错误 5 次锁定 10 分钟；登录成功更新 last_login_time。</td></tr>
    284. 

  284.     </tbody></table>
    285. 

  285.     <div class="code">请求示例：
    286. 

  286. {
    287. 

  287.   "username": "admin",
    288. 

  288.   "password": "******"
    289. 

  289. }
    290. 

  290. 

  291. 返回示例：
    292. 

  292. {
    293. 

  293.   "token": "xxxxxx",
    294. 

  294.   "userId": 1,
    295. 

  295.   "username": "admin",
    296. 

  296.   "nickName": "管理员",
    297. 

  297.   "roleCode": "ADMIN"
    298. 

  298. }</div>
    299. 

  299. 

  300.     <h4>7.2.2 退出登录</h4>
    301. 

  301.     <table><thead><tr><th>项</th><th>内容</th></tr></thead><tbody>
    302. 

  302.       <tr><td>接口地址</td><td>POST /robot-ops/auth/logout</td></tr>
    303. 

  303.       <tr><td>请求参数</td><td>无</td></tr>
    304. 

  304.       <tr><td>返回字段</td><td>无</td></tr>
    305. 

  305.       <tr><td>业务规则</td><td>清理当前登录 token 或 session。</td></tr>
    306. 

  306.     </tbody></table>
    307. 

  307. 

  308.     <h4>7.2.3 修改密码</h4>
    309. 

  309.     <table><thead><tr><th>项</th><th>内容</th></tr></thead><tbody>
    310. 

  310.       <tr><td>接口地址</td><td>POST /robot-ops/auth/change-password</td></tr>
    311. 

  311.       <tr><td>请求参数</td><td>原密码（oldPassword）、新密码（newPassword）、确认新密码（confirmPassword）</td></tr>
    312. 

  312.       <tr><td>返回字段</td><td>无</td></tr>
    313. 

  313.       <tr><td>数据库表</td><td>robot_ops_user</td></tr>
    314. 

  314.       <tr><td>业务规则</td><td>原密码校验通过后更新；新密码和确认密码必须一致。</td></tr>
    315. 

  315.     </tbody></table>
    316. 

  316. 

  317.     <h4>7.2.4 当前登录用户</h4>
    318. 

  318.     <table><thead><tr><th>项</th><th>内容</th></tr></thead><tbody>
    319. 

  319.       <tr><td>接口地址</td><td>GET /robot-ops/auth/current-user</td></tr>
    320. 

  320.       <tr><td>返回字段</td><td>用户ID（userId）、登录账号（username）、用户姓名（nickName）、角色编码（roleCode）、权限标识（permissions）</td></tr>
    321. 

  321.       <tr><td>数据库表</td><td>robot_ops_user 或 RuoYi 原生权限表</td></tr>
    322. 

  322.     </tbody></table>
    323. 

  323. 

  324.     <h4>7.2.5 基础设置查询/保存</h4>
    325. 

  325.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求/返回字段</th><th>数据库表</th></tr></thead><tbody>
    326. 

  326.       <tr><td>/robot-ops/system/base-config</td><td>GET</td><td>获取基础设置</td><td>后台系统名称（systemName）、后台Logo（systemLogo）、页脚文案（footerText）、备案号（recordNo）</td><td>robot_ops_system_config</td></tr>
    327. 

  327.       <tr><td>/robot-ops/system/base-config</td><td>PUT</td><td>保存基础设置</td><td>后台系统名称（systemName）、后台Logo（systemLogo）、页脚文案（footerText）、备案号（recordNo）</td><td>robot_ops_system_config</td></tr>
    328. 

  328.     </tbody></table>
    329. 

  329. 

  330.     <h3>7.3 首页接口</h3>
    331. 

  331.     <h4>7.3.1 首页总览</h4>
    332. 

  332.     <table><thead><tr><th>项</th><th>内容</th></tr></thead><tbody>
    333. 

  333.       <tr><td>接口地址</td><td>GET /robot-ops/home/overview</td></tr>
    334. 

  334.       <tr><td>请求参数</td><td>无</td></tr>
    335. 

  335.       <tr><td>返回字段</td><td>机器人名称（robotName）、机器人编号（robotCode）、在线状态（onlineStatus）、工作状态（workStatus）、电量百分比（batteryLevel）、充电状态（chargeStatus）、网络状态（networkStatus）、IP地址（ipAddress）、存储占用（storageUsed）、当前版本（currentVersion）、今日访客数（todayVisitorCount）、今日预约数（todayAppointmentCount）、今日对话数（todayDialogueCount）、今日播报数（todayBroadcastCount）、今日告警数（todayAlarmCount）、今日操作数（todayOperateCount）</td></tr>
    336. 

  336.       <tr><td>数据来源</td><td>机器人实时接口 + 本地访客/对话/告警/操作记录聚合。</td></tr>
    337. 

  337.       <tr><td>数据库表</td><td>robot_ops_visitor_record、robot_ops_appointment_record、robot_ops_dialogue_log、robot_ops_alarm_log、robot_ops_operate_log；机器人实时状态不落库。</td></tr>
    338. 

  338.     </tbody></table>
    339. 

  339. 

  340.     <h4>7.3.2 首页最近告警/最近记录</h4>
    341. 

  341.     <table><thead><tr><th>接口</th><th>说明</th><th>请求参数</th><th>返回字段</th><th>数据库表</th></tr></thead><tbody>
    342. 

  342.       <tr><td>GET /robot-ops/home/alarms</td><td>获取首页最近告警</td><td>数量（limit，默认5）</td><td>告警ID（id）、告警时间（alarmTime）、告警类型（alarmType）、告警级别（alarmLevel）、描述（description）</td><td>robot_ops_alarm_log</td></tr>
    343. 

  343.       <tr><td>GET /robot-ops/home/quick-records</td><td>获取首页最近记录</td><td>数量（limit，默认5）</td><td>记录类型（recordType）、时间（recordTime）、标题（title）、摘要（summary）、跳转目标（targetUrl）</td><td>robot_ops_operate_log、robot_ops_upgrade_record、robot_ops_sys_log</td></tr>
    344. 

  344.     </tbody></table>
    345. 

  345. 

  346.     <h3>7.4 内容管理接口</h3>
    347. 

  347.     <h4>7.4.1 欢迎语配置接口</h4>
    348. 

  348.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求/返回字段</th><th>数据库表</th></tr></thead><tbody>
    349. 

  349.       <tr><td>/robot-ops/content/welcome-config</td><td>GET</td><td>获取欢迎语配置</td><td>返回：配置标识（configKey，固定 default）、欢迎语文本（welcomeText）、语音播报开关（voiceEnabled）、语音播报冷却时间（cooldownSeconds）、启用欢迎语状态（status）、备注（remark）。前端无需传参，后端以 config_key='default' 查询；如数据库暂无默认配置，可返回空数据，由前端加载默认配置。</td><td>robot_ops_welcome_config</td></tr>
    350. 

  350.       <tr><td>/robot-ops/content/welcome-config</td><td>PUT</td><td>保存欢迎语配置</td><td>请求：配置标识（configKey，固定 default，可由前端传入，也可由后端默认处理）、欢迎语文本（welcomeText）、语音播报开关（voiceEnabled）、语音播报冷却时间（cooldownSeconds）、启用欢迎语状态（status）、备注（remark）。后端保存时应以 config_key='default' 作为定位条件，存在则更新，不存在则新增。</td><td>robot_ops_welcome_config</td></tr>
    351. 

  351.       <tr><td>/robot-ops/content/welcome-config/test</td><td>POST</td><td>测试欢迎语播报</td><td>请求：配置标识（configKey，固定 default）、欢迎语文本（welcomeText）、启用欢迎语状态（status）、语音播报开关（voiceEnabled）。仅下发测试播报，不新增或修改配置数据。</td><td>不新增业务表，可写入 robot_ops_operate_log</td></tr>
    352. 

  352.     </tbody></table>
    353. 

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

  354.     <div class="note">保存欢迎语配置时，后端建议按 config_key='default' 执行"有则更新，无则新增"的逻辑，避免初始化数据缺失时保存失败。</div>
    355. 

  355.     <div class="note">恢复默认由前端本地重置表单完成，不单独调用后端恢复默认接口；用户点击“保存配置”后才真正写入数据库。</div>
    356. 

  356.     <div class="note">status 控制欢迎语功能整体是否启用；voiceEnabled 控制欢迎语触发时是否进行语音播报；cooldownSeconds 表示语音播报冷却时间，用于避免短时间内重复语音播报。</div>
    357. 

  357. 

  358.     <h4>7.4.2 问答库接口</h4>
    359. 

  359.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求参数</th><th>返回/处理字段</th><th>数据库表</th></tr></thead><tbody>
    360. 

  360.       <tr><td>/robot-ops/content/faq/page</td><td>GET</td><td>问答分页</td><td>问题分类（categoryType，字典值）、标准问题关键字（question）、启用状态（status）、pageNum、pageSize</td><td>问答ID（id）、问题分类（categoryType，按字典回显）、标准问题（question）、相似问数量（similarCount）、答案摘要（answerSummary）、启用状态（status）、更新时间（updateTime）</td><td>robot_ops_faq、robot_ops_faq_similar；分类名称通过 RuoYi 字典 robot_faq_category 回显</td></tr>
    361. 

  361.       <tr><td>/robot-ops/content/faq/{id}</td><td>GET</td><td>问答详情</td><td>问答ID（id）</td><td>categoryType、question、similarQuestions 或 robotOpsFaqSimilarList、answer、sortNo、status、remark</td><td>robot_ops_faq、robot_ops_faq_similar</td></tr>
    362. 

  362.       <tr><td>/robot-ops/content/faq</td><td>POST</td><td>新增问答</td><td>categoryType、question、similarQuestions 或 robotOpsFaqSimilarList、answer、status、remark；sortNo 由前端默认传 0 或后端默认写入 0</td><td>新增后的问答ID（id）</td><td>robot_ops_faq、robot_ops_faq_similar</td></tr>
    363. 

  363.       <tr><td>/robot-ops/content/faq</td><td>PUT</td><td>编辑问答</td><td>id、categoryType、question、similarQuestions 或 robotOpsFaqSimilarList、answer、sortNo、status、remark；前端页面不展示 sortNo，编辑时保持原值</td><td>无</td><td>robot_ops_faq、robot_ops_faq_similar</td></tr>
    364. 

  364.       <tr><td>/robot-ops/content/faq/{id}</td><td>DELETE</td><td>删除问答</td><td>问答ID（id）</td><td>无</td><td>robot_ops_faq、robot_ops_faq_similar</td></tr>
    365. 

  365.       <tr><td>/robot-ops/content/faq/export</td><td>GET</td><td>导出问答</td><td>问题分类（categoryType）、标准问题关键字（question）、启用状态（status）</td><td>Excel文件；导出字段建议包括问题分类、标准问题、相似问、答案内容、启用状态、更新时间、备注，不导出 sortNo</td><td>robot_ops_faq、robot_ops_faq_similar；分类名称按 RuoYi 字典 robot_faq_category 回显</td></tr>
    366. 

  366.     </tbody></table>
    367. 

  367. 

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

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

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

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

  372.     <div class="note">删除问答时需同步删除 robot_ops_faq_similar 中对应 faq_id 的相似问数据；启用/停用仅影响主问答状态，相似问不单独设置状态。</div>
    373. 

  373. 

  374.     <h4>7.4.3 素材管理接口</h4>
    375. 

  375. <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求参数</th><th>返回/处理字段</th><th>数据库表</th></tr></thead><tbody>
    376. 

  376. <tr><td>/robot-ops/content/media/page</td><td>GET</td><td>素材分页</td><td>素材名称（assetName）、素材类型（assetType）、启用状态（status）、上传时间范围、pageNum、pageSize</td><td>id、assetName、assetType、fileFormat、fileSize、durationSeconds、resolution、thumbnailUrl、quotedFlag、status、createTime</td><td>robot_ops_media_asset</td></tr>
    377. 

  377. <tr><td>/robot-ops/content/media/{id}</td><td>GET</td><td>素材详情</td><td>素材ID（id）</td><td>id、assetName、assetType、fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、quotedFlag、status、remark、createTime、updateTime</td><td>robot_ops_media_asset</td></tr>
    378. 

  378. <tr><td>/robot-ops/content/media/upload</td><td>POST</td><td>上传素材</td><td>文件（file）、素材名称（assetName，可选，未填写时默认使用文件名）、启用状态（status，可选，默认启用）、备注（remark，可选）</td><td>素材ID（id）、素材名称（assetName）、素材类型（assetType）、文件地址（fileUrl）、缩略图地址（thumbnailUrl）、文件大小（fileSize）、文件格式（fileFormat）、MIME类型（mimeType）、视频时长（durationSeconds）、分辨率（resolution）、启用状态（status）</td><td>robot_ops_media_asset</td></tr>
    379. 

  379. <tr><td>/robot-ops/content/media</td><td>PUT</td><td>编辑素材</td><td>素材ID（id）、素材名称（assetName）、启用状态（status）、备注（remark）</td><td>无</td><td>robot_ops_media_asset</td></tr>
    380. 

  380. <tr><td>/robot-ops/content/media/{id}</td><td>DELETE</td><td>删除素材</td><td>素材ID（id）</td><td>无；如素材已被播放方案引用，应返回不可删除原因和引用数量</td><td>robot_ops_media_asset、robot_ops_play_plan_item</td></tr>
    381. 

  381. <tr><td>/robot-ops/content/media/export</td><td>GET</td><td>导出素材</td><td>同分页查询条件</td><td>Excel文件；建议导出素材名称、素材类型、文件格式、文件大小、视频时长、分辨率、引用状态、启用状态、上传时间、备注</td><td>robot_ops_media_asset</td></tr>
    382. 

  382. </tbody></table>
    383. 

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

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

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

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

  387. 

  388.     <h4>7.4.4 播放方案接口</h4>
    389. 

  389.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求/返回字段</th><th>数据库表</th></tr></thead><tbody>
    390. 

  390.       <tr><td>/robot-ops/content/play-plan/page</td><td>GET</td><td>播放方案分页</td><td>方案名称（planName）、是否默认（isDefault）、启用状态（status）、pageNum、pageSize；返回 id、planName、assetCount、loopMode、isDefault、status、updateTime</td><td>robot_ops_play_plan、robot_ops_play_plan_item</td></tr>
    391. 

  391.       <tr><td>/robot-ops/content/play-plan/{id}</td><td>GET</td><td>播放方案详情</td><td>返回 planName、loopMode、isDefault、status、remark、itemList</td><td>robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset</td></tr>
    392. 

  392.       <tr><td>/robot-ops/content/play-plan</td><td>POST</td><td>新增播放方案</td><td>planName、loopMode、isDefault、status、remark、itemList</td><td>robot_ops_play_plan、robot_ops_play_plan_item</td></tr>
    393. 

  393.       <tr><td>/robot-ops/content/play-plan</td><td>PUT</td><td>编辑播放方案</td><td>id、planName、loopMode、isDefault、status、remark、itemList</td><td>robot_ops_play_plan、robot_ops_play_plan_item</td></tr>
    394. 

  394.       <tr><td>/robot-ops/content/play-plan/{id}</td><td>DELETE</td><td>删除播放方案</td><td>方案ID（id）</td><td>robot_ops_play_plan、robot_ops_play_plan_item</td></tr>
    395. 

  395.       <tr><td>/robot-ops/content/play-plan/{id}/set-default</td><td>POST</td><td>设为默认方案</td><td>方案ID（id）</td><td>robot_ops_play_plan</td></tr>
    396. 

  396.           <tr><td>/robot-ops/content/play-plan/{id}/copy</td><td>POST</td><td>复制播放方案</td><td>方案ID（id）</td><td>robot_ops_play_plan、robot_ops_play_plan_item</td></tr>
    397. 

  397.       <tr><td>/robot-ops/content/play-plan/{id}/preview</td><td>GET</td><td>预览播放方案</td><td>方案ID（id）</td><td>robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset</td></tr>
    398. 

  398.     </tbody></table>
    399. 

  399.     <div class="code">itemList 字段示例：
    400. 

  400. [
    401. 

  401.   {
    402. 

  402.     "assetId": 1,
    403. 

  403.     "playOrder": 1,
    404. 

  404.     "staySeconds": 10,
    405. 

  405.     "transitionType": "fade"
    406. 

  406.   }
    407. 

  407. ]</div>
    408. 

  408. 

  409.     <h4>7.4.5 播报内容与播报任务接口</h4>
    410. 

  410.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>主要字段</th><th>数据库表</th></tr></thead><tbody>
    411. 

  411.       <tr><td>/robot-ops/content/broadcast-content/page</td><td>GET</td><td>播报内容分页</td><td>contentName、contentType、broadcastText、status、updateTime</td><td>robot_ops_broadcast_content</td></tr>
    412. 

  412. <tr><td>/robot-ops/content/broadcast-content/{id}</td><td>GET</td><td>播报内容详情</td><td>内容ID（id）；返回 contentName、contentType、broadcastText、status、remark</td><td>robot_ops_broadcast_content</td></tr>
    413. 

  413.       <tr><td>/robot-ops/content/broadcast-content</td><td>POST</td><td>新增播报内容</td><td>contentName、contentType、broadcastText、status、remark</td><td>robot_ops_broadcast_content</td></tr>
    414. 

  414.       <tr><td>/robot-ops/content/broadcast-content</td><td>PUT</td><td>编辑播报内容</td><td>id、contentName、contentType、broadcastText、status、remark</td><td>robot_ops_broadcast_content</td></tr>
    415. 

  415.       <tr><td>/robot-ops/content/broadcast-content/{id}</td><td>DELETE</td><td>删除播报内容</td><td>内容ID（id）</td><td>robot_ops_broadcast_content</td></tr>
    416. 

  416.       <tr><td>/robot-ops/content/broadcast-content/{id}/test</td><td>POST</td><td>测试播报内容</td><td>内容ID（id）</td><td>robot_ops_broadcast_content、robot_ops_operate_log</td></tr>
    417. 

  417.       <tr><td>/robot-ops/content/broadcast-task/page</td><td>GET</td><td>播报任务分页</td><td>请求字段：任务名称（taskName）、播报内容名称（contentName）、循环类型（cycleType）、启用状态（status）、pageNum、pageSize；返回字段：任务ID（id）、任务名称（taskName）、播报内容ID（contentId）、播报内容名称（contentName）、播报内容状态（contentStatus，建议返回）、开始时间（startTime）、结束时间（endTime）、播报频率（frequencyMinutes，单位：分钟）、循环类型（cycleType：1按星期，2按日期）、循环取值（cycleValue）、启用状态（status）、更新时间（updateTime）。</td><td>robot_ops_broadcast_task、robot_ops_broadcast_content</td></tr>
    418. 

  418. <tr><td>/robot-ops/content/broadcast-task/{id}</td><td>GET</td><td>播报任务详情</td><td>任务ID（id）；返回 taskName、contentId、contentName、contentStatus、startTime、endTime、frequencyMinutes、cycleType、cycleValue、status、remark</td><td>robot_ops_broadcast_task、robot_ops_broadcast_content</td></tr>
    419. 

  419.       <tr><td>/robot-ops/content/broadcast-task</td><td>POST</td><td>新增播报任务</td><td>taskName、contentId、startTime、endTime、frequencyMinutes、cycleType、cycleValue、status、remark；cycleType=1 时 cycleValue 保存星期值，cycleType=2 时 cycleValue 保存日期值</td><td>robot_ops_broadcast_task</td></tr>
    420. 

  420.       <tr><td>/robot-ops/content/broadcast-task</td><td>PUT</td><td>编辑播报任务</td><td>id、taskName、contentId、startTime、endTime、frequencyMinutes、cycleType、cycleValue、status、remark；cycleType=1 时 cycleValue 保存星期值，cycleType=2 时 cycleValue 保存日期值</td><td>robot_ops_broadcast_task</td></tr>
    421. 

  421.       <tr><td>/robot-ops/content/broadcast-task/{id}</td><td>DELETE</td><td>删除播报任务</td><td>任务ID（id）</td><td>robot_ops_broadcast_task</td></tr>
    422. 

  422.       <tr><td>/robot-ops/content/broadcast-task/{id}/copy</td><td>POST</td><td>复制播报任务</td><td>任务ID（id）</td><td>robot_ops_broadcast_task</td></tr>
    423. 

  423.     </tbody></table>
    424. 

  424.     <div class="note">播报任务循环类型使用 RuoYi 字典 <code class="inline">broadcast_task_cycle_type</code>，字典值约定为：1=按星期，2=按日期。按星期时，cycleValue 保存 1-7 的星期值，多个值用英文逗号分隔；按日期时，cycleValue 保存 YYYY-MM-DD 日期值，多个日期用英文逗号分隔。</div>
    425. 

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

  426. 

  427.     <h4>7.4.6 展示主题接口</h4>
    428. 

  428.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求/返回字段</th><th>数据库表</th></tr></thead><tbody>
    429. 

  429.       <tr><td>/robot-ops/content/theme/page</td><td>GET</td><td>主题分页</td><td>themeName、status、pageNum、pageSize；返回 logoUrl、backgroundType、backgroundUrl、primaryColor、currentEnabled、updateTime</td><td>robot_ops_theme</td></tr>
    430. 

  430.       <tr><td>/robot-ops/content/theme/{id}</td><td>GET</td><td>主题详情</td><td>id、themeName、logoUrl、backgroundType、backgroundUrl、primaryColor、secondaryColor、welcomeTitle、welcomeSubTitle、status、currentEnabled</td><td>robot_ops_theme</td></tr>
    431. 

  431.       <tr><td>/robot-ops/content/theme</td><td>POST</td><td>新增主题</td><td>themeName、logoUrl、backgroundType、backgroundUrl、primaryColor、secondaryColor、welcomeTitle、welcomeSubTitle、status</td><td>robot_ops_theme</td></tr>
    432. 

  432.       <tr><td>/robot-ops/content/theme</td><td>PUT</td><td>编辑主题</td><td>id、themeName、logoUrl、backgroundType、backgroundUrl、primaryColor、secondaryColor、welcomeTitle、welcomeSubTitle、status</td><td>robot_ops_theme</td></tr>
    433. 

  433.       <tr><td>/robot-ops/content/theme/{id}</td><td>DELETE</td><td>删除主题</td><td>主题ID（id）</td><td>robot_ops_theme</td></tr>
    434. 

  434.       <tr><td>/robot-ops/content/theme/{id}/enable</td><td>POST</td><td>启用主题</td><td>主题ID（id）</td><td>robot_ops_theme</td></tr>
    435. 

  435.     </tbody></table>
    436. 

  436.     <div class="note">主题 Logo、背景资源可通过通用文件上传接口获取 fileUrl 后，再写入 logoUrl、backgroundUrl；也可根据项目实现复用素材上传接口。</div>
    437. 

  437.     <div class="warn">启用主题时需要将其他主题 current_enabled 置为 0，当前主题置为 1，保证同一时间只有一个主题生效。</div>
    438. 

  438. 

  439.     <h3>7.5 访客管理接口</h3>
    440. 

  440.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求参数</th><th>返回/处理字段</th><th>数据库表</th></tr></thead><tbody>
    441. 

  441.       <tr><td>/robot-ops/visitor/record/page</td><td>GET</td><td>访客记录分页</td><td>visitorName、mobile、idCardNo、visitType、registerType、visitedPerson、visitTimeStart、visitTimeEnd、pageNum、pageSize</td><td>id、visitorName、mobile、idCardNo、visitorPhoto、visitType、registerType、visitorSource、visitReason、appointmentNo、visitedPerson、visitTime</td><td>robot_ops_visitor_record</td></tr>
    442. 

  442.       <tr><td>/robot-ops/visitor/record/{id}</td><td>GET</td><td>访客详情</td><td>记录ID（id）</td><td>visitorName、mobile、idCardNo、visitType、registerType、visitorSource、visitReason、visitorPhoto、appointmentNo、visitedPerson、visitTime、remark</td><td>robot_ops_visitor_record</td></tr>
    443. 

  443.       <tr><td>/robot-ops/visitor/record/export</td><td>GET</td><td>导出访客记录</td><td>同分页查询条件：visitorName、mobile、idCardNo、visitType、registerType、visitedPerson、visitTimeStart、visitTimeEnd</td><td>Excel文件；导出字段建议包括访客姓名、手机号、身份证号、到访类型、登记方式、访客来源、来访事由、预约单号、被访对象、来访时间、访客照片状态</td><td>robot_ops_visitor_record</td></tr>
    444. 

  444.       <tr><td>/robot-ops/visitor/appointment/page</td><td>GET</td><td>预约记录分页</td><td>appointmentNo、visitorName、mobile、status、appointmentTimeStart、appointmentTimeEnd、pageNum、pageSize</td><td>appointmentNo、visitorName、mobile、visitedPerson、appointmentTime、status、syncTime</td><td>robot_ops_appointment_record</td></tr>
    445. 

  445.       <tr><td>/robot-ops/visitor/appointment/{id}</td><td>GET</td><td>预约详情</td><td>预约记录ID（id）</td><td>appointmentNo、visitorName、mobile、visitedPerson、appointmentTime、status、syncTime、sourcePlatform、remark</td><td>robot_ops_appointment_record</td></tr>
    446. 

  446.       <tr><td>/robot-ops/visitor/whitelist/page</td><td>GET</td><td>白名单分页</td><td>姓名（name）、手机号（mobile）、身份证号（idCardNo）、人员类型（whitelistType）、来源类型（sourceType）、启用状态（status）、pageNum、pageSize</td><td>白名单ID（id）、姓名（name）、手机号（mobile）、身份证号（idCardNo）、人员类型（whitelistType）、人脸照片地址（faceImageUrl）、是否有人脸照片（hasFaceImage）、来源类型（sourceType）、有效开始时间（validStartTime）、有效结束时间（validEndTime）、启用状态（status）、更新时间（updateTime）</td><td>robot_ops_whitelist</td></tr>
    447. 

  447.       <tr><td>/robot-ops/visitor/whitelist/{id}</td><td>GET</td><td>白名单详情</td><td>白名单ID（id）</td><td>name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark</td><td>robot_ops_whitelist</td></tr>
    448. 

  448.       <tr><td>/robot-ops/visitor/whitelist</td><td>POST</td><td>新增白名单</td><td>name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark；运维后台新增时 sourceType 默认传 1，表示本地录入</td><td>新增ID（id）</td><td>robot_ops_whitelist</td></tr>
    449. 

  449.       <tr><td>/robot-ops/visitor/whitelist</td><td>PUT</td><td>编辑白名单</td><td>id、name、mobile、idCardNo、whitelistType、faceImageUrl、sourceType、validStartTime、validEndTime、status、remark；sourceType 由系统自动维护，前端只读展示，不允许用户手动修改</td><td>无</td><td>robot_ops_whitelist</td></tr>
    450. 

  450. <tr><td>/robot-ops/visitor/whitelist/{id}/status</td><td>PUT</td><td>启用/停用白名单</td><td>白名单ID（id）、启用状态（status）</td><td>无</td><td>robot_ops_whitelist</td></tr>
    451. 

  451.       <tr><td>/robot-ops/visitor/whitelist/{id}</td><td>DELETE</td><td>删除白名单</td><td>白名单ID（id）</td><td>无</td><td>robot_ops_whitelist</td></tr>
    452. 

  452.       <tr><td>/robot-ops/visitor/whitelist/import</td><td>POST</td><td>导入白名单</td><td>Excel文件（file）；导入字段包括姓名、人员类型、手机号、身份证号、人脸照片地址、有效开始时间、有效结束时间、启用状态、备注；运维后台导入的数据 sourceType 默认写入 1，表示本地录入</td><td>导入总数、成功数、失败数、失败明细；导入时需校验 mobile、idCardNo、faceImageUrl 三者至少填写一种；手机号和身份证号需校验格式</td><td>robot_ops_whitelist</td></tr>
    453. 

  453.       <tr><td>/robot-ops/visitor/whitelist/export</td><td>GET</td><td>导出白名单</td><td>同分页查询条件</td><td>Excel文件；导出字段包括姓名、手机号、身份证号、人员类型、人脸照片地址、来源类型、有效开始时间、有效结束时间、启用状态、更新时间、备注</td><td>robot_ops_whitelist</td></tr>
    454. 

  454.     </tbody></table>
    455. 

  455.     <div class="note">访客记录不设置 resultStatus 和 sourceType 作为页面字段。访客记录代表已完成登记的到访记录；登记失败、扫码失败、读卡失败、预约匹配失败等异常应进入日志中心或后续扩展的登记异常日志。</div>
    456. 

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

  457.     <div class="note">预约记录由主控平台同步；预约到访访客在现场完成登记后生成访客记录，并通过 appointmentNo 关联预约记录。现场登记访客可不关联预约单号。</div>
    458. 

  458.     <div class="note">白名单中的 whitelistType 字段在页面上显示为"人员类型"，用于表示人员身份，如内部人员、访客、VIP、其他。人脸识别不作为人员类型，而是白名单匹配方式之一。</div>
    459. 

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

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

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

  462.     <div class="note">有效期状态由前端根据 validStartTime、validEndTime 和当前时间动态展示，不作为一期分页查询参数。</div>
    463. 

  463. 

  464.     <h3>7.6 监控管理接口</h3>
    465. 

  465.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求参数</th><th>返回/处理字段</th><th>数据库表</th></tr></thead><tbody>
    466. 

  466.       <tr><td>/robot-ops/monitor/video/stream-info</td><td>GET</td><td>获取视频流信息</td><td>无</td><td>视频地址（streamUrl）、播放协议（streamProtocol）、码流类型（streamType）、分辨率（resolution）、过期时间（expireTime）</td><td>实时接口返回，不落库</td></tr>
    467. 

  467.       <tr><td>/robot-ops/monitor/video/status</td><td>GET</td><td>获取视频状态</td><td>无</td><td>播放状态（videoStatus）、错误码（errorCode）、错误信息（errorMsg）、更新时间（updateTime）</td><td>实时接口返回，不落库</td></tr>
    468. 

  468.       <tr><td>/robot-ops/monitor/voice/shout</td><td>POST</td><td>执行远程喊话</td><td>喊话文本（shoutText）、音量（volume）、播放次数（playTimes）、是否打断（interruptFlag）</td><td>记录ID（id）、执行状态（resultStatus）、结果信息（resultMsg）</td><td>robot_ops_shout_record、robot_ops_operate_log</td></tr>
    469. 

  469.       <tr><td>/robot-ops/monitor/voice/shout-record/page</td><td>GET</td><td>喊话记录分页</td><td>shoutText、resultStatus、createTimeStart、createTimeEnd、pageNum、pageSize</td><td>id、shoutText、volume、playTimes、interruptFlag、resultStatus、resultMsg、operateBy、createTime</td><td>robot_ops_shout_record</td></tr>
    470. 

  470.       <tr><td>/robot-ops/monitor/dialogue/page</td><td>GET</td><td>对话日志分页</td><td>sessionId、keyword、hitType、sceneType、askTimeStart、askTimeEnd、pageNum、pageSize</td><td>id、sessionId、askTime、question、answerSummary、hitType、sceneType、resultStatus</td><td>robot_ops_dialogue_log</td></tr>
    471. 

  471.       <tr><td>/robot-ops/monitor/dialogue/{id}</td><td>GET</td><td>对话详情</td><td>日志ID（id）</td><td>sessionId、askTime、question、answer、hitType、sceneType、resultStatus、rawRequest、rawResponse</td><td>robot_ops_dialogue_log</td></tr>
    472. 

  472.       <tr><td>/robot-ops/monitor/dialogue/export</td><td>GET</td><td>导出对话日志</td><td>同分页查询条件</td><td>Excel文件</td><td>robot_ops_dialogue_log</td></tr>
    473. 

  473.       <tr><td>/robot-ops/monitor/alarm/page</td><td>GET</td><td>安防告警分页</td><td>alarmType、alarmLevel、handleStatus、alarmTimeStart、alarmTimeEnd、pageNum、pageSize</td><td>id、alarmTime、alarmType、alarmLevel、sourcePosition、handleStatus、description</td><td>robot_ops_alarm_log</td></tr>
    474. 

  474.       <tr><td>/robot-ops/monitor/alarm/{id}</td><td>GET</td><td>安防告警详情</td><td>告警ID（id）</td><td>alarmTime、alarmType、alarmLevel、sourcePosition、handleStatus、description、snapshotUrl、remark</td><td>robot_ops_alarm_log</td></tr>
    475. 

  475.       <tr><td>/robot-ops/monitor/alarm/{id}/confirm</td><td>PUT</td><td>确认告警</td><td>告警ID（id）、备注（remark）</td><td>无</td><td>robot_ops_alarm_log</td></tr>
    476. 

  476.       <tr><td>/robot-ops/monitor/alarm/{id}/ignore</td><td>PUT</td><td>忽略告警</td><td>告警ID（id）、备注（remark）</td><td>无</td><td>robot_ops_alarm_log</td></tr>
    477. 

  477.       <tr><td>/robot-ops/monitor/alarm/export</td><td>GET</td><td>导出告警日志</td><td>同分页查询条件</td><td>Excel文件</td><td>robot_ops_alarm_log</td></tr>
    478. 

  478.     </tbody></table>
    479. 

  479. 

  480.     <h3>7.7 运维管理接口</h3>
    481. 

  481.     <h4>7.7.1 设备状态与设备控制接口</h4>
    482. 

  482.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求参数</th><th>返回/处理字段</th><th>数据库表</th></tr></thead><tbody>
    483. 

  483.       <tr><td>/robot-ops/ops/device-status/detail</td><td>GET</td><td>设备状态详情</td><td>无</td><td>robotName、robotCode、serialNo、ipAddress、macAddress、uptime、onlineStatus、workStatus、batteryLevel、chargeStatus、networkStatus、cpuUsage、memoryUsage、diskUsage、temperature、cameraStatus、micStatus、speakerStatus、screenStatus、mainServiceStatus、serverTime、lastHeartbeatTime</td><td>实时接口返回，不落库</td></tr>
    484. 

  484.       <tr><td>/robot-ops/ops/control/charge-start</td><td>POST</td><td>一键充电</td><td>无或扩展参数</td><td>taskId、resultStatus、resultMsg</td><td>robot_ops_control_record、robot_ops_operate_log</td></tr>
    485. 

  485.       <tr><td>/robot-ops/ops/control/charge-stop</td><td>POST</td><td>停止充电</td><td>无或扩展参数</td><td>taskId、resultStatus、resultMsg</td><td>robot_ops_control_record、robot_ops_operate_log</td></tr>
    486. 

  486.       <tr><td>/robot-ops/ops/control/reboot</td><td>POST</td><td>重启机器人</td><td>确认标识（confirmFlag）</td><td>taskId、resultStatus、resultMsg</td><td>robot_ops_control_record、robot_ops_operate_log</td></tr>
    487. 

  487.       <tr><td>/robot-ops/ops/control/shutdown</td><td>POST</td><td>关机</td><td>确认标识（confirmFlag）</td><td>taskId、resultStatus、resultMsg</td><td>robot_ops_control_record、robot_ops_operate_log</td></tr>
    488. 

  488.       <tr><td>/robot-ops/ops/control/restart-service</td><td>POST</td><td>重启服务</td><td>服务名称（serviceName）</td><td>taskId、serviceName、resultStatus、resultMsg</td><td>robot_ops_control_record、robot_ops_operate_log</td></tr>
    489. 

  489.       <tr><td>/robot-ops/ops/control/audio-test</td><td>POST</td><td>音频测试</td><td>测试文本（testText，可选）</td><td>resultStatus、resultMsg</td><td>robot_ops_control_record、robot_ops_operate_log</td></tr>
    490. 

  490.       <tr><td>/robot-ops/ops/control/screen-test</td><td>POST</td><td>屏幕测试</td><td>测试类型（testType，可选）</td><td>resultStatus、resultMsg</td><td>robot_ops_control_record、robot_ops_operate_log</td></tr>
    491. 

  491.       <tr><td>/robot-ops/ops/control/record/page</td><td>GET</td><td>设备控制记录分页</td><td>controlType、resultStatus、createTimeStart、createTimeEnd、pageNum、pageSize</td><td>id、controlType、controlName、taskId、resultStatus、resultMsg、operateBy、createTime、finishTime</td><td>robot_ops_control_record</td></tr>
    492. 

  492.       <tr><td>/robot-ops/ops/control/record/{id}</td><td>GET</td><td>设备控制记录详情</td><td>控制记录ID（id）</td><td>controlType、controlName、taskId、requestParam、resultStatus、resultMsg、operateBy、createTime、finishTime</td><td>robot_ops_control_record</td></tr>
    493. 

  493.     </tbody></table>
    494. 

  494. 

  495.     <h4>7.7.2 运行参数接口</h4>
    496. 

  496.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求/返回字段</th><th>数据库表</th></tr></thead><tbody>
    497. 

  497.       <tr><td>/robot-ops/ops/param/groups</td><td>GET</td><td>参数分组列表</td><td>groupCode、groupName、sortNo、status</td><td>robot_ops_param_group</td></tr>
    498. 

  498.       <tr><td>/robot-ops/ops/param/page</td><td>GET</td><td>参数分页/分组参数</td><td>groupCode、keyword、pageNum、pageSize；返回 paramCode、paramName、paramValue、valueType、unit、editable、requiredFlag、minValue、maxValue、enumOptions、remark</td><td>robot_ops_param</td></tr>
    499. 

  499.       <tr><td>/robot-ops/ops/param</td><td>PUT</td><td>保存参数</td><td>参数列表（params：paramCode、paramValue）</td><td>robot_ops_param、robot_ops_operate_log</td></tr>
    500. 

  500.       <tr><td>/robot-ops/ops/param/reset</td><td>POST</td><td>重置参数</td><td>groupCode 或 paramCodes</td><td>robot_ops_param、robot_ops_operate_log</td></tr>
    501. 

  501.     </tbody></table>
    502. 

  502.     <div class="warn">参数保存时必须根据 valueType、requiredFlag、minValue、maxValue、enumOptions 做后端校验。</div>
    503. 

  503. 

  504.     <h4>7.7.3 系统诊断与日志接口</h4>
    505. 

  505.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求/返回字段</th><th>数据库表</th></tr></thead><tbody>
    506. 

  506.       <tr><td>/robot-ops/ops/diagnosis/overview</td><td>GET</td><td>诊断总览</td><td>normalCount、warnCount、failCount、lastCheckTime</td><td>robot_ops_diagnosis_item</td></tr>
    507. 

  507.       <tr><td>/robot-ops/ops/diagnosis/page</td><td>GET</td><td>诊断项分页</td><td>itemName、resultStatus、pageNum、pageSize；返回 itemCode、itemName、resultStatus、detailMsg、lastCheckTime</td><td>robot_ops_diagnosis_item</td></tr>
    508. 

  508.       <tr><td>/robot-ops/ops/diagnosis/run</td><td>POST</td><td>执行诊断</td><td>诊断项编码（itemCodes，可选）</td><td>normalCount、warnCount、failCount、itemList</td><td>robot_ops_diagnosis_item、robot_ops_sys_log</td></tr>
    509. 

  509.       <tr><td>/robot-ops/ops/diagnosis/export</td><td>GET</td><td>导出诊断结果</td><td>resultStatus</td><td>Excel文件</td><td>robot_ops_diagnosis_item</td></tr>
    510. 

  510.       <tr><td>/robot-ops/ops/log/page</td><td>GET</td><td>日志分页</td><td>日志来源类型（sourceType：SYS/OPERATE，可选）、logType、logLevel、keyword、resultStatus、logTimeStart、logTimeEnd、pageNum、pageSize</td><td>id、日志来源类型（sourceType）、logTime、logType、logLevel、moduleName、contentSummary、resultStatus、traceId</td><td>robot_ops_sys_log、robot_ops_operate_log</td></tr>
    511. 

  511.       <tr><td>/robot-ops/ops/log/{id}</td><td>GET</td><td>日志详情</td><td>日志ID（id）、日志来源类型（sourceType）</td><td>logTime、logType、logLevel、moduleName、content、resultStatus、traceId、remark</td><td>robot_ops_sys_log、robot_ops_operate_log</td></tr>
    512. 

  512.       <tr><td>/robot-ops/ops/log/export</td><td>GET</td><td>导出日志</td><td>同日志分页查询条件</td><td>Excel文件</td><td>robot_ops_sys_log、robot_ops_operate_log</td></tr>
    513. 

  513.     </tbody></table>
    514. 

  514. 

  515.     <h4>7.7.4 软件版本与 OTA 升级接口</h4>
    516. 

  516.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求/返回字段</th><th>数据库表</th></tr></thead><tbody>
    517. 

  517.       <tr><td>/robot-ops/ops/version/page</td><td>GET</td><td>软件版本分页</td><td>moduleCode、moduleName、runStatus、pageNum、pageSize；返回 moduleCode、moduleName、currentVersion、installTime、runStatus</td><td>robot_ops_version_info</td></tr>
    518. 

  518.       <tr><td>/robot-ops/ops/upgrade/package/upload</td><td>POST</td><td>上传升级包</td><td>文件（file）、模块编码（moduleCode）、目标版本（targetVersion）、安装包名称（packageName）</td><td>packageId、packageName、moduleCode、targetVersion、fileUrl、fileSize、uploadBy、uploadTime</td><td>robot_ops_upgrade_package</td></tr>
    519. 

  519.       <tr><td>/robot-ops/ops/upgrade/package/page</td><td>GET</td><td>升级包分页</td><td>packageName、moduleCode、targetVersion、pageNum、pageSize</td><td>packageId、packageName、moduleCode、targetVersion、fileSize、uploadBy、uploadTime</td><td>robot_ops_upgrade_package</td></tr>
    520. 

  520.       <tr><td>/robot-ops/ops/upgrade/package/{id}</td><td>DELETE</td><td>删除升级包</td><td>升级包ID（id）</td><td>无</td><td>robot_ops_upgrade_package</td></tr>
    521. 

  521.       <tr><td>/robot-ops/ops/upgrade/execute</td><td>POST</td><td>执行升级</td><td>模块编码（moduleCode）、升级包ID（packageId）、确认标识（confirmFlag）</td><td>升级记录ID（recordId）、升级状态（resultStatus）、升级进度（progressPercent）、结果信息（resultMsg）</td><td>robot_ops_upgrade_record、robot_ops_operate_log</td></tr>
    522. 

  522.       <tr><td>/robot-ops/ops/upgrade/record/page</td><td>GET</td><td>升级记录分页</td><td>moduleCode、resultStatus、startTimeStart、startTimeEnd、pageNum、pageSize</td><td>recordId、moduleCode、moduleName、currentVersion、targetVersion、startTime、endTime、resultStatus、resultMsg、progressPercent</td><td>robot_ops_upgrade_record</td></tr>
    523. 

  523.       <tr><td>/robot-ops/ops/upgrade/record/{id}</td><td>GET</td><td>升级详情</td><td>升级记录ID（id）</td><td>moduleCode、moduleName、currentVersion、targetVersion、packageId、executeBy、startTime、endTime、resultStatus、resultMsg、progressPercent</td><td>robot_ops_upgrade_record</td></tr>
    524. 

  524.     </tbody></table>
    525. 

  525. 

  526.     <h3>7.8 账号管理接口</h3>
    527. 

  527.     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求/返回字段</th><th>数据库表</th></tr></thead><tbody>
    528. 

  528.       <tr><td>/robot-ops/system/user/page</td><td>GET</td><td>账号分页</td><td>username、nickName、status、pageNum、pageSize；返回 userId、username、nickName、roleCode、status、lastLoginTime</td><td>robot_ops_user</td></tr>
    529. 

  529.       <tr><td>/robot-ops/system/user/{id}</td><td>GET</td><td>账号详情</td><td>用户ID（id）</td><td>userId、username、nickName、roleCode、status、remark、lastLoginTime</td><td>robot_ops_user</td></tr>
    530. 

  530.       <tr><td>/robot-ops/system/user</td><td>POST</td><td>新增账号</td><td>username、nickName、password、roleCode、status、remark</td><td>新增用户ID（userId）</td><td>robot_ops_user</td></tr>
    531. 

  531.       <tr><td>/robot-ops/system/user</td><td>PUT</td><td>编辑账号</td><td>userId、nickName、roleCode、status、remark</td><td>无</td><td>robot_ops_user</td></tr>
    532. 

  532.       <tr><td>/robot-ops/system/user/{id}</td><td>DELETE</td><td>删除账号</td><td>用户ID（id）</td><td>无</td><td>robot_ops_user</td></tr>
    533. 

  533.       <tr><td>/robot-ops/system/user/{id}/reset-password</td><td>POST</td><td>重置密码</td><td>用户ID（id）、新密码（newPassword）</td><td>无</td><td>robot_ops_user</td></tr>
    534. 

  534.     </tbody></table>
    535. 

  535.     <div class="warn">admin 默认账号不可删除；账号停用后不可登录；所有账号新增、编辑、删除、重置密码操作均需写入操作日志。</div>
    536. 

  536.   </div>
    537. 

  537. 

  538.   <div class="section" id="s8"><h2>8. 数据库表设计</h2>
    539. 

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

  540.     <div class="warn">数据库建表语句以 MySQL 8.x 为基线，字段中文说明通过 COMMENT 标注。若项目实际使用 RuoYi 默认字段规范，可在开发时结合 create_by、create_time、update_by、update_time、remark 等公共字段做统一封装。</div>
    541. 

  541.     <div class="note">公共字段约定：除日志流水类表外，内容管理类、访客管理类、运维配置类、系统配置类等业务表统一包含 create_by、create_time、update_by、update_time 四个公共字段，用于记录创建人、创建时间、更新人和更新时间。日志流水类表以业务时间、操作人、处理人等字段为主，不强制补齐全部公共字段。</div>
    542. 

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

  543. 

  544.     <h3>8.1 基础与权限表</h3>
    545. 

  545.     <h4>8.1.1 本地账号表 robot_ops_user</h4>
    546. 

  546.     <div class="code">CREATE TABLE `robot_ops_user` (
    547. 

  547.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    548. 

  548.   `username` VARCHAR(50) NOT NULL COMMENT '登录账号',
    549. 

  549.   `password` VARCHAR(100) NOT NULL COMMENT '登录密码，加密存储',
    550. 

  550.   `nick_name` VARCHAR(50) DEFAULT NULL COMMENT '用户姓名/昵称',
    551. 

  551.   `role_code` VARCHAR(50) DEFAULT NULL COMMENT '角色编码：ADMIN、OPS、VIEWER',
    552. 

  552.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '账号状态：0停用，1启用',
    553. 

  553.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    554. 

  554.   `last_login_time` DATETIME DEFAULT NULL COMMENT '最近登录时间',
    555. 

  555.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    556. 

  556.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    557. 

  557.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    558. 

  558.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    559. 

  559.   PRIMARY KEY (`id`),
    560. 

  560.   UNIQUE KEY `uk_robot_ops_user_username` (`username`)
    561. 

  561. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='本地后台账号表';</div>
    562. 

  562. 

  563.     <h4>8.1.2 系统基础配置表 robot_ops_system_config</h4>
    564. 

  564.     <div class="code">CREATE TABLE `robot_ops_system_config` (
    565. 

  565.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    566. 

  566.   `system_name` VARCHAR(100) DEFAULT NULL COMMENT '后台系统名称',
    567. 

  567.   `system_logo` VARCHAR(255) DEFAULT NULL COMMENT '后台系统Logo地址',
    568. 

  568.   `footer_text` VARCHAR(255) DEFAULT NULL COMMENT '页脚文案',
    569. 

  569.   `record_no` VARCHAR(100) DEFAULT NULL COMMENT '备案号/版权信息',
    570. 

  570.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    571. 

  571.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    572. 

  572.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    573. 

  573.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    574. 

  574.   PRIMARY KEY (`id`)
    575. 

  575. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统基础配置表';</div>
    576. 

  576. 

  577.     <h3>8.2 内容管理表</h3>
    578. 

  578.     <h4>8.2.1 欢迎语配置表 robot_ops_welcome_config</h4>
    579. 

  579.     <div class="code">CREATE TABLE `robot_ops_welcome_config` (
    580. 

  580.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    581. 

  581.   `config_key` VARCHAR(50) NOT NULL DEFAULT 'default' COMMENT '配置标识，默认配置固定为default',
    582. 

  582.   `welcome_text` VARCHAR(500) NOT NULL COMMENT '欢迎语文本，前端限制最大200字，数据库预留500字',
    583. 

  583.   `voice_enabled` CHAR(1) NOT NULL DEFAULT '1' COMMENT '是否启用语音播报：0否，1是',
    584. 

  584.   `cooldown_seconds` INT NOT NULL DEFAULT 30 COMMENT '语音播报冷却时间，单位秒',
    585. 

  585.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用欢迎语状态：0停用，1启用',
    586. 

  586.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    587. 

  587.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    588. 

  588.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    589. 

  589.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    590. 

  590.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    591. 

  591.   PRIMARY KEY (`id`),
    592. 

  592.   UNIQUE KEY `uk_robot_ops_welcome_config_key` (`config_key`)
    593. 

  593. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='欢迎语配置表';</div>
    594. 

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

  595.     <div class="note">说明：welcome_text 数据库预留 500 字长度，前端页面按产品规则限制最大 200 字，便于后续扩展欢迎语内容。</div>
    596. 

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

  597.     <div class="code">INSERT INTO `robot_ops_welcome_config`
    598. 

  598. (`config_key`, `welcome_text`, `voice_enabled`, `cooldown_seconds`, `status`, `remark`, `create_by`, `create_time`, `update_by`, `update_time`)
    599. 

  599. VALUES
    600. 

  600. ('default', '您好，欢迎光临！我是迎宾巡逻安防机器人，很高兴为您服务。', '1', 30, '1', '系统默认欢迎语配置', 'system', NOW(), 'system', NOW());</div>
    601. 

  601. 

  602.     <h4>8.2.2 问答库表 robot_ops_faq</h4>
    603. 

  603.     <div class="code">CREATE TABLE `robot_ops_faq` (
    604. 

  604.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    605. 

  605.   `category_type` VARCHAR(50) DEFAULT NULL COMMENT '问题分类字典值，字典类型：robot_faq_category',
    606. 

  606.   `question` VARCHAR(500) NOT NULL COMMENT '标准问题',
    607. 

  607.   `answer` TEXT NOT NULL COMMENT '答案内容',
    608. 

  608.   `sort_no` INT DEFAULT 0 COMMENT '排序号，数字越小越靠前',
    609. 

  609.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用',
    610. 

  610.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    611. 

  611.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    612. 

  612.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    613. 

  613.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    614. 

  614.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    615. 

  615.   PRIMARY KEY (`id`),
    616. 

  616.   KEY `idx_robot_ops_faq_category_type` (`category_type`),
    617. 

  617.   KEY `idx_robot_ops_faq_status` (`status`)
    618. 

  618. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='问答库主表';</div>
    619. 

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

  620. 

  621.     <h4>8.2.3 相似问表 robot_ops_faq_similar</h4>
    622. 

  622.     <div class="code">CREATE TABLE `robot_ops_faq_similar` (
    623. 

  623.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    624. 

  624.   `faq_id` BIGINT NOT NULL COMMENT '问答ID，关联robot_ops_faq.id',
    625. 

  625.   `similar_question` VARCHAR(500) NOT NULL COMMENT '相似问文本',
    626. 

  626.   `sort_no` INT DEFAULT 0 COMMENT '排序号，数字越小越靠前',
    627. 

  627.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    628. 

  628.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    629. 

  629.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    630. 

  630.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    631. 

  631.   PRIMARY KEY (`id`),
    632. 

  632.   KEY `idx_robot_ops_faq_similar_faq_id` (`faq_id`)
    633. 

  633. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='问答相似问表';</div>
    634. 

  634. 

  635.     <h4>8.2.4 素材资源表 robot_ops_media_asset</h4>
    636. 

  636. <div class="code">CREATE TABLE `robot_ops_media_asset` (
    637. 

  637.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    638. 

  638.   `asset_name` VARCHAR(100) NOT NULL COMMENT '素材名称',
    639. 

  639.   `asset_type` VARCHAR(20) NOT NULL COMMENT '素材类型：image图片，video视频',
    640. 

  640.   `file_url` VARCHAR(500) NOT NULL COMMENT '素材文件地址',
    641. 

  641.   `thumbnail_url` VARCHAR(500) DEFAULT NULL COMMENT '缩略图地址，图片可等于file_url，视频可为封面图',
    642. 

  642.   `file_size` BIGINT DEFAULT NULL COMMENT '文件大小，单位字节',
    643. 

  643.   `file_format` VARCHAR(20) DEFAULT NULL COMMENT '文件格式，如jpg、png、webp、mp4',
    644. 

  644.   `mime_type` VARCHAR(100) DEFAULT NULL COMMENT '文件MIME类型，如image/jpeg、video/mp4',
    645. 

  645.   `duration_seconds` INT DEFAULT NULL COMMENT '视频时长，单位秒；图片为空',
    646. 

  646.   `resolution` VARCHAR(50) DEFAULT NULL COMMENT '分辨率，如1920x1080',
    647. 

  647.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用',
    648. 

  648.   `quoted_flag` CHAR(1) NOT NULL DEFAULT '0' COMMENT '是否被播放方案引用：0否，1是，由系统维护',
    649. 

  649.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    650. 

  650.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    651. 

  651.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间/上传时间',
    652. 

  652.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    653. 

  653.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    654. 

  654.   PRIMARY KEY (`id`),
    655. 

  655.   KEY `idx_robot_ops_media_asset_type` (`asset_type`),
    656. 

  656.   KEY `idx_robot_ops_media_asset_status` (`status`),
    657. 

  657.   KEY `idx_robot_ops_media_asset_quoted_flag` (`quoted_flag`)
    658. 

  658. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='素材资源表';</div>
    659. 

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

  660. <div class="note">说明：file_url、thumbnail_url、file_size、file_format、mime_type、duration_seconds、resolution 等字段由上传接口自动生成或解析，前端不允许用户手动填写。duration_seconds 仅视频素材需要，图片素材为空。</div>
    661. 

  661. <div class="note">说明：thumbnail_url 用于列表缩略图和视频封面展示。图片素材如未单独生成缩略图，可使用 file_url；视频素材如一期暂未生成封面图，可为空，前端展示默认视频图标。</div>
    662. 

  662. <div class="note">说明：quoted_flag 由系统维护，表示素材是否被播放方案引用。删除素材时，应以后端检查 robot_ops_play_plan_item 的实际引用关系为准。</div>
    663. 

  663. 

  664.     <h4>8.2.5 播放方案表 robot_ops_play_plan</h4>
    665. 

  665.     <div class="code">CREATE TABLE `robot_ops_play_plan` (
    666. 

  666.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    667. 

  667.   `plan_name` VARCHAR(100) NOT NULL COMMENT '播放方案名称',
    668. 

  668.   `loop_mode` VARCHAR(20) DEFAULT 'loop' COMMENT '循环方式：loop循环播放，once播放一次',
    669. 

  669.   `is_default` CHAR(1) NOT NULL DEFAULT '0' COMMENT '是否默认方案：0否，1是',
    670. 

  670.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用',
    671. 

  671.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    672. 

  672.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    673. 

  673.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    674. 

  674.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    675. 

  675.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    676. 

  676.   PRIMARY KEY (`id`),
    677. 

  677.   KEY `idx_robot_ops_play_plan_default` (`is_default`),
    678. 

  678.   KEY `idx_robot_ops_play_plan_status` (`status`)
    679. 

  679. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播放方案主表';</div>
    680. 

  680. 

  681.     <h4>8.2.6 播放方案素材明细表 robot_ops_play_plan_item</h4>
    682. 

  682.     <div class="code">CREATE TABLE `robot_ops_play_plan_item` (
    683. 

  683.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    684. 

  684.   `plan_id` BIGINT NOT NULL COMMENT '播放方案ID，关联robot_ops_play_plan.id',
    685. 

  685.   `asset_id` BIGINT NOT NULL COMMENT '素材ID，关联robot_ops_media_asset.id',
    686. 

  686.   `play_order` INT DEFAULT 0 COMMENT '播放顺序，数字越小越靠前',
    687. 

  687.   `stay_seconds` INT DEFAULT NULL COMMENT '停留时长，图片必填，视频可为空',
    688. 

  688.   `transition_type` VARCHAR(50) DEFAULT NULL COMMENT '转场方式',
    689. 

  689.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    690. 

  690.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    691. 

  691.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    692. 

  692.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    693. 

  693.   PRIMARY KEY (`id`),
    694. 

  694.   KEY `idx_robot_ops_play_plan_item_plan_id` (`plan_id`),
    695. 

  695.   KEY `idx_robot_ops_play_plan_item_asset_id` (`asset_id`)
    696. 

  696. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播放方案素材明细表';</div>
    697. 

  697. 

  698.     <h4>8.2.7 播报内容表 robot_ops_broadcast_content</h4>
    699. 

  699.     <div class="code">CREATE TABLE `robot_ops_broadcast_content` (
    700. 

  700.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    701. 

  701.   `content_name` VARCHAR(100) NOT NULL COMMENT '播报内容名称',
    702. 

  702.   `content_type` VARCHAR(50) DEFAULT NULL COMMENT '内容分类：通知、宣传、提示、安防提醒、自定义',
    703. 

  703.   `broadcast_text` VARCHAR(2000) NOT NULL COMMENT '播报文本',
    704. 

  704.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用',
    705. 

  705.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    706. 

  706.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    707. 

  707.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    708. 

  708.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    709. 

  709.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    710. 

  710.   PRIMARY KEY (`id`),
    711. 

  711.   KEY `idx_robot_ops_broadcast_content_type` (`content_type`),
    712. 

  712.   KEY `idx_robot_ops_broadcast_content_status` (`status`)
    713. 

  713. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播报内容表';</div>
    714. 

  714. 

  715.     <h4>8.2.8 播报任务表 robot_ops_broadcast_task</h4>
    716. 

  716.     <div class="code">CREATE TABLE `robot_ops_broadcast_task` (
    717. 

  717.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    718. 

  718.   `task_name` VARCHAR(100) NOT NULL COMMENT '播报任务名称',
    719. 

  719.   `content_id` BIGINT NOT NULL COMMENT '播报内容ID，关联robot_ops_broadcast_content.id',
    720. 

  720.   `start_time` VARCHAR(8) DEFAULT NULL COMMENT '开始时间，格式HH:mm:ss',
    721. 

  721.   `end_time` VARCHAR(8) DEFAULT NULL COMMENT '结束时间，格式HH:mm:ss',
    722. 

  722.   `frequency_minutes` INT DEFAULT NULL COMMENT '播报频率，单位分钟',
    723. 

  723.   `cycle_type` VARCHAR(20) DEFAULT NULL COMMENT '循环类型字典值，字典类型：broadcast_task_cycle_type，1按星期，2按日期',
    724. 

  724.   `cycle_value` VARCHAR(255) DEFAULT NULL COMMENT '循环取值：cycle_type=1时保存星期值，如1,2,3,4,5；cycle_type=2时保存日期值，如2026-03-20,2026-03-21',
    725. 

  725.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用',
    726. 

  726.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    727. 

  727.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    728. 

  728.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    729. 

  729.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    730. 

  730.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    731. 

  731.   PRIMARY KEY (`id`),
    732. 

  732.   KEY `idx_robot_ops_broadcast_task_content_id` (`content_id`),
    733. 

  733.   KEY `idx_robot_ops_broadcast_task_status` (`status`)
    734. 

  734. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='播报任务表';
    735. 

  735.     <div class="note">播报任务循环类型使用 RuoYi 字典 <code class="inline">broadcast_task_cycle_type</code>，字典项建议配置为：1=按星期，2=按日期。按星期时，cycle_value 中 1-7 分别代表星期一到星期日。</div></div>
    736. 

  736. 

  737.     <h4>8.2.9 展示主题表 robot_ops_theme</h4>
    738. 

  738.     <div class="code">CREATE TABLE `robot_ops_theme` (
    739. 

  739.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    740. 

  740.   `theme_name` VARCHAR(100) NOT NULL COMMENT '主题名称',
    741. 

  741.   `logo_url` VARCHAR(255) DEFAULT NULL COMMENT 'Logo地址',
    742. 

  742.   `background_type` VARCHAR(20) DEFAULT NULL COMMENT '背景类型：image图片，video视频，color纯色',
    743. 

  743.   `background_url` VARCHAR(255) DEFAULT NULL COMMENT '背景资源地址',
    744. 

  744.   `primary_color` VARCHAR(20) DEFAULT NULL COMMENT '主题主色',
    745. 

  745.   `secondary_color` VARCHAR(20) DEFAULT NULL COMMENT '辅助色',
    746. 

  746.   `welcome_title` VARCHAR(200) DEFAULT NULL COMMENT '欢迎标题',
    747. 

  747.   `welcome_sub_title` VARCHAR(500) DEFAULT NULL COMMENT '欢迎副标题',
    748. 

  748.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用',
    749. 

  749.   `current_enabled` CHAR(1) NOT NULL DEFAULT '0' COMMENT '是否当前启用主题：0否，1是',
    750. 

  750.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    751. 

  751.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    752. 

  752.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    753. 

  753.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    754. 

  754.   PRIMARY KEY (`id`),
    755. 

  755.   KEY `idx_robot_ops_theme_current_enabled` (`current_enabled`),
    756. 

  756.   KEY `idx_robot_ops_theme_status` (`status`)
    757. 

  757. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='机器人展示主题表';</div>
    758. 

  758. 

  759.     <h3>8.3 访客管理表</h3>
    760. 

  760.     <h4>8.3.1 访客记录表 robot_ops_visitor_record</h4>
    761. 

  761.     <div class="code">CREATE TABLE `robot_ops_visitor_record` (
    762. 

  762.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    763. 

  763.   `visitor_name` VARCHAR(100) NOT NULL COMMENT '访客姓名',
    764. 

  764.   `mobile` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
    765. 

  765.   `id_card_no` VARCHAR(50) DEFAULT NULL COMMENT '身份证号',
    766. 

  766.   `visit_type` VARCHAR(50) NOT NULL COMMENT '到访类型：APPOINTMENT预约到访，WALK_IN现场登记',
    767. 

  767.   `register_type` VARCHAR(50) NOT NULL COMMENT '登记方式：SCREEN机器人端，H5手机端',
    768. 

  768.   `visitor_source` VARCHAR(100) DEFAULT NULL COMMENT '访客来源，如公司、单位、亲友、外卖、快递、供应商等',
    769. 

  769.   `visit_reason` VARCHAR(200) DEFAULT NULL COMMENT '来访事由，如业务接洽、走亲访友、酒店入住、配送、维修、参观等',
    770. 

  770.   `visitor_photo` VARCHAR(255) DEFAULT NULL COMMENT '访客照片地址，由机器人端采集上传',
    771. 

  771.   `appointment_no` VARCHAR(100) DEFAULT NULL COMMENT '关联预约单号，现场登记可为空',
    772. 

  772.   `visited_person` VARCHAR(100) DEFAULT NULL COMMENT '被访对象，可为被访人、房号、部门、接待单位等',
    773. 

  773.   `visit_time` DATETIME NOT NULL COMMENT '来访/登记时间',
    774. 

  774.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    775. 

  775.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    776. 

  776.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    777. 

  777.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    778. 

  778.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    779. 

  779.   PRIMARY KEY (`id`),
    780. 

  780.   KEY `idx_robot_ops_visitor_record_name` (`visitor_name`),
    781. 

  781.   KEY `idx_robot_ops_visitor_record_mobile` (`mobile`),
    782. 

  782.   KEY `idx_robot_ops_visitor_record_id_card_no` (`id_card_no`),
    783. 

  783.   KEY `idx_robot_ops_visitor_record_visit_type` (`visit_type`),
    784. 

  784.   KEY `idx_robot_ops_visitor_record_register_type` (`register_type`),
    785. 

  785.   KEY `idx_robot_ops_visitor_record_appointment_no` (`appointment_no`),
    786. 

  786.   KEY `idx_robot_ops_visitor_record_visit_time` (`visit_time`)
    787. 

  787. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='访客记录表';</div>
    788. 

  788.     <div class="note">说明：访客记录表只保存已完成登记的到访记录，不保存登记失败结果。登记失败、扫码失败、身份证读取失败、预约匹配失败等异常，进入日志中心或后续扩展的登记异常日志。</div>
    789. 

  789.     <div class="note">说明：visit_type 建议使用 RuoYi 字典 visitor_visit_type，字典项为 APPOINTMENT=预约到访，WALK_IN=现场登记。</div>
    790. 

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

  791.     <div class="note">说明：visitor_source 和 visit_reason 为通用文本字段，用于适配公司、酒店、小区、园区、展厅等多种场景，不强制做枚举。</div>
    792. 

  792. 

  793.     <h4>8.3.2 预约记录表 robot_ops_appointment_record</h4>
    794. 

  794.     <div class="code">CREATE TABLE `robot_ops_appointment_record` (
    795. 

  795.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    796. 

  796.   `appointment_no` VARCHAR(50) NOT NULL COMMENT '预约单号',
    797. 

  797.   `visitor_name` VARCHAR(100) DEFAULT NULL COMMENT '访客姓名',
    798. 

  798.   `mobile` VARCHAR(20) DEFAULT NULL COMMENT '访客手机号',
    799. 

  799.   `visited_person` VARCHAR(100) DEFAULT NULL COMMENT '被访人/被访对象',
    800. 

  800.   `appointment_time` DATETIME DEFAULT NULL COMMENT '预约到访时间',
    801. 

  801.   `status` VARCHAR(20) DEFAULT NULL COMMENT '预约状态：待到访、已到访、已取消、已过期',
    802. 

  802.   `sync_time` DATETIME DEFAULT NULL COMMENT '同步到本地时间',
    803. 

  803.   `source_platform` VARCHAR(50) DEFAULT NULL COMMENT '来源平台',
    804. 

  804.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    805. 

  805.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    806. 

  806.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    807. 

  807.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    808. 

  808.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    809. 

  809.   PRIMARY KEY (`id`),
    810. 

  810.   UNIQUE KEY `uk_robot_ops_appointment_no` (`appointment_no`),
    811. 

  811.   KEY `idx_robot_ops_appointment_time` (`appointment_time`),
    812. 

  812.   KEY `idx_robot_ops_appointment_mobile` (`mobile`)
    813. 

  813. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='访客预约记录表';</div>
    814. 

  814. 

  815.     <h4>8.3.3 白名单表 robot_ops_whitelist</h4>
    816. 

  816.     <div class="code">CREATE TABLE `robot_ops_whitelist` (
    817. 

  817.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    818. 

  818.   `name` VARCHAR(100) NOT NULL COMMENT '姓名',
    819. 

  819.   `mobile` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
    820. 

  820.   `id_card_no` VARCHAR(50) DEFAULT NULL COMMENT '身份证号',
    821. 

  821.   `whitelist_type` VARCHAR(50) DEFAULT NULL COMMENT '人员类型字典值，如internal内部人员、visitor访客、vip VIP、other其他',
    822. 

  822.   `face_image_url` VARCHAR(255) DEFAULT NULL COMMENT '人脸照片地址，用于机器人侧照片比对',
    823. 

  823.   `source_type` VARCHAR(50) DEFAULT NULL COMMENT '来源类型字典值：1本地录入，2平台同步，3机器人采集',
    824. 

  824.   `valid_start_time` DATETIME DEFAULT NULL COMMENT '有效开始时间，不填表示立即生效',
    825. 

  825.   `valid_end_time` DATETIME DEFAULT NULL COMMENT '有效结束时间，不填表示长期有效',
    826. 

  826.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用',
    827. 

  827.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    828. 

  828.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    829. 

  829.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    830. 

  830.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    831. 

  831.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    832. 

  832.   PRIMARY KEY (`id`),
    833. 

  833.   KEY `idx_robot_ops_whitelist_mobile` (`mobile`),
    834. 

  834.   KEY `idx_robot_ops_whitelist_id_card_no` (`id_card_no`),
    835. 

  835.   KEY `idx_robot_ops_whitelist_type` (`whitelist_type`),
    836. 

  836.   KEY `idx_robot_ops_whitelist_source_type` (`source_type`),
    837. 

  837.   KEY `idx_robot_ops_whitelist_status` (`status`),
    838. 

  838.   KEY `idx_robot_ops_whitelist_valid_time` (`valid_start_time`, `valid_end_time`)
    839. 

  839. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='白名单表';</div>
    840. 

  840.     <div class="note">说明：whitelist_type 当前页面显示为"人员类型"，用于描述人员身份，不表示识别方式。建议字典项为 internal=内部人员、visitor=访客、vip=VIP、other=其他。</div>
    841. 

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

  842.     <div class="note">说明：一期不建设 face_feature_id 字段。当前人脸白名单采用照片比对方式，仅保存 face_image_url。</div>
    843. 

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

  844. 

  845.     <h3>8.4 监控与日志表</h3>
    846. 

  846.     <h4>8.4.1 远程喊话记录表 robot_ops_shout_record</h4>
    847. 

  847.     <div class="code">CREATE TABLE `robot_ops_shout_record` (
    848. 

  848.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    849. 

  849.   `shout_text` VARCHAR(1000) NOT NULL COMMENT '喊话文本',
    850. 

  850.   `volume` INT DEFAULT NULL COMMENT '音量，0-100',
    851. 

  851.   `play_times` INT DEFAULT 1 COMMENT '播放次数',
    852. 

  852.   `interrupt_flag` CHAR(1) DEFAULT '0' COMMENT '是否打断当前播报：0否，1是',
    853. 

  853.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '执行状态：SUCCESS成功，FAIL失败，RUNNING执行中',
    854. 

  854.   `result_msg` VARCHAR(500) DEFAULT NULL COMMENT '执行结果信息/失败原因',
    855. 

  855.   `operate_by` VARCHAR(64) DEFAULT NULL COMMENT '操作人',
    856. 

  856.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间/喊话时间',
    857. 

  857.   PRIMARY KEY (`id`),
    858. 

  858.   KEY `idx_robot_ops_shout_record_create_time` (`create_time`)
    859. 

  859. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='远程喊话记录表';</div>
    860. 

  860. 

  861.     <h4>8.4.2 对话日志表 robot_ops_dialogue_log</h4>
    862. 

  862.     <div class="code">CREATE TABLE `robot_ops_dialogue_log` (
    863. 

  863.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    864. 

  864.   `session_id` VARCHAR(100) DEFAULT NULL COMMENT '会话ID',
    865. 

  865.   `ask_time` DATETIME DEFAULT NULL COMMENT '提问时间',
    866. 

  866.   `question` VARCHAR(1000) DEFAULT NULL COMMENT '用户问题',
    867. 

  867.   `answer` TEXT COMMENT '机器人回答',
    868. 

  868.   `hit_type` VARCHAR(50) DEFAULT NULL COMMENT '命中方式：FAQ命中、未命中、其他',
    869. 

  869.   `scene_type` VARCHAR(50) DEFAULT NULL COMMENT '来源场景：欢迎接待、咨询问答、其他',
    870. 

  870.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '结果状态：SUCCESS成功，FAIL失败，TIMEOUT超时',
    871. 

  871.   `raw_request` TEXT COMMENT '原始请求内容',
    872. 

  872.   `raw_response` TEXT COMMENT '原始响应内容',
    873. 

  873.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    874. 

  874.   PRIMARY KEY (`id`),
    875. 

  875.   KEY `idx_robot_ops_dialogue_log_session_id` (`session_id`),
    876. 

  876.   KEY `idx_robot_ops_dialogue_log_ask_time` (`ask_time`)
    877. 

  877. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='人机对话日志表';</div>
    878. 

  878. 

  879.     <h4>8.4.3 安防告警日志表 robot_ops_alarm_log</h4>
    880. 

  880.     <div class="code">CREATE TABLE `robot_ops_alarm_log` (
    881. 

  881.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    882. 

  882.   `alarm_time` DATETIME DEFAULT NULL COMMENT '告警时间',
    883. 

  883.   `alarm_type` VARCHAR(50) DEFAULT NULL COMMENT '告警类型',
    884. 

  884.   `alarm_level` VARCHAR(20) DEFAULT NULL COMMENT '告警级别：LOW低，MEDIUM中，HIGH高，CRITICAL紧急',
    885. 

  885.   `source_position` VARCHAR(100) DEFAULT NULL COMMENT '来源位置/区域/模块',
    886. 

  886.   `handle_status` VARCHAR(20) DEFAULT 'UNHANDLED' COMMENT '处理状态：UNHANDLED未处理，CONFIRMED已确认，IGNORED已忽略',
    887. 

  887.   `description` VARCHAR(1000) DEFAULT NULL COMMENT '告警描述',
    888. 

  888.   `snapshot_url` VARCHAR(255) DEFAULT NULL COMMENT '抓拍图地址',
    889. 

  889.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    890. 

  890.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    891. 

  891.   PRIMARY KEY (`id`),
    892. 

  892.   KEY `idx_robot_ops_alarm_log_time` (`alarm_time`),
    893. 

  893.   KEY `idx_robot_ops_alarm_log_level` (`alarm_level`),
    894. 

  894.   KEY `idx_robot_ops_alarm_log_status` (`handle_status`)
    895. 

  895. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='安防告警日志表';</div>
    896. 

  896. 

  897.     <h4>8.4.4 系统日志表 robot_ops_sys_log</h4>
    898. 

  898.     <div class="code">CREATE TABLE `robot_ops_sys_log` (
    899. 

  899.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    900. 

  900.   `log_time` DATETIME DEFAULT NULL COMMENT '日志时间',
    901. 

  901.   `log_type` VARCHAR(50) DEFAULT NULL COMMENT '日志类型：系统日志、设备日志、升级日志、服务日志',
    902. 

  902.   `log_level` VARCHAR(20) DEFAULT NULL COMMENT '日志级别：INFO、WARN、ERROR',
    903. 

  903.   `module_name` VARCHAR(100) DEFAULT NULL COMMENT '模块名称',
    904. 

  904.   `content` TEXT COMMENT '日志内容',
    905. 

  905.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '结果状态',
    906. 

  906.   `trace_id` VARCHAR(100) DEFAULT NULL COMMENT '链路追踪ID',
    907. 

  907.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    908. 

  908.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    909. 

  909.   PRIMARY KEY (`id`),
    910. 

  910.   KEY `idx_robot_ops_sys_log_time` (`log_time`),
    911. 

  911.   KEY `idx_robot_ops_sys_log_type` (`log_type`),
    912. 

  912.   KEY `idx_robot_ops_sys_log_level` (`log_level`)
    913. 

  913. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统日志表';</div>
    914. 

  914. 

  915.     <h4>8.4.5 操作日志表 robot_ops_operate_log</h4>
    916. 

  916.     <div class="code">CREATE TABLE `robot_ops_operate_log` (
    917. 

  917.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    918. 

  918.   `operate_time` DATETIME DEFAULT NULL COMMENT '操作时间',
    919. 

  919.   `operate_user` VARCHAR(64) DEFAULT NULL COMMENT '操作人',
    920. 

  920.   `module_name` VARCHAR(100) DEFAULT NULL COMMENT '操作模块',
    921. 

  921.   `operate_type` VARCHAR(50) DEFAULT NULL COMMENT '操作类型：新增、编辑、删除、控制、升级等',
    922. 

  922.   `operate_content` VARCHAR(1000) DEFAULT NULL COMMENT '操作内容',
    923. 

  923.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '操作结果：SUCCESS成功，FAIL失败',
    924. 

  924.   `result_msg` VARCHAR(500) DEFAULT NULL COMMENT '结果信息/失败原因',
    925. 

  925.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    926. 

  926.   PRIMARY KEY (`id`),
    927. 

  927.   KEY `idx_robot_ops_operate_log_time` (`operate_time`),
    928. 

  928.   KEY `idx_robot_ops_operate_log_user` (`operate_user`)
    929. 

  929. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='后台操作日志表';</div>
    930. 

  930. 

  931.     <h3>8.5 运维与升级表</h3>
    932. 

  932.     <h4>8.5.1 参数分组表 robot_ops_param_group</h4>
    933. 

  933.     <div class="code">CREATE TABLE `robot_ops_param_group` (
    934. 

  934.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    935. 

  935.   `group_code` VARCHAR(50) NOT NULL COMMENT '参数分组编码',
    936. 

  936.   `group_name` VARCHAR(100) NOT NULL COMMENT '参数分组名称',
    937. 

  937.   `sort_no` INT DEFAULT 0 COMMENT '排序号，数字越小越靠前',
    938. 

  938.   `status` CHAR(1) NOT NULL DEFAULT '1' COMMENT '启用状态：0停用，1启用',
    939. 

  939.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    940. 

  940.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    941. 

  941.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    942. 

  942.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    943. 

  943.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    944. 

  944.   PRIMARY KEY (`id`),
    945. 

  945.   UNIQUE KEY `uk_robot_ops_param_group_code` (`group_code`)
    946. 

  946. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运行参数分组表';</div>
    947. 

  947. 

  948.     <h4>8.5.2 设备控制记录表 robot_ops_control_record</h4>
    949. 

  949.     <div class="code">CREATE TABLE `robot_ops_control_record` (
    950. 

  950.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    951. 

  951.   `control_type` VARCHAR(50) NOT NULL COMMENT '控制类型：充电、停止充电、重启、关机、重启服务、音频测试、屏幕测试等',
    952. 

  952.   `control_name` VARCHAR(100) DEFAULT NULL COMMENT '控制名称',
    953. 

  953.   `task_id` VARCHAR(100) DEFAULT NULL COMMENT '机器人侧返回的任务ID',
    954. 

  954.   `request_param` TEXT COMMENT '请求参数JSON',
    955. 

  955.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '执行状态：SUCCESS成功，FAIL失败，RUNNING执行中，PENDING等待中',
    956. 

  956.   `result_msg` VARCHAR(500) DEFAULT NULL COMMENT '执行结果信息/失败原因',
    957. 

  957.   `operate_by` VARCHAR(64) DEFAULT NULL COMMENT '操作人',
    958. 

  958.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间/下发时间',
    959. 

  959.   `finish_time` DATETIME DEFAULT NULL COMMENT '完成时间',
    960. 

  960.   PRIMARY KEY (`id`),
    961. 

  961.   KEY `idx_robot_ops_control_record_task_id` (`task_id`),
    962. 

  962.   KEY `idx_robot_ops_control_record_type` (`control_type`),
    963. 

  963.   KEY `idx_robot_ops_control_record_time` (`create_time`)
    964. 

  964. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='设备控制记录表';</div>
    965. 

  965. 

  966.     <h4>8.5.3 运行参数表 robot_ops_param</h4>
    967. 

  967.     <div class="code">CREATE TABLE `robot_ops_param` (
    968. 

  968.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    969. 

  969.   `group_code` VARCHAR(50) NOT NULL COMMENT '参数分组编码，关联robot_ops_param_group.group_code',
    970. 

  970.   `param_code` VARCHAR(100) NOT NULL COMMENT '参数编码',
    971. 

  971.   `param_name` VARCHAR(100) NOT NULL COMMENT '参数名称',
    972. 

  972.   `param_value` VARCHAR(2000) DEFAULT NULL COMMENT '参数值',
    973. 

  973.   `value_type` VARCHAR(20) DEFAULT NULL COMMENT '值类型：string、int、float、boolean、enum、json',
    974. 

  974.   `unit` VARCHAR(20) DEFAULT NULL COMMENT '单位',
    975. 

  975.   `editable` CHAR(1) NOT NULL DEFAULT '1' COMMENT '是否可编辑：0否，1是',
    976. 

  976.   `required_flag` CHAR(1) NOT NULL DEFAULT '0' COMMENT '是否必填：0否，1是',
    977. 

  977.   `min_value` VARCHAR(50) DEFAULT NULL COMMENT '最小值',
    978. 

  978.   `max_value` VARCHAR(50) DEFAULT NULL COMMENT '最大值',
    979. 

  979.   `enum_options` VARCHAR(2000) DEFAULT NULL COMMENT '枚举项JSON',
    980. 

  980.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '参数说明/备注',
    981. 

  981.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    982. 

  982.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    983. 

  983.   PRIMARY KEY (`id`),
    984. 

  984.   UNIQUE KEY `uk_robot_ops_param_code` (`group_code`,`param_code`),
    985. 

  985.   KEY `idx_robot_ops_param_group_code` (`group_code`)
    986. 

  986. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运行参数配置表';</div>
    987. 

  987. 

  988.     <h4>8.5.4 系统诊断项表 robot_ops_diagnosis_item</h4>
    989. 

  989.     <div class="code">CREATE TABLE `robot_ops_diagnosis_item` (
    990. 

  990.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    991. 

  991.   `item_code` VARCHAR(50) NOT NULL COMMENT '诊断项编码',
    992. 

  992.   `item_name` VARCHAR(100) NOT NULL COMMENT '诊断项名称',
    993. 

  993.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '检查结果：NORMAL正常，WARN告警，FAIL失败',
    994. 

  994.   `detail_msg` VARCHAR(1000) DEFAULT NULL COMMENT '详情描述',
    995. 

  995.   `last_check_time` DATETIME DEFAULT NULL COMMENT '最后检查时间',
    996. 

  996.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    997. 

  997.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    998. 

  998.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    999. 

  999.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1000. 

  1000.   PRIMARY KEY (`id`),
    1001. 

  1001.   UNIQUE KEY `uk_robot_ops_diagnosis_item_code` (`item_code`)
    1002. 

  1002. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统诊断项表';</div>
    1003. 

  1003.     <div class="note">说明：一期仅保留各诊断项的最新诊断结果；如后续需要追踪每次诊断历史，可在二期扩展诊断记录表和诊断明细表。</div>
    1004. 

  1004. 

  1005.     <h4>8.5.5 软件版本信息表 robot_ops_version_info</h4>
    1006. 

  1006.     <div class="code">CREATE TABLE `robot_ops_version_info` (
    1007. 

  1007.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1008. 

  1008.   `module_code` VARCHAR(50) NOT NULL COMMENT '模块编码',
    1009. 

  1009.   `module_name` VARCHAR(100) NOT NULL COMMENT '模块名称',
    1010. 

  1010.   `current_version` VARCHAR(50) DEFAULT NULL COMMENT '当前版本号',
    1011. 

  1011.   `install_time` DATETIME DEFAULT NULL COMMENT '安装时间',
    1012. 

  1012.   `run_status` VARCHAR(20) DEFAULT NULL COMMENT '运行状态：RUNNING运行中，STOPPED已停止，ERROR异常',
    1013. 

  1013.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    1014. 

  1014.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1015. 

  1015.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    1016. 

  1016.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1017. 

  1017.   PRIMARY KEY (`id`),
    1018. 

  1018.   UNIQUE KEY `uk_robot_ops_version_module_code` (`module_code`)
    1019. 

  1019. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='软件版本信息表';</div>
    1020. 

  1020. 

  1021.     <h4>8.5.6 升级包表 robot_ops_upgrade_package</h4>
    1022. 

  1022.     <div class="code">CREATE TABLE `robot_ops_upgrade_package` (
    1023. 

  1023.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1024. 

  1024.   `package_name` VARCHAR(100) NOT NULL COMMENT '安装包名称',
    1025. 

  1025.   `module_code` VARCHAR(50) NOT NULL COMMENT '升级模块编码',
    1026. 

  1026.   `target_version` VARCHAR(50) NOT NULL COMMENT '目标版本号',
    1027. 

  1027.   `file_url` VARCHAR(255) NOT NULL COMMENT '升级包文件地址',
    1028. 

  1028.   `file_size` BIGINT DEFAULT NULL COMMENT '文件大小，单位字节',
    1029. 

  1029.   `upload_by` VARCHAR(64) DEFAULT NULL COMMENT '上传人',
    1030. 

  1030.   `upload_time` DATETIME DEFAULT NULL COMMENT '上传完成时间',
    1031. 

  1031.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    1032. 

  1032.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1033. 

  1033.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    1034. 

  1034.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1035. 

  1035.   PRIMARY KEY (`id`),
    1036. 

  1036.   KEY `idx_robot_ops_upgrade_package_module` (`module_code`),
    1037. 

  1037.   KEY `idx_robot_ops_upgrade_package_version` (`target_version`)
    1038. 

  1038. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='OTA升级包表';</div>
    1039. 

  1039. 

  1040.     <h4>8.5.7 升级记录表 robot_ops_upgrade_record</h4>
    1041. 

  1041.     <div class="code">CREATE TABLE `robot_ops_upgrade_record` (
    1042. 

  1042.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1043. 

  1043.   `module_code` VARCHAR(50) NOT NULL COMMENT '模块编码',
    1044. 

  1044.   `module_name` VARCHAR(100) DEFAULT NULL COMMENT '模块名称',
    1045. 

  1045.   `current_version` VARCHAR(50) DEFAULT NULL COMMENT '原版本号',
    1046. 

  1046.   `target_version` VARCHAR(50) DEFAULT NULL COMMENT '目标版本号',
    1047. 

  1047.   `package_id` BIGINT DEFAULT NULL COMMENT '升级包ID，关联robot_ops_upgrade_package.id',
    1048. 

  1048.   `execute_by` VARCHAR(64) DEFAULT NULL COMMENT '执行人',
    1049. 

  1049.   `start_time` DATETIME DEFAULT NULL COMMENT '升级开始时间',
    1050. 

  1050.   `end_time` DATETIME DEFAULT NULL COMMENT '升级结束时间',
    1051. 

  1051.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '升级状态：SUCCESS成功，FAIL失败，RUNNING升级中，PENDING等待中',
    1052. 

  1052.   `result_msg` VARCHAR(1000) DEFAULT NULL COMMENT '升级结果信息/失败原因',
    1053. 

  1053.   `progress_percent` INT DEFAULT 0 COMMENT '升级进度百分比，0-100',
    1054. 

  1054.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1055. 

  1055.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1056. 

  1056.   PRIMARY KEY (`id`),
    1057. 

  1057.   KEY `idx_robot_ops_upgrade_record_module` (`module_code`),
    1058. 

  1058.   KEY `idx_robot_ops_upgrade_record_status` (`result_status`),
    1059. 

  1059.   KEY `idx_robot_ops_upgrade_record_start_time` (`start_time`)
    1060. 

  1060. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='OTA升级记录表';</div>
    1061. 

  1061. 

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

  1063.   </div>
    1064. 

  1064. 

  1065.   <div class="section" id="s9"><h2>9. 状态、日志与控制规则</h2>
    1066. 

  1066.     <h3>9.1 状态枚举建议</h3><table><thead><tr><th>字段</th><th>建议值</th></tr></thead><tbody><tr><td>onlineStatus</td><td>ONLINE / OFFLINE</td></tr><tr><td>workStatus</td><td>IDLE / RECEIVING / BROADCASTING / CHARGING / ERROR</td></tr><tr><td>chargeStatus</td><td>NOT_CHARGING / CHARGING / FULL</td></tr><tr><td>resultStatus</td><td>SUCCESS / FAIL / RUNNING / PENDING</td></tr><tr><td>alarmLevel</td><td>LOW / MEDIUM / HIGH / CRITICAL</td></tr><tr><td>status</td><td>0 停用 / 1 启用</td></tr></tbody></table>
    1067. 

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

  1068.     <h3>9.3 日志规则</h3><ul><li>所有关键业务操作必须写入操作日志。</li><li>机器人端回传的异常和诊断结果，统一映射到日志中心或诊断中心展示。</li><li>日志保留时长一期默认 180 天，可由系统参数配置。</li></ul>
    1069. 

  1069.   </div>
    1070. 

  1070. 

  1071.   <div class="section" id="s10"><h2>10. 权限与账号设计</h2><table><thead><tr><th>角色</th><th>默认权限</th></tr></thead><tbody><tr><td>ADMIN</td><td>全量权限，包括账号管理、参数配置、设备控制、OTA 升级。</td></tr><tr><td>OPS</td><td>首页、内容管理、访客管理、监控管理、运维管理（除账号管理）。</td></tr><tr><td>VIEWER</td><td>仅查看权限，不可执行新增、编辑、删除、升级、控制等动作。</td></tr></tbody></table><p>RuoYi 菜单权限与按钮权限均需保留，避免后期返工。即使一期只有 admin，也要按标准权限框架开发。</p></div>
    1072. 

  1072. 

  1073.   <div class="section" id="s11"><h2>11. 开发优先级与实施顺序</h2><table><thead><tr><th>阶段</th><th>模块</th><th>说明</th></tr></thead><tbody><tr><td>阶段一</td><td>登录、首页、设备状态、设备控制、参数配置、日志中心、版本/OTA</td><td>先打通基础运维闭环。</td></tr><tr><td>阶段二</td><td>欢迎语、问答库、素材管理、播放方案、播报内容、播报任务、主题配置</td><td>打通内容配置闭环。</td></tr><tr><td>阶段三</td><td>访客记录、预约记录、白名单、视频预览、远程喊话、对话日志、安防告警日志</td><td>补齐业务查询和监控能力。</td></tr><tr><td>阶段四</td><td>优化、导入导出、性能提升、操作审计完善</td><td>稳定化阶段。</td></tr></tbody></table></div>
    1074. 

  1074. 

  1075.   <div class="section" id="s12"><h2>12. 对其他团队的配合要求</h2><div class="danger">以下内容不再作为“待定事项”，而是作为其他团队必须按本文配合实现的内容。</div><ul><li><strong>机器人侧：</strong>需提供首页状态接口、设备状态接口、控制接口、视频流信息接口、喊话接口、参数接口、日志接口、版本与升级接口。</li><li><strong>主控平台侧：</strong>需提供预约记录同步接口、可选白名单同步接口。</li><li><strong>展示端：</strong>需支持欢迎语、播放方案、播报任务、展示主题配置的读取与应用。</li><li><strong>算法 / 安防侧：</strong>需向运维端提供安防告警记录标准数据结构。</li></ul><div class="ok">结论：本文件已经作为一期开发基线文档定版。后续若有调整，应基于本文迭代版本，而不是推翻本文重新回到需求澄清阶段。</div></div>
    1076. 

  1076. 

  1077.   <div class="section" id="s13"><h2>13. 测试验收要点</h2><table><thead><tr><th>模块</th><th>验收要点</th></tr></thead><tbody><tr><td>登录</td><td>正确账号可登录，错误账号提示，退出后不可访问后台页面。</td></tr><tr><td>首页</td><td>状态、统计、告警、快捷入口可正常展示和跳转。</td></tr><tr><td>内容管理</td><td>欢迎语、问答库、素材、方案、播报任务、主题均可增删改查。</td></tr><tr><td>访客管理</td><td>访客记录、预约记录、白名单可查询，导出结果正确。</td></tr><tr><td>监控管理</td><td>视频可预览，喊话可执行，对话日志与告警日志可查询。</td></tr><tr><td>运维管理</td><td>设备状态可展示，控制操作有确认弹窗和结果反馈，参数保存有效，OTA 流程完整。</td></tr><tr><td>日志与权限</td><td>关键操作写入操作日志，不同角色权限生效。</td></tr></tbody></table></div>
    1078. 

  1078. 

  1079.   <div class="footer">文档版本：V2.1（完整详细设计开发版）</div>
    1080. 

  1080. </div>
    1081. 

  1081. </body>
    1082. 

  1082. </html>
    1083.