futu_cache/

static_data.rs

// 静态数据缓存：股票列表、经纪商、节假日、停牌

use dashmap::DashMap;
use std::collections::HashSet;
use std::sync::RwLock;
use std::sync::atomic::{AtomicU64, Ordering};

/// v1.4.106 codex 1148 F7 (P2): cache row "完整度 / 来源" 标记。
///
/// 此 enum 区分一个 `CachedSecurityInfo` 是从 stock-list 完整 sync 来的
/// (字段全), 还是 subscribe on-demand CMD 20106 临时补的 (大量字段为空)。
/// `GetStaticInfo` / `GetSecuritySnapshot` / `make_static_info` 等需要完整
/// 静态字段的路径在收到 `OnDemandBasic` 行时**应**触发完整 stock-list /
/// 20106 completed refresh, 或明确返 partial / unavailable, 不假装完整数据。
///
/// 来源 audit: `codex/2026-05-01-1148-v1.4.106-codex-qot-static-data-review.md`
/// Finding 7。
#[derive(Debug, Clone, Copy, PartialEq, Eq, Default)]
pub enum SecurityInfoSource {
    /// 来自 backend stock-list full sync (含 list_time / warrnt_stock_owner
    /// / exch_type / no_search 等所有字段, 是权威数据)。
    StockListFull,
    /// 来自 subscribe / GetStaticInfo / GetSecuritySnapshot 的 on-demand CMD 20106
    /// 临时补行 — 仅含 stock_id / market / mkt_id / code / name / lot_size /
    /// sec_type, 其余字段缺省 (list_time="", warrnt_stock_owner=0,
    /// exch_type=0, no_search=false)。**不**应当作权威静态数据源。
    ///
    /// **作 Default**: 保守策略 — 历史 caller 漏标 source 时, 当 partial 处理
    /// (is_complete()=false), 后续 stock_list_sync / Bootstrap 自动覆写为权威
    /// 来源。这样 cache miss → on-demand fetch → 默认 source = OnDemandBasic
    /// 不会被误当 StockListFull 权威数据消费。
    #[default]
    OnDemandBasic,
    /// SQLite bootstrap reload (启动时从本地数据库恢复)。字段完整度同
    /// `StockListFull` (因为 SQLite 是上次 full sync 的快照), 但**生命期更长**
    /// (跨 daemon 重启)。一般 caller 当 `StockListFull` 处理。
    Bootstrap,
}

impl SecurityInfoSource {
    /// 是否含完整静态字段 (list_time / warrnt_stock_owner / exch_type /
    /// no_search 等)。`OnDemandBasic` 缺这些, 其他 source 都齐。
    #[must_use]
    pub fn is_complete(self) -> bool {
        matches!(self, Self::StockListFull | Self::Bootstrap)
    }
}

