futu_cache/

security_resolver.rs

//! v1.4.106 codex 1148 F5 (P2): 统一 stock_id ↔ Security 双向解析入口。
//!
//! C++ 对照:
//! - `APIServer_Inner_API.cpp:604` `GetStockID(Security, &stock_id)` — Security → stock_id
//! - `APIServer_Inner_API.cpp:669` `GetAPIStock(stock_id, &Security)` — stock_id → Security
//! - 两者底层都查 `INNBiz_Qot_SecList::SearchSecBy{Code,ID}`, 失败语义清晰
//!   (`enReturnRet != Ok` 即 fail), 不 silent drop。
//!
//! Rust 早期实装曾把 `id_to_key` / `securities` 作为公开索引给 caller
//! 直接读写；当前 `StaticDataCache` 已把核心索引私有化，写路径统一走
//! `upsert_*` / `delete_security_info`，读路径通过 cache helper 或本 resolver。
//! 这层 resolver 保留的价值是把 "本地 cache miss" vs "backend 真返空" 的
//! 语义显式化，避免 caller 用 `filter_map` / `continue` / 空 list 把异常吞成
//! `ret_type=0`。
//!
//! 本 module 提供:
//! 1. **bidir API** — `resolve_stock_id_by_security` / `resolve_security_by_stock_id`
//! 2. **loud miss** — miss 时 bump counter (`resolver_miss_total`), 加 stale
//!    mark (复用 mkt_id refresh 路径)
//! 3. **明确返 enum 区分 hit / miss / unsupported** — caller 必处理 miss
//!    (要么 reject, 要么 partial marker, 要么 trigger refresh)
//!
//! 当前 caller 边界:
//! - request-side `Security` → stock_id 路径优先使用 cache helper / resolver
//!   fail-closed，例如 GetReference / GetBroker / Warrant / FutureInfo；
//! - push-side backend stock_id → public Security 仍需要按事件类型决定：
//!   quote push 可以 partial/drop 并打日志，request/response handler 不能把
//!   miss 投成成功空结果；
//! - 若新增 caller 需要 stock_id 双向解析，先选本 resolver 或
//!   `StaticDataCache::get_security_info_by_stock_id()`，不要重新读取底层索引。

use std::sync::Arc;
use std::sync::atomic::{AtomicU64, Ordering};

use crate::static_data::{CachedSecurityInfo, StaticDataCache};

/// stock_id ↔ Security 解析失败的原因。
///
/// 调用方据此选择 `Reject` (loud error) / `Refresh` (重 trigger) /
/// `PartialResponse` (返 partial marker)。
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum ResolverErr {
    /// `stock_id` 不在反向索引 (`id_to_key`)。可能是:
    /// - stock-list 还没 sync 到 (启动早期 / SQLite 丢失)
    /// - stock_id 是后端新枚举值, 本地 cache 没收到 push
    StockIdNotInCache(u64),
    /// `Security` (market+code) 不在正向索引 (`securities`)。
    /// - Symbol 还没 subscribe (on-demand fetch 没触发)
    /// - Code 拼写错 (`HK.00700` vs `1_00700`)
    SecurityNotInCache { market: i32, code: String },
    /// `Security.market` 不是 daemon 支持的 enum 值 (e.g. 0 / 99)。
    UnsupportedMarket(i32),
    /// `stock_id == 0` — backend 返空 ID, 这是 silent-success bug 信号。
    StockIdZero,
}

impl std::fmt::Display for ResolverErr {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            ResolverErr::StockIdNotInCache(id) => {
                write!(f, "stock_id={id} not in cache (id_to_key miss)")
            }
            ResolverErr::SecurityNotInCache { market, code } => {
                write!(f, "Security {market}.{code} not in cache (securities miss)")
            }
            ResolverErr::UnsupportedMarket(m) => write!(f, "unsupported market={m}"),
            ResolverErr::StockIdZero => write!(f, "stock_id=0 (backend returned empty id)"),
        }
    }
}

impl std::error::Error for ResolverErr {}

