供热经营收费管理平台-微服务架构设计

1. 平台概述

1.1 项目背景

供热行业作为市政公用事业的重要组成部分，承担着冬季居民供暖的核心职能。传统供热收费管理多依赖人工台账或单体信息系统，存在数据孤岛严重、业务流程割裂、缴费渠道单一、报表统计滞后等突出问题。随着供热面积持续扩大、用户规模增长以及精细化管理要求的提升，原有系统架构已无法支撑高效的经营管理和优质的用户服务。

本平台采用微服务架构，将供热经营收费全流程拆分为独立部署、独立扩展的业务服务单元，通过服务编排实现新用户开户、热费缴纳、停复供申请、退费处理、报修投诉、报表统计六大核心业务场景的端到端闭环，为供热企业提供高可用、可扩展、易维护的经营收费管理底座。

1.2 设计目标

业务解耦 — 按业务领域拆分服务边界，各服务独立开发、部署和扩展，消除单体架构中的功能耦合。

弹性伸缩 — 缴费高峰期对收费服务和支付服务弹性扩容，IoT 控制服务按设备分片独立扩展，非高峰期自动缩容。

数据贯通 — 通过事件驱动和 API 编排实现跨服务数据流转，打破信息孤岛，支撑经营分析决策。

渐进演进 — 支持新服务独立上线和旧服务逐步替换，降低系统重构风险，保障业务连续性。

1.3 设计原则

1.4 适用范围

本架构设计适用于中等规模以上的供热企业（供热面积 100 万平方米以上、用户 5 万户以上），支持多热源、多片区、多收费标准的经营场景。对于小型供热企业，可基于本架构裁剪为基础版（合并部分微服务为模块化单体），在业务增长后平滑演进为完整微服务架构。

2. 整体架构设计

2.1 架构总览

平台采用分层架构，自上而下分为接入层、网关层、业务服务层、基础服务层、数据存储层五个层次，辅以监控运维和安全管理两大横向支撑体系。各层职责清晰，依赖方向自上而下单向流转。

2.2 架构分层说明

2.3 技术选型

以上选型基于供热行业业务特点（交易金额敏感、季节性峰值明显、设备交互实时性要求）综合评估。如团队已有替代方案，在满足可靠性和事务消息需求的前提下可灵活替换。

3. 微服务拆分与职责

3.1 服务全景图

平台共拆分为 11 个业务微服务 和 6 个基础支撑服务。业务服务按供热经营领域划分为用户域、计费收费域、运营管控域、分析域四个限界上下文。

3.2 核心业务服务

用户服务（User Service）

V2.0 变更：原用户服务中的合同管理功能（模板管理、合同生成、签署流程、归档存储）已抽取为独立的合同服务。用户服务回归纯粹的用户档案管理，迭代频率降低。用户与房产的绑定关系迁移至房产服务管理，用户服务仅保存 property_id 引用。

房产服务（Property Service）

V2.0 变更：用户-房产绑定关系从用户服务迁移至房产服务管理。这一调整使房产域的数据完整性由房产服务统一负责，避免跨服务的数据一致性问题。

合同服务（Contract Service）【新增】

V2.0 新增：从用户服务中抽取。合同管理有独立的业务生命周期——模板版本管理、电子签章对接、到期续签提醒——随着业务发展会不断膨胀（合同变更、多方签署、合同审计），独立后可按自身节奏迭代，不影响用户核心数据稳定性。

计费账单服务（Billing & Bill Service）

V2.0 变更：由原计费服务与账单服务合并而来。两者在业务上高度耦合——计费的输出就是账单的输入，共享"供热季"“用户编号”"房产面积"等同一套领域概念。合并后内部拆分为计费引擎模块（规则计算、热量数据处理）和账单管理模块（账单生成、状态流转、查询导出），模块间通过进程内调用替代网络调用，延迟从约 15ms 降至约 1ms。原跨服务的事务协调（Saga/Seata）简化为本地事务。计费引擎模块通过批量任务异步执行，账单模块处理在线查询，两者资源隔离通过线程池实现。

收费服务（Charge Service）

支付服务（Payment Service）

发票服务（Invoice Service）

审批服务（Approval Service）

粒度说明：当前审批服务仅用于停复供和退费两个场景，作为独立微服务略重。初期可考虑作为审批模块嵌入收费服务或设备档案服务，待审批场景增至 5 个以上时再抽取为独立服务。

设备档案服务（Device Archive Service）【拆分新增】

V2.0 新增：由原设备服务拆分而来，负责设备生命周期管理（CRUD 操作，低频写入，查询为主），是典型的 OLTP 负载。

IoT 控制服务（IoT Control Service）【拆分新增】

V2.0 新增：由原设备服务拆分而来，专注设备通信与实时控制。拆分原因是档案管理（OLTP）与 IoT 控制（长连接、实时性敏感）的负载特征完全不同——混合部署导致 IoT 连接高峰时档案查询响应变慢，批量档案导入时 IoT 指令延迟升高。拆分后 IoT 控制服务可按设备分片独立水平扩展，不影响档案查询性能。

客服服务（Customer Service）

通知服务（Notification Service）

数据分析服务（Analytics Service）【合并新增】

V2.0 变更：由原报表服务与数据同步服务合并而来。两者共享同一套数据仓库基础设施，数据同步的表结构变更必然影响报表查询，报表的新增指标需求也驱动同步逻辑调整。合并后数据管道与查询共享数据仓库的元数据管理，表结构变更一处修改即可。数据管道和查询服务仍可通过 K8s 的不同 Deployment 独立伸缩。

3.3 基础支撑服务

3.4 服务拆分原则

本平台服务拆分遵循领域驱动设计（DDD）方法，以供热经营的业务流程为线索，按限界上下文划分服务边界。同一业务领域内的强一致性需求归属同一服务（如计费与账单同属计费账单服务），跨领域的弱一致性需求通过事件驱动异步协同。拆分粒度避免过细（导致服务间调用链路过长）和过粗（失去独立扩展能力），以一个团队可独立维护 2-3 个服务为基准。

4. 业务场景与服务编排

本章对供热经营的六大核心业务场景逐一展开，说明每个场景涉及的微服务、核心功能以及服务间协作流程。

4.1 新用户开户

涉及服务：用户服务、房产服务、合同服务、文件服务、通知服务

营业员在管理端录入新用户基本信息，绑定供热房产，上传身份证件和房产证明，系统自动生成用户档案并创建供热合同。开户完成后，通知服务向用户发送开户成功短信，同时触发计费账单服务将该房产纳入当季计费范围。

编排要点：用户服务作为开户流程的编排者，同步调用房产服务验证房产有效性并建立绑定关系，调用合同服务生成合同。合同文件生成通过文件服务异步处理，不阻塞开户主流程。用户-房产绑定关系由房产服务管理，绑定操作与用户档案创建通过 Saga 模式协调——任一步骤失败则整体回滚。

4.2 热费缴纳

涉及服务：计费账单服务、收费服务、支付服务、发票服务、通知服务

用户通过小程序或 APP 查询应缴账单，选择缴费方式和支付渠道完成在线支付。支付成功后，收费服务回写账单状态（调用计费账单服务），触发发票服务自动开具电子发票，通知服务向用户推送缴费成功消息和发票链接。

一致性保障：缴费链路涉及收费服务、支付服务、计费账单服务三个数据源，采用 Seata AT 模式保证缴费订单创建与账单状态回写的分布式事务一致性。支付回调采用幂等设计（基于订单号去重），防止重复回调导致重复入账。发票开具为异步操作，通过消息队列解耦，开票失败不影响缴费主流程，由对账任务补偿。

