# 管网业务服务

该上下文承载“城市地下管网及设施建设改造智能化系统项目”软件平台中“地下管网管控平台”的管网业务。当前交付边界聚焦供水子系统“供水管网安全运行监测系统”，覆盖供水设施、监测设备、运行监测、监测报警和工单处置；供水前端与管理端后端共同构成该子系统的完整业务体验。

## Product Boundary

**供水管网安全运行监测系统**：地下管网管控平台中的供水业务子系统，覆盖首页、供水设施管理、监测设备管理、运行监测、监测报警及其关联的查询、统计、GIS、报警和工单操作。
_Avoid_：把供水子系统等同于单一的报警页面，或把监测设备等同于供水设施

## 供水子系统功能需求结构

以下结构描述供水管网安全运行监测系统的业务能力边界，并与已确认的菜单层级保持一致。供水系统的设备台账、异常、监测和工单页面只处理设备类型树判定为“供水”的对象；设备类型未知或未归属时不得静默归入供水。

清单、查询和统计页面不各自嵌入 GIS 联动定位；设施、监测设备和报警的定位与空间详情分别集中在本组的 GIS 一张图中。批量导出属于各清单或统计能力的一部分，但不改变 GIS 集中承载规则。

### 1. 供水设施管理

1.1 **管网信息查询**：清单化展示供水管线和管点，支持按管材、管径、建设年代、所属区域及关键字进行多条件查询和批量导出。

1.2 **水厂信息查询**：提供水厂信息的关键字和分类查询，以及批量导出。

1.3 **泵站信息查询**：提供泵站信息的分类查询和批量导出。

1.4 **水源地信息查询**：提供水源地信息的分类查询和批量导出。

1.5 **用水户信息查询**：面向居民、工业、商业、行政事业等全部用水户，提供多维分类查询和批量导出。

1.6 **管网数据统计分析**：对供水管网数据进行多维统计分析，以柱状图、饼图、表格等形式展示，并支持结果下载导出。

1.7 **供水设施 GIS 一张图**：在同一地图中展示水源地、水厂、泵站、供水管线和用水户，支持设施搜索、定位和详情查看；本功能范围不包含消火栓。

### 2. 监测设备管理

2.1 **设备台账管理**：对供水监测设备进行台账化管理，提供分类统计、查询和批量导出。

2.2 **设备异常管理**：集中展示当前运行异常的供水监测设备，提供异常分类查询、设备状态跟踪和批量导出；本页面为只读状态看板，不承载工单创建或派发。

2.3 **设备维修派单**：作为进入统一工单页的业务入口，面向已判定运行故障的供水监测设备创建故障维修工单；普通手动建单不限制同设备的工单数量，具体派单与处置由统一工单页承载。

2.4 **设备维修记录**：管理设备历史维修记录，支持多维查询、修改、删除、批量导入和批量导出。

2.5 **监测设备 GIS 一张图**：在地图中展示各类供水监测设备及其监测点位，支持设备搜索、定位和详情查看。

### 3. 运行监测

3.1 **流量监测**：接入既有流量计监测数据，清单化展示流量监测点位，支持多条件查询和批量导出。

3.2 **压力监测**：接入既有压力计监测数据，清单化展示压力监测点位，支持多条件查询和批量导出。

3.3 **漏失监测**：接入新建漏失声波监测数据，清单化展示漏失监测点位，支持多条件查询和批量导出。

### 4. 监测报警

4.1 **报警管理**：供水报警管理是供水专属的只读报警流水、四级趋势和态势台账；排水保留公共报警清单。报警展示状态由后端结合报警记录及关联工单推导，设备报警状态来自设备状态表，两者与工单处置状态分别展示；按菜单 `rootTypeId` 校验授权并过滤设备类型树。审核、派发和处置仍在相应页面。排水另有 `remind` 提醒、`drainage/analysis` 研判、`drainage/alarmGIS` GIS（无周边环境页签）。供水专属页面恢复态势、分类占比和导出能力；供水监测报警一张图继续保留。不同报警类型可形成不同工单；同一设备同一报警类型同时只能存在一个未结束的同类报警工单（2026-09-24）。