/// 股票静态信息
///
/// **v1.4.106 codex F5**: 加 `Default` impl 让 caller 可用
/// `CachedSecurityInfo { stock_id: ..., market: ..., ..Default::default() }`.
/// 现有显式 callsite 不动, 新加 callsite 可省冗余字段.
#[derive(Debug, Clone, Default)]
pub struct CachedSecurityInfo {
    pub stock_id: u64,
    /// FTAPI QotMarket 值 (1=HK_Security, 11=US_Security, 21=CNSH, 22=CNSZ 等)
    ///
    /// 由 bridge.rs `market_code_to_qot_market()` 从 backend `market_code`
    /// (NN_QuoteMktID) 映射而来; 用于构造 cache key `"{market}_{code}"`
    pub market: i32,
    /// Backend 原始 NN_QuoteMktID (market_code), **保留子交易所精度**
    ///
    /// 用于 cache-first 路由决策: 比如 CME Group 子交易所 (60=NYMEX, 70=COMEX,
    /// 80=CBOT, 90=CME, 100=CBOE) 都被 `market_code_to_qot_market()` 统一压到
    /// FTAPI QotMarket=11 (US_Security), 但 `mkt_id` 保留原始 range, 使
    /// `derive_security_type` / `us_futures_sub_exchange` 等能做 O(1) 范围
    /// 判别, 替代 CLAUDE.md 坑 #35 的 code-pattern 启发式. SQLite 历史行无此
    /// 字段时读为 0 (默认 Unknown), 下次 upsert 自动修正.
    pub mkt_id: u32,
    pub code: String,
    pub name: String,
    pub lot_size: i32,
    pub sec_type: i32,
    pub list_time: String,
    /// 窝轮所属正股 ID, 0 表示无
    pub warrnt_stock_owner: u64,
    /// 是否已退市
    pub delisting: bool,
    /// 交易所类型 (ExchType)
    pub exch_type: i32,
    /// 不可搜索标记 (对齐 C++ no_search 字段)
    pub no_search: bool,
    /// v1.4.106 codex F5: 期货主连合约关联 stock_id.
    ///
    /// 主连合约 (e.g. `HSImain`, `NQmain`) 此字段非 0, 指向真实月份合约
    /// stock_id (CMD 6747 拉真实 code 用); 普通合约此字段为 0.
    ///
    /// 来源: backend stock_list_sync `CSStockItem.origin_id` (proto field 41).
    /// PlaceOrder F5 用 `info.future_origin_id != 0` 判 NeedPullFutureContractInfo
    /// (对齐 C++ `Ndt_Qot_SecInfo::nFutureOriginID` + `APIServer_Trd_PlaceOrder
    /// .cpp:36-42` `NeedPullFutureContractInfo`).
    ///
    /// SQLite 历史行无此列时默认 0, 下次 stock_list sync (CMD 6746) 重新写入.
    pub future_origin_id: u64,
    /// v1.4.106 codex F5: 期货主力合约 stock_id.
    ///
    /// 主连合约持有此字段, 指向当前主力合约 stock_id (流动性最大). PlaceOrder
    /// F5 在收到 CMD 6747 响应后用此字段反查真实 code 再下单.
    ///
    /// 来源: backend `CSStockItem.zhuli_id` (proto field 40). 普通合约 0.
    pub zhuli_id: u64,
    /// v1.4.106 codex 1148 F7 (P2): 数据来源 / 完整度标记。详见
    /// `SecurityInfoSource` doc。**默认 `OnDemandBasic`** 以保守对待历史 caller
    /// 漏标场景 (能漏标的就是没填全字段, 当 partial 处理最安全)。
    pub source: SecurityInfoSource,
    /// v1.4.110 final E.5 P2#6: 交易所字符串 (proto `CSStockItem.exchange` field 57).
    ///
    /// 数据驱动 (pitfall #35 C++ 数据驱动 vs Rust 启发式): trade handler
    /// `derive_exchange_str` 优先用此字段, 缺失时 fallback 到 code prefix /
    /// pattern match heuristic. 取值例: "SEHK", "NASDAQ", "NYSE", "SSE", "SZSE", "HKEX".
    pub exchange: String,
    /// v1.4.110 final E.5 P2#6: 上市交易所 (proto `CSStockItem.listed_exchange` field 74).
    ///
    /// 通常等同 `exchange`, dual-listed ADR / 双重主要上市等场景下可能不同.
    pub listed_exchange: String,
}

/// Crypto 交易币对元数据。
///
/// C++ `NNProto_Trd_MaxQtyCrypto.cpp` 通过 `INNBiz_Qot_SecList::SearchSecByID`
/// 读取 `Ndt_Qot_SecInfo::szCCOrigin/szCCDestination`，并把它们分别写入
/// backend `GetMaxBuySellReq.coin/currency`。Rust 从 stock-list field 60/61
/// 接入同一份数据，避免在交易路径按 symbol 字符串拆币种。
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct CryptoPairInfo {
    pub cc_origin: String,
    pub cc_destination: String,
}

/// Crypto 交易配置缓存。
///
/// C++ `INNData_Trd_CryptoTradeConfig` 以 `(broker_id, symbol, exchange)` 作为
/// lookup key，MaxBuySellQty 投影用 `minimum_qty` 和 `base_tick_size` 做数量
/// 步进对齐。这里保存解析后的 nano 整数，避免每个 surface 自己解析 decimal。
#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct CryptoTradeConfig {
    pub symbol: String,
    pub exchange: String,
    pub pi_only: bool,
    pub tick_size_nano: i64,
    pub min_trade_qty_nano: i64,
    pub max_trade_qty_nano: i64,
    pub qty_increment_nano: i64,
}

