首页 / 数据流转 / 数据一致性机制
数据一致性机制
幂等键、Outbox、Saga、对账、补偿与时间对齐的可靠性设计。
一致性原则
- 事实分离：状态变更与证据流水分表（支付事实、告警四级事实、绑定会话/任务）。
- 跨系统不靠单次调用证明完成：支付、绑定、升级必须"本地事务 + 事件 + 对账/补偿"闭环。
- 可靠消息：业务写库与消息发布通过 Outbox 解耦，保证不丢不重。
幂等键
| 场景 | 幂等键/唯一约束 |
|---|---|
| 设备绑定 | iot_binding_task：租户内 task_no、pay_order_no、未完成 session/pre-bind/device guard |
| 支付尝试 | pay_payment_attempt：公开 attempt ID、客户端幂等键、提供商幂等键 |
| 支付订单 | pay_order：租户订单号、app_id + merchant_order_id |
| 订阅 Seat | subscription_seat：已占用 session/device guard（+ 状态判断） |
| SIM 回调 | 回调幂等键 + 状态检查 |
Outbox 可靠发布
- 业务写库与 Outbox 写入同一本地事务
- Job 定时扫描 Outbox（如
PayOutboxPublishJob、IotBindingOutboxJob、SubscriptionBindingOutboxJob、GpsReportOutboxPublishJob） - 消息发布成功后标记已发；失败重试，记录发布状态
Saga 长事务
典型：设备绑定 + 权益分配。各服务本地事务 + 事件串联，失败走补偿：
iot 绑定任务 → subscription Seat 预占 → pay 支付（可选）→ subscription 激活
→ iot 完成绑定；任一步失败 → subscription Seat 释放（补偿）事件：entrax-subscription-binding-saga-v1（统一 Topic + Tag 事件类型 + 契约常量）。
对账与补偿
| 机制 | 适用 | 说明 |
|---|---|---|
| 支付对账 | pay | 以提供商流水核对订单/结算，差异生成 case |
| 未知状态恢复 | pay | 超时未回调主动查询恢复 |
| 绑定重试 | iot | IotBindingRetryJob 重试失败任务 |
| SIM 绑定对账 | sim | SimBindingReconcileController 核对两侧 |
| GPS 报表补偿 | prod-gps | gpsReportScheduleRetryJob 重投生成 Outbox |
时间对齐
- 设备时间、服务端接收时间、时区偏移分开存储；跨设备/报表使用统一时间基准。
- 离线补传按设备时间戳排序入库，避免影响行程切分与里程计算。
- 报表计划按用户/设备时区规则生成（XXL-JOB 只控制 UTC 扫描频率，实际时区在数据库计划行）。