1. 背景与目标

传统燃气业务系统通常从营业管理或抄表系统演进而来，早期多采用：

Tomcat + Spring MVC + JSP + MyBatis + MySQL

这类系统经过多年迭代，往往已经覆盖大量业务：

• 客户开户、过户、销户。
• 表具档案和安装维护。
• 远程抄表和冻结数据。
• 阀控、充值、调价、读参、设参。
• IC 卡、STS、NB-IoT、LoRaWAN、RF、RTU 等多种设备形态。
• 预付费、后付费、账户预存、账单缴费。
• 微信、支付宝、银行、APP、线下收费。
• 营业报表、收费报表、抄表报表、异常报表。
• 第三方营业系统、监管平台、支付平台、厂商平台集成。

但随着业务扩大，传统单体系统也会逐渐出现问题：

• Controller、Service、Mapper 与 JSP 耦合严重。
• 客户化代码散落在主工程中。
• 设备协议和业务逻辑混杂。
• 命令下发链路缺少统一闭环。
• 账务、支付、对账边界不清。
• 报表直接查业务表，性能和维护压力大。
• 新能源类型、新协议、新客户项目扩展成本高。

因此，新一代燃气云平台建议按微服务体系重新设计。

目标是：

统一业务模型
统一设备接入
统一命令闭环
统一计费账务
统一开放集成
统一运维监控

2. 总体产品定位

燃气云平台可以定位为：

面向燃气运营企业的计量运营、设备接入、客户服务、账务收费和数据分析一体化平台。

从业务视角看，它服务于四类对象：

对象	诉求
燃气公司	经营管理、收费、报表、设备运维、风险控制
营业人员	开户、缴费、过户、补气、退款、票据、客户查询
运维人员	表具安装、换表、阀控、异常处理、设备监控
终端客户	查询账单、在线缴费、用量分析、报修、消息通知

从系统视角看，它包含五条主线：

1. 客户主线：客户、地址、合同、计量点。
2. 设备主线：表具、网关、通信模块、协议、生命周期。
3. 采集主线：上报、解析、读数、冻结、告警。
4. 账务主线：账户、账单、缴费、对账、退款。
5. 命令主线：业务指令、协议转换、下发、回执、补偿。

3. 当前技术现状抽象

传统系统可以抽象为如下结构：

浏览器 / APP / 第三方系统
        |
Tomcat
        |
Spring MVC Controller
        |
Spring Service
        |
MyBatis Mapper
        |
MySQL

同时还会包含：

• CXF SOAP WebService。
• ActiveMQ 或其他 MQ。
• Netty Socket 客户端/服务端。
• Quartz 定时任务。
• Druid 数据库连接池。
• POI 导入导出。
• Ehcache 本地缓存。
• JSP 页面。

这类架构适合早期快速建设，但不利于产品化和多客户扩展。

新平台可以保留老系统中成熟的业务能力，但服务边界需要重新拆分。

4. 微服务总体架构

目标架构可以设计为：

Web 管理端 / 移动端 / 第三方系统
        |
API 网关
        |
认证鉴权服务
        |
业务微服务层
        |
数据层 / 消息层 / 文件层 / 调度层 / 监控层
        |
设备 / 网关 / 支付渠道 / 银行 / 营业系统 / 监管平台

微服务分层：

接入层：
  - API 网关
  - 设备接入网关
  - 开放集成网关

业务层：
  - 系统基础服务
  - 租户组织服务
  - 客户运营服务
  - 设备资产服务
  - 采集数据服务
  - 命令控制服务
  - 计费账务服务
  - 支付对账服务
  - 报表分析服务
  - 工单运维服务
  - 消息通知服务

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

5. 微服务拆分方案

5.1 API 网关服务

职责：

• 统一入口。
• 登录态校验。
• Token 校验。
• API 签名。
• 限流。
• 黑白名单。
• 路由转发。
• 请求日志。
• 防重放。

典型能力：

