水务云平台产品与微服务架构设计：从传统 Spring MVC 系统到智慧水务平台

1. 设计背景

很多水务系统并不是从零开始建设的，而是从已有的燃气云、营业收费系统或远程抄表系统改造而来。这种改造方式能快速复用客户、账务、表具、抄表、支付等基础能力，但也会带来明显问题：

代码和表结构中残留大量燃气命名。
业务模型里混杂燃气、水务、通用表计能力。
水表特有的漏水、倒流、滴漏、空管、DMA 分区等能力不够突出。
设备协议、前置机通信、业务账务耦合较重。
客户化功能散落在主工程中。
报表和统计直接依赖业务明细表，维护和性能压力较大。

因此，新的水务云平台设计不应只是"把 Gas 改成 Water"，而应该重新抽象水务业务模型。

核心目标是：

text 复制代码

以水务运营为中心，统一客户、计量点、水表、抄表、计费、阀控、报警、工单和报表模型。

2. 水务云平台产品定位

水务云平台可以定位为：

text 复制代码

面向水司的客户服务、远传抄表、计费收费、设备运维、漏损诊断和经营分析一体化平台。

主要服务对象：

用户角色	核心诉求
水司管理人员	经营统计、收费分析、欠费分析、漏损治理、设备状态
营业人员	开户、缴费、过户、退款、客户查询、票据打印
抄表人员	抄表计划、人工补抄、异常读数处理
运维人员	装表、换表、阀控、报警处理、工单闭环
客户用户	查询账单、在线缴费、用水分析、报修、通知
第三方系统	支付、银行、监管、营业系统、厂商平台集成

水务云平台应形成以下核心闭环：

客户闭环。
计量点闭环。
水表资产闭环。
远程抄表闭环。
计费账务闭环。
支付对账闭环。
阀控命令闭环。
报警诊断工单闭环。
报表分析闭环。

3. 现有系统能力抽象

传统水务云老系统通常采用：

text 复制代码

Tomcat + Spring MVC + JSP + MyBatis + MySQL

工程形态常见为：

text 复制代码

管理端 WAR
后台服务 WAR
DAO 模块
Entity 模块
Tools 模块
前置机服务

管理端负责：

页面管理。
菜单权限。
客户管理。
表具资产。
抄表计划。
阀控任务。
报表查询。
报警诊断。
工单处理。

后台服务负责：

移动端 API。
前置机 API。
计费服务。
消息监听。
水表上报处理。
命令下发。
命令重发。
支付回调。
银行文件处理。

前置机负责：

水表上报接入。
协议解析。
MQTT/Socket/UDP/HTTP 等通信。
命令下发。
回执转发。
与业务系统通过 MQ 或接口交互。

这些能力是新平台可以继承的业务资产，但服务边界需要重新设计。

4. 水务云微服务总体架构

建议采用如下微服务体系：

text 复制代码

Web 管理端 / 移动端 / 第三方系统 / 银行 / 支付渠道
        |
API 网关
        |
认证权限服务
        |
业务微服务层
        |
消息队列 / Redis / 数据库 / 文件服务 / 调度平台 / 日志监控
        |
水表前置机 / 网关 / 集中器 / 厂商平台 / 监管平台

微服务分层：

text 复制代码

接入层：
  - API 网关
  - 水表前置机服务
  - 开放集成网关

业务层：
  - 系统基础服务
  - 客户合同服务
  - 计量点服务
  - 水表资产服务
  - 抄表采集服务
  - 命令控制服务
  - 计费账务服务
  - 支付对账服务
  - 水务报警诊断服务
  - 工单运维服务
  - 报表分析服务
  - 移动端服务
  - 消息通知服务

基础层：
  - 配置中心
  - 注册中心
  - 调度中心
  - 文件服务
  - 日志中心
  - 监控告警
  - 数据库
  - Redis
  - MQ

5. 微服务拆分设计

5.1 API 网关服务

职责：

统一入口。
Token 校验。
接口签名。
租户识别。
限流。
黑白名单。
路由转发。
请求审计。
防重放。

网关不处理水务业务，只做接入和治理。

典型路由：

