# 报警提醒、清单、排水研判及 GIS 重构

## 交付入口

后端统一在 `AlarmController`，查询服务/DTO/枚举/Mapper 位于 `zksy-system/base/alarm`。前端公共报警页面及配套 utils/styles 位于 `src/views/subSystem/alarm/common`，详情等共享组件仍位于 `src/views/subSystem/alarm`；排水研判和 GIS 位于 `src/views/subSystem/drainage/alarm`，供水 GIS 位于 `src/views/subSystem/waterSupply/alarm`。

已有环境本次执行 `pipe-network-service/sql/migration_alarm_common_components.sql`，精确更新 2118/2142/2097/2024/2117/2140/2139 的 component，其余菜单属性保持不变；同步部署前后端后重新登录。初装审核及运营脚本已使用 common 路径。

| 既有菜单 | path | component | query |
| --- | --- | --- | --- |
| 2139 | alarmRemind | subSystem/alarm/common/remind | {"rootTypeId":2} |
| 2140 | alarmList | subSystem/alarm/common/list | {"rootTypeId":2} |
| 2141 | drainageAlarmAnalysis | subSystem/drainage/alarm/analysis | {"rootTypeId":2} |
| 2143 | drainageAlarmGIS | subSystem/drainage/alarm/alarmGIS | {"rootTypeId":2} |
| 2117 | alarmList | subSystem/alarm/common/list | {"rootTypeId":1} |
| 2120 | waterSupplyAlarmGIS | subSystem/waterSupply/alarm/alarmGIS | {"rootTypeId":1} |

GIS 按最终要求命名为 `alarmGIS.vue`，没有“周边环境”页签；保留设备信息、报警记录、监测曲线。菜单更新不创建新页面菜单，不调整父级、排序和角色关联。

## 查询与交互

- 报警清单顶部新增报警总数、监测异常、监测已恢复三项统计。复用 `GET /api/alarm/statistics` 的分级结果，在 level/total 之外增加 abnormal（未处理）、recovered（已处理）；状态通过 `AlarmRecordStatusEnum` 传入 SQL，原提醒的分级 total 不变。三项数据均覆盖当前条件和授权范围的全部事件，不受分页影响；未知状态只计入总数。需同步部署前端和管理后端，无数据库结构或菜单变更（2026-09-24）。

- `GET /api/alarm`：框架分页，后端时间排序；支持报警单号、设备关键字、报警等级、监测状态、审核结果、日期。返回 `data.records/total`，清单不再只看 `alarm_status=0`。报警单号为清单和审核列表第一列。清单页面日期条件标题为“报警时间”，设备搜索提示“请输入设备编码/名称”，移除审核结果查询条件但保留表格的审核结果列；通用接口兼容已有审核结果参数。
- `GET /api/alarm/statistics`、`/reminders`、`/options`：等级统计、按最近操作排序的事件提醒、枚举选项。提醒服务固定 `alarm_status=0`，不接受请求参数切换到已处理事件；页面移除“报警清单”操作，保留事件详情。每 30 秒更新，手动、悬停、聚焦、打开详情时暂停滚动，继续缓冲更新。
- `GET /api/alarm/{alarmId}`、`/{alarmId}/timeline`：详情与报警操作历史，时间倒序、同一时间按日志 ID 倒序；人工操作显示用户昵称，前端按日期分组，附件图片缩略图可预览。工单操作不再复制到报警日志，确认日志直接显示“已转工单（实际工单号）”。
- `GET /api/alarm/map`：排水 GIS，默认未恢复报警，按设备聚合；筛选后的报警超过 10000 条时明确提示收窄查询，不静默截断。缺坐标的设备仍保留在左侧列表。设备详情中的报警记录另按设备编码分页查询，包括历史已恢复记录。
- `GET /api/alarm/{alarmId}/analysis?period=CURVE|DAY|DAILY|MONTHLY`：事件前后 60 分钟、事件当天、截至事件日 7 天日均、6 个月月均。与快照分开展示最新采样，不使用模拟数据。