4.2 **报警审核**：四个子系统统一使用 `AlarmController` 的审核接口和 `subSystem/alarm/common/audit` 页面，列表仅展示 `alarm_status=0` 的事件。`audit_status` 独立记录未审核、确认报警、误报警；确认报警时创建待派单工单，误报警只记录结论，两种审核都不直接修改设备状态或报警处理状态。完整派单、接单、处理、验收由统一工单页承载。旧供水审核、直接派单和停用的解除接口已删除。报警生成、审核及处理记录在 `alarm_log`，确认记录直接包含“已转工单（实际工单号）”及选填意见；关联工单、工单操作不再单独写入报警日志。人工操作使用 `sys_user.nick_name`，历史按时间和日志 ID 倒序展示，不回填或删除历史数据。运行采集系统在收到有效恢复数据时，可以自动处理同设备、同报警编码的未处理告警；数值回到预警区即可处理，处理记录注明“系统自动”，不自动完成关联工单（见仓库docs/collection-alarm-recovery-2026-09-23.md）。

4.3 **阈值管理**：支持按传感器分类批量设置阈值、设置分时阈值并查询已配置点位的阈值详情。

4.4 **监测报警一张图**：在地图中只展示供水异常相关点位，同一设备聚合为一个点位；主图标按正常、报警、预警、关联工单和离线状态展示，报警等级作为详情或辅助信息展示，支持异常搜索、定位和详情查看。

供水首页工作台的报警态势通过统一 `GET /api/alarm/dashboard` 查询，保留报警总数、报警中设备、近 N 天分级趋势和分类占比；使用获授权设备类型树及 `alarm:operations:list` 权限，供水传 `rootTypeId=1`，不恢复已删除的旧台账 dashboard 接口。统计由数据库全量聚合，报警中设备按设备状态去重，只有趋势限制自然日范围（2026-09-24 首页导入错误修复）。

### 移动端接口分层

移动端专用 Controller 统一放在 `zksy-admin` 的 `com.zksy.web.controller.mobile` 包，当前包含工单、巡检、设备、故障通知、公告、本人登录日志和通讯录七类入口。PC Controller 不再承载这些移动端专用方法。URL 统一采用 `/api/mobile/...`，工单与巡检位于 `/api/mobile/ops/...`；移动端调用同步迁移，请求参数和响应结构保持不变。

两端复用现有业务 Service，移动端数据范围也在 Service 校验，不复制 PC 业务流程。报警查询、公司范围和审核分别归入 `AlarmOperationsService`、`AlarmReviewScopeService`、`AlarmReviewService`，不单设 `MobileAlarmService`。登录、验证码、资料、通用上传及工单处置等两端共用入口继续保留原 Controller，避免重复路由。此次需同步更新管理后端和移动端，PC 无需改动，无数据库变更；详见 [ADR-0011](docs/adr/0011-mobile-controllers-shared-services.md)（2026-10-14）。

### 移动端故障通知

移动端通过 `/api/mobile/alarm` 查询故障通知；读取要求登录，公司范围由当前部门自身及 ancestors 中的 101/102/103 映射为设备类型直接 parent_id=1/2/3。范围不含共享类型4、不递归扩展，也不因管理员身份放宽；可选 rootTypeId 仅能进一步收窄。已转工单的事件按 work_order.device_id 取设备，无工单事件按报警 device_code 取设备；损坏的工单关联不回退到设备编码。列表固定未处理事件，详情、日志、审核及附件上传共用公司范围校验。审核与上传保留 alarm:review:audit 权限，复用 PC 原审核事务及附件票据；确认报警转待派单工单，误报只记结论。移动端“处置全流程”沿用报警日志，不复制关联工单日志。无需数据库结构变更（2026-10-14）。