4.3 停复供申请

涉及服务：审批服务、计费账单服务、IoT 控制服务、通知服务

用户因房屋空置、装修等原因申请停止或恢复供热。系统根据申请类型发起审批流程，审批通过后，计费账单服务调整费用计算方式（停供期间按基本热费收取），IoT 控制服务远程控制入户阀门关闭或开启，全程通过通知服务向用户和运维人员推送节点状态。

异常处理：阀门控制是物理设备操作，可能因网络中断、设备离线等原因失败。设计三级容错策略：一级自动重试（3 次，间隔递增），二级转人工处理（生成运维工单），三级告警通知（IoT 控制服务向运维人员推送告警）。费用调整在审批通过即刻生效，不依赖阀门控制结果——即使阀门控制失败，费用已按停供计算，避免用户因设备故障多缴费用。

4.4 退费处理

涉及服务：收费服务、审批服务、支付服务、通知服务

用户因多缴、停供退费、计费错误等原因申请退费。收费服务受理退费申请并冻结原收费记录，审批服务按金额分级审批（500 元以下片区审批，500 元以上需财务审批），审批通过后支付服务执行原路退款，收费服务更新账单和发票状态。

资金安全：退费流程涉及资金退还，采用先冻结后退款策略——退费申请提交即冻结原收费记录，防止在此期间再次发起退费。退款操作通过支付服务的退款接口执行，原路退回至用户原支付账户。退款金额超过原缴金额时系统拒绝，退款与发票冲红通过消息队列异步联动，保证财务数据一致性。

4.5 报修投诉

涉及服务：客服服务、通知服务、设备档案服务

用户通过热线电话、小程序或 APP 提交报修或投诉工单。客服服务创建工单并自动分类派单，通知服务向维修人员推送派单信息。维修人员现场处理完毕后回填处理结果，系统触发回访评价通知。如涉及设备故障，工单关联设备档案服务记录维修日志。

SLA 管理：工单按紧急程度设置不同的响应时效（紧急 2 小时、普通 24 小时、咨询 48 小时），超时未接单自动升级并通知主管。维修人员现场无法解决的工单可申请转单或技术支援，工单全程状态可追溯，形成完整的服务闭环。

4.6 报表统计

涉及服务：数据分析服务

管理层通过数据分析服务查看收费统计、欠费分析和经营分析等报表。数据分析服务内部的数据管道组通过 CDC 实时捕获各业务服务的 MySQL 数据变更，清洗转换后写入数据仓库；查询服务组基于数据仓库的预聚合数据生成多维分析报表，支持按时间、片区、用户类型等维度灵活筛选。

数据时效性：收费统计和欠费分析报表基于数据仓库的预聚合数据，数据延迟控制在 5 分钟以内（准实时）。经营分析报表因涉及跨表关联和复杂计算，采用 T+1 批量预计算。实时性要求高的场景（如当日收费看板），查询服务组直接查询业务服务 MySQL 的只读副本，通过缓存减少压力。

4.7 场景与服务对照总览

5. 服务间通信与数据一致性

5.1 通信模式

平台采用同步与异步混合的通信策略。同步调用用于需要即时响应的业务操作（如账单查询、缴费下单），异步消息用于非阻塞的事件通知和解耦操作（如开票通知、数据同步）。

5.2 容错与降级策略

• 熔断（Circuit Breaker）：基于 Sentinel 实现，当某服务错误率超过 50% 或响应时间超过 2s，自动熔断 10s，快速失败避免级联雪崩。
• 降级（Fallback）：非核心服务不可用时返回降级数据（如通知服务宕机时缴费仍可完成，通知延迟补偿发送）。
• 限流（Rate Limiting）：网关层和服务层双重限流。缴费高峰期支付服务限流 500 QPS，超出请求排队等待。
• 重试（Retry）：幂等接口支持自动重试（最多 3 次，指数退避），非幂等接口通过请求 ID 去重。

5.3 数据一致性策略

微服务架构下，每个服务拥有独立数据库，跨服务的数据一致性是架构设计的核心挑战。平台根据业务场景的一致性要求强度，采用分层一致性策略：

5.4 幂等性设计

所有写操作接口均需保证幂等性，防止网络重试或消息重复消费导致数据不一致。平台统一采用请求 ID + 状态机校验的双重幂等方案：客户端每次请求携带唯一 requestId，服务端基于 Redis 记录已处理的 requestId（TTL 24h），同时通过业务状态机校验当前状态是否允许该操作。

6. 数据架构

6.1 数据库分库策略

平台遵循每个微服务独立数据库的原则（Database per Service），禁止跨服务直接访问数据库，所有跨服务数据交互通过 API 或消息完成。

6.2 分库分表策略

对于数据量增长较快的账单表和收费记录表，采用分表策略缓解单表性能瓶颈。分表键选择用户编号，采用一致性哈希分片，保证同一用户的账单和收费记录落在同一分片。分表中间件使用 ShardingSphere。

6.3 缓存策略

6.4 数据归档与备份

归档策略：账单和收费记录按供热季归档，超过 3 个供热季的数据迁移至归档库（独立 MySQL 实例），业务库仅保留近 3 季数据。归档库可独立扩容，不影响在线业务性能。报表查询跨历史数据时，通过联邦查询合并在线库和归档库结果。

7. 部署与运维架构

7.1 容器化部署架构

平台基于 Kubernetes 集群部署，所有微服务容器化运行。集群按环境隔离分为开发、测试、预发、生产四套环境，生产环境采用多节点高可用部署。每个微服务通过 Deployment 管理 Pod 副本，配合 HPA 根据指标自动伸缩。IoT 控制服务因需维持设备长连接，采用 StatefulSet 部署并按设备分片。

7.2 弹性伸缩策略

7.3 监控告警体系

• 指标监控（Prometheus）：采集各服务 JVM 指标、HTTP 请求指标、自定义业务指标（缴费成功率、账单生成量、设备在线率等），15s 采集间隔。
• 可视化看板（Grafana）：服务健康总览、缴费实时看板、数据库性能看板、IoT 设备状态看板。
• 分级告警（AlertManager）：P0 电话+短信（服务宕机）、P1 短信+钉钉（错误率突增）、P2 钉钉（资源预警）。
• 链路追踪（SkyWalking）：分布式调用链追踪，慢请求自动标记，服务依赖拓扑图，帮助快速定位性能瓶颈。

7.4 CI/CD 流水线

采用 GitOps 模式持续部署，代码提交后自动触发构建、测试、镜像打包，通过 ArgoCD 将镜像部署至 K8s 集群。

7.5 日志管理

各服务采用 Logback 输出结构化 JSON 日志，通过 Filebeat 采集至 ELK Stack。日志统一包含 TraceID（SkyWalking 生成），支持按 TraceID 贯穿查询完整调用链。敏感信息（证件号、银行卡号）在日志输出前脱敏处理。IoT 控制服务的设备通信日志单独存储至 InfluxDB，支持按设备编号和时间范围查询。

8. 安全与合规设计

8.1 认证与授权

平台采用 OAuth2 + JWT 的统一认证授权方案。认证中心负责用户身份验证和 Token 签发，网关层负责 Token 校验和权限拦截，业务服务从 Token 中提取用户信息进行细粒度权限控制。

8.2 数据安全

8.3 审计日志

所有涉及资金操作和敏感数据访问的行为均记录审计日志，审计日志独立存储（audit_db），不可篡改，保留期不少于 5 年。

