futu_trd/

currency.rs

//! Broker → supported currencies 表 + currency 校验 helper
//!
//! v1.4.105 (eli funds-currency-display-suggestion 2026-04-29 P0):
//!
//! **触发**: eli 实测 acc=70524409 (Moomoo CA) `/api/funds`:
//! - 请求 `currency=USD/HKD/SGD` 都返同一份 CAD 口径
//! - HKD/SGD 不该支持却 silent 不报错
//!
//! **C++ 对齐**: `APIServer_Trd_GetFunds.cpp:496-511` `CheckCurrencyValid` 调
//! `INNData_Trd_CommonCurrency::GetAccountValidCurrency(accItem)` 拿 broker
//! supported currency set, 不在内 → 返 `NNData_StaticText_InvalidCurrency`
//! "This account does not support converting to this currency".
//!
//! **C++ 静态表**: `INNData_Trd_CommonCurrency.cpp:4-14` 8 个静态 set:
//! ```text
//! HK Future (Futu HK)        HKD/USD/CNH/JPY
//! SG Future (FutuSG)         HKD/USD/CNH/JPY/SGD
//! MY Future (FutuMY)         MYR/CNH/JPY/SGD/HKD
//! HK Universal (Futu HK)     HKD/USD/CNH/JPY
//! US Universal (FutuInc)     HKD/USD/CNH/JPY/SGD
//! SG Universal (FutuSG)      HKD/USD/CNH/JPY/SGD
//! AU Universal (FutuAU)      HKD/USD/CNH/JPY/SGD/AUD
//! CA Universal (FutuCA)      USD/CAD                 ← eli 测试账户
//! MY Universal (FutuMY)      MYR/CNH/USD/SGD/HKD
//! JP Universal (FutuJP)      JPY/USD
//! ```
//! 单币种账户 (其他 trd_market): 由 TrdMarket → currency 派生 (HK→HKD /
//! US→USD / CN/HKCC→CNH).
//!
//! **历史教训** (用户 2026-04-29 强调):
//! > "上一次修复就是因为 deger 提到了 SGD, 结果就把返回 SGD 当作了正确结果."
//!
//! 即: 不能只 trust backend 返的 currency. 必须 broker → supported 表先验,
//! Moomoo CA 账户 (security_firm=5) 不支持 SGD, 即使 backend 真返了 SGD 也
//! 是 stale cache / 错误 routing. 本 helper 在 daemon-side 做 pre-check, 不
//! 发 backend, 直接返结构化 error (Layer A 防御).
//!
//! **相关**: pitfall #36 (SDK metadata 不可信, code/broker 才是真相), pitfall
//! #45 (silent-success — fallback 返 CAD 而无 loud reject), pitfall #51
//! (对齐 C++ 减法 — 抄 C++ 表, 不发明).

/// Trd_Common.proto::Currency enum (对齐 C++ + Rust proto):
/// 0=Unknown, 1=HKD, 2=USD, 3=CNH, 4=JPY, 5=SGD, 6=AUD, 7=CAD, 8=MYR.
/// USDT (9) 不在 C++ 静态表里, 是 daemon-only 扩展 (USDT 不是 broker
/// universal account 支持的法币, 不能 view 转换), 故不进 broker_currencies
/// 任何 set.
pub mod currency_id {
    pub const HKD: i32 = 1;
    pub const USD: i32 = 2;
    pub const CNH: i32 = 3;
    pub const JPY: i32 = 4;
    pub const SGD: i32 = 5;
    pub const AUD: i32 = 6;
    pub const CAD: i32 = 7;
    pub const MYR: i32 = 8;
}

/// Trd_Common.proto::SecurityFirm enum (对齐 C++):
/// 1=FutuSecurities (Futu HK), 2=FutuInc (Moomoo US), 3=FutuSG, 4=FutuAU,
/// 5=FutuCA (Moomoo CA), 6=FutuMY, 7=FutuJP.
pub mod security_firm_id {
    pub const FUTU_HK: i32 = 1; // FutuSecurities
    pub const FUTU_US: i32 = 2; // FutuInc / Moomoo US
    pub const FUTU_SG: i32 = 3;
    pub const FUTU_AU: i32 = 4;
    pub const FUTU_CA: i32 = 5; // Moomoo CA
    pub const FUTU_MY: i32 = 6;
    pub const FUTU_JP: i32 = 7;
}

/// `Trd_Common.proto::TrdMarket` enum (对齐 OpenD canonical NN_TrdMarket
/// values, 不是 App `FTTradeEnableMarket` 也不是 backend raw `Account.market`).
///
/// 主市场:
///   1=HK, 2=US, 3=CN, 4=HKCC, 5=Futures, 6=SG (全能账户/Universal),
///   8=AU, 15=JP, 111=MY, 112=CA.
///
/// 期货模拟 / 基金子市场 (v1.4.106 Finding D 收紧):
///   10=Futures_Simulate_HK, 11=Futures_Simulate_US, 12=Futures_Simulate_SG,
///   13=Futures_Simulate_JP (注意: 13 是 sim JP 期货, **不是** App
///   `FTTradeEnableMarketHKFund=13`).
///   113=HK_Fund, 123=US_Fund, 124=SG_Fund, 125=MY_Fund, 126=JP_Fund.
///
/// **Per Finding D (codex 2026-05-01 source audit)**: 不要把 App enum 值
/// (HK_FUND=13, US_FUND=23, SG_FUND=24) 当成 OpenAPI TrdMarket. App enums
/// 见 `FTCTradeInterfaceDefine.h::FTTradeEnableMarket`, OpenAPI 见
/// `Trd_Common.proto::TrdMarket` (这里的常量).
///
/// **注意**: `CachedTrdAcc.trd_market` 当前**存的是 backend raw
/// `Account.market`** (见 `bridge/account.rs::account_to_cached:202`),
/// backend raw 值 13=HK_Fund / 22=23=US_Fund / 24=SG_Fund 与 OpenAPI 113/123/124
/// **不同**. 详见 `legacy_backend_fund_market_id::*` 常量, 用于在 cache 读
/// 路径识别 fund 账户.
pub mod trd_market_id {
    pub const HK: i32 = 1;
    pub const US: i32 = 2;
    pub const CN: i32 = 3;
    pub const HKCC: i32 = 4;
    pub const FUTURES: i32 = 5;
    pub const SG: i32 = 6; // "全能账户" / Universal account market code
    pub const AU: i32 = 8;
    pub const JP: i32 = 15;
    pub const MY: i32 = 111;
    pub const CA: i32 = 112;

