供水报警与工单验收问题修复规格

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

Problem Statement

供水系统路由和菜单结构已经通过人工验收，但业务功能验收未通过。设备维修派单、设备异常管理、报警管理、报警审核和报警工单处置在数据准入、报警转工单、工单状态流转、详情可读性和页面职责方面仍不满足已确认的供水领域规则。部分页面无法产生可测试的待派单数据，报警编码或设备报警状态展示不准确，同一设备同一报警类型可重复生成未结束工单，审核驳回状态和处置图片输入也不符合实际闭环。

本规格遵循 pipe-network-service/docs/adr/0001-unify-device-work-under-work-orders.md 与 0002-runtime-owns-device-alarm-state.md：维修请求和报警转入统一使用故障维修工单（类型 1）；设备报警状态由运行系统及有效报警原因维护，工单结案只触发清警复核，不能无条件直接清警。

Solution

修正供水后端 REST 契约和前端页面，使异常设备、报警记录和供水工单都能从真实数据进入可重复验证的闭环：

仅展示供水类型监测设备，并明确异常设备的判定来源和筛选规则。
报警记录先确保生成唯一的待派单故障维修工单，再由报警审核或其他允许入口完成责任人派发。
以设备和报警编码限制未结束工单重复创建；报警编码缺失时回退到报警分类。
报警审核提供工单状态数量、责任人派发、接单、开始处理、处理说明及前后置图片、提交验收、验收通过和驳回回处理中。
报警管理只负责态势展示、详情和报警转工单，不承载后续处置。
设备异常管理重做为异常态势与统计入口；设备维修派单聚焦没有适用未结束故障维修工单的异常设备。
设备详情使用右侧抽屉，状态字段采用统一背景框；派单窗口使用左侧部门树和责任人、右侧工单类型/优先级/描述布局。
“报警工单处置”页面保留菜单名称兼容性，但页面标题和职责改为“供水工单总览”，承载全部供水工单检索与后续处置。

User Stories

作为供水运维人员，我想只看到供水类型的监测设备，以免误派其他系统设备。
作为供水运维人员，我想知道设备为什么进入设备异常清单，以便判断是否可以派发故障维修工单。
作为派单人员，我想在设备维修派单页看到当前设备状态、设备报警状态、在线状态、报警等级、关联工单编号和维修状态，以便选择正确的设备。
作为派单人员，我想对没有适用未结束故障维修工单的异常设备发起派单，以便异常设备具备可测试的待派单入口。
作为派单人员，我想看到真实的工单编号 order_no，而不是数据库随机 ID。
作为派单人员，我想在设备详情右侧抽屉查看列表和详情，以便不丢失上下文。
作为派单人员，我想用统一样式辨识设备当前状态、报警状态、在线状态、报警等级和维修状态。
作为派单人员，我想在派单窗口左侧选择部门和单一责任人，右侧填写工单类型、优先级和问题描述，以便快速完成派单。
作为系统，我想保证设备维修派单生成的工单类型固定为故障维修（1）。
作为异常管理人员，我想在设备异常管理看到异常设备数量、按报警等级/状态的统计和当前报警原因，以便先判断整体态势再进入单设备操作。
作为报警管理人员，我想看到报警编码、报警类型、报警等级、设备报警状态、报警记录状态和关联工单状态的独立字段。
作为报警管理人员，我想按红、橙、蓝、绿显示一级、二级、三级、四级报警，并同时显示文字。
作为报警管理人员，我想从报警记录触发“确保待派单工单存在”，而不是直接绕过待派单状态派发责任人。
作为系统，我想阻止同一设备同一报警编码同时创建多个未结束故障维修工单。
作为系统，当报警编码缺失时，我想按报警分类阻止同设备重复生成未结束工单。
作为系统，我想允许同一设备的不同报警编码分别生成故障维修工单。
作为报警审核人员，我想在进入页面时看到全部工单、待处理、处理中、待验收、已完成等状态数量。
作为报警审核人员，我想只在报警审核页处理供水设备故障维修工单。
作为责任人，我想先接单，再开始处理，并在处理前提交现场图片或说明。
作为责任人，我想在提交验收时填写简要处理说明并上传处置后图片，而不是填写验收意见。
作为派单或管理人员，我想在提交验收后看到处理前图片、处置后图片和完整工单信息，以便进行验收审核。
作为审核人员，我想验收通过后结案，并保留工单日志和图片证据。
作为审核人员，我想驳回验收后让工单返回处理中，以便责任人重新处置，而不是取消流程。
作为运行系统，我想在工单结案时触发清警复核，只有不存在其他有效报警原因时才将设备报警状态恢复正常。
作为运行系统，我想同一设备存在多个有效报警原因时保留设备报警状态，不因单个工单结案而直接清警。
作为工单管理人员，我想在供水工单总览查看全部供水类型工单，并按工单类型、来源、责任人和状态筛选。
作为供水责任人，即使巡检或保养工单由其他系统创建，只要工单派给我，我仍想在供水工单总览继续接单、处理和提交验收。
作为用户，我想刷新五个页面后仍保持正确路由、菜单和数据职责，不出现页面错位或重复菜单。
作为测试人员，我想通过 REST/真实数据库接缝验证建单去重、状态流转、图片保存、驳回回处理中和设备报警状态复核。
作为测试人员，我想通过浏览器页面接缝验证五个页面的数据范围、按钮集合、抽屉和派单窗口布局。

Implementation Decisions

