futu_rest/adapter/

symbol_normalize.rs

//! Split from adapter.rs: symbol_normalize.
//!
//! pub items: normalize_json_keys_snake_case,expand_single_symbol_shorthand_to_security_and_owner,expand_symbols_array_to_security_list,parse_symbol_prefix,try_parse_mixed_array_to_securities,to_snake_case.

use serde_json::Value;

use super::*;

/// 只是现在同时也加 `owner` 方便 option-chain 等 endpoint。
pub(super) fn expand_single_symbol_shorthand_to_security_and_owner(
    inner: &mut serde_json::Map<String, Value>,
) -> Result<(), String> {
    // 若用户已显式传 security **对象** 或 owner **对象** → 不动
    // (但如 owner 是 **string**, 属 shorthand input, 继续处理)
    let has_security_obj = matches!(inner.get("security"), Some(Value::Object(_)));
    let has_owner_obj = matches!(inner.get("owner"), Some(Value::Object(_)));
    if has_security_obj || has_owner_obj {
        return Ok(());
    }
    // v1.4.104 external reviewer P1-001 (P1) fix: 若 array path (expand_symbols_array_to_security_list)
    // 已经生成 `security_list` (说明输入用 list-style endpoint shorthand
    // `symbol`/`code` singular → list), 单字符串 shorthand 路径**也跳过**.
    // 否则 single path 会从 `c2s.symbol` 再生成 `c2s.security` + `c2s.owner`
    // orphan objects, strict_fields validator 见 list-style proto (e.g.
    // qot_get_basic_qot.Request 仅有 security_list) 会把 security/owner
    // 当 unknown field → 400 reject.
    //
    // 注意 single path 仍要 remove `symbol`/`code` 这些 source key (不让它们
    // 留下被 strict_fields 当 unknown field). 所以条件是 "security_list 已
    // 存在 → 只 remove source 不再 insert security/owner".
    let _already_has_security_list = matches!(inner.get("security_list"), Some(Value::Array(_)));

    // 找 shorthand source key (按优先级: symbol > code > owner-string > security_string)
    const CANDIDATES: &[&str] = &["symbol", "code", "owner", "security_string"];
    let mut source_key_opt: Option<&'static str> = None;
    for key in CANDIDATES {
        if let Some(v) = inner.get(*key)
            && v.is_string()
        {
            source_key_opt = Some(*key);
            break;
        }
    }
    let Some(source_key) = source_key_opt else {
        return Ok(());
    };
    let Some(raw) = inner.remove(source_key) else {
        return Ok(());
    };
    let Value::String(sym) = raw else {
        inner.insert(source_key.to_string(), raw);
        return Ok(());
    };
    if let Some((market, code)) = parse_symbol_prefix(&sym)? {
        // v1.4.104 external reviewer P1-001 (P1) follow-up: 保留原行为 (生成 security + owner 双
        // 对象), 即使 array path 已生成 security_list. 因为大量已有测试期望
        // single path 生成 security/owner. 改修在 strict_fields 把 c2s.security
        // / c2s.owner 加进 ignore_paths for list-style endpoint (quote / snapshot
        // / subscribe). 此变量 _already_has_security_list 仅作 debug 提示, 不再
        // 改变行为.
        let mut sec = serde_json::Map::new();
        sec.insert("market".to_string(), Value::Number(market.into()));
        sec.insert("code".to_string(), Value::String(code));
        // 生成 security + owner 双对象 (各 proto 按自己字段名取)
        inner.insert("security".to_string(), Value::Object(sec.clone()));
        inner.insert("owner".to_string(), Value::Object(sec));
    } else {
        // prefix 不认识 → 放回 source key, 让 serde 报精确错误
        inner.insert(source_key.to_string(), Value::String(sym));
    }
    Ok(())
}

