futu_cache/

qot_right.rs

// 行情权限缓存
// 存储从后端 CMD 6024 获取的行情权限和 API 额度信息
// 对应 C++ INNData_Qot_Right + INNData_APIInterLimit
//
// v1.4.106 codex 1217 (5月1日) 7 finding 全 default ON 真实装:
//   F1 [P1] epoch / freshness 状态机 + relogin/reconnect/replace 触发
//   F2 [P1] US futures detail 0 值覆盖旧权限 (字段存在=覆盖)
//   F3 [P2] CMD6024 validity predicate 扩为"任意 qot right 字段存在" (push_parser)
//   F4 [P2] startup async refresh window 不暴露默认 quota / Unknown 权限 (sys.rs)
//   F5 [P2] 6651/6006 push 闭环 + NotifyType_QotRight 广播 (push_parser + bridge)
//   F6 [P2] request_qot_right 携带 quote_change_notify (双模式) (push_parser)
//   F7 [P2] TestCmd / RemoteCmd 返结构化 RefreshReport (sys.rs)

use parking_lot::{Mutex, RwLock};

use crate::static_data::CachedSecurityInfo;

const QOT_RIGHT_UNKNOWN: i32 = 0;
const QOT_RIGHT_BMP: i32 = 1;
const QOT_RIGHT_LEVEL1: i32 = 2;
const QOT_RIGHT_LEVEL2: i32 = 3;
pub const QOT_RIGHT_SF: i32 = 4;
const QOT_RIGHT_NO: i32 = 5;
const SECURITY_TYPE_INDEX: i32 = 6;
const SECURITY_TYPE_DRVT: i32 = 8;
const SECURITY_TYPE_FUTURE: i32 = 10;
const SECURITY_TYPE_CRYPTO: i32 = 12;
const QOT_MARKET_CC_SECURITY: i32 = 91;
pub const US_LV2_ORDER_ARCA: u32 = 1;
pub const US_LV2_ORDER_NASDAQ_TV: u32 = 4;
pub const US_LV2_ORDER_OVERNIGHT: u32 = 128;
pub const LV2_ORDER_US_FUTURE: u32 = 1;

fn hk_clt_to_api(clt: u32) -> i32 {
    match clt {
        1 => 3,
        2 => 1,
        3 => 2,
        4 => 4,
        _ => 0,
    }
}

fn us_clt_to_api(clt: u32) -> i32 {
    match clt {
        1 => 2,
        2 => 5,
        _ => 5,
    }
}

fn cn_clt_to_api(clt: u32) -> i32 {
    match clt {
        1 => 2,
        2 => 3,
        3 => 5,
        _ => 5,
    }
}

fn other_clt_to_api(clt: u32) -> i32 {
    match clt {
        1 => 3,
        2 => 2,
        _ => 5,
    }
}

fn us_future_clt_to_api(clt: u32) -> i32 {
    match clt {
        0 => 5,
        1 => 3,
        2 => 1,
        3 => 3,
        4 => 2,
        _ => 5,
    }
}

fn us_option_clt_to_api(clt: u32) -> i32 {
    match clt {
        0 => 1,
        1 => 2,
        _ => 1,
    }
}

fn us_otc_comm_auth_to_api(deal_data_auth: Option<u32>, order_book_auth: Option<u32>) -> i32 {
    // Ref: FutuOpenD/Src/NNProtoCenter/Quote/NNBiz_Qot_Right.cpp:572-604.
    // C++ treats missing OTC fields as COMM_AUTH_RT; OTC is usable only when
    // both deal data and orderbook are realtime.
    const COMM_AUTH_RT: u32 = 2;
    const QOT_RIGHT_LEVEL1: i32 = 2;
    const QOT_RIGHT_NO: i32 = 5;
    let deal = deal_data_auth.unwrap_or(COMM_AUTH_RT);
    let order_book = order_book_auth.unwrap_or(COMM_AUTH_RT);
    if deal == COMM_AUTH_RT && order_book == COMM_AUTH_RT {
        QOT_RIGHT_LEVEL1
    } else {
        QOT_RIGHT_NO
    }
}

fn crypto_auth_to_api(auth: u32) -> i32 {
    if auth == 1 {
        QOT_RIGHT_LEVEL1
    } else {
        QOT_RIGHT_NO
    }
}

