pipe-ner-server/pipe-network-service/docs/2026-09-14-water-supply-home-alarm-work-order-e2e.md

供水首页与监测报警统一验收 Spec

状态：draft 日期：2026-09-14 范围：供水管网安全运行监测系统中的首页、监测设备管理-设备异常管理、监测报警模块（报警管理、报警审核、监测报警一张图）

Problem Statement

供水子系统目前多个页面职责重叠，数据口径和状态语义不一致：报警管理既想总览又要参与派发，设备异常管理和维修派单边界不清，报警审核与统一工单页的处置动作重复，首页缺少面向值班态的统一工作台。这些问题导致用户需要跨多个页面拼凑同一台设备的报警、预警、工单和设备状态，且无法在真实数据库上完成可复现、可验收的端到端流程。

Solution

以最新代码为权威，交付一组职责清晰、可演示、可验收的垂直切片：真实登录态浏览器端进入供水首页、设备异常管理、报警管理、报警审核和监测报警一张图，通过前端 REST API 调用后端聚合服务，最终落到 KingbaseES。设备异常和报警管理只读化，报警审核只保留“转工单 / 误报解除”两个审核动作，完整工单派发和处置统一由既有统一工单页承载；首页采用蓝白业务工作台，自上而下展示指挥台、异常待办和数据总览。

User Stories

1. 作为供水调度人员，我可以在首页一眼看到当前供水设施、监测设备、报警和工单的核心运行总量，以便快速判断当日态势。
2. 作为供水调度人员，我可以在首页看到待处理异常、待审核报警、待派单工单、处理中和待验收工单的数量，以便优先处理高影响事项。
3. 作为供水调度人员，我可以从首页异常待办直接跳转到设备异常管理、报警管理、报警审核或统一工单页，以便从工作台进入对应业务动作而不需要重新搜索。
4. 作为供水值班人员，我可以在设备异常管理页查看当前处于报警、维修或离线状态的供水设备清单，以便跟踪设备异常的可疑集合。
5. 作为供水值班人员，我可以在设备异常管理页按异常类型、设备编码、区域或报警等级筛选异常设备，以便缩小排查范围。
6. 作为供水值班人员，我可以导出当前异常设备的清单，以便离线巡查或上报。
7. 作为供水值班人员，我可以查看异常设备的详细信息，包括设备当前状态、报警状态、报警等级、在线状态、关联维修记录和关联未结束工单，以便判断是否需要介入。
8. 作为供水值班人员，我不应在设备异常管理页直接派单或创建工单，因为该页面只承担只读状态跟踪职责。
9. 作为报警管理人员，我可以在报警管理页查看全部供水报警台账、报警等级、设备报警状态、报警展示状态和关联工单，以便跟踪报警事实。
10. 作为报警管理人员，我可以在报警管理页看到报警趋势、报警分类占比、设备分类占比等态势统计，以便判断报警是否集中爆发。
11. 作为报警管理人员，我可以在报警管理页筛选报警，导出结果，并跳转到报警审核或统一工单页继续处理，而不需要在报警管理页直接创建或派发工单。
12. 作为报警管理人员，我不会在报警管理页看到模糊的“未处置/已处理”噪声，而是看到面向用户推导后的“待审核 / 已转工单 / 已解除”展示状态。
13. 作为报警审核人员，我可以在报警审核页只执行两种审核动作：转工单或误报解除，以便明确报警是否进入工单处置流程。
14. 作为报警审核人员，我选择“转工单”时系统会创建一笔故障维修类型、待派单状态的工单，且不要求在审核时指定责任人，以便后续统一工单页完成派单。
15. 作为报警审核人员，我从报警审核页转工单时，若同一设备、同一报警类型已存在未结束的同类报警工单，系统应阻止重复生成，以便避免重复派修。
16. 作为报警审核人员，我选择“误报解除”时会记录审核意见，并允许上传附件，以便留下审计痕迹且不创建工单。
17. 作为报警审核人员，审核完成后报警展示状态应更新为“已转工单”或“已解除”，以便我可以看到处理结果。
18. 作为接单责任人，我可以从统一工单页查看到由报警审核生成的待派单故障维修工单，并继续完成派单、接单、处理和验收，以便报警处置进入完整工单闭环。
19. 作为现场处置人员，我可以按工单要求上传处理前证据、处理说明和处理后证据，以便验收环节有据可查。
20. 作为管理员，我可以在待验收工单上选择验收通过或驳回，驳回后工单回到处理中并交同一责任人继续整改，以便保证处置质量。
21. 作为管理员，我可以查看报警审核页上方按工单状态统计的数量，包括全部工单、待处理、处理中、待验收和已完成，以便快速掌握处置进度。
22. 作为调度人员，我可以在监测报警一张图看到按设备聚合的异常点位，同一设备只显示一个主点位，以便避免同一设备多条报警记录在地图上重复堆叠。
23. 作为调度人员，监测报警一张图的点位主图标状态优先级为关联工单、报警、预警、离线、正常，以便地图语义一致并能表达设备和工单的联合状态。
24. 作为调度人员，我可以点击地图点位在右侧抽屉查看设备详情、报警等级、预警/报警摘要和关联工单，以便不打断地图视野完成核查。
25. 作为系统集成方，所有新增后端聚合接口应以 KingbaseES 为唯一生产数据源，并在最终验收时使用 KingbaseES，而不是 PostgreSQL，以便与生产环境保持一致。
26. 作为前端开发人员，我可以复用既有菜单结构而不修改菜单名称，以便保持入口可访问性和已有路由兼容。
27. 作为供水系统用户，设备报警状态由运行系统根据有效报警原因维护，工单结案只触发清警复核，前端不得直接清警，以便报警状态保持可信。
28. 作为供水系统用户，即使巡检或保养工单由其他系统派发给供水用户，我也能在统一工单页继续接单、处理和验收，以便供水用户不丢失跨系统派单的处置任务。
29. 作为供水系统用户，供水侧的设备台账、异常、监测和工单页面只展示设备类型树判定为“供水”的对象，以便不会混入排水、燃气、窨井等对象。
30. 作为前端验收人员，我可以在真实登录态浏览器中逐个进入首页、设备异常管理、报警管理、报警审核和监测报警一张图，刷新后确认路由不错位、菜单不重复、页面数据正确，以便完成最终验收。

