# ERP 同步中途失败，最难的是安全重试

> 幂等键、事务性发件箱和三方对账，让客户的账目在期末结账时分毫不差。

原文: https://fdetimes.net/zh/guides/safe-retries-erp-accounting-sync/

期末结账第三天，客户的总会计师发来一张截图：ERP 里同一笔打款有两条一模一样的分录，前一天的打款却不见踪影。代码没有崩溃过，日志里写的是“timeout, retrying”，接着是“success”。

为大客户做会计集成的前线部署工程师（FDE）对这种情况并不陌生。对财务团队来说，重复分录不是小 bug：只要有一个数字对不上，他们就不会在账目上签字。

一周时间足以做出一个漂亮的同步演示，但要让客户信任你的系统，它必须在成千上万次网络抖动中始终正确。

决定 ERP 集成质量的有三个问题：交易会不会丢？会不会记两次？中途失败时，账目处于什么状态？再加上客户真正关心的第四个：怎么证明两边一致？

## 交易在到达 ERP 之前丢失

第一类故障出在自己的服务内部。服务先把交易存进数据库，然后才发出“需要同步”的事件。如果进程恰好在这两步之间退出，记录已经存在，却没人通知同步 worker。Microsoft 把这称为双写问题。

解决办法是事务性发件箱（Transactional Outbox）：把交易和事件写入 outbox 表，并放在*同一个*数据库事务里。Microsoft 的架构文档指出，当业务对象及其事件在同一事务中保存时，系统可以保证不丢数据。

worker 只需读取 outbox，把条目推送到 ERP。无论进程在何时退出，都不会留下缺口。

## 为什么一次重试会多出一条分录？

回到那张截图。设想这样的过程：worker 发送一条分录，ERP 已经入账，但响应在返回途中丢了。worker 看到超时，于是再发一次。ERP 并不知道这是同一个请求，又记了一条。

Stripe 用幂等键解决这个问题。客户端在创建或更新请求上附带一个键，发生连接错误时可以放心重发，不用担心生成第二个对象或把同一次更新执行两遍。

在 API v1 中，服务端会保存某个键的第一次响应，之后的每次重试都原样返回这个响应，即使第一次响应是 `500` 错误。

Stripe 的文档还补充了两个细节：键由客户端生成，至少保留 24 小时后删除；用同一个键搭配不同参数的请求会被拒绝，以便发现误用。

这两个细节引出两条规则。第一，键必须从稳定的业务 ID 派生（例如 `erp-journal:po_123`），绝不能每次发送都用 `uuid4()` 生成，因为随机键会让重试看起来像一个新请求。

第二，键会过期，而且并非所有 ERP 都提供这种机制，所以不能把去重完全交给 ERP。你必须自己维护一张从键到 ERP 记录 ID 的映射表，更重要的是，要在首次发送*之前*写入这一行，而不是等响应回来之后。

## 一个写对了的打款同步 worker

假设每天夜里要把打款推送到 NetSuite。根据 Oracle 的文档，超过并发上限时，NetSuite REST Web Services 会返回 HTTP 429，错误码为 `CONCURRENCY_LIMIT_EXCEEDED`，消息为“Concurrent request limit exceeded. Request blocked.”

Oracle 建议重新发送请求，重试逻辑由你的代码实现。下面的代码使用一个假设的 `erp` 封装，其中有一个按外部 ID 查询分录的函数：

```python
def sync_payout(payout_id):
    key = f"erp-journal:{payout_id}"         # 来自业务 ID，而不是随机生成
    row = mapping.get(key)
    if row and row.erp_id:
        return row.erp_id                     # 已确认入账：不再重发
    if row is None:
        mapping.save_pending(key)             # 在首次发送之前写入“待处理”
    for attempt in range(6):
        found = erp.find_by_external_id(key)  # 之前的某次发送可能已经入账
        if found:
            mapping.confirm(key, found.id)
            outbox.mark_done(payout_id)
            return found.id
        try:
            resp = erp.post_journal(build_payload(payout_id),
                                    external_id=key, idempotency_key=key)
        except Timeout:                       # 不确定 ERP 是否已经入账
            sleep(min(2 ** attempt, 60) + random())
            continue                          # 下一轮循环会在发送前再查一次
        if resp.status == 429:                # CONCURRENCY_LIMIT_EXCEEDED：瞬时错误
            sleep(min(2 ** attempt, 60) + random())
            continue
        resp.raise_for_status()
        mapping.confirm(key, resp.id)         # 先确认映射，再清理 outbox
        outbox.mark_done(payout_id)
        return resp.id
    alert_oncall(payout_id, key)              # 重试次数用完：交给人工处理
```

用这段代码重演那天夜里的情况。发送之前，worker 已经为这个键写了一条“待处理”记录。第一次发送超时，但 ERP 实际上已经入账。worker 捕获 `Timeout` 异常，等待退避时间，进入下一轮循环。

下一轮循环的第一件事不是重发，而是问 ERP：带这个外部 ID 的分录是否已经存在？答案是存在，于是 worker 只确认映射，然后结束。如果 ERP 支持幂等性，同一个键还能再加一层保护，但这个设计并不依赖它。