### 工单视图分工

统一工单视图集中检索和处置所有供水类型工单，覆盖故障维修、日常巡检和设备保养三类业务；报警审核视图只承载由报警转入的故障维修工单。巡检或保养工单即使由其他系统派发给供水用户，仍可在统一工单视图中继续接单、处理和验收。

## 供水 GIS

**供水 GIS 一张图**：
供水子系统内统一空间视图能力的统称，包含供水设施 GIS 一张图、监测设备 GIS 一张图和监测报警一张图。三张图使用同一地图交互框架，但数据边界、图层语义和详情内容不同。
_Avoid_：把三张图混成同一数据集，或在清单页面重复实现 GIS 联动

**GIS 点位**：
地图上可定位、搜索、展示详情的业务要素。它可能是供水设施、监测设备所在位置或报警事件，不是所有对象的统称。
_Avoid_：监测点（指供水设施时）、供水设施（指监测设备时）

**GIS 主图标语义**：
供水设施图的主图标表示设施类型；监测设备图和报警图的主图标表示点位当前运行或处置状态，分为正常、报警、预警、有关联工单和离线。报警等级只作为辅助信息展示，不决定监测点位主图标状态。
_Avoid_：用报警记录状态或工单状态替代设备报警状态，用报警等级替代点位状态语义

## 供水设施

**供水设施**：
构成供水系统并被登记、查询、统计或在地图上展示的业务对象，包括水源地、水厂、泵站、供水管线和用水户；水厂、泵站等是设施，不是监测设备。
_Avoid_：把监测设备统称为供水设施

**水源地**：
为供水系统提供原水的来源地。
_Avoid_：水源、水源点

**水厂**：
对原水进行处理并形成可供给用水户水量的生产设施。
_Avoid_：供水厂、制水厂

**泵站**：
通过水泵为输水过程提供输送或增压能力的设施。泵站为供水/排水共用对象，物理表 `app_user.pump_station`（由 `water_pump_station` 迁移改名）以 `station_type` 区分：`water_supply`=供水泵站、`drainage`=排水泵站；各系统只读写本系统类型的行，类型由后端按入口强制写入（ADR-0007）。
_Avoid_：加压站
_规则_：查询、统计、GIS、回收站与导入导出必须带 `station_type` 归属条件；禁止出现"一张泵站表两个系统共用却不过滤"的查询。

**供水管线**：
连接供水设施并输送水的线性设施。
_Avoid_：管网、管道（指单条设施时）

**管点**：
供水管线上的节点或点状设施，作为管网查询、统计和空间展示的独立业务对象。
_Avoid_：监测点（指监测设备所在位置时）

**用水户**：
接受供水服务的居民、工业、商业或行政事业主体。
_Avoid_：大用水户（除非明确指满足特定用水量或重要性标准的子集）、用户

兼容映射：既有设施类型编码 `user`、接口区块 `waterUser`、Java 类型 `WaterUserInfo`、
持久化表 `water_user_info` 及其 `user_*` 字段均表示“用水户”，覆盖居民、工业、商业和
行政事业等全部类型。为保持现有接口与数据兼容，这些技术标识继续保留，不表示“大用水户”子集。

**契约缺口**：
当前五类供水设施实体、查询服务签名和 KingbaseES DDL 均未定义 `region`/所属区域字段；在字段和数据来源确认前，不得为区域筛选臆造数据库列或查询条件。区域筛选需另行完成 REST、模型和数据库契约评审。

## 运行监测

**驾驶舱事件等级展示颜色**：
面向城市生命线驾驶舱的预警/报警事件展示统一使用 1 级红色、2 级黄色、3 级蓝色、4 级绿色；该展示约定不改变后端等级数值的业务含义，也不等同于监测点主图标的正常/预警/报警/工单/离线状态色。
_Avoid_：将历史预警颜色配置直接当作驾驶舱点位状态色

