Alpaca券商SSE事件流

解决什么问题

轮询 REST 接口拿券商生命周期事件，要么丢事件要么放大延迟。事件流覆盖账户状态、Journal、资金划转、成交回报、非交易活动五条线，路径和版本还不统一，凭经验硬写很容易踩坑：拿不到历史、重连后静默丢数、重复事件触发重复副作用。

这个技能要给出一套可落地的消费方案，从连接建立、断线重连、历史回放到幂等处理，每一步都有明确做法。

核心能力

• 多流统一订阅：账户状态走 /v1/events/accounts/status，成交更新走 /v2/events/trades，Journal 走 /v2/events/journals/status，资金走 /v2/events/funding/status，非交易活动走 /v1/events/nta。路径不是单一版本，逐条验证后再写代码。
• 断点回放：每个事件带 event_id（或 ULID），消费成功后持久化游标。重连时带上 since_id（v2）或 since_ulid（v1），服务端会把断开期间的事件补给你。没有游标的重连等于白断。
• 静默检测与退避重连：lastMessageAt 超过阈值就主动拆连接；重连用指数退避并封顶；加单次重连标志位，防止错误风暴打出一堆并发连接。
• 事件级容错：每个事件的处理逻辑包在 try/catch 里，单条消息坏了只记录日志，不能让整条流停掉。
• 幂等消费管道：以 event_id 为键做 upsert 去重，处理目标行时加锁，状态机只在当前状态允许时才推进，处理成功再推进游标。

适用边界与注意点

• SSE 不是行情通道：这是券商生命周期事件，和行情 WebSocket 是两套传输、两套认证、两套可靠性模型，不能混用。
• 游标参数不能混用：since、since_id、since_ulid 三者只能选一个方向。只给 until 不给 since 是非法请求。
• 同毫秒事件不保证严格排序：ULID 带随机分量，对账场景建议从几分钟前的游标重启，靠幂等吸收重叠。
• 生成式客户端会挂死：OpenAPI 无法建模流式响应，codegen 出来的客户端会一直等一个永远不会结束的 response。要用真正的流式 HTTP/SSE 客户端，且确认它允许你在初始请求上加 Authorization 头。
• SSE 只是低延迟管道，不是正确性保证：长时间宕机、bug、未处理的类型都会漏。始终配一个周期性对账任务，从 Alpaca 拉权威状态做 upsert。SSE 管快，对账管对。