/// v1.4.106 codex 1148 F5 (P2): 统一 stock_id ↔ Security 双向解析。
///
/// 使用 `Arc<StaticDataCache>` 作为底层存储, 不重复持有 cache state — 与现
/// 有 cache 完全 inter-op。可在 handler 构造时 `Arc::new(SecurityResolver::new(
/// cache.clone()))` 持有, handler 全程调 resolver method 而不直接 touch
/// cache 字段。
pub struct SecurityResolver {
    cache: Arc<StaticDataCache>,
    /// 累计 resolver miss 次数 (forward + reverse 合计)。给 metrics observability。
    resolver_miss_total: AtomicU64,
    /// 累计 resolver hit 次数。
    resolver_hit_total: AtomicU64,
}

impl SecurityResolver {
    pub fn new(cache: Arc<StaticDataCache>) -> Self {
        Self {
            cache,
            resolver_miss_total: AtomicU64::new(0),
            resolver_hit_total: AtomicU64::new(0),
        }
    }

    /// 借用底层 cache (caller 仍能直接 query 其他 method, 比如 trade_dates)。
    pub fn cache(&self) -> &Arc<StaticDataCache> {
        &self.cache
    }

    /// 累计 miss 数。
    pub fn miss_total(&self) -> u64 {
        self.resolver_miss_total.load(Ordering::Relaxed)
    }

    /// 累计 hit 数。
    pub fn hit_total(&self) -> u64 {
        self.resolver_hit_total.load(Ordering::Relaxed)
    }

    /// **C++ GetStockID 等价**: `Security` → `stock_id`。
    ///
    /// Cache hit + `info.stock_id > 0` → `Ok(stock_id)`;
    /// 其他情况返 `ResolverErr` (caller 必处理)。
    ///
    /// 同时**触发 mkt_id refresh mark** (若 hit 但 mkt_id stale)。
    pub fn resolve_stock_id_by_security(
        &self,
        security: &SecurityRef<'_>,
    ) -> Result<u64, ResolverErr> {
        if security.market <= 0 {
            self.bump_miss();
            return Err(ResolverErr::UnsupportedMarket(security.market));
        }
        let key = format!("{}_{}", security.market, security.code);
        match self.cache.get_security_info_trigger_refresh(&key) {
            Some(info) if info.stock_id > 0 => {
                self.bump_hit();
                Ok(info.stock_id)
            }
            Some(_) => {
                // info exists but stock_id=0 — 半索引行 / on-demand basic 写入失败
                self.bump_miss();
                Err(ResolverErr::StockIdZero)
            }
            None => {
                self.bump_miss();
                Err(ResolverErr::SecurityNotInCache {
                    market: security.market,
                    code: security.code.to_string(),
                })
            }
        }
    }

    /// **C++ GetAPIStock 等价**: `stock_id` → `Security`。
    ///
    /// Cache hit (id_to_key 含 stock_id 且 securities 含对应 row) → `Ok((market, code))`;
    /// 其他情况返 `ResolverErr`。
    ///
    /// 同时返 `info` 引用让 caller 复用 row 字段 (无需第二次 lookup)。
    pub fn resolve_security_by_stock_id(
        &self,
        stock_id: u64,
    ) -> Result<CachedSecurityInfo, ResolverErr> {
        if stock_id == 0 {
            self.bump_miss();
            return Err(ResolverErr::StockIdZero);
        }
        match self.cache.get_security_info_by_stock_id(stock_id) {
            Some(info) => {
                // F4: market=0 不该出现在公开 API resolver 路径 (bridge 已 reject)
                // 但 SQLite 历史 row 可能含, 这里防御
                if info.market <= 0 {
                    self.bump_miss();
                    return Err(ResolverErr::UnsupportedMarket(info.market));
                }
                self.bump_hit();
                Ok(info)
            }
            None => {
                self.bump_miss();
                Err(ResolverErr::StockIdNotInCache(stock_id))
            }
        }
    }

    fn bump_hit(&self) {
        self.resolver_hit_total.fetch_add(1, Ordering::Relaxed);
    }

    fn bump_miss(&self) {
        self.resolver_miss_total.fetch_add(1, Ordering::Relaxed);
    }
}

/// 轻量 Security 引用 (避免 caller 必须用 prost-generated 类型)。
#[derive(Debug, Clone, Copy)]
pub struct SecurityRef<'a> {
    pub market: i32,
    pub code: &'a str,
}

impl<'a> SecurityRef<'a> {
    pub fn new(market: i32, code: &'a str) -> Self {
        Self { market, code }
    }
}

#[cfg(test)]
mod tests;