**驾驶舱地图摘要接口**：
面向 UE/大屏只读展示的分页接口，返回监测点、关联设备摘要和未关联设备摘要，以及后端解析后的点位状态、原因、统计、新鲜度和快照时间。专用接口 JSON 字段统一使用驼峰命名，包括 `deviceCode`、`pointCode`、`pointStatus` 和 `snapshotAt`。默认分页大小为 500，最大 1000；UE 不通过拼接管理接口自行计算点位状态。

**驾驶舱设备详情聚合接口**：
按数据库设备编码 `equipment_base.equipment_code` 查询并以 `deviceCode` 返回设备基础档案、类别、当前状态、最新监测数据、预警、报警、工单当前状态、工单状态时间线和最新设备图片的只读接口。内部可以联查多张表，但对 UE 暴露稳定聚合契约。

**驾驶舱监测点详情聚合接口**：
按 `point_code` 返回监测点基础信息、坐标校验、所属管网、点位状态、关联设备摘要及关联异常说明的只读接口。管理端监测点接口不自动等同于驾驶舱契约。

**监测设备**：
用于采集供水运行数据的带传感器智能设备，例如水位、压力或流量监测设备；带传感器的井盖也属于监测设备。它与被监测的供水设施是不同业务对象。
_Avoid_：供水设施、监测点（指设备本身时）

**设备编码**：
平台内监测设备的唯一业务标识，格式为“区域-类型-YYYYMMDD+4位流水号”。区域取 CN/CB/TC，业务类型取 RQ/GS/PS/YJ，排水可再细分为 YS/WS；例如 CN-GS-202609020001、TC-PS-YS-202609020012。设备编码用于跨系统定位设备，不承载设备当前状态或报警语义。
_Avoid_：数据库主键、报警编号、工单编号

**设备异常**：
监测设备当前处于报警、维修或离线状态的统称；可由一个或多个报警记录、处置过程或心跳丢失造成。
_Avoid_：报警记录（指一次事件时）、故障（原因尚未确认时）

**设备报警状态**：
表示监测设备当前是否处于报警中的设备级状态；`0` 表示正常，`1` 表示报警，是判断设备当前是否报警的主要依据，由运行系统根据设备的有效报警原因自动维护。
_Avoid_：报警记录状态、工单状态

**有效报警原因**：
当前仍满足报警条件、尚未自行恢复的设备异常原因；同一设备可以同时存在多个有效报警原因。
_Avoid_：报警记录、未结工单

**报警记录**：
设备因阈值越界或其他自动报警原因而产生的一次事件记录，用于保留报警事实和历史，不作为设备当前是否报警的主要依据。
_Avoid_：设备报警状态、设备异常

**报警运营筛选**：
报警提醒固定只查询 `alarm_status=0`，清单可查询历史已处理事件。GIS 监测曲线选项和研判候选事件要求 `actual_value IS NOT NULL`，数值 0 有效；此限制不影响 GIS 点位和报警记录。研判使用 `actualValueOnly=true` 在后端分页前过滤，默认 false 保持一般查询不变，无实际值事件不读取采集曲线。
_Avoid_：用有无实际值判断报警是否存在、把数值 0 当作空值

