pipe-ner-server/docs/alarm-operations-2026-09-24.md

报警提醒、清单、排水研判及 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 集成、真实登录浏览器或地图底图联调；以上构建/测试不能替代实机验收。未提交、推送或部署。