futu_rest/adapter/

response.rs

//! Split from adapter.rs: response.
//!
//! pub items: ApiResponse.

use serde_json::Value;

use super::symbol_normalize::{
    expand_single_symbol_shorthand_to_security_and_owner, expand_symbols_array_to_security_list,
};

#[derive(serde::Serialize)]
pub struct ApiResponse<T: serde::Serialize> {
    pub ret_type: i32,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub ret_msg: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    pub data: Option<T>,
}

/// v1.4.45 (同事 external tester v1.4.43 反馈 "acc_id=0" 根因修): 把 JSON body 里所有
/// camelCase key 转 snake_case。FTAPI proto 文档里字段名是 camelCase
/// (`accID` / `trdEnv` / `filterConditions` / `beginTime`) — py-futu-api 和
/// C++ OpenD 的文档都这样写。但 Rust REST 的 serde 默认按 struct field 名
/// snake_case 匹配 + `#[serde(default)]` 静默吞未知字段 → 用户从官方文档复制
/// 的 curl body 在 Rust daemon 就变成 acc_id=0 默认值。
///
/// **修法**：在 JSON body 进 serde 之前预处理，把 camelCase key 递归转
/// snake_case。snake_case 原本正确的不受影响。
///
/// 边界情况：
/// - 嵌套 object 递归转
/// - Array 元素如果是 object 也递归转
/// - 非字符串 key / 非对象 Value 保持不动
/// - 字段值里的大小写不动（只处理 **key**）
///
/// **CLAUDE.md 核心原则对齐**："任何实现上的细节缺失，对用户来说都是功能缺失"
/// —— 和 FTAPI 官方 camelCase 不兼容 = 功能缺失。
/// v1.4.68 Bug fix (external reviewer v1.4.57 #6): 常见 SDK 字段别名 → proto 字段
///
/// Python SDK 用 `max_count` 作为 K 线查询参数名，FTAPI proto 字段是
/// `maxAckKLNum` / normalize 后 `max_ack_kl_num`。用户直接调 REST 若用
/// Python SDK 习惯的 `max_count` / `req_count` → serde drop → silent fail
/// (handler 用 0 不 truncate → 返 1000+ 条)。
///
/// 解法：在 normalize 之后加通用 field alias 表，同义字段自动 rename 到
/// canonical proto 字段名。Alias 优先级：不覆盖已存在的 canonical 字段。
///
/// 未来加新 alias 时列到本表：
/// - `req_count` → `max_ack_kl_num`（external reviewer 报告用的字段名）
/// - `max_count` → `max_ack_kl_num`（Python SDK 参数名）
#[cfg(test)]
pub(crate) fn apply_known_field_aliases(value: &mut Value) {
    apply_known_field_aliases_for_proto_id(value, None);
}

pub(crate) fn apply_known_field_aliases_for_proto_id(value: &mut Value, proto_id: Option<u32>) {
    // v1.4.82 A1 B1 配套: subscribe SDK 友好别名（双 tester v1.4.81 NEW-c22f-012 发现
    // 用户传 stocks/symbols/sub_types/is_sub 非 proto 字段被 serde 静默 drop
    // → SubHandler 空 list → silent-success）. 本 alias + SubHandler 入口 loud
    // validation 协同（CLAUDE.md 坑 #45）。
    //
    // **注意 symbols → security_list 的结构不匹配**：
    //   - alias 目标 security_list 要求 `[{market: N, code: "..."}, ...]`
    //   - 用户传的 `symbols: ["US.AAPL", ...]` 是扁平字符串
    //   - 本 alias 只做 key rename；结构转换（string array → Security object
    //     array）在 `expand_symbol_shorthand` → `expand_symbols_array_to_security_list`
    //     完成（v1.4.82 B1 + v1.4.88 mixed-array 扩展）
    const COMMON_ALIASES: &[(&str, &str)] = &[
        ("req_count", "max_ack_kl_num"),
        ("max_count", "max_ack_kl_num"),
        // v1.4.82 A1: subscribe 字段名 SDK 友好 alias
        ("symbols", "security_list"),
        ("stocks", "security_list"),
        ("sub_types", "sub_type_list"),
        ("is_sub", "is_sub_or_un_sub"),
    ];
    // These shorthand aliases are only valid for endpoints whose proto really
    // uses begin_time/end_time. StockFilter/GetWarrant have a real `begin`
    // pagination field; applying this globally turns valid requests into
    // "missing begin" before serde sees them.
    const TIME_ALIASES: &[(&str, &str)] = &[
        // v1.4.90 P0-D: history-kline 用户常用 `begin` / `end` 简称
        // (类 Python SDK 风格), proto 字段是 `begin_time` / `end_time`.
        // 漏 alias → serde 静默 drop → handler 用空字符串默认 → backend 返
        // 245 行全量 K 线 + ret_type=0 (silent-success 反模式 #45).
        ("begin", "begin_time"),
        ("end", "end_time"),
        // v1.4.104 external reviewer OBS-P3-002 (P3) fix: option-chain / option-expiration-date
        // / warrant 等 endpoint 也常用 `start` 当 begin_time alias (类 Python
        // SDK + Bloomberg-style). 之前只有 `begin` alias, `start` 被 strict
        // validator silent drop. 加 alias 与 `begin` 并行 (proto 字段不变).
        ("start", "begin_time"),
    ];

    let apply_time_aliases = proto_id.is_none_or(supports_begin_time_aliases);
    match value {
        Value::Object(map) => {
            apply_aliases_to_map(map, COMMON_ALIASES);
            if apply_time_aliases {
                apply_aliases_to_map(map, TIME_ALIASES);
            }
            for v in map.values_mut() {
                apply_known_field_aliases_for_proto_id(v, proto_id);
            }
        }
        Value::Array(arr) => {
            for item in arr {
                apply_known_field_aliases_for_proto_id(item, proto_id);
            }
        }
        _ => {}
    }
}