impl CachedSecurityInfo {
    /// v1.4.89 P2-A: 判断 cache row 是否需要后台 mkt_id refresh.
    ///
    /// **场景**: SQLite 历史行 (v1.4.77 Phase D 之前 upsert) 没有 `mkt_id` 字段,
    /// 读取时默认为 0. 这导致 cache-first 路由走 heuristic fallback (坑 #35).
    ///
    /// 返 `true` 即需要 refresh; 如果 `mkt_id == 0 && market != 0`, 是历史行
    /// (有基本 market 但缺 sub-exchange 精度).
    ///
    /// **使用**: `StaticDataCache::mark_stale_mkt_id` 在 get 时 opportunistic
    /// mark stale, 背景 worker 批量 CMD 20106 refresh.
    #[must_use]
    pub fn needs_mkt_id_refresh(&self) -> bool {
        self.mkt_id == 0 && self.market != 0
    }

    /// v1.4.106 codex 1148 F7: 是否含完整静态字段 (基于 source). 调用方需要
    /// `list_time` / `warrnt_stock_owner` / `exch_type` 等字段时, 应先 check
    /// 此 flag, false 时触发 backend 完整 refresh 或返 partial marker。
    #[must_use]
    pub fn is_complete(&self) -> bool {
        self.source.is_complete()
    }
}

/// 交易日
#[derive(Debug, Clone)]
pub struct CachedTradeDate {
    pub time: String,
    pub timestamp: f64,
}

/// 板块信息
#[derive(Debug, Clone)]
pub struct CachedPlateInfo {
    pub market: i32,
    pub code: String,
    pub name: String,
    pub plate_type: i32,
}

/// 静态数据缓存
pub struct StaticDataCache {
    /// 股票静态信息: "market_code" → info
    ///
    /// **v1.4.106 codex 1148 F9**: 对外 read-only。生产代码不应直接 `.insert()`
    /// 这个 DashMap (会导致 `id_to_key` / `owner_to_warrants` 三索引不一致),
    /// 必须走 `upsert_full_security_info` / `upsert_basic_security_info` /
    /// `delete_security_info` 统一写入口。`pub` 仅为 backwards-compat:
    /// 既有迭代 caller (`snapshot.rs` for-iter `.iter()`) 仍能 read-only 遍历。
    pub securities: DashMap<String, CachedSecurityInfo>,
    /// stock_id → "market_code" key (反向映射，用于推送时查找)
    ///
    /// **v1.4.106 codex 1148 F9**: 对外 read-only (同 `securities`)。
    pub id_to_key: DashMap<u64, String>,
    /// 期货主连/连续合约 push 路由别名: real/origin stock_id → main-link sec_key set.
    ///
    /// Backend 的实时 push 可能以真实月份合约 stock_id 下发，而客户端订阅的是
    /// `HSImain` / `NQmain` 这类主连 symbol。C++ 的 QotSubscribe 用 stock_id
    /// 级别的主连关系做回投；Rust 这里保留同样的数据驱动关系，来源仅限
    /// stock-list 下发的 `origin_id` / `zhuli_id` 字段，不按 code 字符串特判。
    future_main_link_aliases: DashMap<u64, HashSet<String>>,
    /// Crypto sec_key -> 货币对元数据 (`cc_origin` / `cc_destination`)。
    crypto_pairs: DashMap<String, CryptoPairInfo>,
    /// `(broker_id, symbol, exchange)` -> crypto 交易配置。
    crypto_trade_configs: DashMap<String, CryptoTradeConfig>,
    /// 交易日: "market:year-month" → Vec<TradeDate>
    pub trade_dates: DashMap<String, Vec<CachedTradeDate>>,
    /// 板块: "market:plate_type" → Vec<PlateInfo>
    pub plates: DashMap<String, Vec<CachedPlateInfo>>,
    /// 窝轮正股 owner_id → 该正股对应的所有窝轮 stock_id 集合
    ///
    /// **v1.4.106 codex 1148 F6**: value 从 `Vec<u64>` 改为 `HashSet<u64>` 防
    /// 重复 (SQLite reload + stock-list re-sync 同 warrant 多次 push 不会再重复).
    /// stock-list `delete_flag` 时**反向索引清理**: 旧 owner 下移除旧 warrant
    /// (`delete_security_info` 内部维护), update 时也维护。
    pub owner_to_warrants: RwLock<std::collections::HashMap<u64, HashSet<u64>>>,