    // ── 模拟期权 / 模拟融资融券内部市场 ──
    //
    // Ref:
    // - `FutuOpenD/Src/NNBase/NNBase_Define_Enum.h:168-175`
    // - `FutuOpenD/Src/APIServer/Business/Trade/_APIServer_Trd_Comm.cpp:3148-3200`
    //
    // 这些值不是公开 `Trd_Common.proto::TrdMarket` 里的普通市场, 但 C++ 的
    // `GetCurrencyByTrdMarket` / `GetTrdSecMarket` 会在交易读响应投影时识别它们。
    // 因此它们只用于 response projection / cache 兼容, 不能拿来做用户入参枚举。
    pub const SIM_US_OPTION: i32 = 7;
    pub const SIM_HK_OPTION: i32 = 9;
    pub const SIM_US_MARGIN: i32 = 100;

    // ── Futures 模拟 (v1.4.106 Finding D) ──
    pub const FUTURES_SIMULATE_HK: i32 = 10;
    pub const FUTURES_SIMULATE_US: i32 = 11;
    pub const FUTURES_SIMULATE_SG: i32 = 12;
    /// **注意**: 13 是 OpenAPI sim JP 期货, **不是** App `FTTradeEnableMarketHKFund=13`.
    pub const FUTURES_SIMULATE_JP: i32 = 13;

    // ── Fund 子市场 (OpenAPI canonical NN_TrdMarket values) ──
    pub const HK_FUND: i32 = 113;
    pub const US_FUND: i32 = 123;
    pub const SG_FUND: i32 = 124;
    pub const MY_FUND: i32 = 125;
    pub const JP_FUND: i32 = 126;
}

/// Backend raw `Account.market` fund 子市场值 (v1.4.106 Finding D).
///
/// `bridge/account.rs::account_to_cached` 把 backend raw 13/23/24 映射到
/// `trd_market_auth_list` 用 NN_TrdMarket 值 113/123/124, **但** `acc.market`
/// 字段 (top-level account market) 直接当 raw 存进 `CachedTrdAcc.trd_market`.
/// 所以 cache-read 看 `trd_market` 时仍可能见 13/23/24 raw 值.
///
/// 这与 App `FTTradeEnableMarket` 数值碰巧 alias (HK_FUND=13 / US_FUND=23 /
/// SG_FUND=24), 但 **来源完全不同** — 这里是 backend `FTUsrTrdAcc.proto`
/// 下发的内部协议值. 不要用 App 上下文的语义解释.
pub mod legacy_backend_fund_market_id {
    pub const HK_FUND: i32 = 13;
    pub const US_FUND_OLD: i32 = 22; // legacy old encoding
    pub const US_FUND: i32 = 23;
    pub const SG_FUND: i32 = 24;
}

/// 账户类型分类 (用于查 supported currencies 表)
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum AccountKind {
    /// 期货账户 (`trd_market == NN_TrdMarket_Futures = 5`)
    Futures,
    /// 全能账户 / Universal (`trd_market == NN_TrdMarket_SG = 6`)
    /// 注意: SG=6 在 C++ 是 "全能账户" enum 的复用, 不是新加坡市场专属
    /// (见 `Trd_Common.proto:32` 注释 "期货市场"误注 + 实际 C++ 行为 path)
    Universal,
    /// 单币种账户 (其他所有 trd_market)
    SingleCurrency,
}