**报警单号**：
`alarm_data.alarm_no` 是报警事件的唯一业务号码，新建时由管理端或采集端程序生成，格式为 `BJyyyyMMddHHmmss` 加 4 位随机数（0000～9999），北京时间，总长 20 位。两端使用同一数据库事务锁保护取号、查重与入库，碰撞重试最多 100 次，唯一索引兜底；覆盖请求传入的号码，普通更新不改号，不回填历史。不使用单号生成触发器、默认值或序列。`alarm_data.alarm_content` 在新增时按 `warning_code` 关联的指标名称和触发值/上下限固化：触及下限追加“达到或低于下限”，触及上限追加“达到或超过上限”，否则只存指标名称；`remark` 列及两套 `AlarmData` 实体的 `remark`、`warningName` 属性均已删除，写入端不再通过报警对象传递指标名称。清单首列和报警转工单的创建日志使用该号，UUID 仅用于内部关联。新增、自动恢复和人工处理由业务代码在同一事务中主动写 `alarm_log`，不依赖任何自定义数据库函数或触发器；工单操作仅写 `work_order_log`，脚本删除旧日志镜像触发器及函数。`zksy-system` 与 `zk-api-service` 各保留一份 `AlarmLogOperTypeEnum`，不新增共享模块，两端值一致：0 报警触发、1 确认报警、2 误报警、3 报警处理，删除关联工单及工单操作类型。新增记录“系统触发报警”及已固化的报警内容，恢复时记录“监测恢复，报警自动解除”；重复恢复不重复记录，日志写入失败则报警变更一同回滚，自动恢复不关闭工单。
_Avoid_：报警主键、报警类型编码、工单号

**报警展示状态**：
由报警持久化状态、审核结果和关联工单推导出的面向用户的状态，用于区分待审核、已转工单、已解除和误报警；它不替代设备报警状态，误报警不代表监测数据已恢复。
_Avoid_：报警记录持久化状态、设备报警状态

**报警记录状态**：
表示单条报警记录是否已经人工处置的辅助状态；它不决定设备当前是否处于报警中。
_Avoid_：设备报警状态

**报警恢复**：
某个有效报警原因不再满足报警条件的结果，可由实时监测数据、上游恢复事件或有权限人员的人工确认产生。
_Avoid_：报警记录已处理、工单结案

**清警复核**：
汇总检查设备是否仍有有效报警原因的活动；报警恢复或工单结案可以触发复核，但只有不存在有效报警原因时才允许清警。
_Avoid_：直接清警、工单验收

**自动清警**：
运行系统确认设备的所有有效报警原因均已消除后，将设备报警状态从报警恢复为正常；任一报警原因仍有效时不得清警。本能力当前尚未实现：报警审核的误报解除与工单结案都不会清除设备报警状态，误报解除后设备会停留在报警中，属已知缺口（跟踪单 #51）；不得用审核动作或工单动作临时顶替清警。
_Avoid_：工单结案、报警记录已处理

**报警转工单**：
报警记录进入工单处置流程时生成待派单的故障维修工单，生成时不指定接单责任人；后续派发和处置由工单流程完成。
_Avoid_：报警派单、报警处理

## 驾驶舱术语（2026-09-24 重新确认）

**设备类型**：
设备台账所属的层级类别；根类别区分供水、排水、燃气、窨井等业务归属，子类别区分具体监测设备。当前驾驶舱对外 `typeCode` 使用该类型的 ID；展示名称不是编码。
_Avoid_：把类型名称或历史 slug 当作 `typeCode`

**设备业务编码**：
设备面向跨系统查询的唯一标识；与数据库内部主键不同。驾驶舱对外使用 `deviceCode`，即使工单等内部关系由设备主键维护，也不改变对外标识。
_Avoid_：把工单主键、设备主键或事件编号当作设备业务编码

**报警与工单关联**：
报警记录进入处置流程后指向关联工单；工单同时指向设备。预警与报警仍是不同事件家族，预警需先通过其关联的报警才能推导工单，不能用事件名称或时间猜测。
_Avoid_：从工单标题、报警时间或旧的工单设备编码字段反推关系

**驾驶舱工单关联**：
驾驶舱按报警与工单的一对一关系呈现关联事实；多个报警引用同一工单属于关联数据异常，不能任意选取一条充当主报警。未关联报警的工单仍是有效工单，须明确呈现未关联。
_Avoid_：从多个关联报警中默认取首条、用缺少事件查询语境推断未关联

