pipe-ner-server/docs/alarm-review-2026-09-23.md

统一报警审核交付说明

已确认契约

• 前端 city-life-line/src/views/subSystem/alarm/index.vue，后端 AlarmController，独立的审核服务位于 base/alarm。
• 仅 alarm_status=0 进入审核列表，一条事件一行，不按设备去重；后端分页和时间排序。
• audit_status：0 未审核、1 确认报警、2 误报警。alarm_level 继续使用 1～4（一级最严重，红/橙/蓝/绿），不新增或更名为 case_level。
• 确认报警原子更新审核状态、记录审核日志并创建工单；任一步失败整个审核事务回滚。不修改设备状态，也不将报警标为已处理。误报警仅记录结论及意见。
• 审核转工单时，work_order.order_desc 根据原报警信息生成故障描述，审核意见单独记录到 alarm_log.oper_desc，不再覆盖故障描述。实际值为空的报警，页面及自动生成的工单描述均不显示实际值/阈值占位；数值 0 仍视为有效值。
• 报警生成不再提前创建工单；保留井盖必要建案，确认建单时回填已有案件的 order_id。普通手动建单、隐患转工单不再限制同设备的工单数量；仅报警转工单按设备主键 + alarm_data.warning_code 查重，通过 alarm_data.order_id 关联工单，未办结状态使用 WorkOrderStatusEnum.activeCodes()（0/1/2/3/4/6），5 已结案和 7 已取消不占名额。不同报警编码可以分别建单，不按显示名称合并；报警已恢复也不释放尚未办结的工单名额。缺失报警编码时明确报错，不能绕过查重。冲突会回滚本次审核。
• 报警建单在同一事务中先锁定设备档案行，再重新读取报警关联、查询同类未办结工单、创建并关联新工单，避免同设备多条报警并发审核重复建单。锁查询禁用缓存并刷新会话缓存，设备状态不作修改；同一报警重复调用继续返回原关联工单。本项为代码调整，不需要新增数据库结构或迁移历史数据（2026-09-24）。
• 审核意见选填、最多 500 字，两种审核结果均允许不填；审核结果仍必选。正常关闭审核弹窗不再提示“放弃本次审核”，上传或提交中仍禁止关闭。只允许 JPG/JPEG/PNG 图片，最多 5 张、单张 10 MB，前后端均拒绝 PDF。处置记录显示图片缩略图，点击可查看原图并切换同条记录的多张图片。图片复用管理端框架上传目录，票据在 Redis 保留两小时，绑定当前用户和报警。

脚本

pipe-network-service/sql/migration_alarm_review.sql 按 KingbaseES PostgreSQL 兼容语法编写。

• 只做结构和菜单调整，不复制旧 alarm_audit、不补历史日志、不推测历史审核结果；旧表数据不删除，但新代码不再读写。
• alarm_log.log_id int8 DEFAULT nextval('app_user.alarm_log_id_seq'::regclass)；序列单独定义并 OWNED BY，Java 为 Long + IdType.AUTO。不新增 source_key。
• 管理端与采集端在新增/处理事务中主动插入 alarm_log，不依赖日志触发器已部署。新增记录“系统触发报警；报警描述：…”，描述优先取非空备注，否则取报警类型/编码。采集自动恢复记录“监测恢复，报警自动解除”，仅状态真正变为 1 时记录，重复正常上报不重复记日志。部署脚本删除旧生命周期及工单日志镜像触发器/自定义函数，不再由数据库自动写日志。人工处理仍记报警日志；工单关联、工单操作不再单独写入 alarm_log，确认日志直接包含“已转工单（实际工单号）”及选填的审核意见。日志写入失败与业务变更一起回滚。最新单号规则为程序生成 BJyyyyMMddHHmmss + 4位随机数，见运营交付说明。
• 人工操作写入 sys_user.nick_name 与用户 ID；历史查询按用户 ID 关联昵称，用户不存在时保留原日志名称。按 oper_time DESC NULLS LAST, log_id DESC 返回，审核页和详情页共用日期分组历史组件，样式参考工单 dispose.vue，图片保留缩略图和大图预览。
• 日志枚举在 zksy-system 与 zk-api-service 各定义一份 AlarmLogOperTypeEnum，两端值保持一致：0 报警触发、1 确认报警、2 误报警、3 报警处理。不新增共享模块，移除关联工单/工单操作类型，历史旧类型日志保留并显示“历史操作”。已有环境执行增量脚本 migration_alarm_review_log.sql，不迁移或删除历史数据。
• 精准更新已有菜单 2118/2142/2097/2024，path='alarmAudit'、component='subSystem/alarm/index'。设备类型根分别为 1/2/3/4，燃气额外 warning_code='WARN-GAS-CONCENTRATION'；保留原父级和角色关联。
• 页面权限为 alarm:review:list；仅在缺失时创建 alarm:review:audit 按钮权限，给对应页面的现有角色补充新按钮授权，重复执行不恢复已经撤销的按钮授权。不会重复新增四个页面菜单。
• rootTypeId 代表 equipment_type.id 的根，查询包含所有后代；服务端校验当前用户实际获授权的菜单范围，不能仅修改前端 query 跨系统访问。

上线前备份、停止报警/工单写入，完整执行脚本，再部署管理端、采集 API 和前端并重新登录刷新菜单。脚本依赖现有 app_user schema、报警/工单日志/菜单表；既有列若来自其他不兼容的试验版本，不做数据修复或强制转换。

REST 审核接口

公共前缀 /api/alarm。列表、详情、日志、上传、提交均携带 rootTypeId，必要时带 warningCode。

• GET /reviews：pageNum/pageSize、keyword、alarmLevel、auditStatus、startTime/endTime、ascending。
• GET /reviews/statistics：同设备/等级/日期条件，返回 total/pending。
• GET /reviews/options：等级、审核结果和根类型枚举。
• GET /reviews/{alarmId}：详情。
• GET /{alarmId}/logs：时间线。
• POST /{alarmId}/attachments：Multipart 文件，返回附件票据。
• POST /{alarmId}/reviews：auditStatus 必填，opinion 选填（最多 500 字），attachmentTokens 选填。

其他仍被报警总览、地图和独立页面使用的通用接口保留。供水旧审核/停用写接口、通用 approve-to-work-order、旧燃气浓度监测页面独占接口与五个旧 Vue 入口已移除，可通过 Git 恢复源码。

验证与未完成验收

• 管理端 Maven clean test：审核 service/scope/mapper/附件/controller、供水台账/统计/实时/GIS相关契约、清警、工单共 55 项通过。
• 前端生产构建通过，保留原有 Sass 弃用/包体积提示；相关 Node 回归 14 项通过。
• 内存 PGlite SQL 回归 7 项通过：显式序列、精确菜单、初始化/关联/处理日志、回滚、重跑及权限撤销保留。测试文件 pipe-network-service/sql/tests/alarm_review.test.mjs。
• 未连接或修改实际数据库；PGlite 不是 KingbaseES 实机验收，也未执行真实登录端到端测试。
• 2026-09-24 更新：CollectionAlarmWriter 已存在，zk-api-service 编译通过，原缺失类阻塞已解除。后续报警运营重构及新增脚本的执行顺序见 报警运营交付说明。