fn us_index_flags_to_api(
    dow_jones: Option<u32>,
    nasdaq: Option<u32>,
    standard_poor: Option<u32>,
) -> Option<i32> {
    // Ref: FutuOpenD/Src/NNProtoCenter/Quote/NNBiz_Qot_Right.cpp:529-566.
    // Any present index flag makes the aggregate US index right known; any
    // positive family grants Level1 for all US index symbols.
    const QOT_RIGHT_LEVEL1: i32 = 2;
    const QOT_RIGHT_NO: i32 = 5;
    if dow_jones.is_none() && nasdaq.is_none() && standard_poor.is_none() {
        return None;
    }
    let has_any = dow_jones == Some(1) || nasdaq == Some(1) || standard_poor == Some(1);
    Some(if has_any {
        QOT_RIGHT_LEVEL1
    } else {
        QOT_RIGHT_NO
    })
}

fn has_any_us_lv2_flag(flags: UsLv2Flags) -> bool {
    let (arca, nyse, nasdaq_tv, edg, bzx) = flags;
    arca == Some(1) || nyse == Some(1) || nasdaq_tv == Some(1) || edg == Some(1) || bzx == Some(1)
}

pub type UsLv2Flags = (
    Option<u32>,
    Option<u32>,
    Option<u32>,
    Option<u32>,
    Option<u32>,
);
pub type UsIndexFlags = (Option<u32>, Option<u32>, Option<u32>);
pub type UsOtcAuths = (Option<u32>, Option<u32>);
pub type UsFutureDetailAuths = (Option<u32>, Option<u32>, Option<u32>, Option<u32>);

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct Lv2OrderSubDescriptor {
    pub lv2_type: u32,
    pub level: u32,
    pub prob2_v2: bool,
}

#[derive(Debug, Clone, Copy, Default)]
pub struct QotRightBackendExtras {
    pub us_lv2_flags: Option<UsLv2Flags>,
    pub us_index_flags: Option<UsIndexFlags>,
    pub us_otc_auths: Option<UsOtcAuths>,
}

impl QotRightBackendExtras {
    pub const fn none() -> Self {
        Self {
            us_lv2_flags: None,
            us_index_flags: None,
            us_otc_auths: None,
        }
    }
}

#[derive(Debug, Clone, Copy, Default)]
pub struct QotRightBackendUpdate {
    pub hk_got: Option<u32>,
    pub us_got: Option<u32>,
    pub cn_got: Option<u32>,
    pub sh_auth: Option<u32>,
    pub sz_auth: Option<u32>,
    pub hk_option: Option<u32>,
    pub hk_future: Option<u32>,
    pub us_option: Option<u32>,
    pub us_future_cme_cboe: Option<u32>,
    pub us_future_detail: Option<UsFutureDetailAuths>,
    pub sg_future: Option<u32>,
    pub jp_future: Option<u32>,
    pub digital_currency_auth: Option<u32>,
    pub digital_pt_orderbook_auth: Option<u32>,
    pub sub_limit: Option<u32>,
    pub kl_limit: Option<u32>,
    pub extras: QotRightBackendExtras,
}

#[derive(Debug, Clone)]
pub struct QotRightData {
    pub hk_qot_right: i32,
    pub us_qot_right: i32,
    /// C++ `INNData_Qot_Right::GetUSQotStatus()` projection for GetUserInfo/Notify.
    pub api_us_qot_right: i32,
    pub sh_qot_right: i32,
    pub sz_qot_right: i32,
    pub hk_option_qot_right: i32,
    pub hk_future_qot_right: i32,
    pub has_us_option_qot_right: bool,
    pub us_option_qot_right: i32,
    pub us_index_qot_right: i32,
    pub us_otc_qot_right: i32,
    pub us_cme_future_qot_right: i32,
    pub us_cbot_future_qot_right: i32,
    pub us_nymex_future_qot_right: i32,
    pub us_comex_future_qot_right: i32,
    pub us_cboe_future_qot_right: i32,
    pub sg_future_qot_right: i32,
    pub jp_future_qot_right: i32,
    pub cc_qot_right: i32,
    pub cc_pt_orderbook_qot_right: i32,
    pub us_lv2_arca_qot_right: bool,
    pub us_lv2_nyse_qot_right: bool,
    pub us_lv2_nasdaq_totalview_qot_right: bool,
    pub sub_quota: i32,
    pub history_kl_quota: i32,
    /// v1.4.106 codex 1209 F4: HK option/future orderbook depth.
    pub hk_option_orderbook_depth: Option<u32>,
    pub hk_future_orderbook_depth: Option<u32>,
}