GIS 监测曲线选项/曲线操作与研判事件下拉只展示 `alarm_data.actual_value` 非空的事件，数值 0 正常保留。GIS 点位和报警记录仍包含无实际值的报警，不按此条件缩减地图。研判下拉请求 `GET /api/alarm?actualValueOnly=true`，数据库在分页之前加 `actual_value IS NOT NULL`，总数同步遵循此条件；默认 false 不影响普通清单。详情进入研判的按钮同样校验实际值，深链接不将无实际值事件补入候选，曲线接口对无实际值返回 unsupported/空采样且不查询采集表。

所有新接口要求 `alarm:operations:list`，同时服务端按用户获授权的菜单校验 `rootTypeId` 和可选 `warningCode`，并查询设备类型根及全部后代。空设备类型范围返回空，不退化为无限制查询。审核授权仍单独校验 `subSystem/alarm/common/audit`，有清单权限不等于有审核权限。地图和曲线接口接受供水及排水根类型，独立研判页面仍只用于排水。

2117 同时保留 `waterSupply:alarm:list`（框架支持逗号分隔的权限），供供水首页的统计和实时异常接口使用。供水地图及首页报警点位已使用统一地图接口。

监测曲线使用采集协议白名单：雷达流量/流速、水位、压力，以及水质悬浮物/COD/氨氮/电导率/pH。水质按 `device_id` 和 `node_id` 关联原采集数据。日/月均值直接聚合有效原始值，字符串无效值不强转、不补零，空日/月保留断点；原始曲线大于区间中位采样间隔 3 倍时断线。未配置固定采样周期，故不虚构覆盖率。状态类等没有数值数据源的报警显示无曲线。原始结果超过 20000 个时间点时提示改看日/月均值。

## 数据库脚本及部署

页面目录调整的已部署环境执行 `pipe-network-service/sql/migration_alarm_menu_components.sql`：仅更新审核菜单 2118/2142/2097/2024 和排水研判/GIS 菜单 2141/2143 的 component，不改变 path、query 或权限；同步更新前后端后重新登录。供水 GIS 菜单 2120 单独执行 `migration_water_supply_alarm_gis.sql`。初装脚本已经使用最新组件路径。

本轮脚本：`pipe-network-service/sql/migration_alarm_operations.sql`（KingbaseES PostgreSQL 兼容模式）。首次部署顺序：`migration_alarm_case_work_order_id.sql` → `migration_alarm_review.sql` → `migration_alarm_operations.sql`，先落地 `work_order_id`/`create_time` 字段，再创建日志与菜单。各脚本均不再创建生命周期触发器或自定义函数。

已部署上述表结构的环境，本次必须重新部署管理端及 `zk-api-service`，日志已经改为业务代码主动写入，不依赖安装日志触发器。`pipe-network-service/sql/migration_alarm_lifecycle_log.sql` 作为增量补丁，更新单号注释/唯一索引、清除旧数据库赋号机制，并删除旧报警生命周期、工单日志镜像触发器及对应自定义函数，可重复执行，不更新菜单、不补录历史日志。部署时停止相关写入，执行清理脚本并同步更新管理端和采集端，再恢复服务。此后直接 SQL 修改业务表不会自动产生操作日志，应通过业务服务入口操作。

