Alpaca 券商对账与幂等

为什么 Alpaca 集成需要这套架构

Alpaca 是一个异步、最终一致的系统。你发起交易或转账后，写入不会立刻结算；事件可能丢失、重放，某些通道甚至根本不推送事件；你以为已完成的操作，可能因为对账或修正而被反转。

在这种环境下，把本地数据库当作 Alpaca 状态的忠实镜像，远比"调用成功就算完成"复杂。任何对单次调用或单个事件"恰好一次"的假设，在生产环境都会失效。

三层防御，让本地状态自愈

这套技能的核心是三层防御架构，保证本地状态始终收敛到 Alpaca 的源真相：

• Layer 1 幂等写入：每个涉及资金或订单的写操作都必须可安全重试。订单使用自定义 client_order_id（由本地事务 ID 派生），journal 调用携带 Idempotency-Key 头。超时后先查询再重试，避免双重资金移动。
• Layer 2 幂等事件接收：SSE 事件是 at-least-once 的。以 event_id 做 upsert 去重，以 Alpaca ID 作为业务记录键，处理前先检查当前状态，并对行加锁，重复事件才不会触发重复业务动作。
• Layer 3 对账自愈任务：定时从 Alpaca 拉取权威状态并 upsert 回本地。移动窗口策略（例如每晚回看最近 3 天）能吸收修正、延迟结算和部署期间丢失的事件，无需每次全量重扫历史。

没有事件的地方必须轮询

并非所有通道都有 SSE 推送。资金钱包转账状态（GET /v1beta/.../funding_wallet/transfers/{id}）必须轮询。错开轮询时间可分散 API 压力，且只为非终止状态的记录建轮询队列。

注意：经典电汇转账没有按 ID 查询的接口，必须拉列表后在客户端匹配 ID。

状态映射与最终一致性陷阱

Alpaca 暴露多个状态枚举，各有各的词汇表。不要在应用里散落原始状态字符串，应定义统一映射表，对未知状态记录日志并跳过，而不是崩溃。

需要警惕的陷阱：executed / COMPLETE 未必是终态，journal 可能被撤销、转账可能被退回；修正会生成新 ID，原地改原记录的逻辑会失效；200 只代表已接收，不代表已结算。

适用边界

这套架构适合需要高可靠性资金操作的场景，尤其是异步结算、事件可能丢失或重复、存在人工修正流程的券商集成。它不解决业务逻辑本身的正确性问题——你仍需定义清晰的内部状态机，它提供的是让状态可靠同步的基础设施。