impl Default for QotRightData {
    fn default() -> Self {
        const UNKNOWN: i32 = 0;
        Self {
            hk_qot_right: UNKNOWN,
            us_qot_right: UNKNOWN,
            api_us_qot_right: UNKNOWN,
            sh_qot_right: UNKNOWN,
            sz_qot_right: UNKNOWN,
            hk_option_qot_right: UNKNOWN,
            hk_future_qot_right: UNKNOWN,
            has_us_option_qot_right: true,
            us_option_qot_right: UNKNOWN,
            us_index_qot_right: UNKNOWN,
            us_otc_qot_right: UNKNOWN,
            us_cme_future_qot_right: UNKNOWN,
            us_cbot_future_qot_right: UNKNOWN,
            us_nymex_future_qot_right: UNKNOWN,
            us_comex_future_qot_right: UNKNOWN,
            us_cboe_future_qot_right: UNKNOWN,
            sg_future_qot_right: UNKNOWN,
            jp_future_qot_right: UNKNOWN,
            cc_qot_right: UNKNOWN,
            cc_pt_orderbook_qot_right: UNKNOWN,
            us_lv2_arca_qot_right: false,
            us_lv2_nyse_qot_right: false,
            us_lv2_nasdaq_totalview_qot_right: false,
            sub_quota: 4000,
            history_kl_quota: 100,
            hk_option_orderbook_depth: None,
            hk_future_orderbook_depth: None,
        }
    }
}

// ===== v1.4.106 codex 1217 F1 [P1] — freshness state machine =====

#[derive(Debug, Clone, PartialEq, Eq)]
pub enum QotRightFreshness {
    Unknown,
    Pending,
    Fresh,
    Stale,
    Failed { error: String, since_ms: i64 },
}

impl QotRightFreshness {
    pub fn is_fresh(&self) -> bool {
        matches!(self, QotRightFreshness::Fresh)
    }
    pub fn is_unconfirmed(&self) -> bool {
        !self.is_fresh()
    }
}

#[derive(Debug, Clone, Default)]
pub struct PushedQuoteChangeNotify {
    pub change_items: Vec<(i32, i32, i32)>,
}

#[derive(Debug, Clone)]
pub struct QotRightRefreshReport {
    pub changed: bool,
    pub fresh_at_ms: i64,
    pub decoded_fields: Vec<&'static str>,
    pub freshness_after: QotRightFreshness,
    pub login_epoch: u64,
}

#[derive(Debug, Clone)]
pub struct QotRightStateMeta {
    pub freshness: QotRightFreshness,
    pub user_id: Option<u64>,
    pub login_epoch: u64,
    pub backend_generation: u64,
    pub last_refresh_at_ms: i64,
    pub last_pushed_quote_change_notify: Option<PushedQuoteChangeNotify>,
}

impl Default for QotRightStateMeta {
    fn default() -> Self {
        Self {
            freshness: QotRightFreshness::Unknown,
            user_id: None,
            login_epoch: 0,
            backend_generation: 0,
            last_refresh_at_ms: 0,
            last_pushed_quote_change_notify: None,
        }
    }
}

fn now_ms() -> i64 {
    use std::time::{SystemTime, UNIX_EPOCH};
    SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map(|d| d.as_millis() as i64)
        .unwrap_or(0)
}

fn is_hk_future_market(info: &CachedSecurityInfo) -> bool {
    info.sec_type == SECURITY_TYPE_FUTURE && matches!(info.mkt_id, 5 | 6 | 110..=119 | 1400..=1499)
}

fn is_us_future_market(info: &CachedSecurityInfo) -> bool {
    info.sec_type == SECURITY_TYPE_FUTURE && (60..=109).contains(&info.mkt_id)
}

fn is_sg_future_market(info: &CachedSecurityInfo) -> bool {
    info.sec_type == SECURITY_TYPE_FUTURE && (160..=179).contains(&info.mkt_id)
}

fn is_jp_future_market(info: &CachedSecurityInfo) -> bool {
    info.sec_type == SECURITY_TYPE_FUTURE && (185..=194).contains(&info.mkt_id)
}

fn is_hk_option_market(info: &CachedSecurityInfo) -> bool {
    info.sec_type == SECURITY_TYPE_DRVT && matches!(info.mkt_id, 7 | 8 | 570..=579)
}

fn is_us_option_market(info: &CachedSecurityInfo) -> bool {
    info.sec_type == SECURITY_TYPE_DRVT && (41..=49).contains(&info.mkt_id)
}

fn is_hk_security_market(info: &CachedSecurityInfo) -> bool {
    matches!(info.mkt_id, 1..=4 | 1000..=1049)
        || (info.market == 1
            && !is_hk_future_market(info)
            && !is_hk_option_market(info)
            && info.sec_type != SECURITY_TYPE_FUTURE
            && info.sec_type != SECURITY_TYPE_DRVT)
}