/// 账户类型识别 — 对齐 C++ `INNData_Trd_CommonCurrency::GetAccountValidCurrency`
/// (cpp:92-126) 的 3 分支结构:
///
/// ```cpp
/// if (enTrdMkt == NN_TrdMarket_Futures)        → futures set per broker
/// else if (enTrdMkt == NN_TrdMarket_SG /*6*/)  → universal set per broker
/// else                                          → single currency from
///                                                 GetTrdMarketCurrency(enTrdMkt)
///                                                 (HK→HKD / US→USD / CN/HKCC→CNH /
///                                                  default→Unknown+warn)
/// ```
///
/// **本 fn 是 Rust cache normalization defense, 不是 C++ direct copy**.
/// (Per v1.4.106 Finding C from codex source audit 2026-05-01).
///
/// C++ 严格按 `accItem.enTrdMkt == NN_TrdMarket_SG` 判 Universal, 没有任何
/// fallback. Rust 加 `uni_card_num + security_firm` fallback 是因为 Rust
/// cache (`CachedTrdAcc.trd_market`) 直接存 backend raw `Account.market`,
/// raw 值跟 OpenAPI `TrdMarket` 不一定 1:1 对齐 (e.g. backend raw=13=HK_Fund
/// vs OpenAPI 113=HK_Fund). 本 fn 防止 cache drift 把真 Universal 账户错认为
/// SingleCurrency 静默放宽 currency 校验.
///
/// **risk of fallback**: 万一 fallback 路径误把 single-market HK/US 账户认成
/// Universal, 会让 `validate_currency_for_account` 走 universal supported set,
/// 可能 reject C++ 接受的 currency. 本 fn 的 fallback 仅当 trd_market 不在
/// official 表里时启用 — 见 Step 3 实现注释.
///
/// **现实背景** (用户 2026-04-30 强调): "不论 hk/us/sg 等, 各个券商实体开给
/// 客户的都是 Universal account; single account 是**老的账户形态**, 已经被
/// 禁用, 只能浏览了". 所以现代活跃账户**99% 是 Universal** (`trd_market=6`),
/// SingleCurrency 路径仅服务遗留浏览-only 账户.
///
/// 输入信号 (按优先级 + 与 C++ 对齐 + cache drift 防御):
///
/// 1. **`trd_market = FUTURES (5)`**: Futures 账户 (C++ 第 1 分支, 不受
///    fallback 影响)
/// 2. **`trd_market = SG (6) = AccountMarket::UNIVERSAL`**: Universal (C++
///    第 2 分支, canonical)
/// 3. **`uni_card_num` 非空 + `security_firm` 已识别**: 仍按 Universal 处理
///    (cache drift 防御 — 真 Universal 账户必有 uni_card_num + security_firm).
///    **必须排在第 4 步前**, 防 cache 把 trd_market 错存成 raw NN_TrdMarket
///    值 (CA=112 / AU=8 / JP=15 / MY=111) 落进 SingleCurrency 静默放行.
/// 4. **`trd_market` ∈ legacy single 表** (HK=1 / US=2 / CN=3 / HKCC=4 +
///    backend-raw fund 13/22/23/24 + OpenAPI fund 113/123/124/125/126):
///    legacy SingleCurrency (浏览-only 老账户, C++ 第 3 分支的具体派生路径)
/// 5. 其他: SingleCurrency (supported 返 None → Unknown, 让 backend 决定)
///
/// 历史触发 (codex round 1 F1, v1.4.105 review):
/// 之前只看 `trd_market == SG (6)`, 真实 cache 若存 raw NN_TrdMarket 值
/// (CA=112 / AU=8 / JP=15 / MY=111) 则错落进 SingleCurrency, Layer A 静默放
/// 行 → HKD/SGD silent fallback regression 可能复活.
///
/// 用户 2026-04-30 进一步纠偏: legacy single-market HK/US/HKCC 账户在现实里
/// 都是浏览-only, **不应**早 return 抑制 Universal fallback — 真 Universal 账
/// 户即使 cache 漂移到 1/2/4, fallback 仍要识别正确.
pub fn classify_account(
    trd_market: Option<i32>,
    security_firm: Option<i32>,
    uni_card_num: Option<&str>,
) -> AccountKind {
    // Step 1: Futures canonical match (C++ 第 1 分支). Futures 账户没有
    // uni_card_num 概念, 不受 Universal fallback 影响.
    if trd_market == Some(trd_market_id::FUTURES) {
        return AccountKind::Futures;
    }

    // Step 2: Universal canonical match (C++ 第 2 分支, AccountMarket::UNIVERSAL=6).
    // 现代活跃账户 99% 走这条.
    if trd_market == Some(trd_market_id::SG) {
        return AccountKind::Universal;
    }

    // Step 3: Universal cache-drift fallback. **必须**在 Step 4 (legacy single
    // 早 return) 之前. 真 Universal 账户 (Moomoo CA/AU/JP/MY/SG/US) 必有
    // uni_card_num + security_firm. 即使 cache 把 trd_market 错存成 raw
    // NN_TrdMarket (CA=112 / AU=8 / JP=15 / MY=111) 或意外的 1/2/4 (HK/US/HKCC,
    // 但 fallback signal 都齐), 这层 fallback 仍能识别 Universal.
    //
    // Per 用户 2026-04-30: 现代 HK/US 等账户实质都是 Universal, single 是
    // legacy 浏览-only. 若一个有 uni_card_num 的账户被 cache 错存成 trd_market=1,
    // 我们仍按 Universal 处理 (fallback 优先于 legacy 单币种早 return).
    //
    // codex round 2 F2 (P2): defensive check — `uni_card_num=Some("")` 不应
    // trigger Universal fallback. backend 偶发下发空字符串, ingestion 层
    // (`account_to_cached`) 已 trim+filter, 这里再加一道防御 (与 ingestion
    // 一致).
    let uni_card_present = uni_card_num.is_some_and(|s| !s.trim().is_empty());
    if uni_card_present && security_firm.is_some() {
        return AccountKind::Universal;
    }

    // Step 4: Legacy single-market accounts (C++ 第 3 分支具体派生路径)
    // 仅服务**老账户** (HK Sec / US Sec / HKCC + 各国 Fund 子市场), 现代账户
    // 不会进这里. 没有 fallback signal 说明既无 uni_card_num 也无 broker —
    // legacy / browse-only 账户.
    //
    // **v1.4.106 Finding D 收紧**: 区分 backend raw `Account.market` (13=HK_Fund
    // / 22/23=US_Fund / 24=SG_Fund) 与 OpenAPI canonical `TrdMarket`
    // (113=HK_Fund / 123=US_Fund / 124=SG_Fund / 125=MY_Fund / 126=JP_Fund).
    // `CachedTrdAcc.trd_market` 直接存 backend raw `acc.market` (见
    // `bridge/account.rs::account_to_cached:202`), 所以两套都要识别.
    // App `FTTradeEnableMarket` 数值 (HK_FUND=13/US_FUND=23/SG_FUND=24)
    // 在数值上和 backend raw 巧合 alias, 但**绝不是同一概念** — 不能
    // 把 App enum 当 OpenAPI TrdMarket 解释 (per Finding D).
    match trd_market {
        // Legacy single-market (real)
        Some(trd_market_id::HK)
        | Some(trd_market_id::US)
        | Some(trd_market_id::CN)
        | Some(trd_market_id::HKCC)
        // Fund 子市场 — backend raw `Account.market` 值
        | Some(legacy_backend_fund_market_id::HK_FUND)
        | Some(legacy_backend_fund_market_id::US_FUND_OLD)
        | Some(legacy_backend_fund_market_id::US_FUND)
        | Some(legacy_backend_fund_market_id::SG_FUND)
        // Fund 子市场 — OpenAPI canonical `NN_TrdMarket` 值
        | Some(trd_market_id::HK_FUND)
        | Some(trd_market_id::US_FUND)
        | Some(trd_market_id::SG_FUND)
        | Some(trd_market_id::MY_FUND)
        | Some(trd_market_id::JP_FUND) => AccountKind::SingleCurrency,
        // Step 5: 其他 (None / unknown) → SingleCurrency,
        // single_currency_for_market 会返 None → supported_currencies 返 None →
        // Layer A 进 Unknown 分支, 让 backend 决定.
        _ => AccountKind::SingleCurrency,
    }
}