- `alarm_data.alarm_no varchar(64)`，唯一索引；管理端 `AlarmDataServiceImpl.saveAlarmData`（含新增/演练）和采集端 `CollectionAlarmWriter` 在 INSERT 前由程序生成 `BJyyyyMMddHHmmss + 4位随机数`，日期时间取北京时间，随机数为 0000～9999，总长 20 位。覆盖请求带入的号码，复用、恢复和普通更新不改号。两端通过相同的数据库事务锁串行执行随机取号、查重和入库，碰撞重试最多 100 次，耗尽明确报错回滚，不生成重复号或改变格式。不回填历史记录。
- 最新脚本删除旧 `trg_alarm_number` 触发器、`assign_alarm_number()` 函数、字段默认值及 `alarm_no_seq` 序列，不再由数据库赋号；既有号码保持原值。唯一索引继续作为最终约束。
- 每次新增 `alarm_data` 写入一条类型 0 的 `alarm_log`，内容为“系统触发报警；报警单号：…；报警描述：…”。描述优先用非空 `remark`，否则依次用报警类型、报警编码、“监测报警”；保留有效触发值快照，数值为空时不生成实际值/阈值占位，数值 0 正常保留，未配置的上下限不生成空文案。
- 采集 API 的 `CollectionAlarmWriter.markRecovered` 在独立事务中锁定同设备同指标的全部未处理记录，逐条更新状态并主动插入“监测恢复，报警自动解除 / 系统自动”。重复恢复不重复写日志；历史重复报警逐条记日志。不再设置数据库事务来源变量，不调用自定义数据库函数。管理端 `updateById` 统一覆盖通用修改、报警处理、燃气/压力解除入口，人工处理记录“报警已处理”，不误标为自动恢复。
- 报警插入/恢复与日志在同一事务中，失败一起回滚。确认报警生成工单时，`work_order_log.oper_desc` 使用 `alarm_no` 而非 UUID。无号码的历史报警写明“历史记录（未生成单号）”，不迁移旧工单日志。
- 不引入 `source_key`，不回填历史业务数据，不改变审核结果或设备状态。

本次未连接或执行实际数据库，不能据此断言部署环境的触发器状态。旧 Java 代码缺失主动生命周期日志的问题已修复；日志表或权限异常会抛出错误并回滚。保留 Kingbase 原生事务锁及 log_id 的 nextval 序列自增，不引入存储过程。

报警审核日志调整另提供 `pipe-network-service/sql/migration_alarm_review_log.sql`：清除旧日志触发器/自定义函数，把新写入日志类型限制为 0/1/2/3，以 `NOT VALID` 保留历史旧类型行，不删除或改写历史数据。已有环境先停止相关写入，按需要执行生命周期补丁，再执行本脚本；同步部署管理端、采集 API 和前端。首次部署也可在上述结构脚本后执行此补丁，支持重复执行。

按最新要求，`zksy-system` 与 `zk-api-service` 各自保留一份 `AlarmLogOperTypeEnum`，值统一为 0 触发、1 确认、2 误报、3 处理，不增加共享模块或模块依赖。工单操作仅写 `work_order_log`；确认审核成功创建工单后，单条确认日志写入意见及实际工单号。`oper_user_name` 使用 `sys_user.nick_name`，自动动作使用系统名称。建议在仓库根目录通过 `mvn -pl zk-api-service,pipe-network-service/zksy-admin -am package -DskipTests` 联合构建；不再需要安装额外的报警契约模块。

## 清理范围

删除排水旧 `jcbj/bjtx.vue、bjyp.vue、bjqd.vue、dqbj.vue`，供水旧 `monitorAlarm/index.vue、wjcbj/bjgl.vue`。`WaterAlarmPage` 只保留仍在使用的供水 GIS，移除旧管理页分支和独占 JS/CSS；删除独占 API 包装函数。

后端删除排水旧 `firstApprove/finalApprove` controller/service 方法、供水旧 dashboard/export controller、统计 service 和独占 DTO；同步删除/更新对应旧测试。供水首页、供水 GIS、其他模块仍调用的共享查询和排水预警发布/历史功能保留，不删除相应业务表。被删源码可通过 Git 历史恢复。

## 验证