/// C++ `APIServer_Qot_StockSnapshot.cpp:18-43` (`IsHKBMP_OneStock`).
///
/// When this returns true, GetSecuritySnapshot must omit bid/ask price and
/// volume fields instead of returning delayed BMP values.
pub fn snapshot_masks_hk_bmp_bid_ask(info: &CachedSecurityInfo, qr: &QotRightData) -> bool {
    let is_hk = matches!(info.market, 1 | 2);
    if !is_hk {
        return false;
    }

    if is_hk_option_market(info) {
        return qr.hk_option_qot_right == QOT_RIGHT_BMP;
    }
    if is_hk_future_market(info) {
        return qr.hk_future_qot_right == QOT_RIGHT_BMP;
    }
    is_hk_security_market(info) && qr.hk_qot_right == QOT_RIGHT_BMP
}

fn is_us_security_market(info: &CachedSecurityInfo) -> bool {
    matches!(info.mkt_id, 10..=29 | 1200..=1249)
        || (info.market == 11
            && !is_us_future_market(info)
            && !is_us_option_market(info)
            && info.sec_type != SECURITY_TYPE_FUTURE
            && info.sec_type != SECURITY_TYPE_DRVT)
}

/// v1.4.110 codex Phase 4 Slice 7: 把 crypto detection helper 暴露给 push_parser
/// / handler (crypto LV2 sub-system 入口).
///
/// 对齐 C++ `IsCrypto(stockID)` (NNBiz_Qot_SecList.cpp). 三个条件任一: sec_type==Crypto
/// / FTAPI QotMarket=91 (CC_Security) / mkt_id ∈ [360,459] (DigitalCcy range).
pub fn is_crypto_market(info: &CachedSecurityInfo) -> bool {
    info.sec_type == SECURITY_TYPE_CRYPTO
        || info.market == QOT_MARKET_CC_SECURITY
        || (360..=459).contains(&info.mkt_id)
}

/// C++ `SubBitUtil::GetPushTypeSvrSubBit(NN_PushQot_Type_Most)` 对 US /
/// US options / US futures 保留 `SBIT_US_PREMARKET_AFTERHOURS_DETAIL`, 让
/// BasicQot 可以随订阅收到 preMarket / afterMarket / overnight。
///
/// Ref:
/// - `FutuOpenD/Src/NNProtoCenter/Quote/SubBitUtil.cpp:7-17`
/// - `FutuOpenD/Src/NNProtoCenter/Quote/SubBitUtil.cpp:91-95`
pub fn basic_qot_uses_us_pre_after_detail(info: &CachedSecurityInfo) -> bool {
    matches!(info.mkt_id, 10..=29 | 41..=45 | 60..=109 | 1200..=1249) || info.market == 11
}

fn is_sh_market(info: &CachedSecurityInfo) -> bool {
    matches!(info.mkt_id, 30 | 32 | 33 | 34 | 36..=40) || info.market == 21
}

fn is_sz_market(info: &CachedSecurityInfo) -> bool {
    matches!(info.mkt_id, 31 | 35) || info.market == 22
}

fn us_future_right_for_market(qr: &QotRightData, mkt_id: u32) -> i32 {
    match mkt_id {
        60..=69 => qr.us_nymex_future_qot_right,
        70..=79 => qr.us_comex_future_qot_right,
        80..=89 => qr.us_cbot_future_qot_right,
        90..=99 => qr.us_cme_future_qot_right,
        100..=109 => qr.us_cboe_future_qot_right,
        _ => QOT_RIGHT_UNKNOWN,
    }
}

pub fn merged_lv2_order_subs_for_security(
    info: &CachedSecurityInfo,
    qr: &QotRightData,
    _extended_time: bool,
) -> Vec<Lv2OrderSubDescriptor> {
    if is_us_future_market(info) {
        if us_future_right_for_market(qr, info.mkt_id) == QOT_RIGHT_LEVEL2 {
            return vec![Lv2OrderSubDescriptor {
                lv2_type: LV2_ORDER_US_FUTURE,
                level: 60,
                prob2_v2: true,
            }];
        }
        return vec![];
    }

    if !is_us_security_market(info) || info.sec_type == SECURITY_TYPE_INDEX {
        return vec![];
    }
    if !matches!(qr.us_qot_right, QOT_RIGHT_LEVEL1 | QOT_RIGHT_LEVEL2) {
        return vec![];
    }

    let mut subs = Vec::new();
    // Ref: FutuOpenD/Src/NNProtoCenter/Quote/MktQotSubInstance.cpp:118-137.
    // C++ adds E_US_LV2_ORDER_OVERNIGHT for US stock OrderBook whenever any
    // US LV2 orderbook right exists; it does not gate this on Qot_Sub.extendedTime.
    if qr.us_lv2_arca_qot_right || qr.us_lv2_nyse_qot_right || qr.us_lv2_nasdaq_totalview_qot_right
    {
        subs.push(Lv2OrderSubDescriptor {
            lv2_type: US_LV2_ORDER_OVERNIGHT,
            level: 60,
            prob2_v2: true,
        });
    }
    if qr.us_lv2_nasdaq_totalview_qot_right {
        subs.push(Lv2OrderSubDescriptor {
            lv2_type: US_LV2_ORDER_NASDAQ_TV,
            level: 60,
            prob2_v2: false,
        });
    }
    if qr.us_lv2_arca_qot_right {
        subs.push(Lv2OrderSubDescriptor {
            lv2_type: US_LV2_ORDER_ARCA,
            level: 60,
            prob2_v2: false,
        });
    }
    subs
}