8.4 合规要求

供热收费涉及公共事业资金管理，需满足以下合规要求：收费资金日清日结，每日对账确保账实相符；发票开具符合国家税务总局电子发票规范；用户个人信息保护遵循《个人信息保护法》，数据采集需用户授权，敏感数据加密存储；供热计量数据保存期不少于 3 个供热季，支撑费用争议追溯。

8.5 安全防护体系

8.6 容灾与高可用

9. Spring Cloud Alibaba 服务治理

9.1 服务治理体系总览

平台基于 Spring Cloud Alibaba 构建微服务治理体系，涵盖服务注册发现、配置管理、流量控制、服务容错、API 网关、分布式事务和服务安全七大能力域。各组件由 Nacos、Sentinel、Spring Cloud Gateway、Seata、RocketMQ 等 Alibaba 开源组件提供，形成统一的治理技术栈。

9.2 Nacos 服务注册与发现

Nacos 同时承担服务注册中心与配置中心双重角色，是平台服务治理的基础设施入口。

9.2.1 集群部署

生产环境部署 3 节点 Nacos 集群，采用 raft 协议选举 Leader，确保注册数据强一致性。数据存储采用 MySQL 外部持久化（而非内嵌 Derby），支持配置历史版本回滚和审计追踪。

9.2.2 服务注册与健康检查

保护阈值机制说明：当收费服务 10 个实例中 8 个宕机，健康实例仅剩 2 个（20% < 30%），Nacos 进入保护模式——不再摘除剩余实例，并将不健康实例也返回给消费方，让消费方自行决定是否调用。这避免所有实例被摘除后服务完全不可用，消费方可通过 Sentinel 熔断降级保护自身。

9.2.3 动态配置管理

Nacos Config 为各微服务提供集中化配置管理，支持配置的热更新（无需重启服务即生效）。

配置变更审计：Nacos 配置变更需经过审批流程——修改人在控制台提交变更，审批人确认后生效。每次变更记录历史版本，支持一键回滚至任意历史版本。变更通知通过钉钉群推送，确保团队感知。

灰度发布配置示例：通过 Nacos 配置灰度规则，控制部分流量路由到新版本实例。例如收费服务发布 V2 版本时，先在 Nacos 配置 charge-service-prod-gray.yaml 指定 10% 流量路由至 V2 实例，观察无异常后逐步调整至 30%、100%，最终全量切换。

9.3 Sentinel 流量控制与熔断降级

Sentinel 是平台的流量治理核心，提供流控、熔断降级、系统自适应保护和热点参数限流四类能力。所有规则存储在 Nacos 中，支持动态推送和热更新。

9.3.1 流控规则

流控模式说明：

• 直接限流：对资源本身限流（如支付接口 500 QPS）。
• 关联限流：当关联资源达到阈值时限流本资源。例如支付接口达到 500 QPS 时，限制收费服务继续创建新缴费订单，避免支付服务积压。
• 链路限流：只限制从指定入口来的流量。例如同一接口从 Web 端调用限流 1000 QPS，从小程序调用限流 500 QPS。

9.3.2 熔断降级规则

熔断状态机：

9.3.3 系统自适应保护

Sentinel 系统自适应保护从整体维度对服务实例进行保护，避免因负载过高导致服务完全不可用：

与 K8s HPA 的配合：Sentinel 系统自适应保护是"软限流"（拒绝请求但不杀进程），K8s HPA 是"硬扩容"（增加 Pod 副本）。两者配合：CPU 超过 70% 时 HPA 扩容新 Pod，同时 Sentinel 在 80% 时开始限流保护现有 Pod，避免扩容延迟期间服务雪崩。

9.3.4 热点参数限流

针对特定业务参数进行精细化限流，避免热点数据打垮服务：

9.4 Spring Cloud Gateway API 网关

Spring Cloud Gateway 作为平台唯一入口，承载路由转发、认证鉴权、限流熔断、灰度发布等网关层治理职责。

9.4.1 网关架构

9.4.2 路由配置

路由规则存储在 Nacos 中，支持动态新增和修改路由而无需重启网关：

9.4.3 全局过滤器链

请求经过网关时按顺序通过以下过滤器，每个过滤器承担独立职责：

9.4.4 灰度发布

网关层支持基于 Header 的灰度发布，配合 Nacos 的版本元数据实现流量按比例路由：

灰度流程：

1. 新版本服务实例注册到 Nacos 时携带 version=v2 元数据。
2. 网关灰度过滤器检查请求 Header X-Gray-Version：
   • Header 为 v2 → 路由至 version=v2 的实例。
   • Header 为空 → 按权重路由，默认 90% 流量至 v1、10% 至 v2。
3. 灰度比例通过 Nacos 配置动态调整（10% → 30% → 100%），无需修改代码或重启。
4. 灰度期间通过 SkyWalking 监控 v2 实例的调用成功率和响应时间，异常时一键回滚（将 Nacos 灰度比例调回 0%）。

9.5 Seata 分布式事务

Seata 是平台的分布式事务解决方案，覆盖强一致性场景（AT 模式）和柔性事务场景（TCC/Saga 模式）。

9.5.1 Seata 架构

部署说明：Seata Server 部署 3 节点集群，事务会话存储在独立 MySQL 中。各业务服务的数据库中创建 undo_log 表，用于 AT 模式记录数据变更前后的快照，支撑自动回滚。

9.5.2 AT 模式（自动补偿）

AT 模式适用于短事务场景，业务代码无感知（只需添加 @GlobalTransactional 注解），Seata 自动生成反向 SQL 实现补偿。

缴费场景 AT 模式流程：

AT 模式全局锁机制：Seata 通过全局锁防止写冲突——分支事务提交本地事务前需获取全局锁，如果该行数据已被其他全局事务锁定则等待。这保证在全局事务未完成期间，其他全局事务不能修改同一行数据。但本地事务可以读取（读已提交隔离级别）。

9.5.3 TCC 模式（手动补偿）

TCC 模式适用于需要精细化控制补偿逻辑的场景，业务需实现 Try、Confirm、Cancel 三个方法。

适用场景：退费流程中"冻结收费记录"这一步骤。AT 模式只能回滚数据变更，但"冻结"是一个状态流转（已缴费→退费中），需要确保补偿时恢复为"已缴费"而非简单的数据快照回滚。

TCC 注意事项：

• 空回滚：Try 未执行但 Cancel 被调用（如 Try 超时后 TC 触发回滚）。Cancel 需检查 Try 是否执行过，未执行则直接返回成功。
• 幂等：Confirm 和 Cancel 可能被重复调用（网络重试），必须保证幂等。通过事务状态字段判断——已经是目标状态则直接返回成功。
• 悬挂：Cancel 先于 Try 执行（Try 超时后 Cancel 触发，但延迟的 Try 随后到达）。Try 需检查全局事务是否已回滚，已回滚则不执行。

9.5.4 Saga 模式（长流程编排）

Saga 模式适用于多步骤、长耗时、涉及外部系统调用的业务流程（如开户流程）。平台采用 Seata Saga 状态机引擎（State Machine Engine），通过 JSON 定义流程编排。

开户流程 Saga 定义：

