供水管网安全运行监测系统前后端整体交付规格

2026-09-04 口径注记：本规格写于旧状态编码期（现网 1-9）。工单状态以七态共识为权威：目标编码 1-7、验收驳回是“待验收回退到处理中”的动作而非终态、新增任意中间态可进入的“已取消”终态、删除延期，见 ADR-0008 与 work-order-lifecycle.md。

Problem Statement

“城市地下管网及设施建设改造智能化系统项目”的软件平台由“地下管网管控平台”及其业务子系统组成。本规格针对其中的“供水管网安全运行监测系统”，要求 pipe-ner-server 后端与 city-life-line 前端形成可独立构建、可通过版本化 REST 契约集成验收的完整业务体验。

当前系统的路由和菜单已经完成多轮人工修正，但供水业务仍需要以一个统一的外部行为标准验收：用户能从门户进入供水系统，查看供水设施、供水监测设备和报警态势，并将真实报警推进到统一工单生命周期。设备维修派单、设备异常管理、报警管理、报警审核和供水工单总览必须职责清晰、数据来源可追溯、页面刷新后状态一致。

现有问题集中在跨前后端边界：供水设备过滤和异常判定不稳定，报警记录与设备报警状态容易混淆，报警转工单和责任人派发阶段混淆，同一设备同一报警类型可能重复建单，工单处置证据和状态流转不完整，且部分页面仍可能依赖模拟数据或返回无法解释的错误。测试必须以真实登录态、真实 REST API 和 KingbaseES 数据为依据，不能以 PostgreSQL、随机模拟数据或私有实现细节代替生产真相。

Solution

交付一个完整的供水管网安全运行监测系统版本，前后端共同遵守已确认的领域模型、统一工单生命周期和 KingbaseES 数据契约：

以门户到供水系统的真实浏览器流程作为最高层公共验收接缝。
供水设施管理覆盖管网信息查询、水厂信息查询、泵站信息查询、水源地信息查询、用水户信息查询、管网数据统计分析和供水设施 GIS 一张图。
监测设备管理覆盖供水设备台账、设备异常管理、设备维修派单、设备维修记录和监测设备 GIS 一张图；只展示设备类型树归属为供水的设备。
运行监测覆盖流量监测、压力监测和漏失监测，展示真实监测数据及其查询、导出能力。
监测报警覆盖报警管理、报警审核、阈值管理和监测报警一张图；报警管理偏重态势与报警转工单，报警审核偏重供水故障维修工单的完整处置。
报警记录进入处置流程时幂等生成不指定责任人的 1-故障维修 待派单工单；后续由统一工单流程指定唯一接单责任人。
统一工单视图作为“供水工单总览”使用，集中检索和处置全部供水类型工单，包括故障维修、日常巡检和设备保养；菜单兼容名称“报警工单处置”不擅自修改。
工单结案只触发清警复核；运行系统确认设备不存在任何有效报警原因后，才将设备报警状态恢复为正常。

User Stories