    /// v1.4.89 P2-A: 需要 mkt_id refresh 的 cache key 集合.
    ///
    /// Callers `get_security_info_trigger_refresh` 在返 info 前检查
    /// `info.needs_mkt_id_refresh()`, 是则 mark key 到这里. 背景 worker
    /// (gateway bridge) 定期 `drain_stale_mkt_ids()` 批量 CMD 20106 refresh.
    ///
    /// 用 DashMap<String, ()> 替代 HashSet<String> 免 lock 竞争.
    pub stale_mkt_ids: DashMap<String, ()>,

    /// v1.4.89 P2-A: mkt_id refresh 统计计数, 用于 metrics 观察.
    ///
    /// - `mkt_id_refresh_marked_total`: 累积 mark stale 次数
    /// - `mkt_id_refresh_done_total`: 累积 backend CMD 20106 成功 refresh 次数
    /// - `mkt_id_refresh_failed_total`: 累积 refresh failure 次数
    pub mkt_id_refresh_marked_total: AtomicU64,
    pub mkt_id_refresh_done_total: AtomicU64,
    pub mkt_id_refresh_failed_total: AtomicU64,
}

impl StaticDataCache {
    pub fn new() -> Self {
        Self {
            securities: DashMap::new(),
            id_to_key: DashMap::new(),
            future_main_link_aliases: DashMap::new(),
            crypto_pairs: DashMap::new(),
            crypto_trade_configs: DashMap::new(),
            trade_dates: DashMap::new(),
            plates: DashMap::new(),
            owner_to_warrants: RwLock::new(std::collections::HashMap::new()),
            stale_mkt_ids: DashMap::new(),
            mkt_id_refresh_marked_total: AtomicU64::new(0),
            mkt_id_refresh_done_total: AtomicU64::new(0),
            mkt_id_refresh_failed_total: AtomicU64::new(0),
        }
    }

    /// v1.4.89 P2-A: 取 cache info 同时机会性 mark stale (若 mkt_id=0).
    ///
    /// 返 Some(info) 如果 cache hit (无论是否 stale). 返 None 如果 miss.
    ///
    /// 调 `info.needs_mkt_id_refresh()` 判 stale → mark `stale_mkt_ids`,
    /// bump `mkt_id_refresh_marked_total` counter. 用 DashMap::insert 幂等
    /// (同 key 重入不 double mark 但会 bump counter — 可接受).
    ///
    /// 替代 `get_security_info` 的推荐路径; 老 method 保留作 lookup-only 接口.
    pub fn get_security_info_trigger_refresh(&self, key: &str) -> Option<CachedSecurityInfo> {
        let info = self.get_security_info(key)?;
        if info.needs_mkt_id_refresh() {
            self.mark_stale_mkt_id(key);
        }
        Some(info)
    }

    /// v1.4.89 P2-A: 显式 mark key 需要 mkt_id refresh.
    ///
    /// 幂等: 同 key 可重入. Counter `mkt_id_refresh_marked_total` 每次都 bump
    /// (用作 metrics 观察 heuristic fallback 触发频率).
    pub fn mark_stale_mkt_id(&self, key: &str) {
        self.stale_mkt_ids.insert(key.to_string(), ());
        self.mkt_id_refresh_marked_total
            .fetch_add(1, Ordering::Relaxed);
    }

    /// v1.4.89 P2-A: drain 所有 stale keys, 清空集合, 返 Vec (给 backend worker
    /// 批量 CMD 20106 refresh).
    ///
    /// 背景 worker 用法 (伪码):
    /// ```text
    /// loop {
    ///     sleep(Duration::from_secs(60)).await;
    ///     let stale = cache.drain_stale_mkt_ids();
    ///     if stale.is_empty() { continue; }
    ///     for chunk in stale.chunks(50) {
    ///         // CMD 20106 SecuritiesReq for chunk
    ///         // on success: cache.update_mkt_id(key, new_mkt_id)
    ///         //              + cache.record_mkt_id_refresh_done()
    ///         // on failure: cache.record_mkt_id_refresh_failed()
    ///     }
    /// }
    /// ```
    pub fn drain_stale_mkt_ids(&self) -> Vec<String> {
        let keys: Vec<String> = self.stale_mkt_ids.iter().map(|e| e.key().clone()).collect();
        for k in &keys {
            self.stale_mkt_ids.remove(k);
        }
        keys
    }

