完善安放告警功能设计文档

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

@@ -297,11 +297,16 @@
 <tr><td>扩展说明</td><td>一期不设计响应耗时、命中问答库 ID、命中标准问题和匹配置信度等字段；后续如问答能力、知识库命中逻辑或上位平台统计需求明确后再扩展。</td></tr>
 </tbody></table>
 
-    <h4>6.5.4 安防告警日志页面</h4><table><thead><tr><th>模块</th><th>详细设计</th></tr></thead><tbody>
+    <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>告警时间、告警类型、告警级别、位置/来源、处理状态、描述摘要、操作。</td></tr>
-<tr><td>详情字段</td><td>告警时间（alarmTime）、告警类型（alarmType）、告警级别（alarmLevel）、来源位置（sourcePosition）、处理状态（handleStatus）、描述（description）、抓拍图地址（snapshotUrl）、备注（remark）。</td></tr>
+<tr><td>列表字段</td><td>告警时间、告警类型、告警级别、告警标题、来源位置、处理状态、操作。</td></tr>
+<tr><td>详情字段</td><td>告警时间（alarmTime）、告警类型（alarmType）、告警级别（alarmLevel）、告警来源（alarmSource，字典 alarm_source）、来源位置（sourcePosition）、告警标题（alarmTitle）、告警描述（description）、抓拍图地址（snapshotUrl）、处理状态（handleStatus）、处理人（handleBy）、处理时间（handleTime）、处理备注（handleRemark）、备注（remark）。</td></tr>
 <tr><td>操作按钮</td><td>查看详情、确认告警、忽略告警、导出。</td></tr>
+<tr><td>业务规则</td><td>安防告警日志由机器人侧或本地安防服务写入，运维端不提供新增、编辑、删除。运维端只允许对未处理告警执行确认或忽略操作，处理后记录处理人、处理时间和处理备注。</td></tr>
+<tr><td>边界说明</td><td>安防告警日志只记录安防事件，不替代运行日志。算法异常、摄像头异常、服务异常等系统级问题应进入运行日志；安防事件本身进入安防告警日志。</td></tr>
+<tr><td>字典说明</td><td>告警类型（alarmType）、告警级别（alarmLevel）、告警来源（alarmSource）、处理状态（handleStatus）均使用数字字符串字典值，如 1、2、3、4、9，不使用英文代码。告警来源字典 alarm_source 建议为：1=摄像头，2=AI视觉算法，3=传感器，4=人工触发，5=巡逻任务，9=其他。</td></tr>
 </tbody></table>
 
     <h4>6.5.5 软件版本 / 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>
@@ -615,12 +620,14 @@
     </tbody></table>
     <div class="note">对话日志为只读日志，不提供新增、编辑、删除接口。robotCode 用于后续上传上位平台或多机器人汇聚识别；本地运维端当前不作为主要查询条件和列表字段展示。</div>
     <table><thead><tr><th>接口</th><th>方法</th><th>说明</th><th>请求参数</th><th>返回/处理字段</th><th>数据库表</th></tr></thead><tbody>
-      <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>
-      <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>
-      <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>
-      <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>
-      <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>
+      <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、alarmTitle、sourcePosition、handleStatus、snapshotUrl</td><td>robot_ops_alarm_log</td></tr>
+      <tr><td>/robot-ops/monitor/alarm/{id}</td><td>GET</td><td>安防告警详情</td><td>告警ID（id）</td><td>id、alarmTime、alarmType、alarmLevel、alarmSource、sourcePosition、alarmTitle、description、snapshotUrl、handleStatus、handleBy、handleTime、handleRemark、remark</td><td>robot_ops_alarm_log</td></tr>
+      <tr><td>/robot-ops/monitor/alarm/{id}/confirm</td><td>PUT</td><td>确认告警</td><td>告警ID（id）、处理备注（handleRemark）</td><td>处理状态（handleStatus=2）、处理人（handleBy）、处理时间（handleTime）</td><td>robot_ops_alarm_log、robot_ops_operate_log</td></tr>
+      <tr><td>/robot-ops/monitor/alarm/{id}/ignore</td><td>PUT</td><td>忽略告警</td><td>告警ID（id）、处理备注（handleRemark）</td><td>处理状态（handleStatus=3）、处理人（handleBy）、处理时间（handleTime）</td><td>robot_ops_alarm_log、robot_ops_operate_log</td></tr>
+      <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>
     </tbody></table>
+    <div class="note">安防告警为只读日志，不提供新增、编辑、删除接口。确认告警和忽略告警只更新处理状态、处理人、处理时间和处理备注，不修改原始告警内容。</div>
+    <div class="note">alarmSource 为告警来源字典字段，字典类型建议为 alarm_source，字典值使用数字字符串：1=摄像头，2=AI视觉算法，3=传感器，4=人工触发，5=巡逻任务，9=其他。前端详情页通过字典回显中文名称。</div>
  
 
    <div class="note">视频预览和远程喊话接口当前由首页工作台调用，不再单独作为左侧菜单页面；对话日志和安防告警日志已合并到运维管理菜单，作为独立日志页面保留。</div>