{
  "Name": "userOpenAccountSaga",
  "States": [
    {
      "Name": "createUser",
      "Type": "ServiceTask",
      "ServiceName": "userService",
      "ServiceMethod": "createUser",
      "CompensateMethod": "cancelUser",
      "Next": "bindProperty"
    },
    {
      "Name": "bindProperty",
      "Type": "ServiceTask",
      "ServiceName": "propertyService",
      "ServiceMethod": "bindUserProperty",
      "CompensateMethod": "unbindUserProperty",
      "Next": "generateContract"
    },
    {
      "Name": "generateContract",
      "Type": "ServiceTask",
      "ServiceName": "contractService",
      "ServiceMethod": "generateContract",
      "CompensateMethod": "voidContract",
      "Next": "succeed"
    },
    {
      "Name": "succeed",
      "Type": "Succeed"
    }
  ]
}

Saga 状态持久化：Saga 引擎将每一步的执行状态（STARTED/COMPLETED/FAILED/COMPENSATED）持久化到 seata_saga_log 表。如果流程执行中服务宕机，重启后引擎读取日志恢复到中断点，继续执行或触发补偿。

9.6 服务安全与认证

9.6.1 OAuth2 + JWT 认证体系

平台采用 Spring Security OAuth2 + JWT 实现统一身份认证，认证中心独立部署，各业务服务通过网关层完成 Token 校验。

Token 设计：

多端登录控制：Redis 中以 session:{userId}:{deviceId} 为 Key 存储会话信息，支持同一用户多设备同时登录（如 Web 端 + 手机端），但单设备类型只允许一个会话（新登录踢掉旧会话）。

9.6.2 RBAC 权限模型

数据权限隔离：通过网关层在请求中注入用户所属片区信息，业务服务在查询时自动追加片区过滤条件。例如片区营业员只能查询和操作本片区的用户和账单，财务审批人可查看全部片区数据。

9.6.3 服务间调用安全

内部服务间通过 Feign 调用时，需传递认证上下文和防止外部直接访问：

9.7 服务可观测性

9.7.1 链路追踪（SkyWalking）

SkyWalking 通过 Java Agent 字节码增强实现无侵入式链路追踪，自动采集 HTTP、Feign、MQ、数据库等组件的调用链。

TraceID 贯穿：网关层生成 TraceID，通过 HTTP Header 和 MQ 消息属性传递，确保一次业务操作（可能涉及同步调用+异步消息）的全部日志可通过 TraceID 串联查询。

9.7.2 指标监控（Prometheus + Grafana）

各服务通过 Micrometer 暴露 Prometheus 指标端点，Prometheus 每 15s 采集一次：

Grafana 看板体系：

9.7.3 日志管理（ELK）

日志规范：所有日志输出为结构化 JSON，必含字段 timestamp、level、service、traceId、message。敏感字段（证件号、银行卡号）在日志输出前自动脱敏，通过自定义 Logback Layout 实现。

10. RocketMQ 消息交互设计

10.1 消息架构总览

RocketMQ 是平台异步通信和事件驱动的核心中间件，承担三类职责：跨服务事件通知、异步业务解耦、数据同步管道。平台所有业务服务既是消息生产者也是消息消费者，通过 Topic 分类和 Tag 过滤实现消息的精准路由。

10.2 Topic 与消息分类设计

平台按业务领域规划 Topic，每个 Topic 内通过 Tag 区分消息子类型。消费组按服务+场景命名，同一服务的不同业务逻辑通过 Tag 过滤分别消费。

10.3 消息流转全景

以缴费场景为例，展示一次完整缴费从同步调用到异步消息的完整流转：

10.4 消息不丢失保障

消息从生产到消费经历五个环节，每个环节都存在丢失风险。平台通过分层保障机制确保消息端到端可靠投递。

10.4.1 生产端保障

事务消息机制：对于"业务操作+消息发送"必须原子性完成的场景（如缴费成功后触发开票），采用 RocketMQ 事务消息。流程分三步：

1. 发送半消息：生产者先向 Broker 发送一条半消息（此时消费者不可见），Broker 返回半消息发送成功。
2. 执行本地事务：生产者执行本地数据库事务（如更新收费记录状态为"已缴费"）。
3. 提交/回滚：本地事务成功则向 Broker 发送 Commit（消息对消费者可见），失败则发送 Rollback（删除半消息）。

事务回查实现要点：生产者需实现 TransactionListener 接口的 checkLocalTransaction 方法，通过查询本地数据库判断事务是否成功提交。回查超时设置为 60s，最多回查 15 次，超过后 Broker 自动回滚半消息。

普通消息发送重试：对于非事务消息（如审批结果通知），生产端配置同步发送（SendStatus.SEND_OK）+ 重试 3 次（指数退避：1s、2s、4s）。三次均失败则记录本地错误日志，由定时任务补偿重发。

10.4.2 Broker 端保障

10.4.3 消费端保障

手动 ACK 机制：消费者处理完业务逻辑后才向 Broker 发送消费确认（ACK）。如果消费过程中抛出异常，不发送 ACK，Broker 会将消息重新投递给同一消费组的其他实例或重试。

消费重试机制：消费失败的消息进入重试队列（%RETRY%消费组名），RocketMQ 按 1s、5s、10s、30s、1m、2m、3m、4m、5m、6m、7m、8m、9m、10m、20m、30m 的梯度重试 16 次。16 次仍失败的消息进入死信队列（%DLQ%消费组名）。

死信队列处理：死信队列中的消息不会被自动消费，由后台监控任务扫描并告警，运维人员通过 RocketMQ 控制台查看消息内容，判断失败原因后手动重发或标记为已处理。平台额外开发了死信管理看板，展示各消费组的死信数量、积压趋势和失败原因分类。

幂等消费：由于网络重试和消息重投递，消费者可能收到重复消息。所有消费者基于消息 ID（msgId）或业务唯一键实现幂等：

10.5 事务一致性处理

10.5.1 三种一致性场景与方案选型

平台根据业务场景的事务特征选择不同的一致性方案：

10.5.2 缴费场景的事务一致性处理

缴费是平台最核心的交易链路，涉及收费服务、支付服务、计费账单服务三个数据源。采用"Seata 强一致 + RocketMQ 事务消息"组合方案：

设计要点：

• Seata 全局事务只覆盖"缴费订单创建+账单状态回写"这一步强一致性操作。支付回调到达后，收费服务在 Seata 事务内创建/更新缴费订单并调用计费账单服务回写账单状态。任一分支失败，全局事务回滚，缴费订单和账单状态均恢复原值。
• Seata 事务提交后，收费服务通过 RocketMQ 事务消息发送 payment-success 事件。事务消息保证"本地事务提交"与"消息发送"的原子性——本地事务成功则消息一定投递，本地事务失败则消息一定不投递。
• 发票开具、用户通知、数据同步三个下游操作通过普通消费异步执行，消费失败自动重试，不影响缴费主流程。

异常场景处理：

10.5.3 退费场景的事务一致性处理

退费涉及收费服务本地事务（更新收费记录为"已退费"）+ 支付服务外部调用（执行退款）+ 计费账单服务回写（恢复账单为"待缴"）。由于退款是外部支付渠道调用，无法纳入 Seata 事务，采用"本地消息表 + 事务消息"组合方案：

关键设计：

• 退费采用"先标记后执行"策略——审批通过后先将收费记录标记为"退费中"并冻结，防止在此期间重复退费。
• 退款执行（支付服务调用第三方接口）失败时，消息进入重试队列。重试期间收费记录保持"退费中"状态。
• 16 次重试仍失败进入死信队列，运维介入处理（如第三方接口临时故障，恢复后手动重发消息）。
• 如果死信处理最终确认退款无法成功（如原支付渠道已关闭），运维将收费记录状态回滚为"已缴费"，并通过通知服务告知用户退费失败需线下处理。