/// v1.4.82 B1: `"HK.00700"` / `"US.AAPL"` 等 prefix-style symbol 字符串 →
/// `(market: i32, code: String)`。
///
/// 返 None 表示无 `.` 分隔 或 prefix 未知。抽成独立 fn 是因为 `security_list`
/// (v1.4.82 B1) 和 `security` (v1.4.73 BUG-005) 两条 shorthand 路径都需要。
fn parse_symbol_prefix(sym: &str) -> Result<Option<(i32, String)>, String> {
    let Some((prefix, code)) = sym.split_once('.') else {
        return Ok(None);
    };
    // Historical REST shorthand accepted this non-public proto value. Keep the
    // compatibility local instead of teaching the shared QOT parser an enum
    // value that is absent from proto/Qot_Common.proto.
    if prefix.eq_ignore_ascii_case("US_FUTURE") && !code.is_empty() {
        futu_qot::symbol::validate_full_symbol_len(sym).map_err(|err| err.to_string())?;
        futu_qot::symbol::validate_symbol_code_len(code).map_err(|err| err.to_string())?;
        return Ok(Some((12, code.to_string())));
    }
    match futu_qot::symbol::parse_symbol_parts(sym) {
        Ok(parsed) => Ok(Some((parsed.market_i32(), parsed.code))),
        Err(err) => {
            let msg = err.to_string();
            if msg.contains("symbol length") || msg.contains("code length") {
                Err(msg)
            } else {
                Ok(None)
            }
        }
    }
}

