Expand description
v1.4.38 Bug-防赔钱：订单幂等 cache
§Why
任何在线 trade 服务都需要幂等保护：网络抖动 / SDK auto-retry / LLM agent 幻觉 / 脚本 try-except 循环 都可能导致重复下单 —— 金融后果是真金白银。
Futu backend 的 remark 字段只 echo-back 不做 dedup，服务端不提供原生幂等。
所以必须在 client（daemon）侧做。
§Design
短期去重窗口：客户端传 Idempotency-Key → daemon 查 cache：
- cache hit（TTL 内）→ 返缓存的结果，不触发真下单
- cache miss → 真下单 → 写 cache → 返结果
TTL = 90 秒：略长于 SDK auto-retry 典型时窗（5-60s）+ LLM agent 幻觉 重 call 窗口（10s-几分钟）。不用 5 分钟是因为交易语义里“同样的 body 5 分钟 后“大概率是新意图（scalper 策略信号重触发）不是 retry。
daemon 不生成 key，只读：没 key 直接透传（backward-compat）。key 由客户端 / agent 按业务意图 per-intent 分配; daemon 只识别显式 key, 不从订单参数猜测意图。
cache both success + failure：幂等语义要求“同 key 重入得同一结果“。如果 用户想重试失败（比如补了保证金）→ 用新 key表示新意图，不是重用旧 key。
Structs§
- Cache
Key - v1.4.106 codex 0920 F1 (P1): namespaced cache key builder.
- Idempotency
Cache - 订单幂等 cache。线程安全（DashMap + Instant）。
- Idempotency
Flight Guard - Trade
Replay Guard - 交易写路径 PacketID 防重放 guard.
Enums§
- Cache
Outcome - v1.4.38 audit log 扩展字段：本次 place-order 请求的 cache 结果。
- Idempotency
Begin - Trade
Replay Error
Constants§
- DEFAULT_
TTL_ SECS - 默认 TTL：90 秒
Functions§
- spawn_
cleanup_ task - Spawn 一个后台 task 周期性清理过期 entries。返回的 task handle 交由
bridge-owned
crate::bridge::BackgroundRuntime托管。