10.5.4 开户场景的 Saga 编排

开户流程涉及用户服务（创建用户档案）、房产服务（绑定房产关系）、合同服务（生成合同）三个服务，是典型的长流程多步骤场景。采用 Saga 编排式（Orchestration），由用户服务作为编排者协调流程：

Saga 补偿规则：

实现方式：用户服务维护一个 Saga 执行日志表（saga_log），记录每一步的执行状态（STARTED/COMPLETED/FAILED/COMPENSATED）。Saga 编排器读取日志判断当前进度，决定继续执行还是触发补偿。补偿动作通过同步 Feign 调用执行，补偿失败则记录告警，由运维介入。

10.5.5 对账兜底机制

无论采用哪种一致性方案，平台均部署对账任务作为最终兜底，确保数据一致性：

10.6 消息消费顺序性保障

部分业务场景要求消息按业务顺序消费（如同一账单的状态变更：待缴→部分缴→已缴），平台通过以下机制保障：

缴费场景顺序消费示例：同一用户的缴费消息以用户编号为 shardingKey，确保该用户的缴费成功、退费发起、退费完成等消息按业务发生顺序到达消费者。不同用户的消息可并行消费，不影响吞吐量。

10.7 消息积压与流量控制

供热缴费高峰期（11-3 月）消息量激增，需防止消息积压导致消费延迟：

10.8 RocketMQ 集群部署架构

生产环境部署 3 节点 RocketMQ 集群（1 主 2 从或 3 主 3 从），确保高可用：

部署要点：

• NameServer 部署 3 节点，互不通信，各自维护路由信息。生产者和消费者从任一 NameServer 获取 Broker 路由信息，单节点故障不影响服务。
• Broker 部署 2 组（A/B），每组 1 主 1 从。Topic 的队列分布在两个 Broker 组上实现负载均衡。主节点故障时从节点接管读请求，写请求自动切换至另一组主节点。
• 配置同步刷盘（SYNC_FLUSH）+ 同步复制（SYNC_MASTER），确保消息写入主节点并同步至从节点后才返回成功，避免单点故障导致消息丢失。
• RocketMQ Dashboard 提供消息看板、积压监控、死信管理、消息轨迹查询等功能。

10.9 消息设计规范

11. 热费缴纳高可靠与高并发实战

热费缴纳是平台最核心的交易链路，也是业务风险最高的环节。北方供热季集中在 11 月至次年 3 月，缴费高峰出现在供热季首月（11 月）和截止日前一周，日均缴费量可达平时的 10-20 倍。本章先分析缴费全链路可能发生的问题，再给出逐项解决方案和落地实现。

11.1 缴费全链路问题分析

一次完整缴费涉及客户端、API 网关、收费服务、计费账单服务、支付服务、第三方支付渠道、发票服务、通知服务共 8 个参与方，经同步调用和异步消息两阶段完成。下表按链路节点梳理可能出现的故障场景：

11.2 重复下单防护（P2）

问题根因：用户在网络延迟场景下多次点击"缴费"按钮，或客户端因超时自动重试，导致同一账单产生多个缴费订单。如果支付服务为每个订单都调起支付，可能造成用户被多次扣款。

解决方案：前端防抖 + 后端幂等 + 分布式锁三重防护。

落地实现：

11.3 账单并发冲突（P3）

问题根因：同一房产可能有多个缴费人（如房东和租户），两人同时查询到同一账单为"待缴"状态并同时发起缴费，如果不做并发控制，可能导致同一账单被缴纳两次。

解决方案：乐观锁 + 状态机校验。

落地实现：

账单状态流转规则：

11.4 支付超时与订单关闭（P4）

问题根因：用户调起支付后长时间未完成操作（如打开微信支付页面后离开），订单一直停留在"支付中"状态，导致账单被锁定，其他缴费人无法缴纳。

解决方案：订单超时自动关闭 + 定时任务兜底清理。

落地实现：

"关单后支付"异常处理：极端情况下，订单关闭与第三方支付回调存在时间窗口冲突——订单刚关闭，用户在第三方完成了支付。处理策略：

1. 关单前查询第三方支付状态，确认未支付才执行关单。
2. 如果关单后仍收到支付成功回调，执行"补单"流程——恢复订单状态为 PAID，回写账单状态为已缴，发送缴费成功通知。补单通过幂等设计保证安全。

11.5 支付回调可靠性（P6）

问题根因：第三方支付平台（微信/支付宝）通过 HTTP 回调通知支付结果，但回调可能因网络抖动而丢失、延迟或重复推送。如果回调处理不当，会导致"用户已付款但系统未入账"或"重复入账"。

解决方案：回调幂等 + 主动查询补偿 + 回调重试确认。

落地实现：

11.6 事务消息回查容错（P7）

问题根因：收费服务通过 RocketMQ 事务消息发送 payment-success 事件，但发送半消息后如果服务宕机（本地事务执行中断、Commit/Rollback 未送达），Broker 需要回查本地事务状态。如果回查接口本身也不可用，消息状态将不确定。

解决方案：回查接口高可用部署 + 本地事务状态可追溯 + 超时兜底。

落地实现：

11.7 消息消费失败处理（P8/P9）

问题根因：payment-success 消息的三个消费者（发票服务、通知服务、数据分析服务）可能因各自原因消费失败：发票服务对接的税务系统故障、通知服务的短信网关不可用、数据分析服务的 ETL 任务异常。

解决方案：消费失败自动重试 + 死信队列兜底 + 对账任务补偿。

落地实现：

死信队列管理看板：平台开发了独立的死信管理看板，展示：

• 各消费组死信积压数量和趋势
• 死信消息内容和失败原因分类
• 一键重发功能（修复底层问题后批量重发）
• 死信超 10 条 P1 告警、超 50 条 P0 告警

11.8 缴费高峰期高并发架构（P1/P10）

问题根因：供热季首月日均缴费量可达平时的 10-20 倍，瞬时 QPS 从平时的 50 飙升至 1000+。如果不做容量规划和流量治理，单服务过载会通过调用链传导至依赖服务，引发全局雪崩。

整体方案：全链路压测定容量 → 分层限流控入口 → 弹性伸缩扩容量 → 降级保核心 → 削峰填谷平滑流量。

11.8.1 全链路压测与容量规划

上线前通过全链路压测确定各服务的容量上限，制定扩容基线：

压测方式：使用 JMeter 模拟用户缴费全流程（查询账单→创建订单→模拟支付回调→验证通知），逐步加压至预估峰值的 1.5 倍，观察各服务的 CPU、内存、RT、错误率，找到瓶颈点。

预热扩容：供热季开始前一周，通过 Nacos 配置将收费服务和支付服务的最小副本数从 2 调整为 5，提前扩容避免高峰期冷启动延迟。

11.8.2 分层限流策略

限流后的用户体验：被限流的请求返回 HTTP 429 + 友好提示"当前缴费人数较多，请稍后重试"。前端收到 429 后自动延迟 3s 重试，最多重试 3 次。如果持续被限流，引导用户切换至线下缴费渠道（银行代扣、营业厅）。

11.8.3 弹性伸缩

K8s HPA 配置基于 CPU 和自定义指标的自动伸缩：

# 收费服务 HPA 配置示例
apiVersion: autoscaling/v2
kind: HorizontalPodAutoscaler
metadata:
  name: charge-service-hpa