fn apply_aliases_to_map(map: &mut serde_json::Map<String, Value>, aliases: &[(&str, &str)]) {
    for (alias, canonical) in aliases {
        if map.contains_key(*canonical) {
            // canonical 已存在 → 不覆盖，user 显式指定优先
            map.remove(*alias);
        } else if let Some(v) = map.remove(*alias) {
            map.insert((*canonical).to_string(), v);
        }
    }
}

fn supports_begin_time_aliases(proto_id: u32) -> bool {
    matches!(
        proto_id,
        futu_core::proto_id::QOT_GET_HISTORY_KL
            | futu_core::proto_id::QOT_REQUEST_HISTORY_KL
            | futu_core::proto_id::QOT_GET_OPTION_CHAIN
            | futu_core::proto_id::QOT_GET_CAPITAL_FLOW
            | futu_core::proto_id::QOT_GET_SUSPEND
            | futu_core::proto_id::QOT_GET_HOLDING_CHANGE_LIST
            | futu_core::proto_id::QOT_GET_TRADE_DATE
            | futu_core::proto_id::QOT_REQUEST_TRADE_DATE
    )
}

/// v1.4.73 BUG-005 fix: auto-wrap "flat" body 到 `{c2s: ...}` 嵌套结构。
///
/// external reviewer v1.4.71 AI tester 报告：`POST /api/history-kline -d
/// '{"symbol":"HK.00700","kl_type":"day","max_count":5}'` 返
/// `ret_type=-1 "invalid kl_type"`（误导错，实际 proto Request struct 要求
/// 顶层 `c2s` wrapper，用户传的 flat body 让 serde 报 "missing c2s" 被转成
/// 看起来像字段值错的文案）。
///
/// 已在 adapter 入口（`proto_request_with_idempotency`）做 `normalize_json_keys_snake_case`
/// 和 proto-aware field aliases 之后、`serde_json::from_value` 之前调。
///
/// 判断规则：
/// 1. 必须是 object（非 object 不动）
/// 2. 已有 `c2s` key → 不动（nested form 已正确）
/// 3. 有 `s2c` / `ret_type` / `ret_msg` / `err_code` key → 不动（看起来是
///    response 结构误传 body，不 auto-wrap 免得加深错误）
/// 4. 其他情况 → 把整个 object 包一层 `{c2s: body}`
///
/// 不尝试 validate c2s 字段 shape（让 serde_json::from_value 报更精确错误）。
pub(crate) fn maybe_wrap_flat_body_as_c2s(value: &mut Value) {
    let Value::Object(map) = value else {
        return;
    };
    // 已嵌套 c2s 不动
    if map.contains_key("c2s") {
        return;
    }
    // response 结构误传 不动（这种情况交给 serde error message 告诉用户）
    for response_key in ["s2c", "ret_type", "ret_msg", "err_code"] {
        if map.contains_key(response_key) {
            return;
        }
    }
    // empty body → 不需要 wrap（serde_json::from_value(json!({})) 后 Request::default()）
    if map.is_empty() {
        return;
    }
    // 把整个 object 包装进 c2s
    let inner = std::mem::take(map);
    map.insert("c2s".to_string(), Value::Object(inner));
}

