futu_core/

diagnostic_text.rs

//! Stable user-facing diagnostic text keys and shared hint builders.
//!
//! Logs should keep stable machine-readable English markers. These helpers are
//! for CLI / REST / MCP / gateway human hints, where each message also carries
//! a stable diagnostic code so automation and docs can refer to the same row.

use std::collections::BTreeMap;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum DiagnosticTextKey {
    ProtoJsonQotMarketNumeric,
    QuotePermissionOpenMarket,
    StaticCacheMissing,
    OrderbookDetailPermission,
    JpStockQuotePermission,
    JpTradePermission,
    AllDayRiskDisclosure,
    UpdateCheckUnavailable,
    Qot3401UnsupportedMarket,
    Qot3401BackendError,
    Qot3401EntityIdRequired,
    Qot3401DiscoveryEmpty,
    Qot3401SampleUnavailable,
}

impl DiagnosticTextKey {
    pub const fn code(self) -> &'static str {
        match self {
            Self::ProtoJsonQotMarketNumeric => "proto_json.qot_market_numeric",
            Self::QuotePermissionOpenMarket => "quote.permission.open_market",
            Self::StaticCacheMissing => "static.cache_missing",
            Self::OrderbookDetailPermission => "quote.permission.orderbook_detail",
            Self::JpStockQuotePermission => "quote.permission.jp_stock",
            Self::JpTradePermission => "trade.permission.jp_market",
            Self::AllDayRiskDisclosure => "trade.risk_disclosure.all_day",
            Self::UpdateCheckUnavailable => "update.check_unavailable",
            Self::Qot3401UnsupportedMarket => "qot3401.unsupported_market",
            Self::Qot3401BackendError => "qot3401.backend_error",
            Self::Qot3401EntityIdRequired => "qot3401.entity_id_required",
            Self::Qot3401DiscoveryEmpty => "qot3401.discovery_empty",
            Self::Qot3401SampleUnavailable => "qot3401.sample_unavailable",
        }
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
pub enum MessageLocale {
    En,
    ZhCn,
    ZhHk,
}

impl MessageLocale {
    pub fn from_normalized_lang(lang: &str) -> Self {
        match lang {
            "chs" | "zh_CN" | "zh-cn" | "zh-Hans" | "zh_Hans" => Self::ZhCn,
            "cht" | "zh_HK" | "zh_TW" | "zh-hk" | "zh-tw" | "zh-Hant" | "zh_Hant" => Self::ZhHk,
            _ => Self::En,
        }
    }

    pub fn from_app_lang(app_lang: i32) -> Self {
        match app_lang {
            0 => Self::ZhCn,
            1 => Self::ZhHk,
            2 => Self::En,
            _ => Self::En,
        }
    }
}

#[derive(Debug, Clone, Default, PartialEq, Eq)]
pub struct MessageArgs {
    values: BTreeMap<&'static str, String>,
}

impl MessageArgs {
    pub fn new() -> Self {
        Self::default()
    }

    pub fn with(mut self, key: &'static str, value: impl Into<String>) -> Self {
        self.values.insert(key, value.into());
        self
    }
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub struct CatalogMessage {
    pub key: DiagnosticTextKey,
    pub locale: MessageLocale,
    pub template: &'static str,
}

#[derive(Debug, Clone, PartialEq, Eq)]
pub struct DiagnosticText {
    pub key: DiagnosticTextKey,
    pub text: String,
}

impl DiagnosticText {
    pub fn new(key: DiagnosticTextKey, text: impl Into<String>) -> Self {
        Self {
            key,
            text: text.into(),
        }
    }

    pub fn render(key: DiagnosticTextKey, locale: MessageLocale, args: MessageArgs) -> Self {
        let row = catalog_message(key, locale);
        Self::new(key, render_template(row.template, &args))
    }