spec:
  scaleTargetRef:
    apiVersion: apps/v1
    kind: Deployment
    name: charge-service
  minReplicas: 2
  maxReplicas: 10
  metrics:
  - type: Resource
    resource:
      name: cpu
      target:
        type: Utilization
        averageUtilization: 60
  - type: Pods
    pods:
      metric:
        name: http_requests_per_second
      target:
        type: AverageValue
        averageValue: "150"
  behavior:
    scaleUp:
      stabilizationWindowSeconds: 30
      policies:
      - type: Percent
        value: 100
        periodSeconds: 30
    scaleDown:
      stabilizationWindowSeconds: 300

伸缩策略要点：

11.8.4 降级策略

高峰期对非核心服务执行降级，保障缴费主链路：

降级原则：

• 降级只影响非核心功能，缴费主流程（创建订单→支付→入账）不降级。
• 降级动作通过 Sentinel 规则自动触发，规则存储在 Nacos 中动态推送。
• 降级期间向用户明确提示（如"发票将在 24 小时内开具"），管理预期。

11.8.5 数据库高并发优化

11.8.6 削峰填谷

利用 RocketMQ 消息队列平滑峰值流量：

削峰效果：缴费高峰期收费服务以 1000 QPS 处理核心入账逻辑（同步），下游的发票开具、通知发送、数据同步通过 MQ 异步处理，消费者按自身能力匀速消费（200/500/100 QPS），避免瞬时 2000 QPS 直接打垮下游服务。MQ 积压在可接受范围内（通知延迟 < 1 分钟），高峰过后积压逐步消化。

11.9 第三方支付渠道不可用容灾（P5）

问题根因：微信、支付宝等第三方支付渠道可能因系统故障、维护或网络问题不可用，导致用户无法完成在线支付。

解决方案：多渠道兜底 + 降级引导 + 渠道健康检查。

落地实现：

11.10 缴费高峰期保障预案

应急缴费通道：极端情况下（如机房级故障），启动应急通道——用户在小程序提交缴费申请，系统仅记录缴费意向（不调用支付和入账），恢复后后台批量处理。此方案牺牲实时性，但保证用户"已经提交缴费"的业务凭证，避免因系统故障导致用户产生滞纳金。

11.11 缴费链路全链路监控

全链路看板：Grafana 缴费实时看板展示从请求入口到消息消费的完整链路状态，任一节点标红即表示该节点异常，运维可快速定位故障点。SkyWalking 链路追踪支持按 TraceID 查询单笔缴费的完整调用链，用于问题排查。

12. 分布式事务管理

微服务架构下，每个服务拥有独立数据库，一次业务操作往往跨越多个服务和数据源。传统的本地事务（ACID）无法直接覆盖跨服务场景，分布式事务成为平台必须正面解决的核心工程问题。本章先梳理平台各业务场景的事务流转特征与潜在问题，再给出方案选型、落地实现和兜底保障。

12.1 跨服务事务流转全景

平台六大业务场景中，有四个场景涉及跨服务数据写入，需要分布式事务保障一致性。下图展示各场景的事务流转路径与参与方：

12.2 分布式事务面临的核心问题

跨服务事务流转中，以下七类问题在供热收费平台的实际运行中真实存在，必须逐一覆盖：

12.2.1 跨服务数据不一致

问题描述：缴费场景中，收费服务创建缴费订单（charge_db）和计费账单服务回写账单状态（billing_bill_db）分属两个数据库。如果收费订单创建成功但账单回写失败，用户已付款但账单仍显示"待缴"，可能导致重复缴费。反之，账单已标记"已缴"但收费订单未创建，则缺少缴费凭证。

影响范围：直接导致资金账务与业务账单脱节，引发用户投诉和财务对账困难。

12.2.2 网络分区导致的事务悬挂

问题描述：Seata AT 模式下，TC（事务协调者）通知分支提交/回滚时，如果网络分区导致通知无法到达某个分支服务，该分支的 undo_log 记录将长期悬挂——本地事务已执行但全局事务状态不确定。后续如果 TC 恢复并触发回滚，分支根据 undo_log 执行反向 SQL，但如果期间数据已被其他事务修改，回滚可能失败或产生脏数据。

影响范围：undo_log 积压影响数据库性能，数据状态不确定影响业务正确性。

12.2.3 事务超时与长事务

问题描述：Seata AT 模式默认全局事务超时 60s。在缴费高峰期，如果计费账单服务因数据库压力增大导致账单回写响应变慢，全局事务可能超时。超时后 TC 自动回滚全局事务，但此时收费订单的本地事务可能已经提交——用户已付款，但订单被回滚，资金丢失。

影响范围：高峰期高频出现，直接导致资金损失。

12.2.4 消息与本地事务的原子性

问题描述：缴费成功后，收费服务需要同时完成两个操作——更新收费记录状态为"已缴费"（本地事务）和发送 payment-success 消息（通知下游开票和通知）。如果先提交本地事务再发消息，消息发送失败则下游收不到通知；如果先发消息再提交本地事务，本地事务失败则下游收到错误通知。两者无法保证同时成功。

影响范围：下游服务状态与主业务不一致，发票漏开或通知漏发。

12.2.5 并发事务的全局锁冲突

问题描述：Seata AT 模式通过全局锁保证分支事务间的写隔离。当多个全局事务同时修改同一账单行时，后到达的事务需等待前一个事务释放全局锁。缴费高峰期，大量用户同时缴费可能导致全局锁等待超时，事务频繁回滚重试，吞吐量急剧下降。

影响范围：高峰期缴费成功率下降，用户体验恶化。

12.2.6 TCC 空回滚与悬挂

问题描述：TCC 模式下，Try 阶段因网络超时未执行，TC 误判 Try 失败触发 Cancel，但延迟的 Try 请求随后到达并执行——此时 Cancel 已执行但 Try 又预留了资源，资源永久悬挂无人释放。反过来，如果 Cancel 先于 Try 到达，Cancel 执行了补偿但 Try 随后执行了资源预留，预留的资源同样无人释放。

影响范围：退费场景中收费记录状态错乱，"退费中"状态永久卡住。

12.2.7 Saga 流程中断后的恢复

问题描述：开户 Saga 流程涉及用户服务、房产服务、合同服务三步。如果第二步（房产绑定）执行成功后第三步（合同生成）失败，Saga 需要逆序执行补偿（解绑房产→注销用户）。但如果补偿过程中服务再次宕机，Saga 流程中断在中间状态——用户档案已创建但房产绑定未解绑，数据处于半成品状态。

影响范围：开户失败但残留脏数据，影响后续重新开户。

12.3 分布式事务方案选型矩阵

平台根据各业务场景的事务特征（一致性要求、事务时长、参与方数量、是否涉及外部系统），选择差异化的分布式事务方案：

12.4 Seata AT 模式落地实现

12.4.1 适用场景与架构

Seata AT 模式用于缴费入账场景——收费服务创建缴费订单并调用计费账单服务回写账单状态，两步操作必须原子性完成。AT 模式对业务代码侵入性最小，只需添加 @GlobalTransactional 注解。