@@ -1054,22 +1061,30 @@ VALUES
 <div class="note">字典建议：hitType 使用 dialogue_hit_type，字典项 FAQ=命中问答库、AI=AI生成、NONE=未命中、ERROR=异常；sceneType 使用 dialogue_scene_type，字典项 SCREEN=机器人屏幕、VOICE=语音交互、H5=扫码H5、OTHER=其他；resultStatus 复用 common_result_status。</div>
 
     <h4>8.4.3 安防告警日志表 robot_ops_alarm_log</h4>
-    <div class="code">CREATE TABLE `robot_ops_alarm_log` (
+<div class="code">CREATE TABLE `robot_ops_alarm_log` (
   `id` BIGINT NOT NULL AUTO_INCREMENT COMMENT '主键ID',
   `alarm_time` DATETIME DEFAULT NULL COMMENT '告警时间',
-  `alarm_type` VARCHAR(50) DEFAULT NULL COMMENT '告警类型',
-  `alarm_level` VARCHAR(20) DEFAULT NULL COMMENT '告警级别：LOW低，MEDIUM中，HIGH高，CRITICAL紧急',
-  `source_position` VARCHAR(100) DEFAULT NULL COMMENT '来源位置/区域/模块',
-  `handle_status` VARCHAR(20) DEFAULT 'UNHANDLED' COMMENT '处理状态：UNHANDLED未处理，CONFIRMED已确认，IGNORED已忽略',
+  `alarm_type` CHAR(1) DEFAULT NULL COMMENT '告警类型：1人员闯入，2区域越界，3人员跌倒，4长时间滞留，5设备异常，9其他',
+  `alarm_level` CHAR(1) DEFAULT NULL COMMENT '告警级别：1高，2中，3低',
+  `alarm_source` CHAR(1) DEFAULT NULL COMMENT '告警来源：1摄像头，2AI视觉算法，3传感器，4人工触发，5巡逻任务，9其他',
+  `source_position` VARCHAR(100) DEFAULT NULL COMMENT '来源位置，如大厅入口、前台区域、走廊',
+  `alarm_title` VARCHAR(200) DEFAULT NULL COMMENT '告警标题或摘要',
   `description` VARCHAR(1000) DEFAULT NULL COMMENT '告警描述',
-  `snapshot_url` VARCHAR(255) DEFAULT NULL COMMENT '抓拍图地址',
+  `snapshot_url` VARCHAR(500) DEFAULT NULL COMMENT '抓拍图地址',
+  `handle_status` CHAR(1) DEFAULT '1' COMMENT '处理状态：1未处理，2已确认，3已忽略',
+  `handle_by` VARCHAR(64) DEFAULT NULL COMMENT '处理人',
+  `handle_time` DATETIME DEFAULT NULL COMMENT '处理时间',
+  `handle_remark` VARCHAR(500) DEFAULT NULL COMMENT '处理备注',
   `remark` VARCHAR(500) DEFAULT NULL COMMENT '备注',
   `create_time` DATETIME DEFAULT CURRENT_TIMESTAMP COMMENT '创建时间',
   PRIMARY KEY (`id`),
-  KEY `idx_robot_ops_alarm_log_time` (`alarm_time`),
-  KEY `idx_robot_ops_alarm_log_level` (`alarm_level`),
-  KEY `idx_robot_ops_alarm_log_status` (`handle_status`)
+  KEY `idx_alarm_time` (`alarm_time`),
+  KEY `idx_alarm_type` (`alarm_type`),
+  KEY `idx_alarm_level` (`alarm_level`),
+  KEY `idx_alarm_source` (`alarm_source`),
+  KEY `idx_handle_status` (`handle_status`)
 ) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='安防告警日志表';</div>
+<div class="note">字典建议：alarmType 使用 alarm_type，字典项 1=人员闯入、2=区域越界、3=人员跌倒、4=长时间滞留、5=设备异常、9=其他；alarmLevel 使用 alarm_level，字典项 1=高、2=中、3=低；alarmSource 使用 alarm_source，字典项 1=摄像头、2=AI视觉算法、3=传感器、4=人工触发、5=巡逻任务、9=其他；handleStatus 使用 alarm_handle_status，字典项 1=未处理、2=已确认、3=已忽略。所有字典值使用数字字符串，不使用英文代码。</div>
 
     <h4>8.4.4 系统日志表 robot_ops_sys_log</h4>
 <div class="code">CREATE TABLE `robot_ops_sys_log` (
@@ -1233,7 +1248,7 @@ VALUES
   </div>
 
   <div class="section" id="s9"><h2>9. 状态、日志与控制规则</h2>
-    <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>
+    <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>1 高 / 2 中 / 3 低；注意：alarm_log 表的 alarm_level 字段应使用数字字符串 '1'、'2'、'3'，不建议使用英文字符串。</td></tr><tr><td>status</td><td>0 停用 / 1 启用</td></tr></tbody></table>
     <h3>9.2 控制规则</h3><ul><li>重启、关机、充电、停止充电、升级等操作必须记录操作日志。</li><li>重启、关机、升级操作必须弹窗二次确认。</li><li>当机器人处于升级中时，除查看类操作外，禁止执行关机、重启、参数保存等高风险动作。</li><li>当设备离线时，控制按钮置灰并显示“设备离线，无法执行”。</li></ul>
     <h3>9.3 日志规则</h3><ul><li>所有关键业务操作必须写入操作日志。</li><li>机器人端回传的异常和运行日志，统一映射到运行日志页面展示。</li><li>日志保留时长一期默认 180 天，可由系统参数配置。</li></ul>
   </div>