pub fn has_merged_lv2_order_subs_for_security(
    info: &CachedSecurityInfo,
    qr: &QotRightData,
) -> bool {
    !merged_lv2_order_subs_for_security(info, qr, true).is_empty()
}

/// C++ `GetOrderBookMaxNum` 对齐版：根据证券静态市场 + 行情权限决定
/// orderbook push/cache 应保留的档位数。
///
/// Ref:
/// - `FutuOpenD/Src/APIServer/APIServer_Inner_API.cpp:4331-4412`
/// - `FutuOpenD/Src/APIServer/Business/Quote/QotRealTimeData.cpp:1211-1215`
///
/// Hardcoded / Assumption Ledger:
/// - `mkt_id` 范围复用 backend stock-list 的 NN_QuoteMktID 区间；`1400..=1499`
///   只在 `sec_type=Future` 时作为 live HK futures 私有 market_code 兜底。
/// - HK option/future depth 缺省为 0，和 C++ `NNData_Qot_Right` 构造默认值一致。
/// - 普通 HK/US/CN 股票在 Unknown 权限下保留 C++ 初始化默认值/分支语义，
///   避免 push parser 在权限刷新窗口内把有效 backend push 误清空。
pub fn order_book_max_depth_for_security(info: &CachedSecurityInfo, qr: &QotRightData) -> usize {
    if is_crypto_market(info) {
        return if qr.cc_qot_right == QOT_RIGHT_LEVEL1 {
            40
        } else {
            0
        };
    }

    if is_us_option_market(info) {
        return if qr.us_option_qot_right == QOT_RIGHT_BMP {
            0
        } else {
            1
        };
    }

    if is_us_future_market(info) {
        return match us_future_right_for_market(qr, info.mkt_id) {
            QOT_RIGHT_LEVEL1 => 1,
            QOT_RIGHT_LEVEL2 => 40,
            _ => 0,
        };
    }

    if is_hk_option_market(info) {
        return if qr.hk_option_qot_right == QOT_RIGHT_BMP {
            0
        } else {
            qr.hk_option_orderbook_depth.unwrap_or(0) as usize
        };
    }

    if is_hk_future_market(info) {
        return if qr.hk_future_qot_right == QOT_RIGHT_BMP {
            0
        } else {
            qr.hk_future_orderbook_depth.unwrap_or(0) as usize
        };
    }

    if is_hk_security_market(info) {
        return match qr.hk_qot_right {
            QOT_RIGHT_BMP | QOT_RIGHT_NO => 0,
            QOT_RIGHT_LEVEL1 => 1,
            QOT_RIGHT_LEVEL2 | QOT_RIGHT_SF => 10,
            _ => 10,
        };
    }

    if is_us_security_market(info) {
        return if info.sec_type == SECURITY_TYPE_INDEX || qr.us_qot_right == QOT_RIGHT_BMP {
            0
        } else {
            1
        };
    }

    if is_sh_market(info) {
        return if qr.sh_qot_right == QOT_RIGHT_BMP {
            0
        } else {
            10
        };
    }

    if is_sz_market(info) {
        return if qr.sz_qot_right == QOT_RIGHT_BMP {
            0
        } else {
            10
        };
    }

    if is_sg_future_market(info) {
        return match qr.sg_future_qot_right {
            QOT_RIGHT_LEVEL1 => 1,
            QOT_RIGHT_LEVEL2 => 40,
            _ => 0,
        };
    }

    if is_jp_future_market(info) {
        return match qr.jp_future_qot_right {
            QOT_RIGHT_LEVEL1 => 1,
            QOT_RIGHT_LEVEL2 => 40,
            _ => 0,
        };
    }

    10
}