flowchart TB
    subgraph TM 事务管理器
        TM1[收费服务<br/>@GlobalTransactional]
    end
    subgraph TC 事务协调者
        TC1[Seata Server<br/>3节点集群]
    end
    subgraph RM 资源管理器
        RM1[收费服务<br/>charge_db<br/>undo_log表]
        RM2[计费账单服务<br/>billing_bill_db<br/>undo_log表]
    end
    subgraph 存储
        DB[(Seata MySQL<br/>global_table<br/>branch_table<br/>lock_table)]
    end

    TM1 -->|1.开启全局事务获取XID| TC1
    TM1 -->|2.分支注册| TC1
    TC1 --> DB
    TM1 -->|3.执行本地事务| RM1
    RM1 -->|记录undo_log| RM1
    TM1 -->|4.RPC传递XID| RM2
    RM2 -->|5.执行本地事务| RM2
    RM2 -->|记录undo_log| RM2
    RM2 -->|6.分支注册| TC1
    TM1 -->|7.全局提交/回滚| TC1
    TC1 -->|8.通知分支| RM1 & RM2

12.4.2 缴费入账 AT 模式完整流程

支付回调后的入账流程：支付成功回调到达后，收费服务在 Seata 全局事务内执行：分支1 更新缴费订单状态为"已缴费"（charge_db），分支2 更新账单状态为"已缴"（billing_bill_db）。全局事务提交后，再通过 RocketMQ 事务消息发送 payment-success 事件触发下游异步操作。

12.4.3 undo_log 表设计与回滚机制

每个参与 AT 模式的数据库中需创建 undo_log 表：

CREATE TABLE `undo_log` (
    `branch_id`     BIGINT       NOT NULL COMMENT '分支事务ID',
    `xid`           VARCHAR(128) NOT NULL COMMENT '全局事务ID',
    `context`       VARCHAR(128) NOT NULL COMMENT '上下文',
    `rollback_info` LONGBLOB     NOT NULL COMMENT '回滚信息（before/after image）',
    `log_status`    INT          NOT NULL COMMENT '状态：0-正常 1-全局已完成',
    `log_created`   DATETIME     NOT NULL COMMENT '创建时间',
    `log_modified`  DATETIME     NOT NULL COMMENT '修改时间',
    UNIQUE KEY `ux_undo_log` (`xid`, `branch_id`)
) ENGINE=InnoDB COMMENT='AT模式undo_log表';

回滚机制：当全局事务回滚时，TC 通知各分支执行回滚。分支从 undo_log 中读取 before_image（变更前数据快照），生成反向 SQL（INSERT→DELETE、UPDATE→反向 UPDATE、DELETE→INSERT）执行回滚。回滚完成后删除 undo_log 记录。

before_image / after_image 示例（账单状态回写场景）：

{
  "before_image": {
    "table": "bill",
    "id": 123,
    "status": "UNPAID",
    "version": 1
  },
  "after_image": {
    "table": "bill",
    "id": 123,
    "status": "PAYING",
    "version": 2
  },
  "rollback_sql": "UPDATE bill SET status='UNPAID', version=1 WHERE id=123 AND version=2"
}

12.4.4 全局锁机制与写隔离

AT 模式通过全局锁实现分支事务间的写隔离，保证在全局事务未完成期间，其他全局事务不能修改同一行数据：

写隔离效果：用户 A 缴费时，账单行被全局锁锁定。用户 B 尝试缴费同一账单时，分支2（账单回写）需获取全局锁，发现已被用户 A 的事务锁定，等待超时后全局事务回滚，用户 B 收到"账单正在缴费中"提示。

12.4.5 超时与异常处理

超时调优：默认全局事务超时 60s，但缴费场景的正常耗时不超过 3s。平台将超时调整为 30s，留出充足的异常重试余量，同时避免长事务占用全局锁。高峰期如果出现超时频繁，临时调整至 60s 并排查慢 SQL。

12.5 TCC 模式落地实现

12.5.1 适用场景与设计

TCC 模式用于退费场景——收费记录需要从"已缴费"流转到"退费中"再到"已退费"，涉及外部退款接口调用，需要精细化控制补偿逻辑。AT 模式只能按 undo_log 快照回滚，无法表达"退费中→已缴费"这种业务语义的补偿。

退费 TCC 三阶段设计：

12.5.2 TCC 实现

// 退费TCC接口定义
@LocalTCC
public interface RefundTccAction {

    @TwoPhaseBusinessAction(name = "refundTccAction",
        commitMethod = "confirmRefund",
        rollbackMethod = "cancelRefund")
    boolean prepareRefund(BusinessActionContext ctx,
                          @BusinessActionContextParameter(paramName = "chargeId") Long chargeId,
                          @BusinessActionContextParameter(paramName = "refundAmount") BigDecimal refundAmount);

    boolean confirmRefund(BusinessActionContext ctx);

    boolean cancelRefund(BusinessActionContext ctx);
}

// Try 阶段实现
@Transactional
public boolean prepareRefund(BusinessActionContext ctx, Long chargeId, BigDecimal refundAmount) {
    // 幂等检查：防止悬挂（Cancel先于Try到达）
    RefundRecord existing = refundRecordMapper.findByXid(ctx.getXid());
    if (existing != null) {
        return true; // 已执行过Try
    }

    ChargeRecord record = chargeMapper.selectById(chargeId);
    if (record.getStatus() != ChargeStatus.PAID) {
        throw new RuntimeException("收费记录状态不允许退费");
    }

    // 状态流转：PAID → REFUNDING
    int affected = chargeMapper.updateStatusWithVersion(
        chargeId, ChargeStatus.REFUNDING, record.getVersion());
    if (affected == 0) {
        throw new RuntimeException("状态更新失败，可能被并发修改");
    }

    // 记录TCC事务状态（防悬挂+幂等）
    refundRecordMapper.insert(new RefundRecord(
        ctx.getXid(), chargeId, refundAmount, TccPhase.TRY));
    return true;
}

// Confirm 阶段实现
@Transactional
public boolean confirmRefund(BusinessActionContext ctx) {
    Long chargeId = (Long) ctx.getActionContext("chargeId");
    RefundRecord record = refundRecordMapper.findByXid(ctx.getXid());

    // 幂等检查
    if (record.getPhase() == TccPhase.CONFIRM) {
        return true; // 已确认
    }

    // 状态流转：REFUNDING → REFUNDED
    chargeMapper.updateStatus(chargeId, ChargeStatus.REFUNDED);
    refundRecordMapper.updatePhase(ctx.getXid(), TccPhase.CONFIRM);
    return true;
}

// Cancel 阶段实现
@Transactional
public boolean cancelRefund(BusinessActionContext ctx) {
    Long chargeId = (Long) ctx.getActionContext("chargeId");
    RefundRecord record = refundRecordMapper.findByXid(ctx.getXid());

    // 空回滚检查：Try未执行但Cancel被调用
    if (record == null) {
        // 记录空回滚标记，防止后续Try到达时悬挂
        refundRecordMapper.insert(new RefundRecord(
            ctx.getXid(), chargeId, BigDecimal.ZERO, TccPhase.CANCEL));
        return true;
    }

    // 幂等检查
    if (record.getPhase() == TccPhase.CANCEL) {
        return true; // 已取消
    }

    // 状态回滚：REFUNDING → PAID
    chargeMapper.updateStatus(chargeId, ChargeStatus.PAID);
    refundRecordMapper.updatePhase(ctx.getXid(), TccPhase.CANCEL);
    return true;
}

12.5.3 空回滚与悬挂防护

12.6 Saga 模式落地实现

12.6.1 适用场景与流程定义

Saga 模式用于开户流程和停复供流程——多步骤长流程，每步可定义补偿动作。平台采用 Seata Saga 状态机引擎，通过 JSON 定义流程编排。

开户 Saga 流程：

Saga JSON 定义：