As a 项目用户, I want to 从门户进入供水管网安全运行监测系统首页, so that 我能在正确的业务系统上下文中工作。
As a 项目用户, I want to 看到稳定的供水菜单层级和菜单图标, so that 我能按设施、设备、监测和报警职责定位功能。
As a 供水设施管理人员, I want to 查询供水管线和管点, so that 我能按管材、管径、建设年代、所属区域和关键字定位资料。
As a 供水设施管理人员, I want to 查询水源地、水厂、泵站和用水户, so that 我能维护完整的供水设施业务视图。
As a 供水设施管理人员, I want to 将用水户按居民、工业、商业和行政事业等类型查询, so that 所有供水服务对象使用统一术语并可分类管理。
As a 供水设施管理人员, I want to 批量导入和导出五类供水设施及其 WGS84 坐标, so that 我能批量初始化资料并进行线下分析、业务留档。
As a 供水设施管理人员, I want to 在供水设施 GIS 一张图查看水源地、水厂、泵站、供水管线和用水户, so that 我能在统一空间视图中搜索、定位和查看详情。
As a 供水设施管理人员, I want to 在列表页面与 GIS 一张图之间保持职责区分, so that 查询页面不会重复实现空间定位逻辑。
As a 设备管理人员, I want to 只看到设备类型树归属为供水的监测设备, so that 其他系统设备不会混入供水台账或工单。
As a 设备管理人员, I want to 查看设备分类统计、设备状态、在线状态和报警状态, so that 我能判断设备是否需要人工关注。
As a 设备管理人员, I want to 知道设备进入异常清单的报警原因或维修原因, so that 我能选择正确的后续处置动作。
As a 设备管理人员, I want to 在设备异常管理中查看异常态势、处置状态和关联工单, so that 该页面承担异常管理而不是重复设备维修派单页面。
As a 派单人员, I want to 在设备维修派单中只看到已判定运行故障且没有适用未结束故障维修工单的设备, so that 我能创建可执行的维修工单。
As a 派单人员, I want to 在已有关联工单的设备上看到真实工单编号 order_no, so that 我能追踪业务工单而不是辨认随机数据库 ID。
As a 派单人员, I want to 在设备详情侧边栏查看设备当前状态、设备报警状态、在线状态、报警等级和维修状态, so that 详情不会遮挡列表且字段具有一致的辨识度。
As a 派单人员, I want to 在派单窗口左侧选择部门树和唯一责任人、右侧填写工单类型、优先级和问题描述, so that 我能按统一布局完成派单。
As a 派单人员, I want to 使设备维修派单生成的工单类型固定为 1-故障维修, so that 维修流程不会进入巡检或保养生命周期。
As a 运行监测人员, I want to 查看流量、压力和漏失监测点位及查询结果, so that 我能发现供水运行趋势和异常。
As a 报警管理人员, I want to 看到报警编码、报警类型、报警等级、设备报警状态、报警记录状态和关联工单状态的独立字段, so that 不同状态来源不会相互替代。
As a 报警管理人员, I want to 看到一级红色、二级橙色、三级蓝色、四级绿色并同时显示文字, so that 报警等级具有明确且可访问的表达。
As a 报警管理人员, I want to 从报警记录确保生成待派单故障维修工单, so that 报警事实先进入统一工单流程。
As a 系统, I want to 对报警转工单执行幂等处理, so that 同一报警记录重复操作不会生成重复工单。
As a 系统, I want to 限制同一设备同一报警编码同时只能存在一个未结束故障维修工单, so that 并发操作不会产生重复处置。
As a 系统, I want to 在报警编码缺失时按报警分类执行同类工单去重, so that 缺少编码的数据仍具有稳定的幂等规则。
As a 系统, I want to 允许同一设备的不同报警类型分别生成故障维修工单, so that 不同有效报警原因可以分别追踪。
As a 报警审核人员, I want to 在页面上看到全部工单、待处理、处理中、待验收和已完成数量, so that 我能判断处置积压和审核工作量。
As a 报警审核人员, I want to 只处理供水设备关联的故障维修工单, so that 报警审核不会承担其他系统或非故障类型工单。
As a 接单责任人, I want to 接收待接单工单并开始处理, so that 工单状态能反映真实处置阶段。
As a 接单责任人, I want to 在处理前提交简要说明和处理前图片, so that 验收人员能比较处置前现场状态。
As a 接单责任人, I want to 在提交验收时提交处置说明和处置后图片, so that 工单具备可审计的完成证据。
As a 派单或审核人员, I want to 验收通过后结案, so that 已完成工单保留完整日志、责任人和图片证据。
As a 派单或审核人员, I want to 驳回验收后让工单回到处理中, so that 责任人可以继续修复而不是丢失闭环。
As a 供水工单管理人员, I want to 在供水工单总览查看全部供水类型工单, so that 故障维修、日常巡检和设备保养均有统一查询入口。
As a 供水责任人, I want to 继续处置其他系统派发给我的巡检或保养工单, so that 供水总览不会因工单类型而阻断授权处置。
As a 运行系统, I want to 在工单结案后复核设备全部有效报警原因, so that 单个工单结案不会错误清除仍存在的其他报警。
As a 运行系统, I want to 在所有有效报警原因恢复后自动清警, so that 设备状态最终反映真实运行情况。
As a 业务用户, I want to 刷新供水页面后保持正确路由、菜单、筛选、状态和详情关系, so that 页面不会发生错位、重复菜单或状态丢失。
As a 验收人员, I want to 在桌面和移动宽度下检查列表、抽屉、弹窗和工单工作台, so that 页面可读且不会发生溢出、重叠或空白渲染。
As a 验收人员, I want to 通过真实登录态端到端流程核对页面、接口和数据库结果, so that 通过标准代表可交付版本而不是局部模拟成功。

