# 统一报警审核交付说明

## 已确认契约

- 前端 `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`。其他工单入口及既有同设备未办结工单冲突校验保留，发生冲突会返回明确错误并回滚审核。
- 意见必填、最多 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`。
- 通过事务内触发器覆盖各服务的报警 INSERT，初始化日志；报警处理/工单关联、工单操作日志同步进入报警时间线。
- 精准更新已有菜单 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、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 实机验收，也未执行真实登录端到端测试。
- `zk-api-service` 单独编译被既有缺失类 `com.zksy.api.service.CollectionAlarmWriter` 阻塞。HEAD 已引用该类，但 Git 树中无对应文件；本轮不臆造采集恢复实现。部署采集 API 前需要补回该类并重新编译、联调。