    /// v1.4.89 P2-A: 更新已 cache row 的 mkt_id (refresh success 时调).
    ///
    /// 只改 mkt_id 字段, 其他字段保留 (info 可能有 SQLite 里更精准的 lot_size /
    /// list_time 等). 若 key 不在 cache (已被 evict), no-op.
    pub fn update_mkt_id(&self, key: &str, new_mkt_id: u32) -> bool {
        if let Some(mut entry) = self.securities.get_mut(key) {
            entry.mkt_id = new_mkt_id;
            self.mkt_id_refresh_done_total
                .fetch_add(1, Ordering::Relaxed);
            true
        } else {
            false
        }
    }

    /// v1.4.89 P2-A: 记录 refresh failure (不改 cache row, 让下次 drain 重试).
    pub fn record_mkt_id_refresh_failed(&self) {
        self.mkt_id_refresh_failed_total
            .fetch_add(1, Ordering::Relaxed);
    }

    /// v1.4.89 P2-A: 当前 stale keys 数 (给 observability / debug).
    #[must_use]
    pub fn stale_mkt_ids_count(&self) -> usize {
        self.stale_mkt_ids.len()
    }

    /// v1.4.106 codex 1148 F9 (P3): 统一写入口 — 完整静态行 (`StockListFull` /
    /// `Bootstrap` source)。同步维护 `securities` + `id_to_key` + 若有 owner
    /// 还更新 `owner_to_warrants`。**自动 dedup**: 已有同 key 但 `warrnt_stock_owner`
    /// 变化时, 旧 owner 下移除该 warrant id, 新 owner 下添加。
    ///
    /// 替代生产代码里手动调 `securities.insert()` + `id_to_key.insert()` +
    /// `add_warrant_owner()` 三步骤的 pattern。
    ///
    /// **不允许** caller 把不完整的 source 标 `StockListFull`(若 `info.source ==
    /// OnDemandBasic`, 用 `upsert_basic_security_info` 而非本 fn)。
    pub fn upsert_full_security_info(&self, key: &str, info: CachedSecurityInfo) {
        debug_assert!(
            info.source.is_complete(),
            "upsert_full_security_info called with non-complete source ({:?})",
            info.source
        );
        self.upsert_with_owner_index_maintenance(key, info);
    }

    /// 写入 stock-list 下发的 crypto 货币对元数据。
    pub fn upsert_crypto_pair_info(&self, key: &str, pair: CryptoPairInfo) {
        if pair.cc_origin.is_empty() && pair.cc_destination.is_empty() {
            self.crypto_pairs.remove(key);
        } else {
            self.crypto_pairs.insert(key.to_string(), pair);
        }
    }

    /// 读取 crypto 货币对元数据。
    pub fn get_crypto_pair_info(&self, key: &str) -> Option<CryptoPairInfo> {
        self.crypto_pairs.get(key).map(|v| v.clone())
    }

    fn crypto_trade_config_key(broker_id: u32, symbol: &str, exchange: &str) -> String {
        format!(
            "{broker_id}:{}:{}",
            symbol.trim().to_ascii_uppercase(),
            exchange.trim().to_ascii_uppercase()
        )
    }

    /// 用 backend CMD20102 拉回的配置替换某个 broker 的 crypto trade config。
    pub fn set_crypto_trade_configs_for_broker(
        &self,
        broker_id: u32,
        configs: Vec<CryptoTradeConfig>,
    ) {
        let prefix = format!("{broker_id}:");
        self.crypto_trade_configs
            .retain(|key, _| !key.starts_with(&prefix));
        for config in configs {
            if config.symbol.trim().is_empty() || config.exchange.trim().is_empty() {
                continue;
            }
            let key = Self::crypto_trade_config_key(broker_id, &config.symbol, &config.exchange);
            self.crypto_trade_configs.insert(key, config);
        }
    }

    /// 查询某个 crypto symbol 的交易配置。
    pub fn get_crypto_trade_config(
        &self,
        broker_id: u32,
        symbol: &str,
        exchange: &str,
    ) -> Option<CryptoTradeConfig> {
        let key = Self::crypto_trade_config_key(broker_id, symbol, exchange);
        self.crypto_trade_configs.get(&key).map(|v| v.clone())
    }

