# 统一报警审核交付说明

## 已确认契约

- 前端 `city-life-line/src/views/subSystem/alarm/common/audit.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 仍视为有效值。
- 报警生成不再提前创建工单；保留井盖必要建案，确认建单时回填已有案件的 `work_order_id`。普通手动建单、隐患转工单不再限制同设备的工单数量；仅报警转工单按设备主键 + `alarm_data.warning_code` 查重，通过 `alarm_data.work_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/common/audit'`。设备类型根分别为 1/2/3/4，燃气额外 `warning_code='WARN-GAS-CONCENTRATION'`；保留原父级和角色关联。
- 已部署环境本次公共页面移入 `alarm/common`，执行 `pipe-network-service/sql/migration_alarm_common_components.sql` 精准更新七个审核/清单/提醒菜单的 component；同步更新前后端后重新登录，无需重复执行建表或权限初始化，保留 path/query/权限和角色关联。
- 页面权限为 `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` 编译通过，原缺失类阻塞已解除。后续报警运营重构及新增脚本的执行顺序见 [报警运营交付说明](alarm-operations-2026-09-24.md)。