进程直接退出、三天后才重启时，“待处理”记录同样重要：worker 看到一条未确认的记录，就一定会先查 ERP 再发送。唯一的前提是把键存进分录上一个可搜索的外部 ID 字段，这个字段应在第一周就和客户商定。

## 第二步失败了，第一步怎么办？

一笔真实的打款通常要跨几个系统走好几步：创建收入记录、过账分录、标记为已付。没有哪个 ACID 事务能同时覆盖你的平台和 ERP。Saga 模式用一串本地事务来代替：某一步失败时，由一系列补偿事务撤销前面各步的操作。

Saga 中有一个概念叫 pivot 事务，即不可回退点。pivot 之后的步骤必须可重试且幂等，这样即使遇到瞬时错误，saga 也总能到达最终状态。在 ERP 过账流程中，已入账的分录通常就是 pivot。

具体到每个客户，原因最好当作待验证的假设：问问总会计师，分录出错时是直接修改，还是必须做一笔冲销分录。如果它确实是不可回退点，过了这一步就只能向前走。

Microsoft 给出了很实用的优先顺序：先重试瞬时错误；只有某一步反复失败或无法恢复时，才停止并触发补偿；有些失败需要告警，让人来介入。补偿步骤本身也可能失败，所以必须写成可以重跑的幂等命令。

在会计领域，最重要的要求是可审计。Microsoft 要求原始操作和补偿操作能够关联起来，并且可以端到端审计。给原始分录、补偿分录和日志附上同一个关联 ID，审计人员只需一次搜索就能追溯整条链路。

## 对账是证据，不是额外工作

同步正确还不够，客户需要看到证据。Stripe 的银行对账模型是个很好的模板：每笔打款通过共享的参考键与对应的银行入账匹配，然后标记为 Reconciled（已对账）或 Unreconciled（未对账）。把这个模型扩展成三方：平台、ERP 和银行流水，共用一个键。

最大的陷阱是把时间差当成真正的错误。Stripe 的示例提到，银行通常不在周日入账打款，所以示例中 2 月 4 日（周日）的金额单元格是空的。

如果报告把这类行都标成错误，财务团队就会淹没在误报里，不再信任这份报告。

| 类别 | 信号 | 处理 |
|---|---|---|
| 已匹配 | 三方都有，金额一致 | 无需处理 |
| 时间差 | 平台和 ERP 中都有，银行尚未入账 | 等待，结算周期后再核对 |
| 真正的不一致 | 超过截止时间仍有一方缺失，或金额不同 | 建工单，按关联 ID 追查 |

**要点:** 同步正确还不够：客户需要一份对账报告，证明每一分钱都对得上。

## 从零搭建，按什么顺序？

到了新客户那里，第一件事是和总会计师坐下来，问清楚哪一步是不可回退点、出错时如何更正。答案会告诉你 pivot 在哪里，补偿步骤应该是什么样子。

接着在数据库里建好 outbox，基于业务 ID 为每一步定义键，选定 ERP 中存放键的外部 ID 字段，再写一个对瞬时错误带重试和退避的 worker。

之后才轮到补偿和告警。对账应从第一周就开始跑，而不是等到期末：上面这份三类报告，是赶在客户之前发现设计缺陷的最快办法。

## 让财务团队失去信任的错误

最常见的错误是每次发送都生成随机键，幂等性因此形同虚设。紧随其后的是只在响应成功后才写映射，于是恰恰在超时那一刻，映射表是空的。再就是把每个 429 或超时都当成失败，立即执行补偿，而本该先重试。

还有两个。补偿步骤不幂等，重跑一次就补偿两遍。另一个出在沟通上：把每笔尚未到账的金额都报成“不一致”。一份满是误报的报告，客户会记得比十个平稳同步的夜晚更久。

## 简历上怎么写这项技能

简历上一行“NetSuite 集成”几乎什么也说明不了。要写清楚你如何设计幂等同步、处理部分失败、搭建三方对账，以及在多少次期末结账中客户无需手工修改任何一行。

面试时，“ERP 已经入账但响应丢了”这个场景是一个简短的故事，能说明你会在故障发生之前就考虑它。

下次有人说“重试一下就行”，不妨问他：用哪个键重试？再次发送之前，问过 ERP 了吗？

**本周动手试试:**

- 打开现有的同步代码，找出所有用 uuid4() 或时间戳生成键的地方，改成由业务 ID 加步骤名组成的键。
- 写一个测试，模拟 ERP 已记录成功却返回超时，检查重试是否会生成第二条记录。
- 取最近 7 天的打款，把每一行归入三类之一：已匹配、时间差、真正的不一致。

## 信源

- [Idempotent requests | Stripe API Reference](https://docs.stripe.com/api/idempotent_requests)

- [Error Handling in REST Web Services (Oracle NetSuite Help)](https://docs.oracle.com/en/cloud/saas/netsuite/ns-online-help/section_156570709583.html)

- [Saga Design Pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/saga)

- [Compensating Transaction Pattern - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/patterns/compensating-transaction)

- [Implement the Transactional Outbox Pattern by Using Azure Cosmos DB - Azure Architecture Center | Microsoft Learn](https://learn.microsoft.com/en-us/azure/architecture/databases/guide/transactional-out-box-cosmos)

- [Bank reconciliation | Stripe Documentation](https://docs.stripe.com/reconciliation/bank-reconciliation)