{
  "Name": "userOpenAccountSaga",
  "Comment": "用户开户Saga流程",
  "StartState": "createUser",
  "States": {
    "createUser": {
      "Type": "ServiceTask",
      "ServiceName": "userServiceImpl",
      "ServiceMethod": "createUser",
      "CompensateState": "cancelUser",
      "Next": "bindProperty"
    },
    "bindProperty": {
      "Type": "ServiceTask",
      "ServiceName": "propertyServiceImpl",
      "ServiceMethod": "bindUserProperty",
      "CompensateState": "unbindProperty",
      "Next": "generateContract"
    },
    "generateContract": {
      "Type": "ServiceTask",
      "ServiceName": "contractServiceImpl",
      "ServiceMethod": "generateContract",
      "CompensateState": "voidContract",
      "Next": "succeed"
    },
    "cancelUser": {
      "Type": "ServiceTask",
      "ServiceName": "userServiceImpl",
      "ServiceMethod": "cancelUser"
    },
    "unbindProperty": {
      "Type": "ServiceTask",
      "ServiceName": "propertyServiceImpl",
      "ServiceMethod": "unbindUserProperty"
    },
    "voidContract": {
      "Type": "ServiceTask",
      "ServiceName": "contractServiceImpl",
      "ServiceMethod": "voidContract"
    },
    "succeed": {
      "Type": "Succeed"
    }
  }
}

12.6.2 Saga 状态持久化与恢复

Saga 引擎将流程执行状态持久化到 seata_saga_log 表，确保服务宕机后可恢复：

CREATE TABLE `seata_saga_log` (
    `id`              BIGINT       NOT NULL AUTO_INCREMENT,
    `saga_id`         VARCHAR(128) NOT NULL COMMENT 'Saga实例ID',
    `state_name`      VARCHAR(128) NOT NULL COMMENT '当前状态名',
    `state_type`      VARCHAR(32)  NOT NULL COMMENT '状态类型：ServiceTask/Succeed',
    `business_key`    VARCHAR(128) COMMENT '业务键（如用户编号）',
    `status`          VARCHAR(32)  NOT NULL COMMENT '执行状态：RU-运行 SU-成功 FA-失败 CO-补偿',
    `input_params`    TEXT COMMENT '输入参数',
    `output_params`   TEXT COMMENT '输出参数',
    `exception`       TEXT COMMENT '异常信息',
    `created_at`      DATETIME     NOT NULL,
    `updated_at`      DATETIME     NOT NULL,
    PRIMARY KEY (`id`),
    INDEX `idx_saga_id` (`saga_id`),
    INDEX `idx_status` (`status`)
) ENGINE=InnoDB COMMENT='Saga状态日志表';

中断恢复机制：

12.6.3 停复供 Saga 流程

停复供场景的 Saga 流程涉及物理设备操作（阀门控制），补偿逻辑有特殊性——阀门控制失败不能回滚费用调整（用户已获批停供），而是转为人工处理：

关键设计：费用调整在审批通过后立即生效并持久化，阀门控制作为独立步骤——即使阀门控制失败，费用已按停供计算，不会因设备故障导致用户多缴费用。阀门控制失败转人工处理后，Saga 标记为"部分完成"，不触发费用调整的补偿。

12.7 可靠消息事务落地实现

12.7.1 RocketMQ 事务消息

事务消息用于缴费成功后的异步操作——确保"收费记录更新"（本地事务）与"payment-success 消息发送"的原子性。

transaction_log 表设计：

CREATE TABLE `transaction_log` (
    `xid`           VARCHAR(128) NOT NULL COMMENT '事务ID（与MQ msgId关联）',
    `business_key`  VARCHAR(128) NOT NULL COMMENT '业务键（如缴费订单号）',
    `status`        VARCHAR(32)  NOT NULL COMMENT 'STARTED-已开始 COMMITTED-已提交 ROLLED_BACK-已回滚',
    `created_at`    DATETIME     NOT NULL,
    `updated_at`    DATETIME     NOT NULL,
    PRIMARY KEY (`xid`),
    INDEX `idx_business_key` (`business_key`),
    INDEX `idx_status` (`status`)
) ENGINE=InnoDB COMMENT='事务消息本地状态表';

回查接口实现：

public class PaymentTransactionListener implements TransactionListener {

    @Override
    public LocalTransactionState executeLocalTransaction(Message msg, Object arg) {
        String xid = msg.getTransactionId();
        String orderId = msg.getKeys();
        try {
            // 写入事务状态（STARTED）
            transactionLogMapper.insert(new TransactionLog(xid, orderId, "STARTED"));
            // 执行本地事务
            chargeService.confirmPayment(orderId);
            // 更新事务状态（COMMITTED）
            transactionLogMapper.updateStatus(xid, "COMMITTED");
            return LocalTransactionState.COMMIT_MESSAGE;
        } catch (Exception e) {
            transactionLogMapper.updateStatus(xid, "ROLLED_BACK");
            return LocalTransactionState.ROLLBACK_MESSAGE;
        }
    }

    @Override
    public LocalTransactionState checkLocalTransaction(MessageExt msg) {
        String xid = msg.getTransactionId();
        TransactionLog log = transactionLogMapper.findByXid(xid);
        if (log == null) {
            // 事务未开始，回滚
            return LocalTransactionState.ROLLBACK_MESSAGE;
        }
        switch (log.getStatus()) {
            case "COMMITTED":
                return LocalTransactionState.COMMIT_MESSAGE;
            case "ROLLED_BACK":
                return LocalTransactionState.ROLLBACK_MESSAGE;
            default:
                // STARTED 状态：本地事务可能还在执行中，返回未知让Broker稍后再查
                return LocalTransactionState.UNKNOW;
        }
    }
}

12.7.2 本地消息表方案

本地消息表用于数据同步场景——将各业务服务的数据变更可靠地同步至数据仓库。与事务消息不同，本地消息表不需要 RocketMQ 事务消息支持，通过本地事务+定时任务实现：

本地消息表设计：

CREATE TABLE `local_message` (
    `id`             BIGINT       NOT NULL AUTO_INCREMENT,
    `message_id`     VARCHAR(64)  NOT NULL COMMENT '消息唯一ID',
    `topic`          VARCHAR(128) NOT NULL COMMENT 'MQ Topic',
    `tag`            VARCHAR(64)  COMMENT 'MQ Tag',
    `body`           TEXT         NOT NULL COMMENT '消息体（JSON）',
    `status`         VARCHAR(32)  NOT NULL COMMENT 'PENDING-待发送 SENT-已发送 FAILED-发送失败',
    `retry_count`    INT          DEFAULT 0 COMMENT '重试次数',
    `next_retry_at`  DATETIME     COMMENT '下次重试时间',
    `created_at`     DATETIME     NOT NULL,
    `updated_at`     DATETIME     NOT NULL,
    PRIMARY KEY (`id`),
    UNIQUE KEY `uk_message_id` (`message_id`),
    INDEX `idx_status_retry` (`status`, `next_retry_at`)
) ENGINE=InnoDB COMMENT='本地消息表';

工作流程：

12.8 对账兜底体系

无论采用哪种分布式事务方案，平台均部署全链路对账任务作为最终兜底，确保数据一致性：

12.9 分布式事务监控

Seata 事务大盘：Grafana 看板展示全局事务 QPS、成功率、平均耗时、超时率、分支回滚率趋势。按服务维度下钻，可查看各服务的分支事务状态分布。异常事务列表展示 XID、参与服务、失败原因，支持一键跳转 SkyWalking 查看 TraceID 对应的完整调用链。

12.10 分布式事务设计规范