后端以设备类型树作为设备和工单查询的系统归属边界；供水页面只返回供水设备，工单仍使用跨系统统一业务流程并按关联设备类型过滤，不为供水单独复制一套生命周期。
/api/work-order 作为跨系统规范工单 API；供水、排水、燃气、窨井旧接口通过兼容适配接入，不复制平行工单生命周期。
统一工单使用现有数据库状态机和事务服务；新日志采用统一操作语义，历史日志通过兼容映射展示。
工单处理前和处置后图片统一使用现有 MinIO 保存对象、KingbaseES 保存附件元数据；现有 work_order 图片 URL 字段保留兼容，新上传附件按阶段记录并由后端提供受控访问地址。
报警转工单接口负责幂等地创建待派单故障维修工单，并返回工单 ID、工单编号、工单类型、状态和关联报警信息。报警管理入口不得直接把责任人写入报警创建接口。
未结束状态包括待派单、待接单、已接单、处理中、待验收以及其他未终止状态；同一设备与报警编码只能有一个。报警编码为空时使用报警分类作为去重键。
维修派单入口只能对没有适用未结束故障维修工单的供水异常设备启用；已有工单时显示真实 order_no、责任人和当前状态，并提供查看入口。
报警管理和报警审核分别使用设备报警状态与报警记录状态字段，不能互相替代；设备报警状态来源于设备状态表，报警记录状态仅作为辅助历史信息。
报警审核页面聚焦供水故障维修工单，提供状态统计和完整工单操作；报警管理只提供详情、确保建单和跳转后续处置入口。
工单状态机（本文沿用迁移前现网编码 1-6；目标七态编码 1-7 与独立“已取消”终态见 ADR-0008）保持：1 待派单 -> 2 待接单 -> 3 已接单 -> 4 处理中 -> 5 待验收 -> 6 已结案；验收驳回从 5 返回 4，不进入终止状态；任意中间态可由管理员取消进入终态“已取消”（迁移前取消暂落旧值，迁移后为目标编码 7），不存在“已驳回”终态与延期状态。
处理操作支持处理说明和处理前图片；提交验收支持处置说明和处置后图片；图片和说明随工单详情及操作日志返回。
工单结案只执行清警复核；复核检查该设备所有有效报警原因，存在任一原因时保持 equipment_status.alarm_status=1，全部恢复后才写入 0。
设备异常管理采用异常指标带、筛选、设备异常表和右侧详情抽屉；设备维修派单采用待派单队列和突出派单动作；报警管理采用报警态势表和右侧详情抽屉；报警审核采用左列表右工作台；供水工单总览采用全部供水工单主从工作台。
派单弹窗固定为左侧部门树/责任人、右侧工单类型/优先级/问题描述；只提交选中用户 ID，不允许前端手写权威姓名或电话。
菜单名称“报警工单处置”保持兼容，但页面可见标题和说明使用“供水工单总览”。

Testing Decisions

最高层公共 seam 采用真实登录态浏览器端的供水报警工单端到端业务流程：从五个供水页面进入真实后端 API 和真实数据库，以用户可观察结果验证整个闭环，不把私有 Java 方法或内部 Vue 实现作为独立测试目标。
端到端流程必须覆盖供水设备过滤、报警数据加载、报警记录确保建单幂等、同设备同报警编码去重、不同报警编码可建单、故障维修类型、责任人派单、接单、开始处理、处理说明、处理前图片、提交验收、处置后图片、验收通过、驳回回处理中、再次处理和结案。
端到端流程必须通过页面刷新和关联详情确认三类状态分别正确：设备报警状态来自设备状态表，报警记录状态来自报警记录，工单状态来自工单；同时验证工单日志和图片证据可回看。
端到端流程必须验证同一设备存在多个有效报警原因时，单个工单结案只触发清警复核而不错误清警；所有有效原因恢复后才显示设备正常。
端到端页面验收覆盖 1440px、1024px 和 390px：设备维修派单、设备异常管理、报警管理、报警审核、供水工单总览五页的加载、刷新、职责区分、状态统计、右侧抽屉、派单弹窗和工单操作。
自动化回归作为该 seam 的支撑证据，包括前端已有 Node 测试、npm run build:prod、后端 Maven 测试、真实数据库迁移校验、git diff --check，以及浏览器控制台无应用级错误；测试断言外部行为和业务契约。
采用现有燃气、窨井工单处置模块作为视觉和处置交互先例。
图片验收除页面展示外，还需确认附件元数据中的工单关联、阶段、上传人和时间，以及历史 URL 兼容读取。

Out of Scope

不在供水系统创建或首次派发日常巡检、设备保养工单。
不修改门户、窨井和供水菜单名称及已通过验收的路由结构，除非修复本规格涉及的兼容跳转。
不实现新的按钮级权限编码；沿用后端现有权限校验，待编码明确后另行配置。
不改变报警等级的后端计算算法，只修正返回、展示和颜色表达。
不将报警记录“已处理”改造成设备报警状态，不以工单结案直接覆盖运行系统的自动清警职责。
不合并或推送执行者 worktree 的代码。

Further Notes

当前人工验收结论为：路由回归通过；设备维修派单、设备异常管理、报警管理、报警审核、报警工单处置和写操作闭环不通过；设备报警闭环通过但需继续验证多报警原因场景。
当前已知真实环境风险是同一设备存在多个报警原因时的清警复核，以及前端报警编码、设备报警状态字段映射不完整。
已确认最高层公共 seam 为真实登录态浏览器端的供水报警工单端到端业务流程。spec 发布后再重新唤醒后端和前端执行者；执行者继续使用 gpt-5.6-terra、推理强度 high，从现有隔离 worktree 工作，不得合并或推送。

2026-08-26-water-supply-alarm-work-order-acceptance-fixes.md 13 KB تاريخچه خام