Alpaca 券商对账幂等

解决什么问题

Alpaca 交易系统本质是异步且最终一致的：写操作不会立即生效，事件可能丢失或重复，某些通道甚至不产生事件，已执行的交易也可能被撤销。如果仅依赖单次 API 调用或事件处理，本地数据库与 Alpaca 状态必然出现偏差。

核心能力

三层防御机制

1. 幂等写入：每次资金/订单操作必须可安全重试。通过自定义 client_order_id（≤128 字符）和 Idempotency-Key 头实现：超时后先查询本地意图记录，再决定是否重发请求。
2. 事件处理：订阅 Alpaca 事件流时，需结合本地数据库进行去重与状态收敛，而非假设事件按序到达或仅触发一次。
3. 对账循环：定期比对本地数据库与 Alpaca 实时状态，修复因停机、bug 或事件丢失导致的差异。

关键步骤

• 本地优先记录：发起网络请求前，先在本地写入意图记录（含生成的唯一键），确保崩溃时仍有可对账的审计痕迹。
• 重试前查询：超时后通过 orders:by_client_order_id 查询订单状态，避免重复下单。
• 跨技能协作：需先掌握 alpaca-broker-integration、alpaca-broker-sse-events 等前置技能，本技能作为架构层整合所有操作。

适用边界

• 仅适用于 Alpaca 交易系统，依赖其 API 支持幂等键和客户端订单 ID。
• 要求本地数据库具备事务能力，能存储意图记录和审计日志。
• 对账频率需根据业务容忍度调整，高频对账可能增加 API 调用成本。