/// C++ `IsHKSF`: HK 股票 + HK SF 权限要求 backend 全档摆盘。
///
/// Ref:
/// - `FutuOpenD/Src/APIServer/APIServer_Inner_API.cpp:900-913`
/// - `FutuOpenD/Src/APIServer/Business/Quote/QotSubscribe.cpp:1282-1286`
pub fn order_book_requires_backend_full_depth(
    info: &CachedSecurityInfo,
    qr: &QotRightData,
) -> bool {
    qr.hk_qot_right == QOT_RIGHT_SF && is_hk_security_market(info)
}

pub fn order_book_uses_backend_side_count(info: &CachedSecurityInfo, qr: &QotRightData) -> bool {
    order_book_requires_backend_full_depth(info, qr)
}

/// C++ `GetOrderBook` read path skips `GetOrderBookMaxNum` clipping for HK SF
/// and US TotalView Lv2.
///
/// Ref:
/// - `FutuOpenD/Src/APIServer/Business/Quote/APIServer_Qot_OrderBook.cpp:86-89`
/// - `FutuOpenD/Src/APIServer/APIServer_Inner_API.cpp:900-929`
pub fn order_book_read_uses_requested_count(info: &CachedSecurityInfo, qr: &QotRightData) -> bool {
    order_book_uses_backend_side_count(info, qr)
        || (qr.us_lv2_nasdaq_totalview_qot_right && is_us_security_market(info))
}

/// C++ `GetOrderBook` 对 US TotalView Lv2 / Crypto orderbook 还有一层
/// `IsHadAcceptUSLv2TotalViewData` gate: 普通 orderbook cache 存在不等于
/// LV2 真盘口已经到达。
///
/// Ref:
/// - `FutuOpenD/Src/APIServer/Business/Quote/APIServer_Qot_OrderBook.cpp:93-99`
/// - `FutuOpenD/Src/APIServer/Business/Quote/QotRealTimeData.cpp:576-579`
pub fn order_book_requires_accepted_lv2_push(info: &CachedSecurityInfo, qr: &QotRightData) -> bool {
    (qr.us_lv2_nasdaq_totalview_qot_right && is_us_security_market(info)) || is_crypto_market(info)
}

pub struct QotRightCache {
    data: RwLock<QotRightData>,
    meta: Mutex<QotRightStateMeta>,
}

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

impl QotRightCache {
    pub fn new() -> Self {
        Self {
            data: RwLock::new(QotRightData::default()),
            meta: Mutex::new(QotRightStateMeta::default()),
        }
    }

    pub fn get(&self) -> QotRightData {
        self.data.read().clone()
    }

    pub fn freshness(&self) -> QotRightFreshness {
        self.meta.lock().freshness.clone()
    }

    pub fn is_fresh(&self) -> bool {
        self.meta.lock().freshness.is_fresh()
    }

    pub fn meta_snapshot(&self) -> QotRightStateMeta {
        self.meta.lock().clone()
    }

    pub fn set_orderbook_depths(&self, hk_option_depth: Option<u32>, hk_future_depth: Option<u32>) {
        let mut d = self.data.write();
        if let Some(v) = hk_option_depth {
            d.hk_option_orderbook_depth = Some(v);
        }
        if let Some(v) = hk_future_depth {
            d.hk_future_orderbook_depth = Some(v);
        }
    }

    pub fn mark_stale(&self, reason: &str) {
        let mut m = self.meta.lock();
        let old = m.freshness.clone();
        m.freshness = QotRightFreshness::Stale;
        tracing::info!(
            old_freshness = ?old,
            reason,
            login_epoch = m.login_epoch,
            backend_generation = m.backend_generation,
            "QotRightCache: marked stale"
        );
    }

    pub fn advance_login_epoch(&self, new_epoch: u64, user_id: Option<u64>) {
        let mut m = self.meta.lock();
        let old_epoch = m.login_epoch;
        m.login_epoch = new_epoch;
        m.user_id = user_id;
        if matches!(m.freshness, QotRightFreshness::Fresh) {
            m.freshness = QotRightFreshness::Stale;
        }
        tracing::info!(
            old_epoch,
            new_epoch,
            user_id = ?user_id,
            "QotRightCache: login epoch advanced"
        );
    }

    pub fn advance_backend_generation(&self, new_generation: u64) {
        let mut m = self.meta.lock();
        let old_gen = m.backend_generation;
        m.backend_generation = new_generation;
        if matches!(m.freshness, QotRightFreshness::Fresh) {
            m.freshness = QotRightFreshness::Stale;
        }
        tracing::info!(
            old_generation = old_gen,
            new_generation,
            "QotRightCache: backend generation advanced"
        );
    }

    pub fn mark_pending(&self) {
        self.meta.lock().freshness = QotRightFreshness::Pending;
    }

    pub fn mark_fresh(&self) {
        let mut m = self.meta.lock();
        m.freshness = QotRightFreshness::Fresh;
        m.last_refresh_at_ms = now_ms();
    }