    /// v1.4.106 codex 1148 F9 (P3): 统一写入口 — 部分静态行 (`OnDemandBasic`
    /// source)。同步维护 `securities` + `id_to_key`, **不动** `owner_to_warrants`
    /// (因为 OnDemandBasic 不含 `warrnt_stock_owner` 字段, value 必为 0)。
    ///
    /// `info.source` 必须是 `OnDemandBasic` (debug_assert)。
    pub fn upsert_basic_security_info(&self, key: &str, info: CachedSecurityInfo) {
        debug_assert!(
            !info.source.is_complete(),
            "upsert_basic_security_info called with complete source ({:?}); use upsert_full",
            info.source
        );
        debug_assert_eq!(
            info.warrnt_stock_owner, 0,
            "OnDemandBasic must have warrnt_stock_owner=0 (caller didn't query the field)"
        );
        // 不维护 owner_to_warrants (basic 没这个字段).
        // 但仍需检查既有完整行的 owner 是否会被 basic 错误覆盖.
        // 策略: 如果 key 已有 StockListFull / Bootstrap 行, 不让 basic 行覆盖 (full
        // 数据更完整). 这处理 case "subscribe on-demand 后, stock-list sync 来时
        // 应该 prevail; 反过来不行".
        if let Some(existing) = self.securities.get(key) {
            if existing.is_complete() {
                tracing::debug!(
                    key,
                    "upsert_basic_security_info skipped: existing complete row prevails"
                );
                drop(existing);
                return;
            }
            drop(existing);
        }
        if let Some(old_info) = self.securities.get(key).map(|r| r.clone()) {
            self.remove_future_main_link_aliases(key, &old_info);
        }
        self.securities.insert(key.to_string(), info.clone());
        self.id_to_key.insert(info.stock_id, key.to_string());
        self.add_future_main_link_aliases(key, &info);
    }

    /// v1.4.106 codex 1148 F9 (P3): 删除 cache row + 同步清三个索引
    /// (`securities`, `id_to_key`, `owner_to_warrants`)。
    ///
    /// 用于 stock-list `delete_flag = true` 场景。
    /// 返 `true` 如果 row 存在并被删除, `false` 如果 stock_id 不在 `id_to_key`。
    pub fn delete_security_info(&self, stock_id: u64) -> bool {
        let Some((_, key)) = self.id_to_key.remove(&stock_id) else {
            return false;
        };
        // 拿被删 row 的 owner (用于反向索引清理), 如果 key 已不在 securities, owner = 0
        let old_owner = self
            .securities
            .get(&key)
            .map(|r| r.warrnt_stock_owner)
            .unwrap_or(0);
        if let Some(old_info) = self.securities.get(&key).map(|r| r.clone()) {
            self.remove_future_main_link_aliases(&key, &old_info);
        }
        self.securities.remove(&key);
        self.crypto_pairs.remove(&key);
        // F6: stock-list delete 时把 warrant 从 old_owner 反向索引里清掉
        if old_owner != 0
            && let Ok(mut map) = self.owner_to_warrants.write()
            && let Some(set) = map.get_mut(&old_owner)
        {
            set.remove(&stock_id);
            if set.is_empty() {
                map.remove(&old_owner);
            }
        }
        // F6: 该 stock_id 自己也可能是某 owner — 清掉它作为 owner 的 entry
        if let Ok(mut map) = self.owner_to_warrants.write() {
            map.remove(&stock_id);
        }
        true
    }

    /// 内部 helper: F9 unified upsert with owner-index maintenance (F6).
    fn upsert_with_owner_index_maintenance(&self, key: &str, info: CachedSecurityInfo) {
        // 先看老 row 是否存在 + 旧 owner 是什么 (F6: 如果 owner 变了要清旧索引)
        let old_info = self.securities.get(key).map(|r| r.clone());
        let old_owner = old_info.as_ref().map(|r| r.warrnt_stock_owner).unwrap_or(0);
        let new_owner = info.warrnt_stock_owner;

        if let Some(old) = old_info.as_ref() {
            self.remove_future_main_link_aliases(key, old);
        }

        // 写 securities + id_to_key
        let stock_id = info.stock_id;
        self.securities.insert(key.to_string(), info.clone());
        self.id_to_key.insert(stock_id, key.to_string());
        self.add_future_main_link_aliases(key, &info);

        // F6: 维护反向索引
        if old_owner != new_owner {
            // owner 变了 (含 0→X / X→Y / X→0)
            if let Ok(mut map) = self.owner_to_warrants.write() {
                if old_owner != 0
                    && let Some(set) = map.get_mut(&old_owner)
                {
                    set.remove(&stock_id);
                    if set.is_empty() {
                        map.remove(&old_owner);
                    }
                }
                if new_owner != 0 {
                    map.entry(new_owner).or_default().insert(stock_id);
                }
            }
        } else if new_owner != 0 {
            // owner 未变, 但同一 owner 下重 add (idempotent due to HashSet).
            if let Ok(mut map) = self.owner_to_warrants.write() {
                map.entry(new_owner).or_default().insert(stock_id);
            }
        }
    }