/// v1.4.90 P2-D: 把 c2s 顶层的 trade-header 字段(`acc_id` / `trd_env`
/// / `trd_market` / `jp_acc_type`) 自动 expand 到 `c2s.header.{...}` 嵌套.
///
/// **背景**: MCP tool 用 flat schema `{acc_id, trd_market, trd_env}`,
/// REST 11+ trade endpoint 的 proto 是 `{c2s: {header: {trd_env, acc_id,
/// trd_market}, ...}}` 嵌套. tester 常踩坑: 拿 MCP schema 直接 curl REST →
/// header 字段全 silent drop → backend 拿 acc_id=0 + trd_env=0 + trd_market=0
/// 直接报 "acc_id mismatch" 或更糟的 silent-success.
///
/// **触发规则**:
/// 1. 必须存在 `c2s` object
/// 2. `c2s` 已含 `header` 对象 → 不动(用户已显式)
/// 3. `c2s` 顶层含至少一个 trade-header 字段 → 把这些字段 move 进
///    `c2s.header`, 不影响其它字段(如 order_id / price / qty 等)
/// 4. 顶层无 trade-header 字段 → 不动(非 trade endpoint)
///
/// 已在 `maybe_wrap_flat_body_as_c2s` 之后调用, 所以即使用户传纯 flat body
/// (如 `{acc_id, market, code}`) 也已先包成 `{c2s: {acc_id, market, code}}`,
/// 这里再把 `acc_id` 提进 `header`. 无 c2s / 已有 header 时为 no-op.
///
/// proto 字段映射: `Trd_Common.TrdHeader { trd_env, acc_id, trd_market,
/// jp_acc_type }`. 见 `proto/Trd_Common.proto:315-322`.
pub(crate) fn maybe_expand_flat_trd_header(value: &mut Value) {
    let Value::Object(top) = value else {
        return;
    };
    let Some(Value::Object(c2s)) = top.get_mut("c2s") else {
        return;
    };
    // 已有 header object → 不动
    if matches!(c2s.get("header"), Some(Value::Object(_))) {
        return;
    }
    // proto Trd_Common.TrdHeader 字段名(snake_case 已 normalize 过)
    const HEADER_FIELDS: &[&str] = &["trd_env", "acc_id", "trd_market", "jp_acc_type"];
    // 收集 c2s 顶层中存在的 header 字段
    let mut header_map = serde_json::Map::new();
    for field in HEADER_FIELDS {
        if let Some(v) = c2s.remove(*field) {
            header_map.insert((*field).to_string(), v);
        }
    }
    // 任一 header 字段都没传 → 非 trade endpoint, 不动
    if header_map.is_empty() {
        return;
    }
    c2s.insert("header".to_string(), Value::Object(header_map));
}

/// v1.4.73 BUG-005 fix: 处理 `symbol: "HK.00700"` shorthand → `security: {market, code}`。
///
/// Python SDK / 文档里常用 `symbol` 字符串表示 market + code 合并形式。proto
/// 要求嵌套 `security: {market: 1, code: "00700"}`。Adapter 检测 c2s 里有
/// `symbol` 字段但缺 `security` 时自动 parse + 替换。
///
/// Market prefix 覆盖（与 CLAUDE.md 坑 #36 "code-first" 原则一致）：
/// `HK.xxx / US.xxx / SH.xxx / SZ.xxx / HK_CC.xxx / SG.xxx / JP.xxx / AU.xxx
/// / CA.xxx / HK_FUTURE.xxx / US_FUTURE.xxx`
///
/// Unknown prefix → 保留 symbol 字段不处理（交给下游 handler / serde 报错）。
///
/// **v1.4.90 P0-C**: 数组 expand 路径加 `MAX_SYMBOLS_PER_REQUEST` 检查, 超
/// 限返 `Err(msg)`, 由调用方转 400. 空 string 单 symbol shorthand 路径
/// 不受影响(单 symbol 没 DoS 风险).
pub(crate) fn expand_symbol_shorthand(value: &mut Value) -> Result<(), String> {
    let Value::Object(top) = value else {
        return Ok(());
    };
    // 递归进 c2s 处理（新包装的 flat body 已进入 c2s）
    let Some(Value::Object(inner)) = top.get_mut("c2s") else {
        return Ok(());
    };

    // v1.4.82 B1: **数组 shorthand 先处理**（c22f 双 tester v1.4.81 §6 13
    // REST endpoint silent empty 的主要修法之一）。
    //
    // 用户传 `code_list: ["US.AAPL", "HK.00700"]` 或 `symbols: ["US.TSLA"]`
    // 字符串数组，proto 期望 `security_list: [{market, code}, ...]` 对象数组。
    // 不做转换 → serde 反序列化 String[] 到 Security[] 失败 → 400 或 drop →
    // handler 收空 list → silent-success ret_type=0 空数据。
    //
    // 这里在 `security_list` 不存在时，把 `code_list` / `symbols` / `stocks`
    // / `symbol_list` 的字符串数组展开为 Security 对象数组。
    //
    // v1.4.90 P0-C: 数组长度先 cap, 超 MAX_SYMBOLS_PER_REQUEST 直接 400.
    expand_symbols_array_to_security_list(inner)?;

    // v1.4.83 §6 Phase 1.4 extend:
    // tester 报 capital-flow / option-chain / option-expiration-date / warrant
    // 用户传 `{"code": "US.AAPL"}` 或 `{"owner": "HK.00700"}` 单字符串 ret=-1.
    // 这些 proto 期望 `security: {market, code}` 或 `owner: {market, code}` 对象.
    //
    // 扩展 single-security shorthand 支持 4 种输入 key: `symbol` / `code`
    // / `owner` / `security_string`, 生成 **两个字段** (`security` +
    // `owner`), proto struct 各取自己的字段名, 另一个被 serde silent drop.
    //
    // 这样:
    // - capital-flow 用 security → security field hit
    // - option-chain / option-expiration-date / warrant 用 owner → owner field hit
    // - 不破坏 v1.4.73 原 `symbol` → `security` 单 field 行为
    //   (因为大部分 endpoint 只有一个字段, `owner` 被 drop 无害)
    expand_single_symbol_shorthand_to_security_and_owner(inner)?;
    Ok(())
}