/// 从公开 `TrdMarket` / cache auth-list market 推导资金视图币种桶。
///
/// 这不是账户主币种推断，而是用于识别“同一个账户暴露了多个币种/市场资金视图”
/// 的结构信号。Dega 实测里部分现代 FutuHK 综合账户没有可靠 `uni_card_num`，
/// 但 `trd_market_auth_list` 同时带 US + HKFUND/USFUND；这类账户若按
/// SingleCurrency 处理，就会忽略用户显式 `currency` 参数。
///
/// Hardcoded / Assumption Ledger:
/// - 这些映射来自 `Trd_Common.proto::TrdMarket` 与本文件 `trd_market_id`
///   常量；不是按具体账号硬编码。
/// - 仅作为 `classify_account_with_auth_list` 的 fallback 信号；canonical
///   `trd_market=5/6` 与 `uni_card_num + broker` 仍优先。
fn market_currency_bucket(market: i32) -> Option<i32> {
    match market {
        trd_market_id::HK
        | trd_market_id::HKCC
        | trd_market_id::FUTURES
        | trd_market_id::HK_FUND
        | legacy_backend_fund_market_id::HK_FUND => Some(currency_id::HKD),
        trd_market_id::US
        | trd_market_id::US_FUND
        | legacy_backend_fund_market_id::US_FUND_OLD
        | legacy_backend_fund_market_id::US_FUND => Some(currency_id::USD),
        trd_market_id::CN => Some(currency_id::CNH),
        trd_market_id::SG | trd_market_id::SG_FUND | legacy_backend_fund_market_id::SG_FUND => {
            Some(currency_id::SGD)
        }
        trd_market_id::AU => Some(currency_id::AUD),
        trd_market_id::JP | trd_market_id::JP_FUND => Some(currency_id::JPY),
        trd_market_id::MY | trd_market_id::MY_FUND => Some(currency_id::MYR),
        trd_market_id::CA => Some(currency_id::CAD),
        _ => None,
    }
}

fn auth_list_has_cross_currency_view(trd_market_auth_list: &[i32]) -> bool {
    let mut buckets: Vec<i32> = Vec::new();
    for market in trd_market_auth_list {
        let Some(bucket) = market_currency_bucket(*market) else {
            continue;
        };
        if !buckets.contains(&bucket) {
            buckets.push(bucket);
        }
        if buckets.len() > 1 {
            return true;
        }
    }
    false
}

/// `classify_account` 的 cache-auth-list 增强版。
///
/// C++ 入口主要靠 `accItem.enTrdMkt == SG(6)` 识别综合账户，但 Rust cache
/// 的字段来自 backend `FTUsrTrdAcc`，有些现代综合账户可能缺 `uni_card_num`
/// 或 `trd_market=6` 信号。用户显式传 `currency` 时，auth-list 的跨币种
/// 市场组合是更接近用户感知的“综合资金视图”信号。
pub fn classify_account_with_auth_list(
    trd_market: Option<i32>,
    security_firm: Option<i32>,
    uni_card_num: Option<&str>,
    trd_market_auth_list: &[i32],
) -> AccountKind {
    let base = classify_account(trd_market, security_firm, uni_card_num);
    if !matches!(base, AccountKind::SingleCurrency) {
        return base;
    }
    if auth_list_has_cross_currency_view(trd_market_auth_list) {
        return AccountKind::Universal;
    }
    base
}

/// 单币种账户的默认 view currency (对齐 C++
/// `INNData_Trd_CommonCurrency.cpp::GetTrdMarketCurrency` line 63-87)
///
/// 单币种账户**只支持**这一个 currency, 用户传别的 → reject.
pub fn single_currency_for_market(trd_market: Option<i32>) -> Option<i32> {
    match trd_market? {
        // C++ GetTrdMarketCurrency: HK_Fund / Sim_HK_Option 也归 HKD
        trd_market_id::HK | trd_market_id::HKCC => Some(currency_id::HKD),
        trd_market_id::US => Some(currency_id::USD),
        trd_market_id::CN => Some(currency_id::CNH),
        // 注: AU/JP/MY/CA 单市场账户在 C++ 也会进 `default OMWarn` 分支返
        // Unknown — C++ 真实情况是 AU/JP/MY/CA 账户一定通过 trd_market=SG=6
        // 走 Universal 路径 (security_firm=4/7/6/5 区分 broker), 不会单独
        // 用 trd_market=8/15/111/112. 这里写 None 是 conservative.
        _ => None,
    }
}