    pub fn mark_failed(&self, error: impl Into<String>) {
        self.meta.lock().freshness = QotRightFreshness::Failed {
            error: error.into(),
            since_ms: now_ms(),
        };
    }

    pub fn last_refresh_at_ms(&self) -> i64 {
        self.meta.lock().last_refresh_at_ms
    }

    pub fn set_pushed_quote_change_notify(&self, notify: PushedQuoteChangeNotify) {
        self.meta.lock().last_pushed_quote_change_notify = Some(notify);
    }

    pub fn pushed_quote_change_notify(&self) -> Option<PushedQuoteChangeNotify> {
        self.meta.lock().last_pushed_quote_change_notify.clone()
    }

    pub fn apply_6651_changes(&self, items: &[(i32, i32, i32)]) -> Vec<i32> {
        let mut d = self.data.write();
        let mut changed_types = Vec::new();

        for &(quote_type, before, after) in items {
            // Ref: FutuOpenD/Src/NNProtoCenter/Quote/NNBiz_Qot_Right.cpp:983-1010.
            // C++ applies 6651 pushes only when old right is known and actually changed.
            if before == 0 || before == after {
                continue;
            }
            let after_u = after as u32;
            if apply_qot_right_after_change(&mut d, quote_type, after_u) {
                changed_types.push(quote_type);
            }
        }
        if !changed_types.is_empty() {
            drop(d);
            let mut m = self.meta.lock();
            m.freshness = QotRightFreshness::Fresh;
            m.last_refresh_at_ms = now_ms();
        }
        changed_types
    }

    pub fn apply_direct_auth_changes(&self, items: &[(i32, u32)]) -> Vec<i32> {
        let mut d = self.data.write();
        let mut changed_types = Vec::new();

        for &(quote_type, after) in items {
            if apply_qot_right_after_change(&mut d, quote_type, after) {
                changed_types.push(quote_type);
            }
        }
        if !changed_types.is_empty() {
            drop(d);
            let mut m = self.meta.lock();
            m.freshness = QotRightFreshness::Fresh;
            m.last_refresh_at_ms = now_ms();
        }
        changed_types
    }