**正式行业**：
驾驶舱筛选与统计使用供水、排水、燃气、井盖四类；井盖在当前设备类型树中是独立根类型，不应静默归入排水。
_Avoid_：把井盖当作排水子类或非正式行业

**可上图坐标**：
已由可信来源完成校核，且坐标自身有效的空间数据。仅有经纬度数值、或仅落在通用经纬度范围内，不等于业务坐标已校核。
_Avoid_：以“有坐标”或“数值未越界”代替已校核

**驾驶舱已接线**：
在当前领域模型下，真实数据适配器可编译、装配并通过当前真实库联调，且满足只读契约；仅有历史代码、mock 测试或过期数据探查不构成已接线。
_Avoid_：把历史“4/22”尝试记录当成当前可验收进度


## 工单处置

**工单**：
对设备故障、日常巡检或设备保养进行分派、执行和跟踪的跨系统统一处置载体；供水、排水、燃气、窨井等系统通过关联设备类型区分业务归属，共享工单生命周期。
_Avoid_：维修任务、报警工单（作为独立于工单的概念）

**工单处置状态**：
表示统一工单当前所处的待派单、待接单、已接单、处理中、待验收、已结案、延期中或已取消阶段；终态仅已结案与已取消，延期中是处理旁路状态。
_Avoid_：设备报警状态、报警记录状态、已驳回状态

**工单系统归属**：
工单所属系统由关联设备的设备类型树确定，而不是由前端页面名称或单独的“报警工单”概念确定；未知或未归属设备不得被静默归入某个系统。
_Avoid_：用页面入口、工单标题或报警记录状态推断系统归属

**故障维修工单**：
用于核实并修复设备故障的工单；由设备维修需求或监测报警转入的处置都属于此类型。工单流程重构后 `work_order` 不再保留 `order_type` 列，报警转入的故障维修工单以 `alarm_data.work_order_id → work_order.order_id` 关联识别，不得再新增或回滚该列。
_Avoid_：维修任务、报警工单

**同类报警工单**：
同一设备主键针对同一 `alarm_data.warning_code` 建立的故障维修工单，通过 `alarm_data.work_order_id` 关联；同设备同编码同时只能存在一个未办结工单（0/1/2/3/4/6），已结案和已取消不占名额。报警恢复不代表关联工单办结，不同编码可分别建单，普通手动建单及隐患转工单不受此限制。报警编码缺失时阻止报警转工单，不以报警名称替代（2026-09-24）。
_Avoid_：同一报警记录、同设备全部工单

**工单派发**：
在统一工单页中为待派单工单指定唯一接单责任人的活动；报警审核只生成待派单工单，设备异常管理和报警管理不直接派发。
_Avoid_：报警处理、报警审核

**工单处置**：
被派单人员对工单执行接收、处理、提交验收和结案等后续活动；工单进度不直接决定设备报警状态，也不阻止设备满足恢复条件时自动清警。
_Avoid_：报警审核（指工单后续操作时）、报警记录已处理

**工单验收**：
对工单处置结果是否满足要求进行确认的活动；验收通过可以使工单结案，但不直接清除设备报警状态。
_Avoid_：报警审核、自动清警

**工单处置证据**：
与工单处置阶段关联的说明和图片，至少区分处理前与处置后，用于责任人处理、验收审核和历史追溯。
_Avoid_：把处置证据等同于报警记录状态或设备当前状态

**随同修复**：
一次故障维修同时消除了同一设备其他有效报警原因的处置结果；设备是否清警仍由运行系统复核有效报警原因决定，相关工单记录继续保留并按各自流程验收结案。
_Avoid_：自动结案、重复维修

**日常巡检工单**：
用于执行计划内或临时巡查的工单；由其他系统派发给供水用户，供水侧不做类型落库。
_Avoid_：巡检任务

**设备保养工单**：
用于执行设备预防性保养的工单；由其他系统派发给供水用户，供水侧不做类型落库。
_Avoid_：保养任务、维修工单