Module qot_stock_key 

Stable (v1.4.110) — QOT broker-aware stock/security key.

用于 SubscriptionManager / QotCache / push registry / GetSubInfo 全栈对齐 C++ StockKey(stock_id, broker_id). 数字货币 multi-broker 场景下让同一 stock_id 的不同 broker 订阅独立隔离, 避免 push 混投 + cache 互相覆盖.

跨 crate 消费者: futu-server (SubscriptionManager) / futu-cache (QotCache) / futu-gateway-qot (15 behavior-aware handler) / futu-backend (CMD6211 wire). QotStockKey / QotSecurityKey —— QOT 行情订阅 + cache + push broker-aware key.

背景 (v1.4.110 codex QOT C++ alignment Slice 2)

C++ NNProtoCenter/NNProtoCenter_Define_StockKey.h 定义 StockKey 为:

StockKey(stockID)              // 不区分 broker (m_hasBroker=false)
StockKey(stockID, brokerID)    // 仅 brokerID != NN_BrokerID_Unknown 时 m_hasBroker=true

NN_BrokerID_Unknown = 0 不是一个独立 broker key, 等价 “no broker”. Equality 比较: nStockID + m_hasBroker + (m_hasBroker ? brokerID : ignored).

QOT 全模块 (subscription, cache, push registry, quota, GetSubInfo response) 都围绕 StockKey 作 first-class identity. Rust 之前用 public string "market_code" 把不同 broker 合并 → crypto multi-broker 行为系统性偏差.

设计要点

• broker_id: Option<NonZeroU32>: 用 NonZeroU32 类型层 enforce “Some(0) 不可能存在”, 严格对齐 C++ m_hasBroker 语义 (codex 调研 12:18 增量).
• QotSecurityKey 复合: public_sec_key (“market_code”, 给 FTAPI Security 字段回显) + stock_key (cache/subscription 内部识别).
• Display: broker-aware 编码用 "market_code@b1007" (仅内部使用, 不能让 public Security.code 泄漏 @b1007 suffix).

Hardcoded / Assumption Ledger

• NonZeroU32 用作 broker_id enforcement, 不允许 Some(0) 出现 — C++ NN_BrokerID_Unknown = 0 永远走 no-broker 路径.
• display 后缀 @b{N} 是 Rust 内部约定 (codex 调研 17:22 推荐), C++ 无 对应 string 格式 (它用 typed StockKey 比较), 仅内部 cache key encoding.

Structs

QotSecurityKey

QOT broker-aware security key (复合): public "market_code" + broker-aware QotStockKey.

QotStockKey

QOT broker-aware stock 唯一识别.