2026-09-24 提醒/清单/GIS/研判筛选调整：管理端相关 Maven 测试 22 项、前端 Node 测试 26 项、PGlite 实际 Mapper SQL 测试 7 项通过，前端生产构建通过。覆盖提醒强制未处理、空值/零值、研判过滤先于分页及总数、跨子系统范围不泄漏。无需数据库结构脚本；部署前后端后生效，尚未进行真实 KingbaseES/登录浏览器验收。

2026-09-24 后续枚举布局调整：按用户要求移除共享模块，恢复两工程各自的枚举并核对值完全一致。相关根目录联合 `clean test` 共 12 类、98 项通过（零失败/错误/跳过）；代码与 Maven 配置无旧共享模块引用。以下 97 项为调整前验证记录。

2026-09-24 报警审核日志调整：从仓库根目录对管理端和采集端执行 Maven `clean test`，选定 11 类共 97 项通过（零失败/错误/跳过），包含单条确认日志和真实工单号、昵称、两端枚举、生命周期事务回滚与历史查询；干净编译确保不依赖已删除的重复枚举 class。SQL 兼容回归和前端 Node 回归各 18 项通过，前端生产构建通过。

最新规则回归覆盖确认审核单条日志含工单号、昵称取值、工单不写报警日志、两端枚举值一致、历史时间/ID 倒序。`AlarmLogHistoryMapperTest` 导出真实查询 SQL，PGlite 验证昵称关联、排序及历史旧类型保留；移除已失效的工单日志镜像测试。报警单号仍为 `BJyyyyMMddHHmmss + 4位随机数`，业务代码主动记日志，生命周期写入失败随业务变更一起回滚。前端历史组件及相关页面 18 项 Node 测试、生产构建通过，SQL 18 项通过。以下为此前阶段的验证记录，不表示仍采用旧的雪花单号、工单日志镜像或触发器日志方案。

- Maven 管理端相关测试 72 项通过：工单 service 26、工单 Mapper 2、审核 service 17、范围 7、运营 service 7、运营 Mapper 1、审核 controller 8、运营 controller 3、供水保留台账 controller 1。
- `mvn -pl zk-api-service -am -DskipTests compile -q` 通过。
- 前端相关 Node 测试 22 项通过，生产构建通过（保留既有 Sass 弃用及包体积提示）。
- PGlite 兼容性测试 6 项：验证移除旧数据库赋号机制、保留程序提供的号码与唯一索引、不回填历史、自动与人工处理日志、事务回滚、重复部署、5 个精准菜单与角色保留；直接执行 MyBatis 实际生成的清单/GIS/提醒/统计/详情/采样 SQL，验证范围和有效原始样本加权均值。
- 程序赋号专项测试 7 项通过：管理端 3 项覆盖保存前赋号、覆盖请求号码、2000 条并发生成及插入/更新映射策略；采集端 4 项覆盖事务内赋号、复用不改号、入库失败回滚、插入/更新映射策略。工单 26 项和运营 Mapper 1 项通过；SQL 6 项重跑通过。更新 Mapper 测试以适配工作区已有 `work_order_id` 字段改名。
- SQL 测试：先运行 `AlarmOperationsMapperTest` 生成 `zksy-system/target/alarm-operations-queries.json`，再通过 `PGLITE_MODULE` 指向 PGlite ESM 模块，执行 `node --test pipe-network-service/sql/tests/alarm_operations.test.mjs`。
- 2026-09-24 日志补充回归：`CollectionAlarmLifecycleTest` 5 项通过，验证恢复事务来源标记、重复恢复、触发器写日志失败时传播异常并回滚；审核/运营 PGlite 测试合计 17 项通过，覆盖新增描述、空值/零值、多条报警逐条恢复、人工处理区分、真实日志插入失败回滚、补丁重跑及既有工单日志保留。同时移除采集未处理报警查询中已删除的 `alarm_time` 字段，使用 `create_time` 排序。
- 两仓 `git diff --check` 通过。未执行真实 KingbaseES 集成、真实登录浏览器或地图底图联调；以上构建/测试不能替代实机验收。未提交、推送或部署。