Implementation Decisions

• 首页采用蓝白业务工作台，自上而下布局 A 指挥台、B 异常待办、C 数据总览，三块全部纳入首页；配色以蓝白为主，不使用深色大屏风格。
• 设备异常管理为只读状态看板，数据范围为供水类型的监测设备；异常来源包括报警、维修和离线；页面提供统计卡片、异常清单、筛选、导出和右侧详情抽屉，不承载工单创建或派发。
• 报警管理为只读报警台账总览，数据范围为供水设备；展示报警等级、设备报警状态、报警展示状态、关联工单、态势统计、趋势图、分类占比、筛选、导出、详情和跳转入口，不承载审核、转工单、解除或派发操作。
• 报警展示状态由后端根据报警持久化状态、审核结果和关联工单推导，分为“待审核 / 已转工单 / 已解除”，不直接暴露底层报警记录状态字段。
• 报警审核为审核工作台，只提供“转工单”和“误报解除”两个审核动作；完整派单、接单、处置、验收由统一工单页承载。
• 报警转工单创建的工单为故障维修类型，工单状态为 0-待派单；创建时不指定接单责任人，后续在统一工单页派发；必须遵守同类报警工单位一性约束。工单流程重构后 work_order 不再保留 order_type 列，“故障维修类型”由报警来源（alarm_data.work_order_id 关联工单）表达，不得回滚该列；同类工单位一性按“同设备 + 同报警类型 + 未办结工单”判定，终态（5-已结案、7-已取消）不占用名额。
• 工单状态以现有枚举为权威：0-待派单 / 1-待接单 / 2-已接单 / 3-处理中 / 4-待验收 / 5-已结案 / 6-延期中 / 7-已取消；终态仅“已结案”和“已取消”，“延期中”是处理旁路。
• 工单系统归属按关联设备的设备类型树确定，不由页面名称或标题推断；未知或未归属设备不得静默归入供水。
• 前端继续保留当前菜单名称，不修改菜单结构命名；“设备维修派单”继续作为进入统一工单页的业务入口。
• 监测报警一张图只展示供水异常相关点位，同一设备聚合为一个点位；点位主图标状态优先级为关联工单 > 报警 > 预警 > 离线 > 正常，报警等级作为辅助信息展示。
• GIS 展示沿用供水 GIS 一张图的地图交互规范，点位使用“坐标点 + 名称”；点击点位以右侧抽屉展示详情。
• 设备报警状态仍以设备表报警状态为当前是否报警的主要依据；运行系统负责自动清警和清警复核，前端只展示。该清警能力当前尚未实现：误报解除与工单结案都不会清除设备报警状态，误报解除后设备会停留在报警中（跟踪单 #51）；本 Spec 不实现清警，也不允许审核动作或工单动作临时顶替清警。
• 后端复用既有服务、接口和数据库模式，不因本 Spec 重新设计统一工单状态机；缺失的聚合和只读接口按本 Spec 补充。
• 最终数据底色为 KingbaseES；测试和验收环境不允许把 PostgreSQL 当生产真相源。
• 巡检和保养工单由其他系统派发时，供水用户仍可在统一工单页执行后续处置。
• 报警审核是供水报警唯一的写入口；旧的“一键标记已处理”（PUT /resolve/{alarmId}）与“直接派发工单”（POST /dispatch）已停用：路由与实现暂时保留，调用一律返回停用提示且不修改任何数据，去留由后续工单决定。
• 报警审核页顶部展示按工单状态的数量统计（全部 / 待处理 / 处理中 / 待验收 / 已完成），分组口径取自权威工单状态枚举，只统计供水设备且由报警审核生成（alarm_id 非空）的工单。
• 监测报警一张图由独立任务（共用 GIS 画布接入）交付；本 Spec 对该页只做核查测试，不重复实现。

