用途:该技能用于让本地数据库与 Alpaca Broker API 状态保持一致,适用于需要生产级可靠性的经纪业务集成。核心原则是把 Alpaca 视为唯一事实来源,本地库视为必须收敛的缓存;每次写入只是请求而非事实,每个事件只是提示而非保证。
主要能力分三层防御。第一层幂等写入:订单使用自定义 client_order_id(≤128 字符),响应丢失时先通过 orders:by_client_order_id 查询再重试;journals 使用 Idempotency-Key 请求头,同 key 同 body 返回原 journal,同 key 不同 body 返回 422;先写本地意图行再发网络请求,并立即持久化返回的 Alpaca ID。第二层幂等事件接收:以 event_id(ULID)为唯一约束做 upsert 或跳过重复,业务记录以 Alpaca ID 为键并采用 upsert,变更前检查状态是否已终态,修改时锁定行,成功后再推进游标。第三层对账修复:定时任务重新拉取权威状态并 upsert,例如每晚对活跃账户分页拉取最近 N 天(如 3 天)的 trade/non-trade activities、journals 和 transfers,限制并发并遵守速率限制。
对无事件通道需轮询,例如 funding-wallet 转账状态需定时 GET 查询;错开轮询时间,只轮询非终态记录。经典 wire transfers 没有按 ID 查询接口,需拉取列表后在客户端匹配。
限制与注意事项:executed/COMPLETE 不一定最终,journal 可能被冲正、transfer 可能被退回;corrections 会生成新 ID;200 仅表示已接受而非已结算;事件可能乱序或重复。需为每个域定义 Alpaca 状态到内部状态的映射表,优雅处理未知状态,并识别各枚举的终态。反模式包括:SSE 重连不带 since_id 游标、把 SSE 当作唯一来源、无幂等键盲目重试、把 executed 当作不可逆、按已确认集合而非已见集合去重。
使用方式:按写入、实时消费、轮询、对账、状态映射五步组合。相关技能包括 alpaca-broker-sse-events、alpaca-broker-journals、alpaca-broker-trading-orders、alpaca-broker-funding-transfers、alpaca-broker-rate-limits-resilience。具体安装命令与代码示例资料未提供。