/// 交易读响应的 market → currency 投影。
///
/// 这不是 `GetFunds` 单币种入参校验规则。C++ 在 positions / orders 等响应
/// 组包时调用 `_APIServer_Trd_Comm.cpp::GetCurrencyByTrdMarket`, 覆盖 SG/AU/JP
/// 和各类 sim market；而 `single_currency_for_market` 是用户传 `currency`
/// 时的单币种账户校验，故两者必须分开，避免再次把资金查询语义污染到订单/持仓
/// 响应投影。
///
/// Ref:
/// - `FutuOpenD/Src/APIServer/Business/Trade/_APIServer_Trd_Comm.cpp:3148-3200`
pub fn trade_read_currency_for_market(trd_market: Option<i32>) -> Option<i32> {
    match trd_market? {
        trd_market_id::HK | trd_market_id::SIM_HK_OPTION | trd_market_id::FUTURES_SIMULATE_HK => {
            Some(currency_id::HKD)
        }
        trd_market_id::US
        | trd_market_id::SIM_US_OPTION
        | trd_market_id::SIM_US_MARGIN
        | trd_market_id::FUTURES_SIMULATE_US => Some(currency_id::USD),
        trd_market_id::CN | trd_market_id::HKCC => Some(currency_id::CNH),
        trd_market_id::SG | trd_market_id::FUTURES_SIMULATE_SG => Some(currency_id::SGD),
        trd_market_id::AU => Some(currency_id::AUD),
        trd_market_id::JP | trd_market_id::FUTURES_SIMULATE_JP => Some(currency_id::JPY),
        trd_market_id::MY => Some(currency_id::MYR),
        trd_market_id::CA => Some(currency_id::CAD),
        _ => None,
    }
}

/// 期货账户 broker → supported currencies (对齐 C++
/// `INNData_Trd_CommonCurrency.cpp:4-6`)
fn futures_supported_currencies(security_firm: i32) -> Option<&'static [i32]> {
    match security_firm {
        // gs_setHKFuture
        security_firm_id::FUTU_HK => Some(&[
            currency_id::HKD,
            currency_id::USD,
            currency_id::CNH,
            currency_id::JPY,
        ]),
        // gs_setSGFuture
        security_firm_id::FUTU_SG => Some(&[
            currency_id::HKD,
            currency_id::USD,
            currency_id::CNH,
            currency_id::JPY,
            currency_id::SGD,
        ]),
        // gs_setMYFuture
        security_firm_id::FUTU_MY => Some(&[
            currency_id::MYR,
            currency_id::CNH,
            currency_id::JPY,
            currency_id::SGD,
            currency_id::HKD,
        ]),
        _ => None,
    }
}

/// 全能账户 broker → supported currencies (对齐 C++
/// `INNData_Trd_CommonCurrency.cpp:8-14`)
fn universal_supported_currencies(security_firm: i32) -> Option<&'static [i32]> {
    match security_firm {
        // gs_setHKUniversal
        security_firm_id::FUTU_HK => Some(&[
            currency_id::HKD,
            currency_id::USD,
            currency_id::CNH,
            currency_id::JPY,
        ]),
        // gs_setUSUniversal
        security_firm_id::FUTU_US => Some(&[
            currency_id::HKD,
            currency_id::USD,
            currency_id::CNH,
            currency_id::JPY,
            currency_id::SGD,
        ]),
        // gs_setSGUniversal
        security_firm_id::FUTU_SG => Some(&[
            currency_id::HKD,
            currency_id::USD,
            currency_id::CNH,
            currency_id::JPY,
            currency_id::SGD,
        ]),
        // gs_setAUUniversal
        security_firm_id::FUTU_AU => Some(&[
            currency_id::HKD,
            currency_id::USD,
            currency_id::CNH,
            currency_id::JPY,
            currency_id::SGD,
            currency_id::AUD,
        ]),
        // gs_setCAUniversal — eli 测试账户 (acc=70524409 Moomoo CA)
        security_firm_id::FUTU_CA => Some(&[currency_id::USD, currency_id::CAD]),
        // gs_setMYUniversal
        security_firm_id::FUTU_MY => Some(&[
            currency_id::MYR,
            currency_id::CNH,
            currency_id::USD,
            currency_id::SGD,
            currency_id::HKD,
        ]),
        // gs_setJPUniversal
        security_firm_id::FUTU_JP => Some(&[currency_id::JPY, currency_id::USD]),
        _ => None,
    }
}

/// 取账户 supported currencies 完整列表 (对齐 C++
/// `INNData_Trd_CommonCurrency::GetAccountValidCurrency` line 90-146)
///
/// - 期货账户: 按 broker 取 futures set
/// - 全能账户: 按 broker 取 universal set
/// - 单币种账户: 仅一个 currency (TrdMarket → Currency 派生)
/// - broker 未识别: None (无法判断, daemon 不该 hard reject — 让 backend 决定)
pub fn supported_currencies(
    security_firm: Option<i32>,
    trd_market: Option<i32>,
    uni_card_num: Option<&str>,
) -> Option<Vec<i32>> {
    match classify_account(trd_market, security_firm, uni_card_num) {
        AccountKind::Futures => security_firm
            .and_then(futures_supported_currencies)
            .map(|s| s.to_vec()),
        AccountKind::Universal => security_firm
            .and_then(universal_supported_currencies)
            .map(|s| s.to_vec()),
        AccountKind::SingleCurrency => single_currency_for_market(trd_market).map(|c| vec![c]),
    }
}