Testing Decisions

• 最高层公共 seam 为真实登录态浏览器端的供水首页、设备异常管理、报警管理、报警审核和监测报警一张图联动流程，链路为浏览器页面 -> 前端 REST API -> 后端聚合服务 -> KingbaseES。
• 测试只验证外部行为，不验证内部实现细节；验收以浏览器可操作、数据正确、路由不串台为准。
• 需要覆盖的后端模块包括设备异常聚合查询、报警台账与趋势聚合、报警审核动作、报警展示状态推导和监测报警 GIS 聚合查询。
• 需要覆盖的前端模块包括供水首页、设备异常管理、报警管理、报警审核和监测报警一张图，以及它们到统一工单页、右侧详情抽屉和导出的路由。
• 测试数据优先使用专用种子数据或测试脚本，验收后如需清理则清理；不得依赖人工点击之外的外部状态。
• 已有测试中若包含同类列表页、同类聚合接口测试，可作为先例；最终验收环境使用 KingbaseES。
• 报警审核闭环的人工审查数据统一由 sql/water_supply_monitoring_alarm_rebuild_test_data.sql 重建（幂等，可重复执行）。该脚本同时取代 water_supply_monitoring_test_data.sql、water_supply_device_test_data.sql、water_supply_abnormal_test_data.sql、water_supply_alarm_ledger_test_data.sql、water_supply_alarm_audit_test_data.sql 五个失效种子，覆盖 16 条报警（四级齐全、展示状态 待审核7/已转工单7/已解除2）、8 张工单（状态 0..7 各一张，计数条 全部8/待处理2/处理中3/待验收1/已完成2）与误报解除样本；口径写在文件头，执行后自检语句与之一致。

Out of Scope

• 阈值管理页面及其业务逻辑不在本 Spec 范围内。
• 统一工单页内部状态机重构不在本 Spec 范围内；本 Spec 只复用其现有处置流程，并补充报警审核生成待派单工单的入口。
• 排水、燃气、窨井系统菜单和页面改版不在本 Spec 范围内。
• 门户总体导航框架重构和菜单重命名不在本 Spec 范围内。
• 设备台账、设施管理、运行监测已完成的历史页面重构不在本 Spec 范围内，除非首页统计卡片需要轻量调用其既有接口。
• GIS 坐标坐标系升级或多坐标系切换不在此次报警一张图的交付边界内，继续遵循已确认的 GIS 一张图展示规范。

Further Notes

• 本 Spec 以最新代码为权威，和已写入的 CONTEXT、工单生命周期文档以及 ADR-0010 保持一致。
• 首页原型的 A、B、C 三块已确认，最终实现按纵向蓝白工作台落地。
• 下一阶段在执行 to-tickets 时，每个 Ticket 应是可以演示的 tracer-bullet 垂直切片，并在 Gogs issue 中写明 Blocked by。