Implementation Decisions

前端和后端保持独立仓库、独立构建，通过版本化 REST 契约和真实登录态端到端流程集成；只有契约、页面和数据库验收同时通过，才视为同一系统版本。
KingbaseES 是生产和最终验收唯一数据库真相源。PostgreSQL 不作为本项目生产验收或主要集成测试数据库；只有在无法避免时才可用于非权威兼容性检查。
供水系统只展示设备类型树稳定编码判定为供水的设备、报警和工单。工单跨供水、排水、燃气和窨井共用统一生命周期，系统归属由关联设备类型判定，不由页面名称或报警记录状态推断。
既有统一工单 API 和数据库状态机继续作为工单契约；不引入新的平行维修任务、报警工单生命周期或 Flowable 工作流。
工单类型固定为：1-故障维修、2-日常巡检、3-设备保养。报警转入和设备故障派单均使用类型 1；供水系统不负责首次创建或首次派发巡检、保养工单，但被派给供水责任人的巡检或保养工单可在供水工单总览继续处置。
报警转工单是“生成待派单工单”，工单派发是“为待派单工单指定唯一接单责任人”，两者必须在契约、页面文案和状态上分开。报警创建接口不能接收责任人并越过待派单阶段。
同一设备与同一报警编码只能有一个未结束同类故障维修工单；报警编码缺失时使用报警分类作为去重键；不同报警类型允许分别建单。并发重复请求必须返回既有工单或明确的业务冲突结果。
设备报警状态来自设备状态表，由运行系统根据全部有效报警原因维护；报警记录状态只表示单条历史记录的人工处置辅助状态，工单状态只表示处置生命周期，三者不得互相替代。
工单状态保持现有数据库状态机：待派单、待接单、已接单、处理中、待验收、已结案，另设任意中间态可进入的终态“已取消”；验收驳回从待验收回到处理中（非终态）。目标七态编码 1-7 与新旧编码对照见 ADR-0008，不存在“已驳回”终态，也不存在延期状态。工单结案只触发清警复核，不直接写正常状态。
同一设备存在多个有效报警原因时，一项维修可以产生“随同修复”结果，但其他工单仍保留记录并完成各自验收；只有清警复核确认没有有效报警原因时，设备才恢复正常。
处理前和处置后图片及说明是工单处置证据。附件使用既有 MinIO 与 KingbaseES 元数据方案，现有工单图片 URL 字段保留兼容，读取时不得丢失历史图片。
页面职责固定：设备异常管理展示异常态势和处置跟踪；设备维修派单聚焦可派单故障设备；报警管理展示报警态势、详情和报警转工单/派发入口；报警审核承载供水故障维修工单完整流程；“报警工单处置”菜单兼容保留，页面职责为供水工单总览。
GIS 联动统一集中到供水设施 GIS 一张图、监测设备 GIS 一张图和监测报警一张图；供水设施 GIS 范围包括水源地、水厂、泵站、供水管线和用水户，不包含消火栓。
报警等级由运行监测规则计算，前端只展示一级至四级及其红、橙、蓝、绿颜色，不在前端重新计算等级。
页面采用已确认的蓝白运行指挥台视觉规范：状态文字与颜色同时表达，详情使用右侧抽屉，派单窗口采用部门/责任人与工单表单左右分栏，菜单项使用语义图标并提供缺失图标兜底。
后端优先复用已有接口和服务，在不破坏旧入口的前提下通过兼容适配接入统一契约；新能力不得制造与现有统一工单流程相冲突的替代实现。