    pub fn text_with_code(&self) -> String {
        format!("{} [diag:{}]", self.text, self.key.code())
    }
}

pub fn render_with_lang(
    key: DiagnosticTextKey,
    normalized_lang: &str,
    args: MessageArgs,
) -> DiagnosticText {
    DiagnosticText::render(
        key,
        MessageLocale::from_normalized_lang(normalized_lang),
        args,
    )
}

pub fn render_with_app_lang(
    key: DiagnosticTextKey,
    app_lang: i32,
    args: MessageArgs,
) -> DiagnosticText {
    DiagnosticText::render(key, MessageLocale::from_app_lang(app_lang), args)
}

pub fn proto_json_numeric_qot_market_hint() -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::ProtoJsonQotMarketNumeric,
        MessageLocale::En,
        MessageArgs::new(),
    )
}

pub fn quote_permission_action_for_market(
    market_suffix: Option<&str>,
    symbol: &str,
) -> DiagnosticText {
    let market = market_suffix.unwrap_or("market");
    let market_label = match market_suffix {
        Some("JP") => "JP stock",
        Some("US") => "US stock",
        Some("HK") => "HK stock",
        Some(market) => market,
        None => "the market",
    };
    DiagnosticText::render(
        DiagnosticTextKey::QuotePermissionOpenMarket,
        MessageLocale::En,
        MessageArgs::new()
            .with("market", market)
            .with("market_label", market_label)
            .with("symbol", symbol),
    )
}

pub fn static_cache_missing_message(normalized_symbol: &str, sec_key: &str) -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::StaticCacheMissing,
        MessageLocale::En,
        MessageArgs::new()
            .with("symbol", normalized_symbol)
            .with("sec_key", sec_key),
    )
}

pub fn orderbook_detail_permission_action() -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::OrderbookDetailPermission,
        MessageLocale::En,
        MessageArgs::new(),
    )
}

pub fn jp_stock_quote_permission_hint() -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::JpStockQuotePermission,
        MessageLocale::ZhCn,
        MessageArgs::new(),
    )
}

pub fn jp_trade_permission_hint() -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::JpTradePermission,
        MessageLocale::ZhCn,
        MessageArgs::new(),
    )
}

pub fn all_day_risk_disclosure_hint(help_url: &str) -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::AllDayRiskDisclosure,
        MessageLocale::ZhCn,
        MessageArgs::new().with("help_url", help_url),
    )
}

pub fn update_check_unavailable_action() -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::UpdateCheckUnavailable,
        MessageLocale::En,
        MessageArgs::new(),
    )
}

pub fn qot3401_unsupported_market_action() -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::Qot3401UnsupportedMarket,
        MessageLocale::En,
        MessageArgs::new(),
    )
}

pub fn qot3401_backend_error_action(api_name: &str, ret_code: i32) -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::Qot3401BackendError,
        MessageLocale::En,
        MessageArgs::new()
            .with("api_name", api_name)
            .with("ret_code", ret_code.to_string()),
    )
}

pub fn qot3401_entity_id_required_action() -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::Qot3401EntityIdRequired,
        MessageLocale::En,
        MessageArgs::new(),
    )
}

pub fn qot3401_discovery_empty_action() -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::Qot3401DiscoveryEmpty,
        MessageLocale::En,
        MessageArgs::new(),
    )
}

pub fn qot3401_sample_unavailable_action() -> DiagnosticText {
    DiagnosticText::render(
        DiagnosticTextKey::Qot3401SampleUnavailable,
        MessageLocale::En,
        MessageArgs::new(),
    )
}

