pipe-ner-server/T6-water-device-handoff.md

T6 供水设备准入、台账与异常态势 · Handoff

目标

继续完成 Gogs Issue #10 / T6“供水设备准入、台账与异常态势”。当前对话已经完成后端与前端的主要实现，剩余工作集中在测试补齐、全量验证、两轴代码审查和提交。

仓库与当前状态

• 后端仓库：E:\pipe-ner-server
  • 分支：master
  • 状态：ahead 1
  • T6 相关改动已暂存，另有多处无关脏文件；不要清理或覆盖。
• 前端仓库：E:\city-life-line
  • 分支：master
  • 状态：ahead 10
  • T6 相关改动仍在工作区，尚未暂存；同样存在无关脏文件，不要清理或覆盖。

已完成的核心工作

后端

• WaterSupplyDeviceServiceImpl
  • 通过 equipmentBaseService.findByTopLevelType("供水") 统一执行供水设备准入。
  • 设备状态、在线状态、报警状态分别建模，不再互相替代。
  • 异常原因来自有效报警或维修状态。
  • 关联工单使用真实 order_no，并映射为 relatedWorkOrderNo、relatedWorkOrderStatus、relatedWorkOrderPerson。
  • 异常页只关联“未结案的故障维修工单”。
• WaterSupplyDeviceService / WaterSupplyDeviceServiceImplTest
  • 仅保留 GIS 一张图所需的 4 个方法：getDeviceTypeStatistics、getAllDeviceGisPoints、getDeviceDetail、getAbnormalDeviceGisPoints。
  • 测试收敛为仅覆盖上述 4 个 GIS 方法（类型统计、GIS 点位、详情、异常点位）。
• 设备台账管理（已收口）
  • 供水设备台账/异常/维保管理页面与 Controller（DeviceLedgerController、DeviceAbnormalController、DeviceMaintainController）已下线，统一收口至 EquipmentBaseController（/equipment-base）。
  • 台账/异常导出 DTO（WaterDeviceLedgerExportDTO、WaterDeviceAbnormalExportDTO）与导入服务（WaterDeviceLedgerImportService）已随台账管理下线删除。
  • 窨井设备关联、测点关联、状态查询及 DeviceGisController 所需的供水 GIS 查询方法保留。
• 测试数据
• 测试数据统一由 pipe-network-service/sql/water_supply_monitoring_alarm_rebuild_test_data.sql 重建（原 water_supply_device_test_data.sql 已随 #56 退役），覆盖真实供水类型 11/12/14 下的设备、正常/报警/维修/离线状态、异常原因与真实工单编号。

前端

• src/views/subSystem/waterSupply/components/WaterDevicePage.vue
  • 台账页聚焦资产信息。
  • 异常页聚焦异常态势、异常原因、处置状态、关联工单。
  • 展示设备状态、在线状态、报警状态、报警等级、异常原因、关联工单号、工单状态、接单责任人。
  • 详情使用右侧抽屉。
  • 导出改为 Blob 下载并处理 JSON 错误。
• src/utils/waterSupplyUiModel.js
  • 统一设备行归一化，明确区分 currentStatus、onlineStatus、alarmStatus、alertLevel、abnormalReason、relatedWorkOrderNo、relatedWorkOrderStatus、relatedWorkOrderPerson。
• src/api/pipeNetwork/waterSupply.js
  • 设备台账和异常设备导出接口改为 responseType: 'blob'。
• 测试
  • 更新 tests/waterSupplyUiModel.test.mjs
  • 新增 tests/waterDeviceExport.test.mjs

剩余工作

1. 补一个 relatedWorkOrderPerson 的测试，mock ISysUserService，确认多个接单人可映射为昵称并用“、”连接。
2. 后端运行：
   • mvn -q -pl zksy-system "-Dtest=WaterSupplyDeviceServiceImplTest" test
   • mvn -q test
3. 前端运行：
   • node --test tests
   • npm run build:prod
4. 按两轴完成代码审查：
   • Standards：检查是否符合 CONTEXT / ADR / 设计规范。
   • Spec：检查 T6 验收标准是否完整覆盖。
5. 只暂存 T6 相关文件，分别提交后端与前端仓库；不要推送、不要合并。

参考文档

• 交付规格：E:\pipe-ner-server\docs\superpowers\specs\2026-08-27-water-supply-subsystem-e2e-delivery.md
• 后端上下文：E:\pipe-ner-server\CONTEXT-MAP.md
• 后端领域文档：E:\pipe-ner-server\pipe-network-service\CONTEXT.md
• 前端上下文：E:\city-life-line\CONTEXT.md
• 前端设计规范：E:\city-life-line\docs\design\2026-08-22-water-supply-work-order-ui.md
• ADR：
  • E:\pipe-ner-server\pipe-network-service\docs\adr\0003-water-supply-subsystem-product-boundary.md
  • E:\pipe-ner-server\pipe-network-service\docs\adr\0004-cross-system-unified-work-order-lifecycle.md
  • E:\pipe-ner-server\pipe-network-service\docs\adr\0005-independent-frontend-backend-contract-gate.md
  • E:\pipe-ner-server\pipe-network-service\docs\adr\0006-work-order-attachment-storage.md
  • E:\pipe-ner-server\pipe-network-service\docs\adr\0007-shared-pump-station-by-type.md

环境注意事项

• 当前机器的 Windows 沙箱助手曾出现 helper_unknown_error: setup refresh had errors。
• 使用 require_escalated 可以绕过该问题并正常执行命令。
• 若再次遇到沙箱初始化失败，优先对命令使用提权执行，而不是清理工作区。

Suggested skills

• implement
• tdd
• code-review
• verification-before-completion