Testing Decisions

最高层公共 seam 是真实登录态浏览器端的供水报警工单端到端业务流程：从门户进入供水系统，经真实前端页面、REST API 和 KingbaseES 数据完成可观察闭环。不得把私有 Java 方法、单个 Mapper、Vue 内部状态或随机模拟数据当成独立交付标准。
端到端流程至少覆盖：门户路由、供水菜单、供水设备过滤、设施与监测页面加载、报警数据加载、报警转工单幂等、同设备同报警类型去重、不同报警类型建单、故障维修类型、唯一责任人派发、接单、开始处理、处理说明、处理前图片、提交验收、处置后图片、验收通过、驳回回处理中、再次处理、验收结案和清警复核。
每个关键页面刷新后重新读取真实数据，确认路由不错位、不产生重复菜单、不回退随机数据；接口失败必须显示可解释的错误和重试状态。
端到端断言必须区分三类状态来源：设备报警状态来自设备状态表，报警记录状态来自报警记录，工单处置状态来自工单；同时确认 order_no、责任人、日志和处置证据可回看。
必须构造同一设备存在两个有效报警原因的场景：结案一个工单后设备仍报警，全部原因恢复后才显示正常；不得以单个工单结案直接覆盖设备状态。
浏览器验收覆盖 1440px、1024px 和 390px，检查设备维修派单、设备异常管理、报警管理、报警审核和供水工单总览五页的职责区分、状态统计、右侧抽屉、派单弹窗、图片证据和工单工作台。
自动化测试作为该公共 seam 的支撑证据：前端生产构建和已有 Node 测试、后端 Maven 编译/测试、KingbaseES SQL 迁移校验、接口冒烟测试、浏览器控制台无应用级错误、git diff --check。测试断言外部行为、REST 契约和数据库业务结果。
现有燃气和窨井工单处置模块作为交互先例；图片验证除视觉展示外，还要核对工单、阶段、对象键/URL、上传人和时间等元数据关联。
测试数据必须可重复初始化且与业务真实字段一致；生产验收不得依赖 PostgreSQL 或只在内存数据库中通过。

Out of Scope

不改变已确认的门户、窨井和供水菜单名称及已通过验收的路由结构，除非为本规格的兼容跳转修复必要错误。
不在供水系统首次创建或首次派发日常巡检、设备保养工单；不复制其他系统的工单生命周期。
不改变报警等级计算算法、设备类型树编码体系或统一工单数据库状态机。
不把报警记录状态改造成设备报警状态，不以工单结案无条件清警。
不新增消火栓实体、消火栓 GIS 图层或消火栓专用业务流程。
不新增未经确认的按钮级权限编码；权限沿用现有后端校验，待编码明确后另行配置。
不将前后端合并为单仓库，不要求执行者合并、推送或发布代码。
不把 UI 视觉重构扩展到本规格未覆盖的其他业务系统页面。

Further Notes

当前已确认的最高层 seam 是真实登录态浏览器端供水报警工单端到端流程，前后端局部测试只提供证据，不替代该接缝验收。
当前重点风险是供水设备准入判定、报警编码和关联工单映射、同类工单并发去重、状态字段来源、报警审核驳回回处理中，以及多报警原因下的清警复核。
生产数据库变更和集成验收必须在 KingbaseES 环境完成；无法连接目标数据库时，应记录为环境阻塞，不得用其他数据库的通过结果替代。
执行者从隔离 worktree 开始工作，默认使用 gpt-5.6-terra、推理强度 high，不得合并或推送；当前对话负责项目管理、代码审查和最终验收。

2026-08-27-water-supply-subsystem-e2e-delivery.md 17 KB Байнгын холболт Түүх Анхны өгөгдөл