/api/**
/openapi/**
/app/**
/admin/**

网关不处理具体业务，只做流量治理和安全控制。

5.2 认证与权限服务

职责：

• 用户登录。
• 角色权限。
• 菜单权限。
• 按钮权限。
• API 权限。
• 数据权限。
• 租户隔离。
• 审计日志。

核心模型：

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

权限需要支持：

• 总部。
• 分公司。
• 营业厅。
• 区域。
• 小区。
• 自定义数据范围。

5.3 系统基础服务

职责：

• 字典管理。
• 参数配置。
• 菜单管理。
• 区域管理。
• 价格基础配置。
• 文件模板。
• 打印模板。
• 系统日志。
• 数据导入导出。

这部分属于所有业务服务都会依赖的公共基础能力。

5.4 客户运营服务

职责：

• 客户档案。
• 地址档案。
• 开户。
• 过户。
• 销户。
• 停复用。
• 客户资料变更。
• 客户导入。
• 客户查询。
• 合同管理。

核心模型：

Customer 客户
ServiceContract 服务合同/户号
ServiceAddress 服务地址
MeasuringPoint 计量点
CustomerContact 联系方式
CustomerOperationRecord 客户业务记录

建议把“客户”和“户号/合同”分开。

一个客户可以有多个服务合同，一个服务合同可以绑定一个或多个计量点，一个计量点绑定具体表具。

客户 -> 合同/户号 -> 地址 -> 计量点 -> 表具

5.5 设备资产服务

职责：

• 表具档案。
• 网关档案。
• RTU 档案。
• 集中器档案。
• SIM 卡管理。
• 设备安装。
• 换表。
• 拆表。
• 设备绑定。
• 设备生命周期。
• 设备参数。

核心模型：

Device 设备主档
MeterDevice 表具扩展
GatewayDevice 网关扩展
DeviceRelation 设备关系
DeviceInstall 安装信息
DeviceLifecycle 生命周期
DeviceParameter 设备参数

设备类型可以统一抽象：

GAS_METER      燃气表
WATER_METER    水表
RTU            RTU
GATEWAY        网关
CONCENTRATOR   集中器
SIM            SIM 卡

5.6 设备接入网关服务

设备接入网关是燃气云平台的核心基础设施。

职责：

• 接收设备上报。
• 保存原始报文。
• 协议识别。
• 报文解析。
• 标准数据转换。
• 命令下发。
• 回执接收。
• 通道监控。

支持通道：

NB-IoT
LoRaWAN
RF Mesh
RTU
TCP Socket
HTTP
MQ
SMS
IC/STS 离线通道

接入网关不直接处理客户账务，只负责设备通信和协议适配。

推荐链路：

设备/网关
  -> 接入通道
  -> 原始报文入库
  -> 协议解析
  -> 标准读数/事件/日志
  -> 发布 MQ
  -> 业务服务消费

5.7 协议适配服务

职责：

• 不同厂商协议解析。
• 上报报文转换。
• 命令报文组包。
• 回执报文解析。
• 协议版本管理。
• 协议插件加载。

协议插件接口示例：

public interface DeviceProtocol {

    String protocolCode();

    ParseResult parseUpstream(RawMessage message);

    EncodedCommand encodeCommand(CommandTask command);

    CommandResult parseCommandResult(RawMessage message);
}

设计原则：

• 协议插件不处理账务。
• 协议插件不直接操作客户表。
• 协议插件只做编解码和标准化转换。
• 原始报文必须保留，方便排障。

5.8 采集数据服务

职责：

• 实时读数。
• 冻结读数。
• 用量计算。
• 上报日志。
• 设备状态。
• 设备告警。
• 异常数据。
• 原始报文查询。

核心模型：

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

读数类型：

REALTIME       实时读数
DAILY_FROZEN   日冻结
MONTH_FROZEN   月冻结
BILLING        计费读数
MANUAL         人工读数
ESTIMATED      估抄读数

5.9 命令控制服务

职责：

• 创建命令。
• 参数校验。
• 权限校验。
• 风险校验。
• 命令排队。
• 协议组包。
• 命令下发。
• 回执处理。
• 超时补偿。
• 失败重试。
• 命令审计。

命令类型：

OPEN_VALVE          开阀
CLOSE_VALVE         关阀
FORCE_CLOSE_VALVE   强制关阀
REMOTE_RECHARGE     远程充值
PRICE_ADJUST        调价
READ_PARAM          读参
SET_PARAM           设参
SYNC_TIME           校时
FIRMWARE_UPGRADE    固件升级
CANCEL_COMMAND      撤销命令

命令状态：

CREATED
WAITING_SEND
SENDING
SENT
DEVICE_RECEIVED
SUCCESS
FAILED
TIMEOUT
CANCELLED
MANUAL_REQUIRED

命令闭环：

业务触发
  -> 创建命令任务
  -> 校验权限和参数
  -> 协议组包
  -> 入发送队列
  -> 设备接入网关下发
  -> 设备回执
  -> 解析结果
  -> 更新命令状态
  -> 回写业务结果
  -> 失败补偿/人工处理

5.10 IC/STS 离线售气服务

职责：

• IC 卡发卡。
• 补卡。
• 读卡。
• 购气。
• 退气。
• 补气。
• 扣气。
• 圈存。
• STS Token 生成。
• STS 售气记录。
• 离线表读数导入。

这部分和在线物联网命令不同，建议单独建服务。

核心模型：

CardInfo 卡信息
CardOperation 卡操作
OfflineSaleOrder 离线售气订单
StsTokenOrder STS Token 订单
OfflineReading 离线读数

5.11 计费账务服务

职责：

• 账户管理。
• 账单生成。
• 抄表计费。
• 阶梯价。
• 其他费用。
• 滞纳金。
• 优惠减免。
• 账户流水。
• 欠费管理。
• 退款。
• 冲正。
• 核销。

账务核心模型：

Account 账户
AccountLedger 账户流水
Bill 账单
BillDetail 账单明细
Receivable 应收
PaymentRecord 收款记录
RefundOrder 退款单
AdjustmentOrder 调账单
InvoiceRecord 票据/发票

计费流程：

读数产生
  -> 读数校验
  -> 用量计算
  -> 价格方案匹配
  -> 阶梯价计算
  -> 生成账单
  -> 生成应收
  -> 支付/扣款
  -> 核销

计费服务应避免直接依赖具体设备协议，只消费标准读数。

5.12 支付对账服务

职责：

• 支付订单。
• 微信支付。
• 支付宝支付。
• 银行代扣。
• APP 支付。
• 线下收款。
• 支付回调。
• 支付对账。
• 差错处理。
• 退款处理。

核心模型：

PaymentOrder 支付订单
ChannelOrder 渠道订单
PaymentCallback 支付回调
ReconciliationBatch 对账批次
ReconciliationDetail 对账明细
RefundOrder 退款单
PaymentException 支付异常

对账流程：

下载渠道账单
  -> 解析账单
  -> 匹配平台订单
  -> 校验金额/状态/时间
  -> 标记平账/长款/短款/状态不一致
  -> 自动补偿或人工处理

5.13 报表分析服务

职责：

• 营业报表。
• 收费报表。
• 客户报表。
• 抄表报表。
• 欠费报表。
• 异常报表。
• 设备报表。
• 对账报表。
• 经营看板。

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

推荐三层：

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

明细层：

• 账单。
• 缴费。
• 读数。
• 命令。
• 设备事件。

汇总层：

• 日用量。
• 月用量。
• 日收费。
• 月收费。
• 区域收费。
• 客户欠费。
• 设备异常。

展示层：

• 分页查询。
• 图表。
• Excel 导出。
• 定时报表。

5.14 工单运维服务

职责：

• 报修工单。
• 安检工单。
• 换表工单。
• 阀控工单。
• 设备异常工单。
• 客诉工单。
• 现场处理。
• 工单派发。
• 工单回访。

工单可以和设备异常、客户报修、账务异常联动。

异常产生 -> 自动建单 -> 派发人员 -> 现场处理 -> 回填结果 -> 关闭工单

5.15 消息通知服务

职责：

• 短信。
• 邮件。
• APP 推送。
• 公众号消息。
• 站内信。
• 语音通知。

通知场景：

• 缴费成功。
• 欠费提醒。
• 阀门关闭。
• 充值成功。
• 账单生成。
• 报修受理。
• 工单完成。
• 异常告警。

6. 数据架构设计

6.1 主数据模型

Tenant 租户
Organization 组织
Area 区域
Customer 客户
ServiceContract 合同/户号
ServiceAddress 服务地址
MeasuringPoint 计量点
Device 设备
MeterDevice 表具
DeviceRelation 设备关系
PricePlan 价格方案
Account 账户

核心关系：

租户 -> 组织 -> 区域 -> 地址 -> 客户/合同 -> 计量点 -> 表具

6.2 采集数据模型

RawMessage
MeterReading
FrozenReading
DeviceEvent
DeviceAlarm
DeviceLog
DeviceStatusSnapshot

采集数据通常量大，需要按时间分区或分表，并设计冷热归档。

6.3 命令数据模型

CommandTask
CommandTarget
CommandPayload
CommandDispatchLog
CommandResult
CommandRetry
CommandAudit

所有命令必须具备：

• 业务来源。
• 操作人。
• 操作原因。
• 目标设备。
• 协议报文。
• 下发时间。
• 回执时间。
• 最终状态。

6.4 账务数据模型

Account
AccountLedger
Bill
BillDetail
PaymentOrder
PaymentRecord
RefundOrder
ReconciliationBatch
ReconciliationDetail
InvoiceRecord

账务数据必须保证可追溯，不建议物理删除。

6.5 报表数据模型

StatDailyUsage
StatMonthlyUsage
StatDailyPayment
StatMonthlyPayment
StatDeviceException
StatCustomerArrearage
StatAreaOperation

报表服务应尽量查询汇总表，而不是直接聚合交易明细。

7. 核心业务流程设计

7.1 开户流程

录入客户
  -> 校验客户唯一性
  -> 创建客户档案
  -> 创建合同/户号
  -> 创建服务地址
  -> 创建计量点
  -> 绑定价格方案
  -> 绑定表具
  -> 创建账户
  -> 收取开户费/预存
  -> 生成开户记录
  -> 打印票据
  -> 写审计日志

7.2 换表流程

选择客户/计量点
  -> 查询旧表信息
  -> 读取旧表末读数
  -> 校验未结清账单
  -> 登记新表
  -> 解绑旧表
  -> 绑定新表
  -> 生成换表记录
  -> 处理用量差额
  -> 下发新表参数
  -> 写审计日志

7.3 远程抄表流程

设备上报
  -> 接入网关接收
  -> 保存原始报文
  -> 协议解析
  -> 标准读数入库
  -> 异常识别
  -> 更新设备状态快照
  -> 发布读数事件
  -> 触发计费/报表/告警

7.4 远程充值流程

客户支付
  -> 支付成功回调
  -> 创建收款记录
  -> 更新账户流水
  -> 创建远程充值命令
  -> 协议组包
  -> 下发设备
  -> 设备回执
  -> 更新命令状态
  -> 更新充值结果
  -> 对账
  -> 异常补偿

7.5 阀控流程

业务触发/人工操作
  -> 权限校验
  -> 风险校验
  -> 创建阀控命令
  -> 下发设备
  -> 接收回执
  -> 更新阀门状态
  -> 失败重试/人工处理
  -> 审计日志

7.6 抄表计费流程

采集读数/人工读数
  -> 读数有效性校验
  -> 计算用量
  -> 匹配价格方案
  -> 计算阶梯价
  -> 生成账单
  -> 生成应收
  -> 推送缴费渠道
  -> 账单核销
  -> 报表汇总

7.7 支付对账流程

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

8. 设备接入与 LoRaWAN 模式设计

燃气云平台可能支持多种接入方式，其中 LoRaWAN 模式通常链路更长。

典型链路：

燃气表
  -> LoRaWAN 网关
  -> NS Server
  -> 应用接入服务
  -> 协议解析服务
  -> 采集数据服务
  -> 业务服务

各组件职责：

组件	职责
燃气表	采集读数、阀门状态、电池状态、异常事件
LoRaWAN 网关	射频接入、转发上下行报文
NS Server	设备入网、上下行路由、设备会话管理
应用接入服务	接收 NS 回调、发送下行命令
协议解析服务	解码表具业务报文
采集数据服务	保存标准读数和事件
命令控制服务	创建业务命令并跟踪回执

LoRaWAN 下行命令需要特别注意：

• 下行窗口。
• 设备休眠。
• 命令超时。
• 重试策略。
• 重复回执。
• 网关覆盖质量。

9. 开放集成设计

燃气云平台通常需要对接：

• 营业系统。
• 支付平台。
• 银行。
• 监管平台。
• 厂商平台。
• 短信平台。
• 发票平台。
• 第三方 APP。

建议建立开放集成网关。

集成网关职责：

• 协议适配。
• 签名验签。
• 报文转换。
• 幂等控制。
• 重试补偿。
• 接口日志。
• 错误码映射。
• 限流和熔断。

接口风格：

内部统一 REST / MQ
外部按需支持 REST / SOAP / Socket / 文件 / MQ

老系统里的 SOAP、Socket、客户化 Controller 可以逐步迁移为适配器模块。

10. 安全设计

10.1 用户安全

• 密码加密存储。
• 登录失败锁定。
• 多因素认证。
• 登录日志。
• 会话超时。

10.2 接口安全

• Token。
• AK/SK。
• 时间戳。
• nonce。
• 签名。
• IP 白名单。
• 防重放。

10.3 数据安全

• 租户隔离。
• 组织数据权限。
• 敏感字段脱敏。
• 敏感字段加密。
• 操作审计。

敏感操作包括：

• 远程关阀。
• 退款。
• 冲正。
• 调价。
• 补气。
• 修改客户资料。
• 导出客户数据。

11. 非功能设计

能力	设计要求
高可用	网关、业务服务、MQ、Redis、数据库均需高可用
可扩展	协议、支付渠道、客户化接口插件化
可观测	API、命令、设备、账务、任务全链路可追踪
性能	采集数据分区，报表预汇总，大表分页走索引
安全	租户隔离、权限隔离、敏感数据加密
可维护	标准核心和客户化适配隔离
国际化	支持多语言、多币种、多时区、不同计量单位
容错	命令、支付、对账、消息消费支持补偿

12. 技术架构建议

12.1 从传统架构到微服务

传统架构：

Tomcat + Spring MVC + JSP + MyBatis + MySQL

目标架构：

Spring Boot / Spring Cloud
API Gateway
微服务集群
MySQL/PostgreSQL
Redis
MQ
对象存储
调度平台
日志监控

12.2 服务通信

同步调用：

REST / OpenFeign / gRPC

异步调用：

Kafka / RabbitMQ / RocketMQ

设备采集、命令回执、支付回调、报表汇总都适合使用异步事件。

12.3 数据库设计

建议：

• 每个核心服务有自己的数据库或 schema。
• 不跨服务直接联表。
• 跨服务查询通过 API、事件、数据同步或报表库解决。
• 账务数据只追加，不物理删除。
• 采集数据按时间分区或归档。

12.4 任务调度

调度场景：

• 日冻结处理。
• 月账单生成。
• 支付对账。
• 报表汇总。
• 设备离线扫描。
• 命令超时补偿。
• 数据归档。

可选：

XXL-JOB / Quartz / 云调度

13. 产品功能清单

13.1 系统管理

• 租户管理。
• 公司组织。
• 区域小区。
• 用户角色。
• 菜单权限。
• 字典参数。
• 操作日志。
• 文件模板。
• 打印模板。

13.2 客户管理

• 客户档案。
• 开户。
• 过户。
• 销户。
• 停复用。
• 客户导入。
• 客户查询。
• 合同管理。
• 地址管理。

13.3 表具管理

• 表具档案。
• 表具安装。
• 换表。
• 拆表。
• 设备绑定。
• SIM 卡。
• 网关。
• RTU。
• 集中器。
• 参数管理。

13.4 采集管理

• 实时读数。
• 冻结读数。
• 原始报文。
• 异常报文。
• 设备日志。
• 设备状态。
• 离线监控。
• 上报率分析。

13.5 命令管理

• 开阀。
• 关阀。
• 充值。
• 调价。
• 读参。
• 设参。
• 校时。
• 升级。
• 命令日志。
• 超时补偿。

13.6 账务管理

• 账户。
• 账单。
• 缴费。
• 退款。
• 冲正。
• 滞纳金。
• 优惠。
• 其他费用。
• 欠费。
• 票据。

13.7 支付对账

• 微信支付。
• 支付宝支付。
• 银行代扣。
• APP 支付。
• 线下收费。
• 对账。
• 差错处理。
• 补单。

13.8 报表分析

• 营业报表。
• 收费报表。
• 客户报表。
• 抄表报表。
• 欠费报表。
• 异常报表。
• 设备报表。
• 经营看板。

13.9 工单运维

• 报修。
• 安检。
• 换表。
• 阀控处理。
• 异常处理。
• 派工。
• 回访。

13.10 开放平台

• 第三方查询接口。
• 第三方缴费接口。
• 设备状态接口。
• 账单接口。
• 回调接口。
• 签名管理。
• 接口日志。

14. 建设路线

阶段一：核心模型建设

• 租户组织。
• 客户。
• 地址。
• 计量点。
• 表具。
• 账户。
• 价格方案。

目标是建立统一主数据模型。

阶段二：燃气核心闭环

• 开户。
• 表具绑定。
• 抄表。
• 计费。
• 缴费。
• 账单。
• 报表。

目标是形成最小可用的燃气营业闭环。

阶段三：设备接入和命令闭环

• NB/LoRa/RTU/RF 接入。
• 原始报文。
• 协议解析。
• 阀控。
• 充值。
• 命令回执。
• 异常补偿。

目标是形成远程运营能力。

阶段四：支付对账和开放集成

• 支付渠道。
• 银行代扣。
• 对账。
• 第三方营业系统。
• 监管平台。
• 厂商平台。

目标是形成外部生态连接能力。

阶段五：报表数仓和运维平台

• 汇总报表。
• 经营看板。
• 设备监控。
• 命令监控。
• 任务调度。
• 日志追踪。
• 数据治理。

目标是提升运营效率和可观测性。

15. 总结

燃气云平台的复杂度不在于单个功能，而在于多个闭环同时存在：

• 客户闭环。
• 设备闭环。
• 采集闭环。
• 命令闭环。
• 账务闭环。
• 支付闭环。
• 工单闭环。
• 报表闭环。

传统 Tomcat + Spring MVC 系统沉淀了大量业务能力，但如果继续把所有能力堆在一个工程中，后续产品化、国际化、多客户交付和多协议扩展都会越来越困难。

新一代燃气云平台更适合采用微服务体系：

标准核心服务 + 设备接入网关 + 协议插件 + 开放集成网关 + 客户化适配模块

核心原则是：

业务模型统一，协议适配隔离，账务核心独立，命令全链路闭环，客户化能力插件化。

这样既能复用传统燃气系统的业务积累，又能支撑后续云化、产品化、多能源、多协议和多区域扩展。