text 复制代码

/admin/**
/app/**
/openapi/**
/device/**
/payment/**

5.2 认证与权限服务

职责：

用户登录。
角色管理。
菜单权限。
按钮权限。
API 权限。
数据权限。
操作审计。

核心模型：

text 复制代码

Tenant 租户
Organization 组织
Region 区域
User 用户
Role 角色
Permission 权限
DataScope 数据权限
AuditLog 审计日志

数据权限需要支持：

总公司。
分公司。
营业所。
区域。
小区。
抄表册。
客户组。

5.3 系统基础服务

职责：

字典。
参数。
菜单。
区域。
小区。
多语言。
文件模板。
打印模板。
任务配置。
操作日志。

水务平台常用字典：

客户类型。
水表类型。
水表口径。
阀门状态。
抄表方式。
计费方式。
支付渠道。
报警等级。
工单状态。

5.4 客户合同服务

职责：

客户档案。
联系人。
合同/户号。
服务地址。
开户。
过户。
销户。
停复用。
客户导入。
客户分群。

核心模型：

text 复制代码

Customer 客户
Contract 合同/户号
CustomerContact 联系人
ServiceAddress 服务地址
CustomerGroup 客户组
CustomerOperationRecord 客户业务记录

建议模型：

text 复制代码

客户 -> 合同/户号 -> 服务地址 -> 计量点 -> 水表

不要把客户、户号、地址、水表全部混在一个对象里。

5.5 计量点服务

计量点是水务云平台的核心业务对象。

职责：

计量点创建。
计量点维护。
计量点与客户/合同绑定。
计量点与水表绑定。
计量点状态管理。
计费方式绑定。
价格方案绑定。
抄表周期绑定。

核心模型：

text 复制代码

MeasuringPoint 计量点
MeasuringPointBinding 绑定关系
MeasuringPointStatus 状态
MeasuringPointBusinessRecord 业务记录

计量点字段建议：

text 复制代码

计量点编号
合同/户号
服务地址
水务类型
价格方案
计费方式
抄表周期
账户
当前绑定水表
状态
启用时间
停用时间

换表、销户、停用时，计量点可以保持不变，只变更绑定关系和状态。

5.6 水表资产服务

职责：

水表档案。
水表安装。
水表更换。
水表拆除。
水表导入。
集中器管理。
中继器管理。
网关管理。
SIM 卡管理。
设备关系。
设备参数。
密钥管理。
固件升级。
设备在线状态。

核心模型：

text 复制代码

Device 设备主档
WaterMeter 水表扩展
Gateway 网关/集中器
Repeater 中继器
SimCard SIM 卡
DeviceRelation 设备关系
DeviceParameter 设备参数
DeviceKey 设备密钥
DeviceLifecycle 生命周期

设备类型：

text 复制代码

WATER_METER
GATEWAY
CONCENTRATOR
REPEATER
SIM
PRESSURE_SENSOR
FLOW_SENSOR
VALVE_CONTROLLER

5.7 水表前置机服务

水表前置机是设备侧和业务侧之间的通信桥梁。

职责：

接入水表、集中器、网关。
支持 MQTT、UDP、TCP、HTTP 等协议。
接收上行报文。
处理分包、组包、校验。
调用协议引擎解析。
将标准数据投递给业务系统。
接收业务系统命令。
组包并下发设备。
回传命令结果。

典型链路：

text 复制代码

水表/集中器/网关
  -> 前置机
  -> 原始报文
  -> 协议解析
  -> MQ/接口
  -> 抄表采集服务

命令下行链路：

text 复制代码

命令控制服务
  -> MQ/接口
  -> 前置机
  -> 协议组包
  -> 水表/集中器/网关
  -> 回执
  -> 命令结果

5.8 协议适配服务

职责：

水表协议解析。
实时报文解析。
日冻结解析。
月冻结解析。
故障报文解析。
命令报文组包。
命令回执解析。
协议版本管理。

协议插件接口示例：

java 复制代码

public interface WaterMeterProtocol {

    String protocolCode();

    ParseResult parseUpstream(RawMessage message);

    EncodedCommand encodeCommand(CommandTask command);

    CommandResult parseCommandResult(RawMessage message);
}

设计原则：

协议插件不处理客户和账务。
协议插件只做编解码。
前置机只负责通道收发。
业务系统只处理标准模型。
原始报文必须保存。

5.9 抄表采集服务

职责：

抄表册。
抄表计划。
抄表任务。
远程抄表。
人工抄表。
估抄。
补抄。
读数校验。
实时读数。
冻结读数。
抄表成功率。
上报日志。

核心模型：

text 复制代码

MeterBook 抄表册
ReadingPlan 抄表计划
ReadingTask 抄表任务
MeterReading 标准读数
FrozenReading 冻结读数
ReadingValidation 读数校验
ReadingPublishRecord 发布记录
ReadingSuccessStat 成功率统计

读数类型：

text 复制代码

REALTIME
DAILY_FROZEN
MONTHLY_FROZEN
MANUAL
ESTIMATED
BILLING

远程抄表流程：

text 复制代码

创建计划
  -> 分解任务
  -> 生成表具清单
  -> 下发抄表命令
  -> 接收上报/回执
  -> 解析读数
  -> 校验异常
  -> 发布读数
  -> 统计成功率

5.10 水务报警诊断服务

这是水务云区别于普通抄表系统的重点。

职责：

水表报警。
异常诊断。
漏水识别。
倒流识别。
滴漏识别。
空管识别。
长时间未上报。
阀门异常。
电池低压。
通讯异常。
自动生成工单。
异常统计。

水务异常分类：

分类	异常
设备类	低电压、阀门异常、存储故障、通讯模块异常、开盖
计量类	倒流、持续流、滴漏、大流量、小流量、表码异常
环境类	空管、压力异常、温度异常、磁干扰
通讯类	连续未上报、上报失败、网关离线
业务类	透支、零额、少额、欠费关阀

诊断链路：

text 复制代码

设备事件/读数异常
  -> 诊断规则匹配
  -> 生成诊断案例
  -> 确定严重等级
  -> 推送通知
  -> 生成工单
  -> 处理闭环

诊断规则建议配置化：

text 复制代码

规则编码
规则名称
异常类型
时间窗口
触发次数
阈值
严重等级
是否自动工单
通知策略

5.11 命令控制服务

职责：

开阀。
关阀。
读表。
读参。
设参。
调价。
校时。
密钥更新。
固件升级。
命令撤销。
命令重发。
命令审计。

命令状态：

text 复制代码

CREATED
WAITING_SEND
SENDING
SENT
FRONT_ACCEPTED
DEVICE_RECEIVED
SUCCESS
FAILED
TIMEOUT
CANCELLED
MANUAL_REQUIRED

命令闭环：

text 复制代码

业务触发
  -> 权限校验
  -> 风险校验
  -> 创建命令
  -> 协议组包
  -> 前置机下发
  -> 设备回执
  -> 结果解析
  -> 状态回写
  -> 失败补偿
  -> 审计留痕

水务命令必须重点审计：

关阀。
批量关阀。
调价。
远程充值。
密钥更新。
固件升级。

5.12 计费账务服务

职责：

价格方案。
阶梯水价。
水费计算。
污水处理费。
垃圾费。
其他附加费。
账户管理。
账户流水。
账单。
账单明细。
欠费管理。
退款。
冲正。
预付费扣款。
后付费核销。

核心模型：

text 复制代码

PricePlan 价格方案
PriceTier 阶梯价格
Account 账户
AccountLedger 账户流水
Bill 账单
BillDetail 账单明细
Receivable 应收
PaymentRecord 收款
RefundOrder 退款
AdjustmentOrder 调账

计费流程：

text 复制代码

读数产生
  -> 读数校验
  -> 计算本期用量
  -> 匹配价格方案
  -> 计算阶梯水费
  -> 计算附加费用
  -> 生成账单
  -> 预付费扣款或后付费待缴
  -> 写账户流水
  -> 账单核销

水务费用项可以包括：

基础水费。
阶梯水费。
污水处理费。
垃圾费。
滞纳金。
违约金。
优惠减免。
其他代收费。

5.13 支付对账服务

职责：

支付订单。
渠道订单。
APP 支付。
微信支付。
支付宝支付。
银行代扣。
线下收费。
支付回调。
对账文件。
长短款处理。
退款。
补单。

支付模型：

text 复制代码

PaymentOrder 平台支付订单
ChannelOrder 渠道订单
PaymentCallback 支付回调
RechargeRecord 充值记录
ReconciliationBatch 对账批次
ReconciliationDetail 对账明细
RefundOrder 退款单

对账流程：

text 复制代码

下载渠道账单
  -> 解析文件
  -> 匹配平台订单
  -> 校验金额、状态、时间、户号
  -> 标记平账/长款/短款/状态不一致
  -> 自动补单/退款/人工处理
  -> 生成对账报表

5.14 工单运维服务

职责：

报修工单。
漏水工单。
换表工单。
安装工单。
阀控工单。
异常处理工单。
派工。
处理记录。
回访。
关闭。

工单来源：

客户报修。
水表报警。
诊断规则。
人工创建。
巡检任务。
批量安装任务。

工单流程：

text 复制代码

工单创建
  -> 派发
  -> 接单
  -> 现场处理
  -> 上传照片/读数/说明
  -> 审核
  -> 关闭
  -> 回访

5.15 移动端服务

职责：

用户注册。
登录。
短信验证码。
绑定户号。
查询余额。
查询账单。
在线缴费。
查询缴费记录。
用水分析。
报修。
消息通知。
工单进度。

移动端用户与营业客户需要分离：

text 复制代码

AppUser -> CustomerBinding -> Customer/Contract

一个 APP 用户可以绑定多个户号，一个户号也可以允许多个用户查看，具体由业务规则控制。

5.16 报表分析服务

职责：

日用水量。
月用水量。
区域用水量。
收费报表。
欠费报表。
抄表成功率。
设备在线率。
报警统计。
漏损分析。
工单统计。
经营看板。

报表不建议直接查业务大表。

推荐三层：

text 复制代码

明细层 -> 汇总层 -> 展示层

汇总指标：

text 复制代码

stat_daily_usage
stat_monthly_usage
stat_payment_daily
stat_arrearage
stat_meter_alarm
stat_read_success_rate
stat_device_online
stat_work_order

5.17 开放集成服务

职责：

营业系统接口。
支付平台接口。
银行文件接口。
监管平台接口。
厂商平台接口。
前置机接口。
第三方查询接口。

统一能力：

签名验签。
报文转换。
幂等控制。
限流。
熔断。
重试。
接口日志。
错误码映射。

对外接口建议统一走开放网关，不让第三方直接调用核心服务。

6. 水务核心数据模型

6.1 主数据模型

text 复制代码

Tenant 租户
Organization 组织
Region 区域
Customer 客户
Contract 合同/户号
ServiceAddress 服务地址
MeasuringPoint 计量点
WaterMeter 水表
Account 账户
PricePlan 价格方案

核心关系：

text 复制代码

租户 -> 组织 -> 区域 -> 客户 -> 合同/户号 -> 服务地址 -> 计量点 -> 水表

6.2 水表采集模型

text 复制代码

RawMessage 原始报文
ParseResult 解析结果
MeterReading 标准读数
FrozenReading 冻结读数
DeviceEvent 设备事件
DeviceAlarm 告警
DeviceLog 日志
DeviceSnapshot 设备状态快照

6.3 命令控制模型

text 复制代码

CommandTask 命令任务
CommandTarget 命令目标
CommandPayload 命令报文
CommandDispatchLog 下发日志
CommandResult 回执结果
CommandRetry 重试记录
CommandAudit 审计记录

6.4 账务支付模型

text 复制代码

Account 账户
AccountLedger 账户流水
Bill 账单
BillDetail 账单明细
PaymentOrder 支付订单
RechargeRecord 充值记录
RefundOrder 退款
ReconciliationBatch 对账批次
ReconciliationDetail 对账明细

6.5 报警工单模型

text 复制代码

AlarmEvent 报警事件
DiagnosticRule 诊断规则
DiagnosticCase 诊断案例
WorkOrder 工单
WorkOrderAction 工单处理
Notice 通知
NoticeRead 通知阅读

7. 核心业务流程设计

7.1 开户装表流程

text 复制代码

录入客户
  -> 创建合同/户号
  -> 创建服务地址
  -> 创建计量点
  -> 选择水表
  -> 绑定水表
  -> 设置价格方案
  -> 创建账户
  -> 设置预付费/后付费
  -> 下发表具参数
  -> 设备开通
  -> 生成业务凭证
  -> 写审计日志

7.2 批量安装流程

text 复制代码

导入安装模板
  -> 校验客户、地址、计量点、水表
  -> 生成批量安装任务
  -> 移动端领取任务
  -> 现场装表
  -> 上传照片和安装资料
  -> 回写安装结果
  -> 异常数据人工处理

7.3 远程抄表流程

text 复制代码

创建抄表计划
  -> 按抄表册生成任务
  -> 下发抄表命令
  -> 前置机发送
  -> 水表/集中器回执
  -> 保存原始报文
  -> 解析标准读数
  -> 读数校验
  -> 发布读数
  -> 统计成功率

7.4 水表主动上报流程

text 复制代码

水表上报
  -> 前置机接收
  -> 保存原始报文
  -> 协议解析
  -> 读数/冻结/事件入库
  -> 更新设备状态快照
  -> 触发报警诊断
  -> 必要时生成工单

7.5 计费扣费流程

text 复制代码

标准读数
  -> 获取上期读数
  -> 计算本期用量
  -> 匹配价格方案
  -> 计算阶梯水费
  -> 计算附加费用
  -> 生成账单
  -> 预付费扣款或后付费待缴
  -> 写账户流水
  -> 生成报表数据

7.6 在线缴费流程

text 复制代码

客户查询账单
  -> 创建支付订单
  -> 跳转支付渠道
  -> 支付成功回调
  -> 幂等校验
  -> 写收款记录
  -> 核销账单
  -> 更新账户
  -> 推送缴费成功通知
  -> 后续对账

7.7 阀控流程

text 复制代码

人工/欠费/策略触发
  -> 权限校验
  -> 风险校验
  -> 创建阀控命令
  -> 前置机下发
  -> 设备执行
  -> 回执解析
  -> 更新阀门状态
  -> 失败重试或人工处理
  -> 审计日志

7.8 报警诊断工单流程

text 复制代码

设备事件/读数异常
  -> 诊断规则匹配
  -> 生成诊断案例
  -> 判断严重等级
  -> 发送通知
  -> 自动或人工建工单
  -> 派工处理
  -> 回填处理结果
  -> 关闭工单
  -> 统计分析

7.9 对账流程

text 复制代码

下载银行/支付渠道账单
  -> 解析文件
  -> 匹配平台订单
  -> 校验金额、状态、户号
  -> 标记平账/长款/短款/状态不一致
  -> 自动补单或人工处理
  -> 输出对账报表

8. 水务特色能力设计

8.1 漏损分析

漏损分析可以分为两类：

用户侧漏水：单户持续小流量、夜间持续用水、滴漏。
区域侧漏损：区域总表与户表差异、DMA 分区产销差。

用户侧漏水判断：

text 复制代码

连续多个时间窗口存在小流量
夜间低峰持续有流量
用水曲线无明显归零点

区域侧漏损判断：

text 复制代码

区域总表用量 - 区域户表汇总用量 = 差额
差额 / 区域总表用量 = 漏损率

8.2 倒流识别

倒流通常来自：

安装方向错误。
管网压力变化。
表具异常。
人为拆装。

判断依据：

text 复制代码

读数回退
反向流量标志
设备上报倒流事件

8.3 滴漏识别

滴漏一般表现为：

长时间存在极小流量。
夜间仍持续流动。
用水曲线呈低幅稳定状态。

可作为水务诊断规则之一。

8.4 空管识别

空管可能表示：

管道无水。
表具安装异常。
传感器异常。
现场施工问题。

空管事件应与工单联动。

8.5 产销差分析

产销差是水务运营的重要指标。

text 复制代码

产销差 = 供水量 - 售水量
产销差率 = 产销差 / 供水量

需要结合：

总表。
分区表。
户表。
未计量水量。
管网漏损。
非法用水。
抄表误差。

9. 从燃气遗留代码中保留与剔除的能力

由于水务云可能由燃气云改造而来，需要明确哪些能力可复用，哪些应剔除或弱化。

9.1 可复用能力

客户管理。
合同/户号。
计量点。
表具资产。
抄表计划。
阀控命令。
账户账单。
支付对账。
报表分析。
移动端绑定。
权限菜单。
多语言。
任务调度。
前置机通信框架。
协议插件框架。

9.2 水务需增强能力

漏水诊断。
滴漏诊断。
倒流诊断。
空管诊断。
DMA 分区。
产销差分析。
污水处理费。
水质、压力、流量扩展。
水表上报质量分析。

9.3 应剔除或隔离的能力

燃气专属安检流程。
IC/STS 售气。
补气、退气、购气命名。
燃气 RTU 专属逻辑。
燃气价格和周期气量语义。
与水务无关的历史客户化接口。

这些能力如果未来要做"通用公用事业平台"，可以作为独立能源插件保留；如果只做水务云，应从主流程中剥离。

10. 安全与权限设计

重点控制：

远程关阀。
批量关阀。
退款。
冲正。
调价。
客户资料导出。
水表密钥更新。
设备升级。

安全能力：

用户权限。
数据权限。
API 签名。
防重放。
IP 白名单。
操作审计。
敏感信息脱敏。
重要操作二次确认或审批。

11. 非功能设计

能力	要求
可用性	前置机、MQ、支付、命令、抄表任务支持重试和补偿
性能	读数和冻结数据按时间分区，报表预汇总
扩展性	协议、支付渠道、诊断规则、客户化接口插件化
可观测	抄表链路、命令链路、支付链路、工单链路全程可追踪
安全性	远程阀控、退款、调价、导出重点审计
国际化	多语言、多时区、多币种、单位和地址格式可配置
数据治理	历史读数归档、账务不可篡改、统计口径版本化

12. 建设路线

阶段一：水务核心模型建设

客户。
合同/户号。
服务地址。
计量点。
水表。
账户。
价格方案。

阶段二：水务营业闭环

开户。
装表。
抄表。
计费。
缴费。
欠费。
票据。
报表。

阶段三：远传采集与命令闭环

前置机。
协议解析。
原始报文。
实时读数。
冻结读数。
阀控命令。
命令回执。
失败重试。

阶段四：报警诊断与工单闭环

水表报警。
漏水诊断。
倒流诊断。
滴漏诊断。
空管诊断。
工单派发。
处理闭环。

阶段五：支付对账与开放集成

APP 支付。
银行代扣。
支付回调。
对账文件。
监管接口。
第三方系统集成。

阶段六：报表数仓和运营分析

用水分析。
收费分析。
欠费分析。
抄表成功率。
设备在线率。
产销差。
DMA 漏损。
经营看板。

13. 总结

水务云平台的核心不是"水表上报数据能入库"，而是围绕水司运营形成完整闭环：

text 复制代码

客户 -> 计量点 -> 水表 -> 抄表 -> 计费 -> 缴费 -> 对账 -> 报表

同时还要形成运维闭环：

text 复制代码

水表事件 -> 报警诊断 -> 工单 -> 处理 -> 统计

如果系统是从燃气云改造而来，最重要的是识别哪些能力属于"公用事业通用能力"，哪些能力是"燃气专属遗留"。水务云应该保留客户、计量点、设备、抄表、账务、支付、权限、前置机这些通用能力，同时强化水务特有的漏损、滴漏、倒流、空管、DMA、产销差和工单诊断。

面向产品化的新水务云平台，建议采用：

text 复制代码

标准水务领域模型 + 水表前置机 + 协议插件 + 计费账务中心 + 报警诊断中心 + 开放集成网关

核心原则是：

text 复制代码

水务主线清晰，燃气遗留隔离，设备协议插件化，账务核心独立，异常工单闭环。