/// v1.4.82 B1: 把 `code_list` / `symbols` / `stocks` / `symbol_list` 的字符串
/// 数组展开为 `security_list: [{market, code}, ...]` proto 期望格式。
///
/// **两类来源**:
/// 1. `security_list` 本身是 `[String]`（A1 alias 已把 `stocks`/`symbols`
///    rename 成 `security_list` 但保留原 string array 值）— 就地 transform
/// 2. `code_list` / `symbol_list` 等独立 shorthand key 存在 — take + transform
///
/// 用户已传 `security_list: [{market, code}, ...]`（正确 proto 格式）时不动。
/// 处理三种形式的 transform:
///   - 纯 `[String]` 数组（v1.4.82 B1 原实装）
///   - 纯 `[{market, code}]` 对象数组（proto 正确格式，不动）
///   - **混合** `[{market, code}, "US.AAPL", ...]`（v1.4.88 扩展；string 元素
///     被就地展开成 object，object 元素透传）
///
/// 若任一 string 元素 prefix 未知或非 String/Object → 整体回退放回，让 serde
/// 报精确错误，不 silent transform。
///
/// **v1.4.90 P0-C**: 任一路径数组长度超 `MAX_SYMBOLS_PER_REQUEST` 立即返
/// `Err(msg)`, 上抛由 `proto_request_with_idempotency` 转 400. v1.4.82 B1
/// 漏的 input validation, 攻击者 / buggy SDK 一次传 150k symbols → quota
/// 爆 + RSS 40× 放大. 检查覆盖三种来源:
///   - `security_list` 已含 string 元素(混合或纯 string)
///   - `security_list` 已是纯 object array(用户绕过 shorthand 直传)
///   - 独立 shorthand key (`code_list` / `symbols` / `stocks` / `symbol_list`)
pub(super) fn expand_symbols_array_to_security_list(
    inner: &mut serde_json::Map<String, Value>,
) -> Result<(), String> {
    // 路径 1: security_list 存在（A1 alias rename 后的形态 / 用户直传）
    if let Some(existing) = inner.get("security_list") {
        // v1.4.90 P0-C: 不论 string / object array 都先 cap 长度
        if let Value::Array(items) = existing
            && items.len() > MAX_SYMBOLS_PER_REQUEST
        {
            return Err(format!(
                "security_list length {} exceeds MAX_SYMBOLS_PER_REQUEST={}; \
                 split into multiple requests",
                items.len(),
                MAX_SYMBOLS_PER_REQUEST
            ));
        }
        // 判断 security_list 当前值是否需要 transform（含 string 元素即需要）
        if let Value::Array(items) = existing
            && items.iter().any(|it| it.is_string())
        {
            // 从 shorthand string/mixed array → Security objects（v1.4.88
            // 扩展：支持 string + object 混合，object 元素直接透传）
            // 取出后重新插入（避免 borrow 冲突）
            let Some(raw) = inner.remove("security_list") else {
                return Ok(());
            };
            let Value::Array(items) = raw else {
                inner.insert("security_list".to_string(), raw);
                return Ok(());
            };
            if let Some(expanded) = try_parse_mixed_array_to_securities(&items)? {
                inner.insert("security_list".to_string(), Value::Array(expanded));
            } else {
                // parse 失败 → 放回让 serde 报错
                inner.insert("security_list".to_string(), Value::Array(items));
            }
            // 已处理 path 1，不再 fall through 到 path 2 （security_list 已
            // 就地 transformed，避免再次触发）
            return Ok(());
        }
        // security_list 是纯 object array / 空数组 / 非 array — 用户显式传，不动
        return Ok(());
    }
    // 路径 2: 独立 shorthand key（code_list / symbols / stocks / symbol_list）
    //
    // v1.4.104 external reviewer P1-001 (P1) extension: 也接受单字符串 `symbol` / `code`
    // 作 1-element list shorthand. CLI/MCP 都接 `symbol: "US.AAPL"`, REST 之
    // 前要求 array (`symbols: ["US.AAPL"]`), 不一致让 agent 困惑. 现在两边
    // 都接, single-string 路径生成 `security_list: [{market, code}]`.
    //
    // 注: `symbol` / `code` 也是 `expand_single_symbol_shorthand_to_security_and_owner`
    // (path 后续) 的输入. 两个 path 用同 source key 时, 这里 (array path)
    // 优先 — security_list 是更通用形态, 单 security/owner endpoint 仍能用
    // security_list[0] 的 fallback (因 proto 字段名不同 serde 会 silent drop).
    // 但 single-symbol endpoint 通常显式传 `security` 对象, shorthand 走
    // single path 才需要; 此处只在 list 类 endpoint 配合.
    //
    // **去重策略**: 我们不 remove `symbol`/`code` (留给后续 single path 处理),
    // 只 clone 其值生成 `security_list`. 这样两个 path 各取所需, 互不打架.
    const CANDIDATES: &[&str] = &["code_list", "symbols", "stocks", "symbol_list"];
    const SINGULAR_CANDIDATES: &[&str] = &["symbol", "code"];
    let mut source_key_opt: Option<&'static str> = None;
    for key in CANDIDATES {
        if inner.contains_key(*key) {
            source_key_opt = Some(*key);
            break;
        }
    }
    if source_key_opt.is_none() {
        // v1.4.104 external reviewer P1-001 (P1) fix: 尝试 singular shorthand → 1-element list.
        // **重要**: 不 remove `symbol`/`code` 让 single path 后续也用 (生成
        // security/owner objects). single path 会 remove. 但 strict_fields
        // validator 在 expand_symbol_shorthand 后立即跑 deny_unknown_fields,
        // 此时 single path 已经 remove 了, 不会冲突.
        for key in SINGULAR_CANDIDATES {
            if let Some(Value::String(s)) = inner.get(*key)
                && let Some((market, code)) = parse_symbol_prefix(s)?
            {
                let mut sec = serde_json::Map::new();
                sec.insert("market".to_string(), Value::Number(market.into()));
                sec.insert("code".to_string(), Value::String(code));
                inner.insert(
                    "security_list".to_string(),
                    Value::Array(vec![Value::Object(sec)]),
                );
                // 不 return — 让外层 expand_symbol_shorthand 继续走 single path
                // (会 remove `symbol`/`code`, 防 strict_fields unknown-field reject)
                return Ok(());
            }
        }
        return Ok(());
    }
    let Some(source_key) = source_key_opt else {
        return Ok(());
    };
    let Some(raw) = inner.remove(source_key) else {
        return Ok(());
    };
    let Value::Array(items) = raw else {
        // 不是 array → 放回让 serde 报错
        inner.insert(source_key.to_string(), raw);
        return Ok(());
    };
    // v1.4.90 P0-C: shorthand-key 路径同样 cap 长度
    if items.len() > MAX_SYMBOLS_PER_REQUEST {
        return Err(format!(
            "{} length {} exceeds MAX_SYMBOLS_PER_REQUEST={}; \
             split into multiple requests",
            source_key,
            items.len(),
            MAX_SYMBOLS_PER_REQUEST
        ));
    }
    if let Some(expanded) = try_parse_mixed_array_to_securities(&items)? {
        inner.insert("security_list".to_string(), Value::Array(expanded));
    } else {
        // parse 失败 → 回退原 key + 原 array
        inner.insert(source_key.to_string(), Value::Array(items));
    }
    Ok(())
}

