Alpaca券商日志

解决什么问题

Alpaca 券商账户体系里，资金在慢速银行通道上跑，但产品体验要求「秒到账」。Journals 机制解决的是这个矛盾：在你自己的 omnibus 账户内部，把预先归集到 firm/sweep 账户的钱或股票，瞬间划转到用户账户。典型场景是 instant funding、cashback 和注册送股。它只动内部账本，不触碰外部银行世界——那是 alpaca-broker-funding-transfers 的职责。

核心能力

• 两种 entry_type：JNLC 走现金，firm ↔ user 双向；JNLS 走证券，仅 firm → user，用于送股奖励。
• 端点：POST /v1/journals 单笔、POST /v1/journals/batch 一对多（仅 JNLC）、POST /v1/journals/reverse_batch 多对一（仅 JNLC）、GET 查询与 DELETE 取消。
• 批量是全有或全无：任何一个条目校验失败，整个 batch 作废，响应里逐条给出 error_message。
• 幂等重试：创建时带 Idempotency-Key（建议用客户端生成的 UUID）。同 key + 相同 body 返回原 journal，同 key + 不同 body 返回 422。这是资金操作重试安全的正确姿势——网络超时后盲目重发可能双重入账。
• 状态流：GET /v2/events/journals/status 以 SSE 推送状态变更；v1 是 legacy，不要用。

状态机里的坑

正常路径是 queued → sent_to_clearing → executed，但有两条教训：

1. executed 不等于最终。未获许可的 journal 可能被 cashiering 撤销，必须对齐后续事件做对账。
2. correct 会产生新的 journal ID。纠正不是原地编辑，而是取消原单、新建一张修正金额的单。按 ID 对账时必须同时处理原 ID（变 correct/cancelled）和新 ID（真实资金流向）。

适用边界

• 现金归集/journals 用途需要 Alpaca 审核，可能还涉及本地牌照，需先咨询法务。
• DELETE 只对 pending 状态有效（204）；要撤销已执行的 journal，只能反向创建一张镜像 journal。
• 余额不足时创建返回 403；触及日限额会退回 pending 等待人工审批。
• GET /v1/journals 结果集超过 10 万条会 422，务必用 after/before/limit 过滤。
• 涉及资金移动的 journal 要带 Travel Rule 字段（transmitter_*）；测试可用 description 里的 sandbox fixtures 模拟 rejected/pending。