futu_trd/

currency.rs

//! Broker → supported currencies 表 + currency 校验 helper
//!
//! v1.4.105 (external reviewer funds-currency-display-suggestion 2026-04-29 P0):
//!
//! **触发**: 外部 reviewer 实测 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                 ← Moomoo CA 测试账户
//! 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 强调):
//! > "上一次修复就是因为 external reviewer 提到了 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++ 表, 不发明).

mod account;
mod ids;
mod labels;

pub use account::{AccountKind, classify_account, classify_account_with_auth_list};
pub use ids::{
    broker_id, currency_id, legacy_backend_fund_market_id, security_firm_id,
    security_firm_to_broker_id, trd_market_id,
};
pub use labels::{
    broker_label, currency_label, default_currency_by_security_firm, known_currency_label,
    missing_currency_error_message, parse_currency_label, unsupported_error_message,
};

/// 单币种账户的默认 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 — 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,
}

/// `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,
    }
}

/// **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(),
    }
}

#[cfg(test)]
mod tests;