/// 真实持仓刷新 CMD3020 使用的默认查询币种。
///
/// 对齐 C++:
/// - `APIServer_Trd_GetPositionList.cpp:197,210` 调
///   `INNProto_Trd_Acc::QueryPositionListNoLimit(...)`
/// - `NNProto_Trd_Acc.cpp:787-801` 内部调用
///   `QueryAssetInner(false, INNData_Trd_CommonCurrency::GetAccountFirstValidCurrency(accItem), ...)`
/// - `INNData_Trd_CommonCurrency.cpp:148-192` 对 futures/universal 账户取
///   supported currency set 的 `begin()`，single-currency 账户走
///   `GetTrdMarketCurrency`.
///
/// 注意这不是用户侧 `GetFunds` 默认币种策略。`GetFunds` 为 UX 会按券商本地
/// 币种补齐未传 currency；`GetPositionList` 没有 currency 字段，只是在
/// C++ 内部用 first-valid currency 拉一次 AccountInfoReq 来刷新持仓 cache。
///
/// Hardcoded / Assumption Ledger:
/// - supported currency set 来自本文件上方 C++ 对齐表，不按具体账号硬编码。
/// - C++ 用 `std::set<NN_TrdCurrency>::begin()`，Rust 用数值最小 currency
///   等价表达；若 C++ 改为保持插入顺序，这里必须同步调整。
pub fn first_valid_currency_for_account(
    security_firm: Option<i32>,
    trd_market: Option<i32>,
    uni_card_num: Option<&str>,
    trd_market_auth_list: &[i32],
) -> Option<i32> {
    let kind = classify_account_with_auth_list(
        trd_market,
        security_firm,
        uni_card_num,
        trd_market_auth_list,
    );
    let mut supported = supported_currencies_for_kind(kind, security_firm, trd_market)?;
    supported.sort_unstable();
    supported.into_iter().next()
}

fn supported_currencies_for_kind(
    kind: AccountKind,
    security_firm: Option<i32>,
    trd_market: Option<i32>,
) -> Option<Vec<i32>> {
    match kind {
        AccountKind::Futures => security_firm
            .and_then(futures_supported_currencies)
            .map(|s| s.to_vec()),
        AccountKind::Universal => security_firm
            .and_then(universal_supported_currencies)
            .map(|s| s.to_vec()),
        AccountKind::SingleCurrency => single_currency_for_market(trd_market).map(|c| vec![c]),
    }
}

/// Layer A 校验结果 (用 enum 让 caller 区分四种状态)
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum CurrencyValidation {
    /// requested currency 在 broker supported set 内 → OK 发 backend.
    /// SingleCurrency 缺 currency 也归 Ok (跟 C++ legacy 分支一致).
    Ok,
    /// **v1.4.106 Finding F1**: Futures / Universal 账户**必传** currency,
    /// 未传 → loud reject (对齐 C++ `CheckReqParams_GetFunds`:
    /// `if (!c2s.has_currency()) return false;`).
    /// SingleCurrency 缺 currency 不进此分支, 仍归 Ok.
    Missing {
        broker_label: &'static str,
        supported_label_list: Vec<&'static str>,
    },
    /// requested currency 不在 set 内 → 立即 reject (不发 backend)
    /// 含 broker 标签 + supported list 用于 error message
    Unsupported {
        broker_label: &'static str,
        supported_label_list: Vec<&'static str>,
    },
    /// 无法判断 (security_firm=None / cache miss / unknown broker) — 不 hard
    /// reject, 让 backend 决定. 仍记录 hint 用于日志.
    Unknown,
}

/// security_firm enum int → 对齐 broker 标签 (用于 error message)
pub fn broker_label(security_firm: Option<i32>) -> &'static str {
    match security_firm {
        Some(security_firm_id::FUTU_HK) => "Futu HK",
        Some(security_firm_id::FUTU_US) => "Moomoo US",
        Some(security_firm_id::FUTU_SG) => "Moomoo SG",
        Some(security_firm_id::FUTU_AU) => "Moomoo AU",
        Some(security_firm_id::FUTU_CA) => "Moomoo CA",
        Some(security_firm_id::FUTU_MY) => "Moomoo MY",
        Some(security_firm_id::FUTU_JP) => "Moomoo JP",
        _ => "unknown broker",
    }
}

/// Broker 默认资金视图币种。
///
/// 这是 surface UX 层用于“用户未显式传 currency”时补齐 `Trd_GetFunds`
/// 请求币种的规则，不是 C++ `CheckReqParams_GetFunds` 的参数校验规则。
/// C++ 对 Futures / Universal 缺 `currency` 会直接 missing-parameter；Rust
/// CLI/REST/MCP 为了让用户可直接用 App 可见 card-num 查资金，在 gateway
/// 统一派生一个用户可预期的默认币种后再发 backend。
///
/// Hardcoded / Assumption Ledger:
/// - broker enum 来自 `Trd_Common.proto::SecurityFirm` 与本文件
///   `security_firm_id` 常量，不按具体账号硬编码。
/// - 默认币种按券商本地记账币种选择：FutuHK=HKD, FutuInc=USD,
///   FutuSG=SGD, FutuAU=AUD, FutuCA=CAD, FutuMY=MYR, FutuJP=JPY。
/// - 若后续 backend 下发显式 base currency，应优先替换这张静态 broker 表。
pub fn default_currency_by_security_firm(security_firm: Option<i32>) -> Option<i32> {
    match security_firm? {
        security_firm_id::FUTU_HK => Some(currency_id::HKD),
        security_firm_id::FUTU_US => Some(currency_id::USD),
        security_firm_id::FUTU_SG => Some(currency_id::SGD),
        security_firm_id::FUTU_AU => Some(currency_id::AUD),
        security_firm_id::FUTU_CA => Some(currency_id::CAD),
        security_firm_id::FUTU_MY => Some(currency_id::MYR),
        security_firm_id::FUTU_JP => Some(currency_id::JPY),
        _ => None,
    }
}

/// `Trd_GetFunds` 用户侧 effective currency。
///
/// - 用户显式传 `currency`：原样使用，后续 validator 负责校验 supported set。
/// - Futures / Universal 未传：按 broker 默认币种补齐，避免 CLI/REST/MCP 每个
///   surface 自己猜，也避免用户必须先知道内部 acc_id/currency 规则。
/// - SingleCurrency 未传：保持 `None`，对齐 C++ legacy 分支“currency 被忽略”
///   的语义。
pub fn effective_get_funds_currency_for_account(
    requested_currency: Option<i32>,
    security_firm: Option<i32>,
    trd_market: Option<i32>,
    uni_card_num: Option<&str>,
    trd_market_auth_list: &[i32],
) -> Option<i32> {
    if requested_currency.is_some() {
        return requested_currency;
    }

    let kind = classify_account_with_auth_list(
        trd_market,
        security_firm,
        uni_card_num,
        trd_market_auth_list,
    );
    match kind {
        AccountKind::Futures | AccountKind::Universal => {
            default_currency_by_security_firm(security_firm)
        }
        AccountKind::SingleCurrency => None,
    }
}