    fn future_main_link_target_ids(info: &CachedSecurityInfo) -> Vec<u64> {
        let mut ids = Vec::with_capacity(2);
        for target in [info.future_origin_id, info.zhuli_id] {
            if target != 0 && target != info.stock_id && !ids.contains(&target) {
                ids.push(target);
            }
        }
        ids
    }

    fn add_future_main_link_aliases(&self, key: &str, info: &CachedSecurityInfo) {
        for target in Self::future_main_link_target_ids(info) {
            self.future_main_link_aliases
                .entry(target)
                .or_default()
                .insert(key.to_string());
        }
    }

    fn remove_future_main_link_aliases(&self, key: &str, info: &CachedSecurityInfo) {
        for target in Self::future_main_link_target_ids(info) {
            if let Some(mut aliases) = self.future_main_link_aliases.get_mut(&target) {
                aliases.remove(key);
                let empty = aliases.is_empty();
                drop(aliases);
                if empty {
                    self.future_main_link_aliases.remove(&target);
                }
            }
        }
    }

    /// 查询某个 backend push stock_id 对应的主连/连续合约 sec_key 别名。
    ///
    /// 只返回 stock-list 明确下发 `origin_id` / `zhuli_id` 关系的 key；不做
    /// `HSImain` 等字符串启发式。调用方通常先按 `id_to_key` 处理真实合约，
    /// 再把这里返回的 main-link key 一并投递。
    #[must_use]
    pub fn get_future_main_link_alias_keys(&self, stock_id: u64) -> Vec<String> {
        let Some(aliases) = self.future_main_link_aliases.get(&stock_id) else {
            return Vec::new();
        };
        let mut keys: Vec<String> = aliases.iter().cloned().collect();
        keys.sort();
        keys
    }

    /// 查询 backend push stock_id 的所有 quote 投递目标。
    ///
    /// 顺序保持为：真实 stock_id 对应 key（如有）优先，然后是 stock-list
    /// `origin_id` / `zhuli_id` 下发的主连/连续合约别名 key。调用方不再直接
    /// 读取 `id_to_key` 和 `future_main_link_aliases` 两个索引，避免 alias 逻辑
    /// 分散在 push parser 里。
    #[must_use]
    pub fn quote_push_targets_for_stock_id(
        &self,
        stock_id: u64,
    ) -> Vec<(String, CachedSecurityInfo)> {
        let mut targets = Vec::new();

        if let Some(sec_key_ref) = self.id_to_key.get(&stock_id) {
            let sec_key = sec_key_ref.clone();
            drop(sec_key_ref);
            if let Some(info) = self.get_security_info(&sec_key) {
                targets.push((sec_key, info));
            }
        }

        for alias_key in self.get_future_main_link_alias_keys(stock_id) {
            if targets.iter().any(|(key, _)| key == &alias_key) {
                continue;
            }
            if let Some(info) = self.get_security_info(&alias_key) {
                targets.push((alias_key, info));
            }
        }

        targets
    }

