Начало Каталог Помощ
Вход
gebadi
/
robot_screen
4
0
Разклонения 0
Файлове Задачи 0 Заявки за сливане 0 Уики
ИН на ревизия: 35a56d2447
Клонове Маркери
robot_screen
/
迎宾巡逻安防机器人运维端Web管理系统详细设计开发文档_V2.1.html

迎宾巡逻安防机器人运维端Web管理系统详细设计开发文档_V2.1.html 156 KB
История Директен файл

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976977978979980981982983984985986987988989990991992993994995996997998999100010011002100310041005100610071008100910101011101210131014101510161017101810191020102110221023102410251026102710281029103010311032103310341035103610371038103910401041104210431044104510461047104810491050105110521053105410551056105710581059106010611062106310641065106610671068106910701071107210731074107510761077107810791080108110821083108410851086108710881089109010911092109310941095109610971098109911001101110211031104110511061107110811091110111111121113111411151116111711181119112011211122112311241125112611271128112911301131113211331134113511361137113811391140114111421143114411451146114711481149115011511152115311541155115611571158 
  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 生成基础列表、查询、详情、编辑、删除、导出接口和页面；当前前端已基于 RuoYi 接口和 /common/uploadMediaFile 上传接口完成定制。前端只允许用户维护素材名称、启用状态和备注，文件信息由上传接口返回或系统维护；缩略图展示、图片/视频预览、引用状态展示、删除引用保护提示均需定制。</td></tr>
    105. 

  105.         <tr><td>播放方案管理</td><td>RuoYi 主子表生成后定制</td><td>部分适合</td><td>播放方案由主表 robot_ops_play_plan 和子表 robot_ops_play_plan_item 组成，适合先使用 RuoYi 主子表生成基础列表、表单、Controller、Service、Mapper，再进行定制。前端需将原始子表表格调整为“选择素材 + 素材编排”交互，支持素材选择、顺序调整、图片停留时长、视频默认播完切换、播放状态切换、预览方案。播放状态 status=1 表示当前播放方案，status=0 表示备用方案；同一时间只允许一个播放方案处于当前播放状态，该规则需由后端事务控制。素材 quotedFlag 维护需由后端补充业务逻辑。</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，视频只有后端返回 thumbnailUrl 时才展示封面，否则前端显示默认视频图标；fileSize 为文件大小，单位字节；fileFormat 为文件格式/后缀；mimeType 为文件 MIME 类型；resolution 为分辨率；durationSeconds 为视频时长，图片素材为空。resolution、durationSeconds 允许为空。</td></tr>
    162. 

  162. <tr><td>上传规则</td><td>图片支持 jpg/png/webp；视频支持 mp4；单文件大小默认上限 500MB。当前前端实际调用 /common/uploadMediaFile 上传素材文件，上传成功后回填 fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、assetType 等字段。若部分字段为空，前端按默认图标或“-”兜底展示。</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>
    169. 

  169. <table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody>
    170. 

  170. <tr><td>页面目标</td><td>维护机器人屏幕播放使用的素材编排方案。一个播放方案由主表信息和多个素材明细组成，素材来源于素材管理模块。</td></tr>
    171. 

  171. <tr><td>开发方式</td><td>基于 RuoYi 主子表生成基础页面和接口，主表 robot_ops_play_plan，子表 robot_ops_play_plan_item，关联字段 plan_id。生成后前端需要定制为“选择素材 + 素材编排”的交互方式。</td></tr>
    172. 

  172. <tr><td>查询条件</td><td>方案名称、循环方式（loopMode）、播放状态（status）。</td></tr>
    173. 

  173. <tr><td>列表字段</td><td>方案名称（planName）、循环方式（loopMode）、素材数量（assetCount）、播放状态（status）、更新时间（updateTime）、操作。</td></tr>
    174. 

  174. <tr><td>主表编辑字段</td><td>方案名称（planName）、循环方式（loopMode）、播放状态（status）、备注（remark）。播放状态 status=1 表示当前播放，status=0 表示备用方案。</td></tr>
    175. 

  175. <tr><td>素材明细字段</td><td>素材ID（assetId）、播放顺序（playOrder）、停留时长（staySeconds）、转场方式（transitionType，预留字段，默认 none）。素材名称、素材类型、文件地址、缩略图、视频时长、分辨率等展示字段不在明细表中冗余保存，由后端根据 assetId 关联 robot_ops_media_asset 返回。</td></tr>
    176. 

  176. <tr><td>素材选择</td><td>新增素材明细时，通过“选择素材”弹窗从素材库选择启用状态的素材。前端保存时只提交 assetId、playOrder、staySeconds、transitionType 等播放编排字段；素材名称、素材类型、文件地址、缩略图、视频时长等信息由后端查询详情或预览时关联素材表返回。</td></tr>
    177. 

  177. <tr><td>素材编排</td><td>播放方案明细支持上移、下移或拖拽排序。保存时根据当前顺序重新生成 playOrder。</td></tr>
    178. 

  178. <tr><td>图片播放规则</td><td>当 assetType=image 时，staySeconds 必填，建议默认 10 秒，取值范围 1-3600 秒。</td></tr>
    179. 

  179. <tr><td>视频播放规则</td><td>当 assetType=video 时，staySeconds 可为空，表示按视频自身播放。一期不做视频截断播放逻辑。</td></tr>
    180. 

  180. <tr><td>转场方式</td><td>transitionType 作为预留字段，一期前端不展示、不编辑，默认值为 none。后续车端屏幕支持转场效果后，再开放配置，例如 none=无转场、fade=淡入淡出。</td></tr>
    181. 

  181. <tr><td>操作按钮</td><td>新增、编辑、删除、启用播放、设为备用、预览。</td></tr>
    182. 

  182. <tr><td>播放状态规则</td><td>status=1 表示当前播放方案，status=0 表示备用方案。同一时间只允许一个播放方案 status=1。启用某个方案为当前播放时，后端应在事务中将其他方案 status 置为 0，将当前方案 status 置为 1。车端只读取 status=1 的播放方案。</td></tr>
    183. 

  183. <tr><td>删除规则</td><td>删除方案时需要同步删除其素材明细，并重新计算相关素材的 quotedFlag。如删除当前播放方案，可能导致车端无可播放方案，建议后端根据实际业务策略进行限制或提示。</td></tr>
    184. 

  184. <tr><td>素材引用规则</td><td>播放方案新增、编辑、删除后，后端需要重新计算相关素材的 quotedFlag。只要素材被任意播放方案明细引用，则 quotedFlag=1；不再被任何播放方案引用，则 quotedFlag=0。</td></tr>
    185. 

  185. <tr><td>预览规则</td><td>一期前端已基于播放方案详情接口实现预览弹窗。点击"预览"后，前端调用详情接口获取方案信息和素材明细，按 playOrder 顺序展示播放清单；左侧展示当前素材的大图或视频播放器，右侧展示播放清单，支持上一个、下一个和点击清单切换。图片按 staySeconds 展示停留时长；视频使用 fileUrl 播放，默认播完后切换到下一个素材。若后续后端提供独立 preview 接口，可仅替换预览数据源，页面结构无需大改。</td></tr>
    186. 

  186. <tr><td>业务规则</td><td>新增/编辑时至少选择一个素材。停用素材不可被新播放方案选择，但历史方案中已引用的停用素材仍需支持回显。</td></tr>
    187. 

  187. <tr><td>素材信息回显</td><td>播放方案详情、编辑回显和预览接口需要关联 robot_ops_media_asset 返回素材展示信息，包括 assetName、assetType、fileUrl、thumbnailUrl、durationSeconds、resolution、assetStatus 等。明细表本身不保存这些快照字段。</td></tr>
    188. 

  188. </tbody></table>
    189. 

  189.     <div class="note">字典建议：loopMode 可使用 RuoYi 字典 play_plan_loop_mode，字典项：loop=循环播放，once=播放一次。transitionType 为预留字段，一期不开放配置。</div>
    190. 

  190.     <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>
    191. 

  191.     <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>
    192. 

  192.     <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>
    193. 

  193. 

  194.     <h3>6.4 访客管理</h3>
    195. 

  195.     <h4>6.4.1 访客记录页面</h4>
    196. 

  196. <table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody>
    197. 

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

  212. </tbody></table>
    213. 

  213.     <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>
    214. 

  214.     <h4>6.4.3 白名单管理页面</h4>
    215. 

  215. <table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody>
    216. 

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

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

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

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

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

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

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

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

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

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

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

  227. </tbody></table>
    228. 

  228. 

  229.     <h3>6.5 监控管理</h3>
    230. 

  230.     <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>
    231. 

  231.     <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>
    232. 

  232.     <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>
    233. 

  233.     <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>
    234. 

  234. 

  235.     <h3>6.6 运维管理</h3>
    236. 

  236.     <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>
    237. 

  237.     <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>
    238. 

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

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

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

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

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

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

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

  245.     <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>
    246. 

  246.     <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>
    247. 

  247.     <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>
    248. 

  248.     <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>
    249. 

  249. 

  250.     <h3>6.7 系统设置</h3>
    251. 

  251.     <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>
    252. 

  252.     <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>
    253. 

  253.     <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>
    254. 

  254.   </div>
    255. 

  255. 

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

  257.     <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>
    258. 

  258.     <h3>7.0 通用文件上传接口</h3>
    259. 

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

  260.       <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>
    261. 

  261.       <tr><td>/common/uploadMediaFile</td><td>POST</td><td>素材文件上传</td><td>文件（file）</td><td>文件地址（fileUrl/url）、素材类型（assetType）、缩略图地址（thumbnailUrl）、文件大小（fileSize）、文件格式（fileFormat）、MIME 类型（mimeType）、视频时长（durationSeconds）、分辨率（resolution）等；具体字段以后端实际返回为准</td><td>当前素材管理前端实际使用的上传接口。上传后前端回填文件信息，再通过素材新增/编辑接口保存素材记录。</td></tr>
    262. 

  262.     </tbody></table>
    263. 

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

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

  265.     <div class="note">开发设计中的 <code class="inline">/robot-ops/content/media/upload</code> 属于后续统一接口规划路径；本期前端已按当前项目实际接口 <code class="inline">/common/uploadMediaFile</code> 落地。</div>
    266. 

  266. 

  267. 

  268.     <h3>7.1 通用接口规范</h3>
    269. 

  269.     <h4>7.1.1 通用返回结构</h4>
    270. 

  270.     <div class="code">{
    271. 

  271.   "code": 200,
    272. 

  272.   "msg": "操作成功",
    273. 

  273.   "data": {},
    274. 

  274.   "timestamp": "2026-04-24 10:00:00"
    275. 

  275. }</div>
    276. 

  276.     <h4>7.1.2 分页返回结构</h4>
    277. 

  277.     <div class="code">{
    278. 

  278.   "code": 200,
    279. 

  279.   "msg": "查询成功",
    280. 

  280.   "data": {
    281. 

  281.     "total": 100,
    282. 

  282.     "pageNum": 1,
    283. 

  283.     "pageSize": 10,
    284. 

  284.     "rows": []
    285. 

  285.   },
    286. 

  286.   "timestamp": "2026-04-24 10:00:00"
    287. 

  287. }</div>
    288. 

  288.     <h4>7.1.3 通用状态码</h4>
    289. 

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

  290.       <tr><td>200</td><td>成功</td><td>正常处理 data。</td></tr>
    291. 

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

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

  293.       <tr><td>403</td><td>无权限</td><td>提示无权限。</td></tr>
    294. 

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

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

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

  297.     </tbody></table>
    298. 

  298. 

  299.     <h3>7.2 认证与系统接口</h3>
    300. 

  300.     <h4>7.2.1 登录</h4>
    301. 

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

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

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

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

  305.       <tr><td>数据库表</td><td>robot_ops_user</td></tr>
    306. 

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

  307.     </tbody></table>
    308. 

  308.     <div class="code">请求示例：
    309. 

  309. {
    310. 

  310.   "username": "admin",
    311. 

  311.   "password": "******"
    312. 

  312. }
    313. 

  313. 

  314. 返回示例：
    315. 

  315. {
    316. 

  316.   "token": "xxxxxx",
    317. 

  317.   "userId": 1,
    318. 

  318.   "username": "admin",
    319. 

  319.   "nickName": "管理员",
    320. 

  320.   "roleCode": "ADMIN"
    321. 

  321. }</div>
    322. 

  322. 

  323.     <h4>7.2.2 退出登录</h4>
    324. 

  324.     <table><thead><tr><th>项</th><th>内容</th></tr></thead><tbody>
    325. 

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

  326.       <tr><td>请求参数</td><td>无</td></tr>
    327. 

  327.       <tr><td>返回字段</td><td>无</td></tr>
    328. 

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

  329.     </tbody></table>
    330. 

  330. 

  331.     <h4>7.2.3 修改密码</h4>
    332. 

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

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

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

  335.       <tr><td>返回字段</td><td>无</td></tr>
    336. 

  336.       <tr><td>数据库表</td><td>robot_ops_user</td></tr>
    337. 

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

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

  339. 

  340.     <h4>7.2.4 当前登录用户</h4>
    341. 

  341.     <table><thead><tr><th>项</th><th>内容</th></tr></thead><tbody>
    342. 

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

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

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

  345.     </tbody></table>
    346. 

  346. 

  347.     <h4>7.2.5 基础设置查询/保存</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/system/base-config</td><td>GET</td><td>获取基础设置</td><td>后台系统名称（systemName）、后台Logo（systemLogo）、页脚文案（footerText）、备案号（recordNo）</td><td>robot_ops_system_config</td></tr>
    350. 

  350.       <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>
    351. 

  351.     </tbody></table>
    352. 

  352. 

  353.     <h3>7.3 首页接口</h3>
    354. 

  354.     <h4>7.3.1 首页总览</h4>
    355. 

  355.     <table><thead><tr><th>项</th><th>内容</th></tr></thead><tbody>
    356. 

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

  357.       <tr><td>请求参数</td><td>无</td></tr>
    358. 

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

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

  360.       <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>
    361. 

  361.     </tbody></table>
    362. 

  362. 

  363.     <h4>7.3.2 首页最近告警/最近记录</h4>
    364. 

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

  365.       <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>
    366. 

  366.       <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>
    367. 

  367.     </tbody></table>
    368. 

  368. 

  369.     <h3>7.4 内容管理接口</h3>
    370. 

  370.     <h4>7.4.1 欢迎语配置接口</h4>
    371. 

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

  372.       <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>
    373. 

  373.       <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>
    374. 

  374.       <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>
    375. 

  375.     </tbody></table>
    376. 

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

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

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

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

  380. 

  381.     <h4>7.4.2 问答库接口</h4>
    382. 

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

  383.       <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>
    384. 

  384.       <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>
    385. 

  385.       <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>
    386. 

  386.       <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>
    387. 

  387.       <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>
    388. 

  388.       <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>
    389. 

  389.     </tbody></table>
    390. 

  390. 

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

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

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

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

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

  396. 

  397.     <h4>7.4.3 素材管理接口</h4>
    398. 

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

  399. <tr><td>/base/mediAasset/list</td><td>GET</td><td>素材分页</td><td>素材名称（assetName）、素材类型（assetType）、启用状态（status）、引用状态（quotedFlag）、上传时间范围、pageNum、pageSize</td><td>id、assetName、assetType、fileFormat、fileSize、durationSeconds、resolution、thumbnailUrl、fileUrl、quotedFlag、status、createTime</td><td>robot_ops_media_asset</td></tr>
    400. 

  400. <tr><td>/base/mediAasset/{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>
    401. 

  401. <tr><td>/common/uploadMediaFile</td><td>POST</td><td>上传素材文件</td><td>文件（file）</td><td>返回文件信息：fileUrl/url、assetType、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution 等。前端上传成功后回填文件信息。</td><td>不直接等同于普通 CRUD 接口；是否直接入库以后端实现为准。当前前端兼容返回 id 或不返回 id 两种情况。</td></tr>
    402. 

  402. <tr><td>/base/mediAasset</td><td>POST</td><td>新增素材记录</td><td>assetName、assetType、fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、status、quotedFlag、remark</td><td>新增后的素材ID</td><td>robot_ops_media_asset</td></tr>
    403. 

  403. <tr><td>/base/mediAasset</td><td>PUT</td><td>编辑素材</td><td>id、assetName、assetType、fileUrl、thumbnailUrl、fileSize、fileFormat、mimeType、durationSeconds、resolution、status、quotedFlag、remark。页面仅允许用户维护 assetName、status、remark；其他字段由上传接口回填或系统维护。</td><td>无</td><td>robot_ops_media_asset</td></tr>
    404. 

  404. <tr><td>/base/mediAasset/{ids}</td><td>DELETE</td><td>删除素材</td><td>素材ID或ID数组（ids）</td><td>无；如素材已被播放方案引用，应返回不可删除原因和引用数量</td><td>robot_ops_media_asset、robot_ops_play_plan_item</td></tr>
    405. 

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

  406. </tbody></table>
    407. 

  407. <div class="note">当前素材管理前端基于 RuoYi 生成接口落地，列表、详情、新增、编辑、删除、导出使用 <code class="inline">/base/mediAasset</code> 相关接口；素材文件上传使用 <code class="inline">/common/uploadMediaFile</code>。</div>
    408. 

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

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

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

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

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

  413. 

  414.     <h4>7.4.4 播放方案接口</h4>
    415. 

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

  416.       <tr><td>/robot-ops/content/play-plan/page</td><td>GET</td><td>播放方案分页</td><td>请求：方案名称（planName）、循环方式（loopMode）、播放状态（status）、pageNum、pageSize；返回：id、planName、assetCount、loopMode、status、updateTime</td><td>robot_ops_play_plan</td></tr>
    417. 

  417.       <tr><td>/robot-ops/content/play-plan/{id}</td><td>GET</td><td>播放方案详情</td><td>返回：id、planName、assetCount、loopMode、status、remark、itemList；itemList 从明细表返回 assetId、playOrder、staySeconds、transitionType，并通过关联 robot_ops_media_asset 补充 assetName、assetType、fileUrl、thumbnailUrl、durationSeconds、resolution、assetStatus 等展示字段。</td><td>robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset</td></tr>
    418. 

  418.       <tr><td>/robot-ops/content/play-plan</td><td>POST</td><td>新增播放方案</td><td>请求：planName、loopMode、status、remark、itemList。itemList 只需提交 assetId、playOrder、staySeconds、transitionType；其中 transitionType 为预留字段，一期可不传，由后端默认写入 none；新增时至少包含一个素材明细；assetCount 由后端根据 itemList 数量计算。后端保存时需校验 assetId 对应素材是否存在且可用。</td><td>robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset</td></tr>
    419. 

  419.       <tr><td>/robot-ops/content/play-plan</td><td>PUT</td><td>编辑播放方案</td><td>请求：id、planName、loopMode、status、remark、itemList。itemList 只需提交 assetId、playOrder、staySeconds、transitionType；其中 transitionType 为预留字段，一期可不传，由后端默认写入 none；保存时以后端接收的 itemList 为准重建或更新明细；assetCount 由后端重新计算。后端保存时需校验 assetId 对应素材是否存在。</td><td>robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset</td></tr>
    420. 

  420.       <tr><td>/robot-ops/content/play-plan/{id}</td><td>DELETE</td><td>删除播放方案</td><td>方案ID（id）。删除时同步删除明细并重新计算相关素材 quotedFlag。如删除当前播放方案，可能导致车端无可播放方案，建议后端根据实际业务策略进行限制或提示。</td><td>robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset</td></tr>
    421. 

  421.       <tr><td>/robot-ops/content/play-plan/{id}/status</td><td>POST</td><td>切换播放状态</td><td>方案ID（id）、播放状态（status）。当 status=1 时，后端事务中将其他方案 status 置为 0，将当前方案 status 置为 1；当 status=0 时，需根据业务策略判断是否允许将当前播放方案设为备用。</td><td>robot_ops_play_plan</td></tr>
    422. 

  422.       <tr><td>/robot-ops/content/play-plan/{id}/preview</td><td>GET</td><td>预览播放方案（后续规划）</td><td>方案ID（id）。返回方案基本信息和按 playOrder 排序后的 itemList；itemList 需关联素材表返回 assetName、assetType、fileUrl、thumbnailUrl、durationSeconds、resolution、assetStatus 等字段，用于前端预览。当前前端一期已先基于详情接口 getPlan(id) 实现预览弹窗，后续可切换为该接口。</td><td>robot_ops_play_plan、robot_ops_play_plan_item、robot_ops_media_asset</td></tr>
    423. 

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

  424.     <div class="code">新增/编辑播放方案请求 itemList 示例：
    425. 

  425. [
    426. 

  426.   {
    427. 

  427.     "assetId": 1,
    428. 

  428.     "playOrder": 1,
    429. 

  429.     "staySeconds": 10,
    430. 

  430.     "transitionType": "none"
    431. 

  431.   },
    432. 

  432.   {
    433. 

  433.     "assetId": 2,
    434. 

  434.     "playOrder": 2,
    435. 

  435.     "staySeconds": null,
    436. 

  436.     "transitionType": "none"
    437. 

  437.   }
    438. 

  438. ]
    439. 

  439. 播放方案详情/预览返回 itemList 示例：
    440. 

  440. [
    441. 

  441.   {
    442. 

  442.     "assetId": 1,
    443. 

  443.     "assetName": "大厅欢迎背景图",
    444. 

  444.     "assetType": "image",
    445. 

  445.     "fileUrl": "/profile/upload/media/welcome-bg.jpg",
    446. 

  446.     "thumbnailUrl": "/profile/upload/media/welcome-bg.jpg",
    447. 

  447.     "durationSeconds": null,
    448. 

  448.     "resolution": "1920x1080",
    449. 

  449.     "assetStatus": "1",
    450. 

  450.     "playOrder": 1,
    451. 

  451.     "staySeconds": 10,
    452. 

  452.     "transitionType": "none"
    453. 

  453.   },
    454. 

  454.   {
    455. 

  455.     "assetId": 2,
    456. 

  456.     "assetName": "展厅轮播宣传视频",
    457. 

  457.     "assetType": "video",
    458. 

  458.     "fileUrl": "/profile/upload/media/showroom-video.mp4",
    459. 

  459.     "thumbnailUrl": "/profile/upload/media/showroom-video.jpg",
    460. 

  460.     "durationSeconds": 90,
    461. 

  461.     "resolution": "1920x1080",
    462. 

  462.     "assetStatus": "1",
    463. 

  463.     "playOrder": 2,
    464. 

  464.     "staySeconds": null,
    465. 

  465.     "transitionType": "none"
    466. 

  466.   }
    467. 

  467. ]</div>
    468. 

  468.     <div class="note">播放方案保存时，后端应根据 itemList 数量更新主表 asset_count，并根据 itemList 顺序更新 play_order。</div>
    469. 

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

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

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

  472.     <div class="note">新增、编辑、删除播放方案后，需要重新计算相关素材的 quoted_flag，确保素材管理列表中的引用状态准确。</div>
    473. 

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

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

  475.     <div class="note">字典建议：loopMode 可使用 RuoYi 字典 play_plan_loop_mode，字典项：loop=循环播放，once=播放一次。transitionType 为预留字段，一期不开放配置。</div>
    476. 

  476. 

  477.     <h4>7.4.5 播报内容与播报任务接口</h4>
    478. 

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

  479.       <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>
    480. 

  480. <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>
    481. 

  481.       <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>
    482. 

  482.       <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>
    483. 

  483.       <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>
    484. 

  484.       <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>
    485. 

  485.       <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>
    486. 

  486. <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>
    487. 

  487.       <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>
    488. 

  488.       <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>
    489. 

  489.       <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>
    490. 

  490.       <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>
    491. 

  491.     </tbody></table>
    492. 

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

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

  494. 

  495.     <h4>7.4.6 展示主题接口</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/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>
    498. 

  498.       <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>
    499. 

  499.       <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>
    500. 

  500.       <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>
    501. 

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

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

  503.     </tbody></table>
    504. 

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

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

  506. 

  507.     <h3>7.5 访客管理接口</h3>
    508. 

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

  509.       <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>
    510. 

  510.       <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>
    511. 

  511.       <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>
    512. 

  512.       <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>
    513. 

  513.       <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>
    514. 

  514.       <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>
    515. 

  515.       <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>
    516. 

  516.       <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>
    517. 

  517.       <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>
    518. 

  518. <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>
    519. 

  519.       <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>
    520. 

  520.       <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>
    521. 

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

  522.     </tbody></table>
    523. 

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

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

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

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

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

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

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

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

  531. 

  532.     <h3>7.6 监控管理接口</h3>
    533. 

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

  534.       <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>
    535. 

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

  536.       <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>
    537. 

  537.       <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>
    538. 

  538.       <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>
    539. 

  539.       <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>
    540. 

  540.       <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>
    541. 

  541.       <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>
    542. 

  542.       <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>
    543. 

  543.       <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>
    544. 

  544.       <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>
    545. 

  545.       <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>
    546. 

  546.     </tbody></table>
    547. 

  547. 

  548.     <h3>7.7 运维管理接口</h3>
    549. 

  549.     <h4>7.7.1 设备状态与设备控制接口</h4>
    550. 

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

  551.       <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>
    552. 

  552.       <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>
    553. 

  553.       <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>
    554. 

  554.       <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>
    555. 

  555.       <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>
    556. 

  556.       <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>
    557. 

  557.       <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>
    558. 

  558.       <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>
    559. 

  559.       <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>
    560. 

  560.       <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>
    561. 

  561.     </tbody></table>
    562. 

  562. 

  563.     <h4>7.7.2 运行参数接口</h4>
    564. 

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

  565.       <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>
    566. 

  566.       <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>
    567. 

  567.       <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>
    568. 

  568.       <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>
    569. 

  569.     </tbody></table>
    570. 

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

  571. 

  572.     <h4>7.7.3 系统诊断与日志接口</h4>
    573. 

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

  574.       <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>
    575. 

  575.       <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>
    576. 

  576.       <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>
    577. 

  577.       <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>
    578. 

  578.       <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>
    579. 

  579.       <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>
    580. 

  580.       <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>
    581. 

  581.     </tbody></table>
    582. 

  582. 

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

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

  585.       <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>
    586. 

  586.       <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>
    587. 

  587.       <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>
    588. 

  588.       <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>
    589. 

  589.       <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>
    590. 

  590.       <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>
    591. 

  591.       <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>
    592. 

  592.     </tbody></table>
    593. 

  593. 

  594.     <h3>7.8 账号管理接口</h3>
    595. 

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

  596.       <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>
    597. 

  597.       <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>
    598. 

  598.       <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>
    599. 

  599.       <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>
    600. 

  600.       <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>
    601. 

  601.       <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>
    602. 

  602.     </tbody></table>
    603. 

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

  604.   </div>
    605. 

  605. 

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

  607.     <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>
    608. 

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

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

  610.     <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>
    611. 

  611. 

  612.     <h3>8.1 基础与权限表</h3>
    613. 

  613.     <h4>8.1.1 本地账号表 robot_ops_user</h4>
    614. 

  614.     <div class="code">CREATE TABLE `robot_ops_user` (
    615. 

  615.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    616. 

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

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

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

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

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

  621.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    622. 

  622.   `last_login_time` DATETIME DEFAULT NULL COMMENT '最近登录时间',
    623. 

  623.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    624. 

  624.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    625. 

  625.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    626. 

  626.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    627. 

  627.   PRIMARY KEY (`id`),
    628. 

  628.   UNIQUE KEY `uk_robot_ops_user_username` (`username`)
    629. 

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

  630. 

  631.     <h4>8.1.2 系统基础配置表 robot_ops_system_config</h4>
    632. 

  632.     <div class="code">CREATE TABLE `robot_ops_system_config` (
    633. 

  633.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    634. 

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

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

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

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

  638.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    639. 

  639.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    640. 

  640.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    641. 

  641.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    642. 

  642.   PRIMARY KEY (`id`)
    643. 

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

  644. 

  645.     <h3>8.2 内容管理表</h3>
    646. 

  646.     <h4>8.2.1 欢迎语配置表 robot_ops_welcome_config</h4>
    647. 

  647.     <div class="code">CREATE TABLE `robot_ops_welcome_config` (
    648. 

  648.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    649. 

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

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

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

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

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

  654.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    655. 

  655.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    656. 

  656.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    657. 

  657.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    658. 

  658.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    659. 

  659.   PRIMARY KEY (`id`),
    660. 

  660.   UNIQUE KEY `uk_robot_ops_welcome_config_key` (`config_key`)
    661. 

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

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

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

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

  665.     <div class="code">INSERT INTO `robot_ops_welcome_config`
    666. 

  666. (`config_key`, `welcome_text`, `voice_enabled`, `cooldown_seconds`, `status`, `remark`, `create_by`, `create_time`, `update_by`, `update_time`)
    667. 

  667. VALUES
    668. 

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

  669. 

  670.     <h4>8.2.2 问答库表 robot_ops_faq</h4>
    671. 

  671.     <div class="code">CREATE TABLE `robot_ops_faq` (
    672. 

  672.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    673. 

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

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

  675.   `answer` TEXT NOT NULL COMMENT '答案内容',
    676. 

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

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

  678.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    679. 

  679.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    680. 

  680.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    681. 

  681.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    682. 

  682.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    683. 

  683.   PRIMARY KEY (`id`),
    684. 

  684.   KEY `idx_robot_ops_faq_category_type` (`category_type`),
    685. 

  685.   KEY `idx_robot_ops_faq_status` (`status`)
    686. 

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

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

  688. 

  689.     <h4>8.2.3 相似问表 robot_ops_faq_similar</h4>
    690. 

  690.     <div class="code">CREATE TABLE `robot_ops_faq_similar` (
    691. 

  691.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    692. 

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

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

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

  695.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    696. 

  696.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    697. 

  697.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    698. 

  698.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    699. 

  699.   PRIMARY KEY (`id`),
    700. 

  700.   KEY `idx_robot_ops_faq_similar_faq_id` (`faq_id`)
    701. 

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

  702. 

  703.     <h4>8.2.4 素材资源表 robot_ops_media_asset</h4>
    704. 

  704. <div class="code">CREATE TABLE `robot_ops_media_asset` (
    705. 

  705.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    706. 

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

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

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

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

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

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

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

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

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

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

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

  717.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    718. 

  718.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    719. 

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

  720.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    721. 

  721.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    722. 

  722.   PRIMARY KEY (`id`),
    723. 

  723.   KEY `idx_robot_ops_media_asset_type` (`asset_type`),
    724. 

  724.   KEY `idx_robot_ops_media_asset_status` (`status`),
    725. 

  725.   KEY `idx_robot_ops_media_asset_quoted_flag` (`quoted_flag`)
    726. 

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

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

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

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

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

  731. 

  732.     <h4>8.2.5 播放方案表 robot_ops_play_plan</h4>
    733. 

  733.     <div class="code">CREATE TABLE `robot_ops_play_plan` (
    734. 

  734.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    735. 

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

  736.   `loop_mode` VARCHAR(20) NOT NULL DEFAULT 'loop' COMMENT '循环方式：loop循环播放，once播放一次',
    737. 

  737.   `asset_count` INT NOT NULL DEFAULT 0 COMMENT '素材数量',
    738. 

  738.   `status` CHAR(1) NOT NULL DEFAULT '0' COMMENT '播放状态：0备用方案，1当前播放',
    739. 

  739.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    740. 

  740.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    741. 

  741.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    742. 

  742.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    743. 

  743.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    744. 

  744.   PRIMARY KEY (`id`),
    745. 

  745.   KEY `idx_robot_ops_play_plan_status` (`status`)
    746. 

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

  747.     <div class="note">说明：status 表示播放状态，0=备用方案，1=当前播放。车端只读取 status=1 的播放方案。</div>
    748. 

  748.     <div class="note">说明：asset_count 为素材数量，由后端根据播放方案明细 itemList 数量维护，前端不允许手动填写。</div>
    749. 

  749.     <div class="note">说明：同一时间仅允许一个播放方案 status=1，唯一性由后端事务控制，不依赖数据库唯一索引。</div>
    750. 

  750. 

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

  752.     <div class="code">CREATE TABLE `robot_ops_play_plan_item` (
    753. 

  753.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    754. 

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

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

  756.   `play_order` INT NOT NULL DEFAULT 0 COMMENT '播放顺序，数字越小越靠前',
    757. 

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

  758.   `transition_type` VARCHAR(50) NOT NULL DEFAULT 'none' COMMENT '转场方式，预留字段：none无转场，fade淡入淡出',
    759. 

  759.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    760. 

  760.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    761. 

  761.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    762. 

  762.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    763. 

  763.   PRIMARY KEY (`id`),
    764. 

  764.   KEY `idx_robot_ops_play_plan_item_plan_id` (`plan_id`),
    765. 

  765.   KEY `idx_robot_ops_play_plan_item_asset_id` (`asset_id`),
    766. 

  766.   KEY `idx_robot_ops_play_plan_item_order` (`plan_id`, `play_order`)
    767. 

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

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

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

  770.     <div class="note">说明：图片素材 stay_seconds 必填；视频素材 stay_seconds 可为空，表示按视频自身播放。一期不做视频截断播放逻辑。</div>
    771. 

  771.     <div class="note">说明：transition_type 为预留字段，一期前端不展示、不编辑，默认值为 none。后续车端屏幕支持转场动画后，再开放 fade 等转场配置。</div>
    772. 

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

  773. 

  774.     <h4>8.2.7 播报内容表 robot_ops_broadcast_content</h4>
    775. 

  775.     <div class="code">CREATE TABLE `robot_ops_broadcast_content` (
    776. 

  776.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    777. 

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

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

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

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

  781.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    782. 

  782.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    783. 

  783.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    784. 

  784.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    785. 

  785.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    786. 

  786.   PRIMARY KEY (`id`),
    787. 

  787.   KEY `idx_robot_ops_broadcast_content_type` (`content_type`),
    788. 

  788.   KEY `idx_robot_ops_broadcast_content_status` (`status`)
    789. 

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

  790. 

  791.     <h4>8.2.8 播报任务表 robot_ops_broadcast_task</h4>
    792. 

  792.     <div class="code">CREATE TABLE `robot_ops_broadcast_task` (
    793. 

  793.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    794. 

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

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

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

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

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

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

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

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

  802.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    803. 

  803.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    804. 

  804.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    805. 

  805.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    806. 

  806.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    807. 

  807.   PRIMARY KEY (`id`),
    808. 

  808.   KEY `idx_robot_ops_broadcast_task_content_id` (`content_id`),
    809. 

  809.   KEY `idx_robot_ops_broadcast_task_status` (`status`)
    810. 

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

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

  812. 

  813.     <h4>8.2.9 展示主题表 robot_ops_theme</h4>
    814. 

  814.     <div class="code">CREATE TABLE `robot_ops_theme` (
    815. 

  815.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    816. 

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

  817.   `logo_url` VARCHAR(255) DEFAULT NULL COMMENT 'Logo地址',
    818. 

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

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

  820.   `primary_color` VARCHAR(20) DEFAULT NULL COMMENT '主题主色',
    821. 

  821.   `secondary_color` VARCHAR(20) DEFAULT NULL COMMENT '辅助色',
    822. 

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

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

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

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

  826.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    827. 

  827.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    828. 

  828.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    829. 

  829.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    830. 

  830.   PRIMARY KEY (`id`),
    831. 

  831.   KEY `idx_robot_ops_theme_current_enabled` (`current_enabled`),
    832. 

  832.   KEY `idx_robot_ops_theme_status` (`status`)
    833. 

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

  834. 

  835.     <h3>8.3 访客管理表</h3>
    836. 

  836.     <h4>8.3.1 访客记录表 robot_ops_visitor_record</h4>
    837. 

  837.     <div class="code">CREATE TABLE `robot_ops_visitor_record` (
    838. 

  838.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    839. 

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

  840.   `mobile` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
    841. 

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

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

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

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

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

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

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

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

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

  850.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    851. 

  851.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    852. 

  852.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    853. 

  853.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    854. 

  854.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    855. 

  855.   PRIMARY KEY (`id`),
    856. 

  856.   KEY `idx_robot_ops_visitor_record_name` (`visitor_name`),
    857. 

  857.   KEY `idx_robot_ops_visitor_record_mobile` (`mobile`),
    858. 

  858.   KEY `idx_robot_ops_visitor_record_id_card_no` (`id_card_no`),
    859. 

  859.   KEY `idx_robot_ops_visitor_record_visit_type` (`visit_type`),
    860. 

  860.   KEY `idx_robot_ops_visitor_record_register_type` (`register_type`),
    861. 

  861.   KEY `idx_robot_ops_visitor_record_appointment_no` (`appointment_no`),
    862. 

  862.   KEY `idx_robot_ops_visitor_record_visit_time` (`visit_time`)
    863. 

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

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

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

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

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

  868. 

  869.     <h4>8.3.2 预约记录表 robot_ops_appointment_record</h4>
    870. 

  870.     <div class="code">CREATE TABLE `robot_ops_appointment_record` (
    871. 

  871.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    872. 

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

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

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

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

  876.   `appointment_time` DATETIME DEFAULT NULL COMMENT '预约到访时间',
    877. 

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

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

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

  880.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    881. 

  881.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    882. 

  882.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    883. 

  883.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    884. 

  884.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    885. 

  885.   PRIMARY KEY (`id`),
    886. 

  886.   UNIQUE KEY `uk_robot_ops_appointment_no` (`appointment_no`),
    887. 

  887.   KEY `idx_robot_ops_appointment_time` (`appointment_time`),
    888. 

  888.   KEY `idx_robot_ops_appointment_mobile` (`mobile`)
    889. 

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

  890. 

  891.     <h4>8.3.3 白名单表 robot_ops_whitelist</h4>
    892. 

  892.     <div class="code">CREATE TABLE `robot_ops_whitelist` (
    893. 

  893.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    894. 

  894.   `name` VARCHAR(100) NOT NULL COMMENT '姓名',
    895. 

  895.   `mobile` VARCHAR(20) DEFAULT NULL COMMENT '手机号',
    896. 

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

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

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

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

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

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

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

  903.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    904. 

  904.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    905. 

  905.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    906. 

  906.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    907. 

  907.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    908. 

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

  909.   KEY `idx_robot_ops_whitelist_mobile` (`mobile`),
    910. 

  910.   KEY `idx_robot_ops_whitelist_id_card_no` (`id_card_no`),
    911. 

  911.   KEY `idx_robot_ops_whitelist_type` (`whitelist_type`),
    912. 

  912.   KEY `idx_robot_ops_whitelist_source_type` (`source_type`),
    913. 

  913.   KEY `idx_robot_ops_whitelist_status` (`status`),
    914. 

  914.   KEY `idx_robot_ops_whitelist_valid_time` (`valid_start_time`, `valid_end_time`)
    915. 

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

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

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

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

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

  920. 

  921.     <h3>8.4 监控与日志表</h3>
    922. 

  922.     <h4>8.4.1 远程喊话记录表 robot_ops_shout_record</h4>
    923. 

  923.     <div class="code">CREATE TABLE `robot_ops_shout_record` (
    924. 

  924.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    925. 

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

  926.   `volume` INT DEFAULT NULL COMMENT '音量，0-100',
    927. 

  927.   `play_times` INT DEFAULT 1 COMMENT '播放次数',
    928. 

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

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

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

  931.   `operate_by` VARCHAR(64) DEFAULT NULL COMMENT '操作人',
    932. 

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

  933.   PRIMARY KEY (`id`),
    934. 

  934.   KEY `idx_robot_ops_shout_record_create_time` (`create_time`)
    935. 

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

  936. 

  937.     <h4>8.4.2 对话日志表 robot_ops_dialogue_log</h4>
    938. 

  938.     <div class="code">CREATE TABLE `robot_ops_dialogue_log` (
    939. 

  939.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    940. 

  940.   `session_id` VARCHAR(100) DEFAULT NULL COMMENT '会话ID',
    941. 

  941.   `ask_time` DATETIME DEFAULT NULL COMMENT '提问时间',
    942. 

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

  943.   `answer` TEXT COMMENT '机器人回答',
    944. 

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

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

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

  947.   `raw_request` TEXT COMMENT '原始请求内容',
    948. 

  948.   `raw_response` TEXT COMMENT '原始响应内容',
    949. 

  949.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    950. 

  950.   PRIMARY KEY (`id`),
    951. 

  951.   KEY `idx_robot_ops_dialogue_log_session_id` (`session_id`),
    952. 

  952.   KEY `idx_robot_ops_dialogue_log_ask_time` (`ask_time`)
    953. 

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

  954. 

  955.     <h4>8.4.3 安防告警日志表 robot_ops_alarm_log</h4>
    956. 

  956.     <div class="code">CREATE TABLE `robot_ops_alarm_log` (
    957. 

  957.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    958. 

  958.   `alarm_time` DATETIME DEFAULT NULL COMMENT '告警时间',
    959. 

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

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

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

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

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

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

  965.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    966. 

  966.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    967. 

  967.   PRIMARY KEY (`id`),
    968. 

  968.   KEY `idx_robot_ops_alarm_log_time` (`alarm_time`),
    969. 

  969.   KEY `idx_robot_ops_alarm_log_level` (`alarm_level`),
    970. 

  970.   KEY `idx_robot_ops_alarm_log_status` (`handle_status`)
    971. 

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

  972. 

  973.     <h4>8.4.4 系统日志表 robot_ops_sys_log</h4>
    974. 

  974.     <div class="code">CREATE TABLE `robot_ops_sys_log` (
    975. 

  975.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    976. 

  976.   `log_time` DATETIME DEFAULT NULL COMMENT '日志时间',
    977. 

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

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

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

  980.   `content` TEXT COMMENT '日志内容',
    981. 

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

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

  983.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    984. 

  984.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    985. 

  985.   PRIMARY KEY (`id`),
    986. 

  986.   KEY `idx_robot_ops_sys_log_time` (`log_time`),
    987. 

  987.   KEY `idx_robot_ops_sys_log_type` (`log_type`),
    988. 

  988.   KEY `idx_robot_ops_sys_log_level` (`log_level`)
    989. 

  989. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统日志表';</div>
    990. 

  990. 

  991.     <h4>8.4.5 操作日志表 robot_ops_operate_log</h4>
    992. 

  992.     <div class="code">CREATE TABLE `robot_ops_operate_log` (
    993. 

  993.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    994. 

  994.   `operate_time` DATETIME DEFAULT NULL COMMENT '操作时间',
    995. 

  995.   `operate_user` VARCHAR(64) DEFAULT NULL COMMENT '操作人',
    996. 

  996.   `module_name` VARCHAR(100) DEFAULT NULL COMMENT '操作模块',
    997. 

  997.   `operate_type` VARCHAR(50) DEFAULT NULL COMMENT '操作类型：新增、编辑、删除、控制、升级等',
    998. 

  998.   `operate_content` VARCHAR(1000) DEFAULT NULL COMMENT '操作内容',
    999. 

  999.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '操作结果：SUCCESS成功，FAIL失败',
    1000. 

  1000.   `result_msg` VARCHAR(500) DEFAULT NULL COMMENT '结果信息/失败原因',
    1001. 

  1001.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1002. 

  1002.   PRIMARY KEY (`id`),
    1003. 

  1003.   KEY `idx_robot_ops_operate_log_time` (`operate_time`),
    1004. 

  1004.   KEY `idx_robot_ops_operate_log_user` (`operate_user`)
    1005. 

  1005. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='后台操作日志表';</div>
    1006. 

  1006. 

  1007.     <h3>8.5 运维与升级表</h3>
    1008. 

  1008.     <h4>8.5.1 参数分组表 robot_ops_param_group</h4>
    1009. 

  1009.     <div class="code">CREATE TABLE `robot_ops_param_group` (
    1010. 

  1010.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1011. 

  1011.   `group_code` VARCHAR(50) NOT NULL COMMENT '参数分组编码',
    1012. 

  1012.   `group_name` VARCHAR(100) NOT NULL COMMENT '参数分组名称',
    1013. 

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

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

  1015.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
    1016. 

  1016.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    1017. 

  1017.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1018. 

  1018.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    1019. 

  1019.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1020. 

  1020.   PRIMARY KEY (`id`),
    1021. 

  1021.   UNIQUE KEY `uk_robot_ops_param_group_code` (`group_code`)
    1022. 

  1022. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运行参数分组表';</div>
    1023. 

  1023. 

  1024.     <h4>8.5.2 设备控制记录表 robot_ops_control_record</h4>
    1025. 

  1025.     <div class="code">CREATE TABLE `robot_ops_control_record` (
    1026. 

  1026.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1027. 

  1027.   `control_type` VARCHAR(50) NOT NULL COMMENT '控制类型：充电、停止充电、重启、关机、重启服务、音频测试、屏幕测试等',
    1028. 

  1028.   `control_name` VARCHAR(100) DEFAULT NULL COMMENT '控制名称',
    1029. 

  1029.   `task_id` VARCHAR(100) DEFAULT NULL COMMENT '机器人侧返回的任务ID',
    1030. 

  1030.   `request_param` TEXT COMMENT '请求参数JSON',
    1031. 

  1031.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '执行状态：SUCCESS成功，FAIL失败，RUNNING执行中，PENDING等待中',
    1032. 

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

  1033.   `operate_by` VARCHAR(64) DEFAULT NULL COMMENT '操作人',
    1034. 

  1034.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间/下发时间',
    1035. 

  1035.   `finish_time` DATETIME DEFAULT NULL COMMENT '完成时间',
    1036. 

  1036.   PRIMARY KEY (`id`),
    1037. 

  1037.   KEY `idx_robot_ops_control_record_task_id` (`task_id`),
    1038. 

  1038.   KEY `idx_robot_ops_control_record_type` (`control_type`),
    1039. 

  1039.   KEY `idx_robot_ops_control_record_time` (`create_time`)
    1040. 

  1040. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='设备控制记录表';</div>
    1041. 

  1041. 

  1042.     <h4>8.5.3 运行参数表 robot_ops_param</h4>
    1043. 

  1043.     <div class="code">CREATE TABLE `robot_ops_param` (
    1044. 

  1044.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1045. 

  1045.   `group_code` VARCHAR(50) NOT NULL COMMENT '参数分组编码，关联robot_ops_param_group.group_code',
    1046. 

  1046.   `param_code` VARCHAR(100) NOT NULL COMMENT '参数编码',
    1047. 

  1047.   `param_name` VARCHAR(100) NOT NULL COMMENT '参数名称',
    1048. 

  1048.   `param_value` VARCHAR(2000) DEFAULT NULL COMMENT '参数值',
    1049. 

  1049.   `value_type` VARCHAR(20) DEFAULT NULL COMMENT '值类型：string、int、float、boolean、enum、json',
    1050. 

  1050.   `unit` VARCHAR(20) DEFAULT NULL COMMENT '单位',
    1051. 

  1051.   `editable` CHAR(1) NOT NULL DEFAULT '1' COMMENT '是否可编辑：0否，1是',
    1052. 

  1052.   `required_flag` CHAR(1) NOT NULL DEFAULT '0' COMMENT '是否必填：0否，1是',
    1053. 

  1053.   `min_value` VARCHAR(50) DEFAULT NULL COMMENT '最小值',
    1054. 

  1054.   `max_value` VARCHAR(50) DEFAULT NULL COMMENT '最大值',
    1055. 

  1055.   `enum_options` VARCHAR(2000) DEFAULT NULL COMMENT '枚举项JSON',
    1056. 

  1056.   `remark` VARCHAR(500) DEFAULT NULL COMMENT '参数说明/备注',
    1057. 

  1057.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1058. 

  1058.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1059. 

  1059.   PRIMARY KEY (`id`),
    1060. 

  1060.   UNIQUE KEY `uk_robot_ops_param_code` (`group_code`,`param_code`),
    1061. 

  1061.   KEY `idx_robot_ops_param_group_code` (`group_code`)
    1062. 

  1062. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='运行参数配置表';</div>
    1063. 

  1063. 

  1064.     <h4>8.5.4 系统诊断项表 robot_ops_diagnosis_item</h4>
    1065. 

  1065.     <div class="code">CREATE TABLE `robot_ops_diagnosis_item` (
    1066. 

  1066.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1067. 

  1067.   `item_code` VARCHAR(50) NOT NULL COMMENT '诊断项编码',
    1068. 

  1068.   `item_name` VARCHAR(100) NOT NULL COMMENT '诊断项名称',
    1069. 

  1069.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '检查结果：NORMAL正常，WARN告警，FAIL失败',
    1070. 

  1070.   `detail_msg` VARCHAR(1000) DEFAULT NULL COMMENT '详情描述',
    1071. 

  1071.   `last_check_time` DATETIME DEFAULT NULL COMMENT '最后检查时间',
    1072. 

  1072.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    1073. 

  1073.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1074. 

  1074.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    1075. 

  1075.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1076. 

  1076.   PRIMARY KEY (`id`),
    1077. 

  1077.   UNIQUE KEY `uk_robot_ops_diagnosis_item_code` (`item_code`)
    1078. 

  1078. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='系统诊断项表';</div>
    1079. 

  1079.     <div class="note">说明：一期仅保留各诊断项的最新诊断结果；如后续需要追踪每次诊断历史，可在二期扩展诊断记录表和诊断明细表。</div>
    1080. 

  1080. 

  1081.     <h4>8.5.5 软件版本信息表 robot_ops_version_info</h4>
    1082. 

  1082.     <div class="code">CREATE TABLE `robot_ops_version_info` (
    1083. 

  1083.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1084. 

  1084.   `module_code` VARCHAR(50) NOT NULL COMMENT '模块编码',
    1085. 

  1085.   `module_name` VARCHAR(100) NOT NULL COMMENT '模块名称',
    1086. 

  1086.   `current_version` VARCHAR(50) DEFAULT NULL COMMENT '当前版本号',
    1087. 

  1087.   `install_time` DATETIME DEFAULT NULL COMMENT '安装时间',
    1088. 

  1088.   `run_status` VARCHAR(20) DEFAULT NULL COMMENT '运行状态：RUNNING运行中，STOPPED已停止，ERROR异常',
    1089. 

  1089.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    1090. 

  1090.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1091. 

  1091.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    1092. 

  1092.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1093. 

  1093.   PRIMARY KEY (`id`),
    1094. 

  1094.   UNIQUE KEY `uk_robot_ops_version_module_code` (`module_code`)
    1095. 

  1095. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='软件版本信息表';</div>
    1096. 

  1096. 

  1097.     <h4>8.5.6 升级包表 robot_ops_upgrade_package</h4>
    1098. 

  1098.     <div class="code">CREATE TABLE `robot_ops_upgrade_package` (
    1099. 

  1099.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1100. 

  1100.   `package_name` VARCHAR(100) NOT NULL COMMENT '安装包名称',
    1101. 

  1101.   `module_code` VARCHAR(50) NOT NULL COMMENT '升级模块编码',
    1102. 

  1102.   `target_version` VARCHAR(50) NOT NULL COMMENT '目标版本号',
    1103. 

  1103.   `file_url` VARCHAR(255) NOT NULL COMMENT '升级包文件地址',
    1104. 

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

  1105.   `upload_by` VARCHAR(64) DEFAULT NULL COMMENT '上传人',
    1106. 

  1106.   `upload_time` DATETIME DEFAULT NULL COMMENT '上传完成时间',
    1107. 

  1107.   `create_by` VARCHAR(64) DEFAULT NULL COMMENT '创建人',
    1108. 

  1108.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1109. 

  1109.   `update_by` VARCHAR(64) DEFAULT NULL COMMENT '更新人',
    1110. 

  1110.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1111. 

  1111.   PRIMARY KEY (`id`),
    1112. 

  1112.   KEY `idx_robot_ops_upgrade_package_module` (`module_code`),
    1113. 

  1113.   KEY `idx_robot_ops_upgrade_package_version` (`target_version`)
    1114. 

  1114. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='OTA升级包表';</div>
    1115. 

  1115. 

  1116.     <h4>8.5.7 升级记录表 robot_ops_upgrade_record</h4>
    1117. 

  1117.     <div class="code">CREATE TABLE `robot_ops_upgrade_record` (
    1118. 

  1118.   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
    1119. 

  1119.   `module_code` VARCHAR(50) NOT NULL COMMENT '模块编码',
    1120. 

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

  1121.   `current_version` VARCHAR(50) DEFAULT NULL COMMENT '原版本号',
    1122. 

  1122.   `target_version` VARCHAR(50) DEFAULT NULL COMMENT '目标版本号',
    1123. 

  1123.   `package_id` BIGINT DEFAULT NULL COMMENT '升级包ID，关联robot_ops_upgrade_package.id',
    1124. 

  1124.   `execute_by` VARCHAR(64) DEFAULT NULL COMMENT '执行人',
    1125. 

  1125.   `start_time` DATETIME DEFAULT NULL COMMENT '升级开始时间',
    1126. 

  1126.   `end_time` DATETIME DEFAULT NULL COMMENT '升级结束时间',
    1127. 

  1127.   `result_status` VARCHAR(20) DEFAULT NULL COMMENT '升级状态：SUCCESS成功，FAIL失败，RUNNING升级中，PENDING等待中',
    1128. 

  1128.   `result_msg` VARCHAR(1000) DEFAULT NULL COMMENT '升级结果信息/失败原因',
    1129. 

  1129.   `progress_percent` INT DEFAULT 0 COMMENT '升级进度百分比，0-100',
    1130. 

  1130.   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
    1131. 

  1131.   `update_time` DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP COMMENT '更新时间',
    1132. 

  1132.   PRIMARY KEY (`id`),
    1133. 

  1133.   KEY `idx_robot_ops_upgrade_record_module` (`module_code`),
    1134. 

  1134.   KEY `idx_robot_ops_upgrade_record_status` (`result_status`),
    1135. 

  1135.   KEY `idx_robot_ops_upgrade_record_start_time` (`start_time`)
    1136. 

  1136. ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='OTA升级记录表';</div>
    1137. 

  1137. 

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

  1139.   </div>
    1140. 

  1140. 

  1141.   <div class="section" id="s9"><h2>9. 状态、日志与控制规则</h2>
    1142. 

  1142.     <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>
    1143. 

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

  1144.     <h3>9.3 日志规则</h3><ul><li>所有关键业务操作必须写入操作日志。</li><li>机器人端回传的异常和诊断结果，统一映射到日志中心或诊断中心展示。</li><li>日志保留时长一期默认 180 天，可由系统参数配置。</li></ul>
    1145. 

  1145.   </div>
    1146. 

  1146. 

  1147.   <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>
    1148. 

  1148. 

  1149.   <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>
    1150. 

  1150. 

  1151.   <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>
    1152. 

  1152. 

  1153.   <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>
    1154. 

  1154. 

  1155.   <div class="footer">文档版本：V2.1（完整详细设计开发版）</div>
    1156. 

  1156. </div>
    1157. 

  1157. </body>
    1158. 

  1158. </html>
    1159.