/// currency enum int → 对齐 currency 标签 (用于 error message)
pub fn currency_label(c: i32) -> &'static str {
    match c {
        currency_id::HKD => "HKD",
        currency_id::USD => "USD",
        currency_id::CNH => "CNH",
        currency_id::JPY => "JPY",
        currency_id::SGD => "SGD",
        currency_id::AUD => "AUD",
        currency_id::CAD => "CAD",
        currency_id::MYR => "MYR",
        9 => "USDT", // daemon-only extension, not in C++
        _ => "UNKNOWN",
    }
}

/// Parse a user-facing currency code into `Trd_Common.Currency` enum int.
///
/// This is the shared contract for CLI / MCP / REST-like adapters that accept
/// textual currency input. Unknown values must be rejected loudly by the caller
/// instead of silently falling back to "no currency".
pub fn parse_currency_label(s: &str) -> anyhow::Result<i32> {
    match s.trim().to_ascii_uppercase().as_str() {
        "HKD" => Ok(currency_id::HKD),
        "USD" => Ok(currency_id::USD),
        "CNH" | "CNY" | "RMB" => Ok(currency_id::CNH),
        "JPY" => Ok(currency_id::JPY),
        "SGD" => Ok(currency_id::SGD),
        "AUD" => Ok(currency_id::AUD),
        "CAD" => Ok(currency_id::CAD),
        "MYR" => Ok(currency_id::MYR),
        "USDT" => Ok(9),
        _ => anyhow::bail!("invalid currency {s:?}: expected HKD|USD|CNH|JPY|SGD|AUD|CAD|MYR|USDT"),
    }
}

/// Display label for known currency IDs.
///
/// `currency_label` deliberately returns `UNKNOWN` for diagnostics. Table/JSON
/// presentation often needs a tri-state instead: absent / unknown should stay
/// absent so the surface can render `-`, omit a field, or choose its own
/// fallback text.
#[must_use]
pub fn known_currency_label(c: Option<i32>) -> Option<&'static str> {
    match c? {
        currency_id::HKD => Some("HKD"),
        currency_id::USD => Some("USD"),
        currency_id::CNH => Some("CNH"),
        currency_id::JPY => Some("JPY"),
        currency_id::SGD => Some("SGD"),
        currency_id::AUD => Some("AUD"),
        currency_id::CAD => Some("CAD"),
        currency_id::MYR => Some("MYR"),
        9 => Some("USDT"),
        _ => None,
    }
}

/// **Layer A pre-check** — 严格对齐 C++ `CheckReqParams_GetFunds` /
/// `CheckCurrencyValid` (`APIServer_Trd_GetFunds.cpp:457-491`):
///
/// ```cpp
/// // 期货综合账户或全能账户需要传货币参数
/// if (accItem.enTrdMkt == NN_TrdMarket_Futures || accItem.enTrdMkt == NN_TrdMarket_SG)
/// {
///     if (!c2s.has_currency()) return false;     // missing → reject
///     if (!CheckCurrencyValid(...)) return false; // out-of-set → reject
/// }
/// return true;
/// ```
///
/// **C++ 只对 `Futures` (trd_market=5) + `SG/Universal` (trd_market=6)
/// 验证 currency**. 其他账户 (legacy HK Sec / US Sec / HKCC / Crypto / Forex
/// / HK_Fund / US_Fund / sim) **完全不验证** — backend 在 `FillFunds` else
/// branch 用 `nnFunds.enCurrency` 返 native currency, 静默忽略 client 传的
/// `currency` 参数.
///
/// **v1.4.106 修法 (P0 + Finding F1, 真机 vs C++ OpenD 4/4 不一致 catalog 触发)**:
/// 之前 v1.4.105 对**所有**账户 strict reject, 违反 pitfall #51 "对齐
/// C++ = 减法". legacy 单市场账户 + USD/CAD/SGD daemon reject 但 C++ 接受.
/// 现在严格只 validate Futures + Universal, SingleCurrency 直接 pass-through.
///
/// **v1.4.106 Finding F1 收紧**: 之前 `requested_currency=None` 全部账户都
/// pass-through (太宽松). C++ `CheckReqParams_GetFunds` 对 Futures + SG/Universal
/// 强制要求 `c2s.has_currency()`, 缺则返 missing-parameter. 现在分两层:
///   - SingleCurrency 缺 currency → `Ok` (legacy pass-through 不变)
///   - Futures / Universal 缺 currency → `Missing` (loud reject)
///
/// SGD silent-trust regression 防御仍由 `Universal` 分支锁住:
/// Moomoo CA Universal (security_firm=5 + uni_card_num + AccountMarket=6)
/// 进 `AccountKind::Universal` 分支, supported set 不含 SGD → reject.
///
/// Return 分类:
/// - `Ok`:
///   1. SingleCurrency kind (legacy 单市场 / Crypto / Forex / Fund / sim) —
///      pass-through, 无论 requested 是否 = None.
///   2. Futures/Universal + supported list 已知 + requested ∈ set
/// - `Missing` (v1.4.106 新加):
///   - Futures / Universal kind + requested = None + supported list 已知
/// - `Unsupported`:
///   - Futures / Universal kind + supported list 已知 + requested ∉ set
/// - `Unknown`:
///   - Futures / Universal kind 但 broker 未识别 (security_firm=None / cache
///     miss) → 让 backend 决定 (无法构造 supported list, 也无 Missing
///     loud-reject 上下文)
pub fn validate_currency_for_account(
    requested_currency: Option<i32>,
    security_firm: Option<i32>,
    trd_market: Option<i32>,
    uni_card_num: Option<&str>,
) -> CurrencyValidation {
    // **v1.4.106 Finding F1**: classify FIRST, 之前 missing-currency 在
    // classify 前 early-return Ok 让 Futures/Universal 缺 currency 静默放行,
    // 与 C++ 不一致.
    let kind = classify_account(trd_market, security_firm, uni_card_num);

    // **v1.4.106 P0 减法**: SingleCurrency kind 直接 Pass-through (无论 requested
    // 是否 = None), 跟 C++ legacy 分支一致 (只对 Futures + SG validate).
    // 此 kind 涵盖 legacy 单市场 / Crypto / Forex / HK_Fund / US_Fund / sim 账户.
    if matches!(kind, AccountKind::SingleCurrency) {
        return CurrencyValidation::Ok;
    }

    // 到这里: kind ∈ {Futures, Universal}. 跟 C++ 同样 strict validate.
    let Some(supported) = supported_currencies(security_firm, trd_market, uni_card_num) else {
        // broker 未知 (security_firm=None) → 让 backend 决定. 不 hard reject.
        return CurrencyValidation::Unknown;
    };

    // **v1.4.106 Finding F1**: missing currency on Futures/Universal → loud reject.
    // 对齐 C++ `CheckReqParams_GetFunds:475-485`:
    //   `if (!c2s.has_currency()) return false;`
    let Some(req) = requested_currency else {
        return CurrencyValidation::Missing {
            broker_label: broker_label(security_firm),
            supported_label_list: supported.iter().map(|&c| currency_label(c)).collect(),
        };
    };

    if supported.contains(&req) {
        return CurrencyValidation::Ok;
    }

    // requested ∉ supported → Layer A reject (历史 SGD silent-trust 防御).
    // 跟 C++ backend `CheckCurrencyValid` 行为一致.
    CurrencyValidation::Unsupported {
        broker_label: broker_label(security_firm),
        supported_label_list: supported.iter().map(|&c| currency_label(c)).collect(),
    }
}