    /// **v1.4.110 Phase 2 Slice 5**: broker-aware 推送投递目标查询.
    ///
    /// 对应 push parser 从 `SecurityQuote.broker_id` 重建 broker-aware
    /// `QotStockKey` 的路径 (对齐 C++ `NNBiz_Qot_PushQot.cpp:220-269`).
    ///
    /// 语义:
    /// - `broker_id = None` (C++ `m_hasBroker=false`): 只查 no-broker key,
    ///   返 `QotSecurityKey::no_broker(public_sec_key, stock_id)` 与
    ///   `quote_push_targets_for_stock_id` 等价
    /// - `broker_id = Some(N)` (C++ `m_hasBroker=true`): 沿 stock_id 反向
    ///   找到 public_sec_key, 再用 `QotSecurityKey::from_broker_id(...)`
    ///   构造 broker-aware key. 该 broker 下 cache 写入独立桶
    ///   `"market_code@b{N}"`, 不污染同 stock_id 其他 broker 的 cache.
    ///
    /// **Phase 2 默认**: backend 当前对普通股 push 仍不下发 broker_id (=None),
    /// 与升级前行为完全等价. crypto multi-broker push 会带 broker_id,
    /// Phase 3 reader caller (handler `GetBasicQot` 等) 替换走 `_broker`
    /// 版本后, broker-aware cache 才被消费.
    #[must_use]
    pub fn quote_push_targets_for_stock_key(
        &self,
        stock_id: u64,
        broker_id: Option<std::num::NonZeroU32>,
    ) -> Vec<(futu_core::qot_stock_key::QotSecurityKey, CachedSecurityInfo)> {
        // 先用 no-broker 路径查 stock_id → (public_sec_key, info) 列表
        // (id_to_key + future_main_link_aliases). broker_id 注入到返 key
        // 不改变 lookup 逻辑.
        let bare = self.quote_push_targets_for_stock_id(stock_id);
        bare.into_iter()
            .map(|(public_sec_key, info)| {
                let key = match broker_id {
                    Some(nz) => futu_core::qot_stock_key::QotSecurityKey::from_broker_id(
                        public_sec_key,
                        stock_id,
                        nz.get(),
                    ),
                    None => futu_core::qot_stock_key::QotSecurityKey::no_broker(
                        public_sec_key,
                        stock_id,
                    ),
                };
                (key, info)
            })
            .collect()
    }

    /// **deprecated**: 改用 `upsert_full_security_info` /
    /// `upsert_basic_security_info` 维护三索引一致性。本 method 仅写
    /// `securities`, **不**更新 `id_to_key` / `owner_to_warrants` — 直接调
    /// 会产生半索引行 (按 code 查得到, 按 stock_id 反向查不到)。
    ///
    /// v1.4.106 codex 1148 F9 起仅保留作 unit test / bench 兼容。生产代码
    /// 禁用 (review-time grep `set_security_info` 须 0 命中 in `crates/futu-*/src/`)。
    #[deprecated(
        since = "1.4.106",
        note = "use upsert_full_security_info / upsert_basic_security_info / delete_security_info"
    )]
    pub fn set_security_info(&self, key: &str, info: CachedSecurityInfo) {
        self.securities.insert(key.to_string(), info);
    }

    pub fn get_security_info(&self, key: &str) -> Option<CachedSecurityInfo> {
        self.securities.get(key).map(|v| v.clone())
    }

    /// 通过 stock_id 查找股票信息 (使用 id_to_key 反向映射)
    pub fn get_security_info_by_stock_id(&self, stock_id: u64) -> Option<CachedSecurityInfo> {
        let key = self.id_to_key.get(&stock_id)?;
        self.securities.get(key.value().as_str()).map(|v| v.clone())
    }

    /// 添加窝轮→正股的映射关系
    ///
    /// **v1.4.106 codex 1148 F6**: HashSet 自动去重, 重复 add 同 (warrant, owner)
    /// 是 idempotent — SQLite reload + stock-list sync 不会重复入。
    pub fn add_warrant_owner(&self, warrant_stock_id: u64, owner_stock_id: u64) {
        if owner_stock_id == 0 {
            return;
        }
        if let Ok(mut map) = self.owner_to_warrants.write() {
            map.entry(owner_stock_id)
                .or_default()
                .insert(warrant_stock_id);
        }
    }

    /// 通过正股 ID 搜索该正股的所有窝轮
    ///
    /// **v1.4.106 codex 1148 F6**: 内部 HashSet, 返 Vec (call site backward
    /// compatible)。返序非确定 (HashSet 不保留 insertion order); call site 若
    /// 需要稳定序应自己 sort。
    #[must_use]
    pub fn search_warrants_by_owner(&self, owner_stock_id: u64) -> Vec<u64> {
        match self.owner_to_warrants.read() {
            Ok(map) => map
                .get(&owner_stock_id)
                .map(|set| set.iter().copied().collect())
                .unwrap_or_default(),
            _ => Vec::new(),
        }
    }
}

impl Default for StaticDataCache {
    fn default() -> Self {
        Self::new()
    }
}

#[cfg(test)]
mod tests;