/// v1.4.88: 把 `[String | Security{market, code}]` 混合数组解析为
/// `[Security{market, code}]`（pure object / pure string / mixed 三形态）。
///
/// 每个元素的处理：
///   - `Value::String(sym)` → parse_symbol_prefix → `{market, code}` object
///   - `Value::Object` 含 `market` + `code` 字段 → 直接透传（不重 parse）
///   - 其他（Object 缺字段 / Number / Bool / null / Array） → 整体返 None
///
/// 只要一个 string 元素 prefix 未知 → 返 None，调用方回退原数组让 serde 报精确错。
/// 这保证 "要么全部合法转换，要么原样回退" 的 all-or-nothing 语义，避免半转换
/// 留下混合状态 confuse 下游 handler。
fn try_parse_mixed_array_to_securities(items: &[Value]) -> Result<Option<Vec<Value>>, String> {
    let mut out: Vec<Value> = Vec::with_capacity(items.len());
    for item in items {
        match item {
            Value::String(sym) => {
                let Some((market, code)) = parse_symbol_prefix(sym)? else {
                    return Ok(None);
                };
                let mut sec = serde_json::Map::new();
                sec.insert("market".to_string(), Value::Number(market.into()));
                sec.insert("code".to_string(), Value::String(code));
                out.push(Value::Object(sec));
            }
            // 已是 Security object — 校验含 market + code 字段（防用户误传
            // 其他 schema 也 silently 透传 junk 下去）
            Value::Object(obj) if obj.contains_key("market") && obj.contains_key("code") => {
                out.push(Value::Object(obj.clone()));
            }
            _ => return Ok(None),
        }
    }
    Ok(Some(out))
}

pub fn normalize_json_keys_snake_case(value: &mut Value) {
    match value {
        Value::Object(map) => {
            // 取出所有 entries，重建 map（遇到同 key snake_case 已存在，后到的覆盖）
            let mut new_map = serde_json::Map::with_capacity(map.len());
            // 用 std::mem::take 避免 clone
            let old = std::mem::take(map);
            for (k, mut v) in old {
                normalize_json_keys_snake_case(&mut v);
                let sk = to_snake_case(&k);
                new_map.insert(sk, v);
            }
            *map = new_map;
        }
        Value::Array(arr) => {
            for item in arr {
                normalize_json_keys_snake_case(item);
            }
        }
        _ => {}
    }
}

/// camelCase / PascalCase → snake_case 转换。
/// 已经是 snake_case / lowercase 的保持不变。
/// 规则：每个 uppercase letter 前加 `_`（除非在开头），然后全小写。
///
/// 例:
/// - `accID` → `acc_id` (ID 两个大写合并成一个 _id)
/// - `trdEnv` → `trd_env`
/// - `filterConditions` → `filter_conditions`
/// - `acc_id` → `acc_id` (已经 snake_case, 不动)
/// - `id` → `id`
/// - `ID` → `id`
pub(super) fn to_snake_case(s: &str) -> String {
    let mut out = String::with_capacity(s.len() + 4);
    let chars: Vec<char> = s.chars().collect();
    for (i, &c) in chars.iter().enumerate() {
        if c.is_ascii_uppercase() {
            // v1.4.47 P1.3 修（external reviewer 验收报告 §14.5）：之前 `pwdMD5` → `pwd_m_d5`（错），
            // `TRD_ENV` → `tr_d_env`（错）。根因：之前"连续大写 abbreviation"判据用
            // `next is uppercase or end`，不考虑 next 是**数字或下划线**的情况 ——
            // 这时应该**继续** treat as abbreviation（MD5 整体 / TRD 整体）不 break。
            //
            // 新规则：boundary 触发 = 从 non-upper 进 upper （正常 camelCase），
            // OR 从 upper 进 upper 再接 **lowercase** （acronym 结束，如 XMLParser
            // 在 P 前 break: `xml_parser`）。数字 / 下划线 / 结尾都算 "abbreviation
            // 继续"，不触发 boundary.
            //
            // 覆盖新场景：
            //  - `pwdMD5` → `pwd_md5` ✓（MD5 作为 abbreviation）
            //  - `TRD_ENV` → `trd_env` ✓（TRD 下划线前不 break 内部）
            //  - `accID` → `acc_id` ✓（原行为保持）
            //  - `XMLParser` → `xml_parser` ✓（acronym 遇 lowercase break）
            //
            // 未覆盖：`trdenv` / `TRDENV` 这种无 boundary marker 的全连写，无法拆（需字典）。
            let prev = if i > 0 { Some(chars[i - 1]) } else { None };
            let next = chars.get(i + 1).copied();
            let prev_upper = prev.map(|p| p.is_ascii_uppercase()).unwrap_or(false);
            // v1.4.47 P1.3: 判"abbreviation 继续"时考虑数字和下划线
            let next_is_not_lower = next.map(|n| !n.is_ascii_lowercase()).unwrap_or(true);
            let at_boundary = i > 0 && prev != Some('_') && !(prev_upper && next_is_not_lower);
            if at_boundary {
                out.push('_');
            }
            out.push(c.to_ascii_lowercase());
        } else {
            out.push(c);
        }
    }
    out
}