fn catalog_message(key: DiagnosticTextKey, locale: MessageLocale) -> CatalogMessage {
    let template = match (key, locale) {
        (DiagnosticTextKey::ProtoJsonQotMarketNumeric, MessageLocale::ZhCn) => {
            "`market` 是生成的 proto 数字枚举，不是字符串。请使用 Qot_Common.QotMarket 数值，例如 HK=1, US=11, SH=21, SZ=22, SG=31, JP=41, AU=51, MY=61。示例：{\"market\":11}"
        }
        (DiagnosticTextKey::ProtoJsonQotMarketNumeric, MessageLocale::ZhHk) => {
            "`market` 是生成的 proto 數字枚舉，不是字串。請使用 Qot_Common.QotMarket 數值，例如 HK=1, US=11, SH=21, SZ=22, SG=31, JP=41, AU=51, MY=61。示例：{\"market\":11}"
        }
        (DiagnosticTextKey::ProtoJsonQotMarketNumeric, MessageLocale::En) => {
            "`market` is a numeric generated proto enum, not a string. Use Qot_Common.QotMarket values such as HK=1, US=11, SH=21, SZ=22, SG=31, JP=41, AU=51, MY=61. Example: {\"market\":11}"
        }

        (DiagnosticTextKey::QuotePermissionOpenMarket, MessageLocale::ZhCn) => {
            "先运行 futucli quote-rights；请在官方 Futu/moomoo App 开通{market_label}行情权限，然后用 futucli quote-rights 和 futucli quote-capability {symbol} 复查。"
        }
        (DiagnosticTextKey::QuotePermissionOpenMarket, MessageLocale::ZhHk) => {
            "先執行 futucli quote-rights；請在官方 Futu/moomoo App 開通{market_label}行情權限，然後用 futucli quote-rights 和 futucli quote-capability {symbol} 複查。"
        }
        (DiagnosticTextKey::QuotePermissionOpenMarket, MessageLocale::En) => {
            "run futucli quote-rights; open {market_label} quote permission in the official Futu/moomoo App if it remains zero, then recheck with futucli quote-rights and futucli quote-capability {symbol}"
        }

        (DiagnosticTextKey::StaticCacheMissing, MessageLocale::ZhCn) => {
            "静态缓存缺少 {symbol} ({sec_key})；请等待 stock-list sync 收敛，或先调用 static/static-warmup。"
        }
        (DiagnosticTextKey::StaticCacheMissing, MessageLocale::ZhHk) => {
            "靜態快取缺少 {symbol} ({sec_key})；請等待 stock-list sync 收斂，或先呼叫 static/static-warmup。"
        }
        (DiagnosticTextKey::StaticCacheMissing, MessageLocale::En) => {
            "static cache missing {symbol} ({sec_key}); wait stock-list sync or call static/static-warmup first"
        }

        (DiagnosticTextKey::OrderbookDetailPermission, MessageLocale::ZhCn) => {
            "请检查 quote-rights，并确认订阅账户具备所需 orderbook detail/depth 行情权限。"
        }
        (DiagnosticTextKey::OrderbookDetailPermission, MessageLocale::ZhHk) => {
            "請檢查 quote-rights，並確認訂閱帳戶具備所需 orderbook detail/depth 行情權限。"
        }
        (DiagnosticTextKey::OrderbookDetailPermission, MessageLocale::En) => {
            "check quote-rights and subscribe with the required orderbook detail permission"
        }

        (DiagnosticTextKey::JpStockQuotePermission, MessageLocale::ZhCn) => {
            "App 延时行情不等于 OpenD API 实时行情权限；请在官方 Futu/moomoo App 开通日股实时行情 / Premium 权限，然后用 futucli quote-rights 确认 JP stock 权限。"
        }
        (DiagnosticTextKey::JpStockQuotePermission, MessageLocale::ZhHk) => {
            "App 延時行情不等於 OpenD API 即時行情權限；請在官方 Futu/moomoo App 開通日股即時行情 / Premium 權限，然後用 futucli quote-rights 確認 JP stock 權限。"
        }
        (DiagnosticTextKey::JpStockQuotePermission, MessageLocale::En) => {
            "App delayed JP quotes do not imply OpenD API realtime quote permission; open JP realtime / Premium quote permission in the official Futu/moomoo App, then confirm JP stock permission with futucli quote-rights."
        }

        (DiagnosticTextKey::JpTradePermission, MessageLocale::ZhCn) => {
            "当前账户未开通日股交易权限（JP / trd_market=15）。请在 Futu/moomoo App 中开通日股交易权限，并按提示完成相关协议、风险披露、税务/市场权限流程。开通后重新查询账户，确认 trdmarket_auth 包含 JP/15，再重试下单。App 路径建议：账户 > 更多/交易权限 > 日股交易权限（以当前 App 实际入口为准）"
        }
        (DiagnosticTextKey::JpTradePermission, MessageLocale::ZhHk) => {
            "當前帳戶未開通日股交易權限（JP / trd_market=15）。請在 Futu/moomoo App 中開通日股交易權限，並按提示完成相關協議、風險披露、稅務/市場權限流程。開通後重新查詢帳戶，確認 trdmarket_auth 包含 JP/15，再重試下單。App 路徑建議：帳戶 > 更多/交易權限 > 日股交易權限（以當前 App 實際入口為準）"
        }
        (DiagnosticTextKey::JpTradePermission, MessageLocale::En) => {
            "The account does not have JP trading permission (JP / trd_market=15). Open JP trading permission in the Futu/moomoo App, finish the required agreements, risk disclosure, tax and market permission steps, then query accounts again and confirm trdmarket_auth contains JP/15 before retrying the order."
        }

        (DiagnosticTextKey::AllDayRiskDisclosure, MessageLocale::ZhCn) => {
            "后端要求先完成全时段交易风险披露。请在官方 Futu/moomoo App 内完成全时段交易相关风险披露后重试；daemon 只透传下单协议，无法代用户确认该披露。官方帮助入口：{help_url}"
        }
        (DiagnosticTextKey::AllDayRiskDisclosure, MessageLocale::ZhHk) => {
            "後端要求先完成全時段交易風險披露。請在官方 Futu/moomoo App 內完成全時段交易相關風險披露後重試；daemon 只透傳下單協議，無法代用戶確認該披露。官方幫助入口：{help_url}"
        }
        (DiagnosticTextKey::AllDayRiskDisclosure, MessageLocale::En) => {
            "The backend requires all-day trading risk disclosure before this order. Complete the all-day trading risk disclosure in the official Futu/moomoo App, then retry. The daemon only forwards order protocols and cannot confirm this disclosure for the user. Help: {help_url}"
        }

        (DiagnosticTextKey::UpdateCheckUnavailable, MessageLocale::ZhCn) => {
            "更新检查不可用；稍后重跑 `futucli version --check`，或用 `--url` / FUTU_UPDATE_CHECK_URL 指定 manifest，也可以用 `futucli doctor --no-update-check` 跳过 doctor 的更新检查。"
        }
        (DiagnosticTextKey::UpdateCheckUnavailable, MessageLocale::ZhHk) => {
            "更新檢查不可用；稍後重跑 `futucli version --check`，或用 `--url` / FUTU_UPDATE_CHECK_URL 指定 manifest，也可以用 `futucli doctor --no-update-check` 跳過 doctor 的更新檢查。"
        }
        (DiagnosticTextKey::UpdateCheckUnavailable, MessageLocale::En) => {
            "update check unavailable; rerun `futucli version --check` later, override with `--url` / FUTU_UPDATE_CHECK_URL, or skip doctor with `futucli doctor --no-update-check`"
        }

        (DiagnosticTextKey::Qot3401UnsupportedMarket, MessageLocale::ZhCn) => {
            "该 3401+ 接口当前不支持传入的 market。请使用数字 Qot_Common.QotMarket，并先用包内 examples/qot-3401-plus-proto-json-examples.json 查看该接口已登记的市场样例。常用值：HK=1, US=11, SH=21, SZ=22, SG=31, JP=41, AU=51, MY=61, CA=71。"
        }
        (DiagnosticTextKey::Qot3401UnsupportedMarket, MessageLocale::ZhHk) => {
            "該 3401+ 介面目前不支援傳入的 market。請使用數字 Qot_Common.QotMarket，並先用包內 examples/qot-3401-plus-proto-json-examples.json 查看該介面已登記的市場示例。常用值：HK=1, US=11, SH=21, SZ=22, SG=31, JP=41, AU=51, MY=61, CA=71。"
        }
        (DiagnosticTextKey::Qot3401UnsupportedMarket, MessageLocale::En) => {
            "this 3401+ endpoint does not support the supplied market; use numeric Qot_Common.QotMarket values and check examples/qot-3401-plus-proto-json-examples.json for the endpoint sample. Common values: HK=1, US=11, SH=21, SZ=22, SG=31, JP=41, AU=51, MY=61, CA=71"
        }

        (DiagnosticTextKey::Qot3401BackendError, MessageLocale::ZhCn) => {
            "{api_name} 后端返回 ret={ret_code}。请先运行对应发现入口并使用返回 ID；如果发现入口也返回空或 ret=-1，请把 market、C2S JSON、daemon 日志和 qot_3401_plus_discovery_chain_smoke.py 输出一起回传。"
        }
        (DiagnosticTextKey::Qot3401BackendError, MessageLocale::ZhHk) => {
            "{api_name} 後端返回 ret={ret_code}。請先執行對應發現入口並使用返回 ID；如果發現入口也返回空或 ret=-1，請把 market、C2S JSON、daemon 日誌和 qot_3401_plus_discovery_chain_smoke.py 輸出一起回傳。"
        }
        (DiagnosticTextKey::Qot3401BackendError, MessageLocale::En) => {
            "{api_name} backend returned ret={ret_code}; run the discovery list endpoint first and use the returned id. If discovery is empty or also returns ret=-1, attach market, C2S JSON, daemon logs, and qot_3401_plus_discovery_chain_smoke.py output to the bug report"
        }

        (DiagnosticTextKey::Qot3401EntityIdRequired, MessageLocale::ZhCn) => {
            "该详情接口需要有效 ID。机构详情请先跑 institution-list 取 institution_id；产业链详情请先跑 industrial-chain-list 取 chain_id；板块详情请从 heat-map-data / plate-list / chain-detail 返回的 plate_id 继续查询。"
        }
        (DiagnosticTextKey::Qot3401EntityIdRequired, MessageLocale::ZhHk) => {
            "該詳情介面需要有效 ID。機構詳情請先跑 institution-list 取 institution_id；產業鏈詳情請先跑 industrial-chain-list 取 chain_id；板塊詳情請從 heat-map-data / plate-list / chain-detail 返回的 plate_id 繼續查詢。"
        }
        (DiagnosticTextKey::Qot3401EntityIdRequired, MessageLocale::En) => {
            "this detail endpoint needs a valid id. Run institution-list for institution_id, industrial-chain-list for chain_id, and heat-map-data / plate-list / chain-detail for plate_id before querying detail endpoints"
        }

        (DiagnosticTextKey::Qot3401DiscoveryEmpty, MessageLocale::ZhCn) => {
            "发现入口没有返回可用 ID。请换 HK/US 等已登记市场样例重试；若仍为空，把请求 JSON 和 daemon 日志回传，先不要把详情接口当作可用路径。"
        }
        (DiagnosticTextKey::Qot3401DiscoveryEmpty, MessageLocale::ZhHk) => {
            "發現入口沒有返回可用 ID。請換 HK/US 等已登記市場示例重試；若仍為空，把請求 JSON 和 daemon 日誌回傳，先不要把詳情介面當作可用路徑。"
        }
        (DiagnosticTextKey::Qot3401DiscoveryEmpty, MessageLocale::En) => {
            "the discovery endpoint returned no usable id; retry with a registered HK/US sample and attach request JSON plus daemon logs before treating detail endpoints as usable"
        }

        (DiagnosticTextKey::Qot3401SampleUnavailable, MessageLocale::ZhCn) => {
            "当前请求缺少已验证生产样例。请参考包内 examples/qot-3401-plus-proto-json-examples.json，用真实后端成功样例补齐后再对外宣称可用。"
        }
        (DiagnosticTextKey::Qot3401SampleUnavailable, MessageLocale::ZhHk) => {
            "當前請求缺少已驗證生產示例。請參考包內 examples/qot-3401-plus-proto-json-examples.json，用真實後端成功示例補齊後再對外宣稱可用。"
        }
        (DiagnosticTextKey::Qot3401SampleUnavailable, MessageLocale::En) => {
            "this request has no verified production sample yet; use examples/qot-3401-plus-proto-json-examples.json and add a real backend success sample before claiming the path is usable"
        }
    };
    CatalogMessage {
        key,
        locale,
        template,
    }
}

fn render_template(template: &str, args: &MessageArgs) -> String {
    let mut rendered = template.to_string();
    for (key, value) in &args.values {
        rendered = rendered.replace(&format!("{{{key}}}"), value);
        rendered = rendered.replace(&format!("{{{{{key}}}}}"), value);
    }
    rendered
}