    /// 从后端 CMD 6024 响应更新权限数据.
    ///
    /// **v1.4.106 codex 1217 F2 [P1] (5月1日)**: us_future_detail 子字段存在 =
    /// 覆盖 (含值=0). 之前 `if cme > 0` 跳过 0 让 LV1 → 0 (No) 实质降级被
    /// silent 保留；但 C++ 逐个 `has_open_api_*_auth()` 判断，父字段存在不代表
    /// 未返回的子市场可按 0 覆盖。
    ///
    /// **v1.4.106 codex 1217 F1**: apply 成功后自动 mark Fresh.
    pub fn update_from_backend(&self, update: QotRightBackendUpdate) {
        let QotRightBackendUpdate {
            hk_got,
            us_got,
            cn_got,
            sh_auth,
            sz_auth,
            hk_option,
            hk_future,
            us_option,
            us_future_cme_cboe,
            us_future_detail,
            sg_future,
            jp_future,
            digital_currency_auth,
            digital_pt_orderbook_auth,
            sub_limit,
            kl_limit,
            extras,
        } = update;
        let mut d = self.data.write();

        if let Some(v) = hk_got {
            d.hk_qot_right = hk_clt_to_api(v);
        }
        if let Some(v) = us_got {
            let right = us_clt_to_api(v);
            d.us_qot_right = right;
        }
        if let Some(flags) = extras.us_lv2_flags {
            let (arca, nyse, nasdaq_tv, _edg, _bzx) = flags;
            d.us_lv2_arca_qot_right = arca == Some(1);
            d.us_lv2_nyse_qot_right = nyse == Some(1);
            d.us_lv2_nasdaq_totalview_qot_right = nasdaq_tv == Some(1);
            if has_any_us_lv2_flag(flags) && matches!(d.us_qot_right, 2 | 3) {
                // Ref: FutuOpenD/Src/NNProtoCenter/Quote/NNBiz_Qot_Right.cpp:157-180.
                // US stock LV2 is promoted by independent LV2 venue flags when the
                // base US right is not BMP/no-right.
                d.us_qot_right = 3;
            }
        }
        if let Some((dow_jones, nasdaq, standard_poor)) = extras.us_index_flags
            && let Some(api_right) = us_index_flags_to_api(dow_jones, nasdaq, standard_poor)
        {
            d.us_index_qot_right = api_right;
        }
        if let Some((deal_data_auth, order_book_auth)) = extras.us_otc_auths {
            d.us_otc_qot_right = us_otc_comm_auth_to_api(deal_data_auth, order_book_auth);
        }
        if let Some(v) = sh_auth {
            d.sh_qot_right = cn_clt_to_api(v);
        } else if let Some(v) = cn_got {
            d.sh_qot_right = cn_clt_to_api(v);
        }
        if let Some(v) = sz_auth {
            d.sz_qot_right = cn_clt_to_api(v);
        } else if let Some(v) = cn_got {
            d.sz_qot_right = cn_clt_to_api(v);
        }
        if let Some(v) = hk_option {
            d.hk_option_qot_right = hk_clt_to_api(v);
        }
        if let Some(v) = hk_future {
            d.hk_future_qot_right = hk_clt_to_api(v);
        }
        if let Some(v) = us_option {
            d.us_option_qot_right = us_option_clt_to_api(v);
            d.has_us_option_qot_right = d.us_option_qot_right != 1;
        }
        if let Some(v) = us_future_cme_cboe {
            d.us_cme_future_qot_right = us_future_clt_to_api(v);
            // Ref: FutuOpenD/Src/NNProtoCenter/Quote/NNBiz_Qot_Right.cpp:474-509.
            // OpenAPI currently keeps CBOE futures as no-right until the server
            // provides an open_api CBOE field; do not inherit the legacy
            // cme_cboe aggregate.
            d.us_cboe_future_qot_right = 5;
        }

        // F2 [P1] (v1.4.106 codex 1217): 子字段存在 = 覆盖 (含值=0).
        // Ref: FutuOpenD/Src/NNProtoCenter/Quote/NNBiz_Qot_Right.cpp:396-478.
        if let Some((cme, cbot, nymex, comex)) = us_future_detail {
            if let Some(cme) = cme {
                d.us_cme_future_qot_right = us_future_clt_to_api(cme);
            }
            if let Some(cbot) = cbot {
                d.us_cbot_future_qot_right = us_future_clt_to_api(cbot);
            }
            if let Some(nymex) = nymex {
                d.us_nymex_future_qot_right = us_future_clt_to_api(nymex);
            }
            if let Some(comex) = comex {
                d.us_comex_future_qot_right = us_future_clt_to_api(comex);
            }
            // Ref: FutuOpenD/Src/NNProtoCenter/Quote/NNBiz_Qot_Right.cpp:474-509.
            d.us_cboe_future_qot_right = 5;
        }

        if let Some(v) = sg_future {
            d.sg_future_qot_right = other_clt_to_api(v);
        }
        if let Some(v) = jp_future {
            d.jp_future_qot_right = other_clt_to_api(v);
        }
        if let Some(v) = digital_currency_auth {
            d.cc_qot_right = crypto_auth_to_api(v);
        }
        if let Some(v) = digital_pt_orderbook_auth {
            d.cc_pt_orderbook_qot_right = crypto_auth_to_api(v);
        }

        if let Some(v) = sub_limit
            && v > 0
        {
            d.sub_quota = v as i32;
        }
        if let Some(v) = kl_limit
            && v > 0
        {
            d.history_kl_quota = v as i32;
        }

        // F1 (v1.4.106 codex 1217): apply 成功 → 自动 mark Fresh.
        drop(d);
        let mut m = self.meta.lock();
        m.freshness = QotRightFreshness::Fresh;
        m.last_refresh_at_ms = now_ms();
    }
}

fn apply_qot_right_after_change(data: &mut QotRightData, quote_type: i32, after: u32) -> bool {
    match quote_type {
        1 => data.hk_qot_right = hk_clt_to_api(after),
        3 | 17 => {
            let right = us_clt_to_api(after);
            data.us_qot_right = right;
            data.api_us_qot_right = right;
        }
        4 => data.hk_future_qot_right = hk_clt_to_api(after),
        5 => data.hk_option_qot_right = hk_clt_to_api(after),
        36 => data.sg_future_qot_right = other_clt_to_api(after),
        39 => data.jp_future_qot_right = other_clt_to_api(after),
        30 => data.us_cme_future_qot_right = us_future_clt_to_api(after),
        31 => data.us_cbot_future_qot_right = us_future_clt_to_api(after),
        32 => data.us_nymex_future_qot_right = us_future_clt_to_api(after),
        33 => data.us_comex_future_qot_right = us_future_clt_to_api(after),
        37 => data.us_otc_qot_right = if after == 2 { 2 } else { 5 },
        38 => data.us_index_qot_right = us_clt_to_api(after),
        40 => data.sh_qot_right = cn_clt_to_api(after),
        41 => data.sz_qot_right = cn_clt_to_api(after),
        _ => return false,
    }
    true
}

#[cfg(test)]
mod tests;