/// User-facing `Trd_GetFunds` currency validation.
///
/// 用户感知语义（2026-05-05 真机反馈）：
/// - 未显式传 `currency`：使用账户/backend 默认口径，不因为现代综合账户缺参数而
///   拒绝；不能自行硬贴 HKD/USD 标签。
/// - 显式传 `currency`：必须落在账户支持集合内，并由 backend 返回同币种的
///   `union_fund_info`，否则 gateway 后置校验会 loud reject。
/// - Legacy SingleCurrency 账户沿用 C++ legacy 分支 pass-through：不在本层按
///   单市场默认币种拒绝用户显式 currency；后续 refresh/cache key 会保留该参数。
///
/// 这与 `validate_currency_for_account` 的 C++ strict-missing 行为不同，后者仍保留
/// 给需要完全模拟 C++ 参数检查的路径。
pub fn validate_get_funds_currency_for_account(
    requested_currency: Option<i32>,
    security_firm: Option<i32>,
    trd_market: Option<i32>,
    uni_card_num: Option<&str>,
    trd_market_auth_list: &[i32],
) -> CurrencyValidation {
    let kind = classify_account_with_auth_list(
        trd_market,
        security_firm,
        uni_card_num,
        trd_market_auth_list,
    );
    if matches!(kind, AccountKind::SingleCurrency) {
        return CurrencyValidation::Ok;
    }

    let Some(req) = requested_currency else {
        return CurrencyValidation::Ok;
    };

    let Some(supported) = supported_currencies_for_kind(kind, security_firm, trd_market) else {
        return CurrencyValidation::Unknown;
    };

    if supported.contains(&req) {
        return CurrencyValidation::Ok;
    }

    CurrencyValidation::Unsupported {
        broker_label: broker_label(security_firm),
        supported_label_list: supported.iter().map(|&c| currency_label(c)).collect(),
    }
}

/// 把 Unsupported 变 user-friendly error message (PII-free, 不暴露内部
/// 实现细节 / 私仓源码路径 / 发版引用)
///
/// codex round 1 F3 (P2) v1.4.105: 之前 message 含 `APIServer_Trd_GetFunds.cpp
/// ::CheckCurrencyValid` C++ 私仓引用 + `see CHANGELOG v1.4.105` release-process
/// hint, 这俩不应进 user-facing public surface (`/api/funds` / MCP / CLI). 改成
/// 只保留 broker / requested currency / supported list — 用户能看懂 + ops 能
/// debug 即可. C++ 对齐证据保留在本 helper 上方代码注释.
pub fn unsupported_error_message(
    requested: i32,
    broker_label: &str,
    supported_labels: &[&'static str],
) -> String {
    format!(
        "InvalidCurrency: account at broker {broker} does not support currency {req}. \
         supported currencies for this account: {sup}.",
        broker = broker_label,
        req = currency_label(requested),
        sup = supported_labels.join(", "),
    )
}

/// **v1.4.106 Finding F1**: missing-currency 错误消息 (Futures / Universal 必传).
/// 对齐 C++ `CheckReqParams_GetFunds:475-485` "missing necessary parameter
/// Currency" 语义.
pub fn missing_currency_error_message(
    broker_label: &str,
    supported_labels: &[&'static str],
) -> String {
    format!(
        "MissingCurrency: futures/universal account at broker {broker} requires \
         the `currency` parameter. supported currencies for this account: {sup}.",
        broker = broker_label,
        sup = supported_labels.join(", "),
    )
}

#[cfg(test)]
mod tests;