futu_rest/adapter/

response.rs

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

use serde_json::Value;

use futu_core::{trade_market, trade_parsing};

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

pub(crate) type EndpointRequestNormalizer = fn(&mut Value) -> Result<(), String>;

#[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 之后按 endpoint proto id 应用 field alias，同义字段自动
/// rename 到 canonical proto 字段名。Alias 优先级：不覆盖已存在的 canonical 字段。
///
/// `max_count` 本身也是 SearchQuote/SearchNews 的 canonical 字段，不能全局改写。
/// C++ 对照：`APIServer_Qot_Search.cpp:229-233,274-278` 直接读取各搜索 C2S 的
/// `max_count`；只有声明 `maxAckKLNum` 的历史 K 线 endpoint 才能应用下列别名。
/// 未来加新 alias 时必须同时登记适用的 proto id：
/// - `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_with_scope(value, true, true);
}

pub(crate) fn apply_known_field_aliases_for_proto_id(value: &mut Value, proto_id: Option<u32>) {
    apply_known_field_aliases_with_scope(
        value,
        proto_id.is_some_and(supports_max_ack_kl_num_aliases),
        proto_id.is_some_and(supports_begin_time_aliases),
    );
}

fn apply_known_field_aliases_with_scope(
    value: &mut Value,
    apply_max_ack_kl_num_aliases: bool,
    apply_time_aliases: bool,
) {
    // 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 MAX_ACK_KL_NUM_ALIASES: &[(&str, &str)] = &[
        ("req_count", "max_ack_kl_num"),
        ("max_count", "max_ack_kl_num"),
    ];
    const COMMON_ALIASES: &[(&str, &str)] = &[
        // 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"),
    ];

    match value {
        Value::Object(map) => {
            if apply_max_ack_kl_num_aliases {
                apply_aliases_to_map(map, MAX_ACK_KL_NUM_ALIASES);
            }
            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_with_scope(
                    v,
                    apply_max_ack_kl_num_aliases,
                    apply_time_aliases,
                );
            }
        }
        Value::Array(arr) => {
            for item in arr {
                apply_known_field_aliases_with_scope(
                    item,
                    apply_max_ack_kl_num_aliases,
                    apply_time_aliases,
                );
            }
        }
        _ => {}
    }
}

/// Normalize high-level REST `/api/cancel-order` aliases into the underlying
/// `Trd_ModifyOrder(Cancel)` C2S shape.
///
/// This is intentionally endpoint-local. `ModifyOrder` remains the low-level
/// proto surface, while `CancelOrder` accepts the CLI/MCP-style flat shape:
/// `env`, `market`, `op`, `order_id_ex`, and string-form numeric `order_id`.
/// Strict-field validation, route-level checks, and the adapter decoder all
/// call this same function so the three boundaries cannot drift.
fn normalize_cancel_order_env_alias_in_map(
    map: &mut serde_json::Map<String, Value>,
) -> Result<(), String> {
    if map.contains_key("trd_env") {
        map.remove("env");
        return Ok(());
    }
    let Some(value) = map.remove("env") else {
        return Ok(());
    };
    let trd_env = parse_rest_trd_env(&value)?;
    map.insert("trd_env".to_string(), Value::Number(trd_env.into()));
    Ok(())
}

pub(crate) fn normalize_cancel_order_env_alias(value: &mut Value) -> Result<(), String> {
    let Some(root) = value.as_object_mut() else {
        return Ok(());
    };
    let owner = match root.get_mut("c2s") {
        Some(Value::Object(c2s)) => c2s,
        _ => root,
    };

    let header_has_canonical = owner
        .get("header")
        .and_then(Value::as_object)
        .is_some_and(|header| header.contains_key("trd_env"));
    if header_has_canonical {
        owner.remove("trd_env");
        owner.remove("env");
        if let Some(header) = owner.get_mut("header").and_then(Value::as_object_mut) {
            header.remove("env");
        }
        return Ok(());
    }

    normalize_cancel_order_env_alias_in_map(owner)?;
    let owner_env = owner.remove("trd_env");
    if let Some(header) = owner.get_mut("header").and_then(Value::as_object_mut) {
        if let Some(owner_env) = owner_env {
            header.remove("env");
            header.insert("trd_env".to_string(), owner_env);
        } else {
            normalize_cancel_order_env_alias_in_map(header)?;
        }
    } else if let Some(owner_env) = owner_env {
        owner.insert("trd_env".to_string(), owner_env);
    }
    Ok(())
}

pub(crate) fn normalize_cancel_order_request_aliases(value: &mut Value) -> Result<(), String> {
    normalize_cancel_order_env_alias(value)?;
    let Some(map) = value.as_object_mut() else {
        return Ok(());
    };
    if let Some(c2s) = map.get_mut("c2s").and_then(Value::as_object_mut) {
        normalize_cancel_order_c2s_aliases(c2s)?;
    } else {
        normalize_cancel_order_c2s_aliases(map)?;
    }
    Ok(())
}

/// Normalize REST history-order aliases into the underlying
/// `Trd_GetHistoryOrderList` / `Trd_GetHistoryOrderFillList` C2S shape.
///
/// CLI and MCP expose `market` as both the trade header market and the
/// APIServer-side `filter_conditions.filter_market`. Raw REST previously only
/// had the proto JSON shape, so SDK-style flat calls could accidentally query a
/// wider account market set than CLI/MCP.
pub(crate) fn normalize_history_order_request_aliases(value: &mut Value) -> Result<(), String> {
    let Some(map) = value.as_object_mut() else {
        return Ok(());
    };
    if let Some(c2s) = map.get_mut("c2s").and_then(Value::as_object_mut) {
        normalize_history_order_c2s_aliases(c2s)?;
    } else {
        normalize_history_order_c2s_aliases(map)?;
    }
    Ok(())
}

/// Normalize the documented `/api/margin-ratio` flat request into the
/// underlying `TrdHeader` shape. Alias/canonical duplicates fail closed so a
/// request never depends on map ordering.
pub(crate) fn normalize_margin_ratio_request_aliases(value: &mut Value) -> Result<(), String> {
    let Some(root) = value.as_object_mut() else {
        return Ok(());
    };
    let owner = match root.get_mut("c2s") {
        Some(Value::Object(c2s)) => c2s,
        Some(_) => return Err("invalid margin-ratio c2s; expected object".to_string()),
        None => root,
    };
    let mut header = match owner.remove("header") {
        Some(Value::Object(header)) => header,
        Some(_) => return Err("invalid margin-ratio header; expected object".to_string()),
        None => serde_json::Map::new(),
    };

    if let Some(value) =
        take_unique_margin_ratio_header_field(owner, &mut header, "acc_id", &["acc_id"])?
    {
        header.insert("acc_id".to_string(), value);
    }
    if let Some(value) = take_unique_margin_ratio_header_field(
        owner,
        &mut header,
        "env/trd_env",
        &["trd_env", "env"],
    )? {
        let trd_env = parse_rest_trd_env(&value)?;
        header.insert("trd_env".to_string(), Value::Number(trd_env.into()));
    }
    if let Some(value) = take_unique_margin_ratio_header_field(
        owner,
        &mut header,
        "market/trd_market",
        &["trd_market", "market"],
    )? {
        let trd_market = parse_rest_write_trd_market(&value)?;
        header.insert("trd_market".to_string(), Value::Number(trd_market.into()));
    }

    if !header.is_empty() {
        owner.insert("header".to_string(), Value::Object(header));
    }
    Ok(())
}

fn take_unique_margin_ratio_header_field(
    owner: &mut serde_json::Map<String, Value>,
    header: &mut serde_json::Map<String, Value>,
    logical_name: &str,
    names: &[&str],
) -> Result<Option<Value>, String> {
    let mut values = Vec::new();
    for name in names {
        if let Some(value) = header.remove(*name) {
            values.push(value);
        }
        if let Some(value) = owner.remove(*name) {
            values.push(value);
        }
    }
    if values.len() > 1 {
        return Err(format!(
            "conflicting margin-ratio {logical_name} fields; supply exactly one alias or canonical field"
        ));
    }
    Ok(values.pop())
}

pub(crate) fn endpoint_local_request_normalizer_for_spec(
    spec: &futu_surface_spec::EndpointSpec,
) -> Option<EndpointRequestNormalizer> {
    super::endpoint_policy::endpoint_adapter_policy_for_spec(spec)
        .and_then(|policy| policy.request_normalizer)
}

pub(crate) fn normalize_endpoint_local_request_aliases_for_spec(
    spec: &futu_surface_spec::EndpointSpec,
    value: &mut Value,
) -> Result<(), String> {
    if let Some(normalizer) = endpoint_local_request_normalizer_for_spec(spec) {
        normalizer(value)
    } else {
        Ok(())
    }
}

pub(crate) fn normalize_endpoint_local_request_aliases_for_rest_path(
    rest_path: &str,
    value: &mut Value,
) -> Result<(), String> {
    if let Some(policy) = super::endpoint_policy::endpoint_adapter_policy_for_rest_path(rest_path)
        && let Some(normalizer) = policy.request_normalizer
    {
        return normalizer(value);
    }
    let Some(spec) = futu_surface_spec::lookup_endpoint_by_rest_path(rest_path) else {
        return Ok(());
    };
    normalize_endpoint_local_request_aliases_for_spec(spec, value)
}

fn normalize_cancel_order_c2s_aliases(
    c2s: &mut serde_json::Map<String, Value>,
) -> Result<(), String> {
    normalize_cancel_order_header_aliases(c2s)?;
    normalize_cancel_order_id_aliases(c2s)?;
    let move_trd_market = c2s
        .get("header")
        .and_then(Value::as_object)
        .is_some_and(|header| !header.contains_key("trd_market"))
        .then(|| c2s.remove("trd_market"))
        .flatten();
    if let Some(header) = c2s.get_mut("header").and_then(Value::as_object_mut) {
        normalize_cancel_order_header_aliases(header)?;
        if let Some(value) = move_trd_market {
            header.insert("trd_market".to_string(), value);
        }
    }
    normalize_cancel_order_op(c2s)
}

fn normalize_history_order_c2s_aliases(
    c2s: &mut serde_json::Map<String, Value>,
) -> Result<(), String> {
    let header_market = normalize_history_order_header_aliases(c2s)?;
    normalize_history_order_filter_aliases(c2s, header_market)
}

fn normalize_history_order_header_aliases(
    c2s: &mut serde_json::Map<String, Value>,
) -> Result<Option<i32>, String> {
    let mut header = c2s
        .remove("header")
        .map(|v| match v {
            Value::Object(map) => map,
            other => {
                let mut map = serde_json::Map::new();
                map.insert("invalid_header".to_string(), other);
                map
            }
        })
        .unwrap_or_default();

    if !header.contains_key("acc_id")
        && let Some(value) = c2s.remove("acc_id")
    {
        header.insert("acc_id".to_string(), value);
    }
    if !header.contains_key("trd_env")
        && let Some(value) = remove_first(c2s, &["trd_env", "env"])
    {
        let trd_env = parse_rest_trd_env(&value)?;
        header.insert("trd_env".to_string(), Value::Number(trd_env.into()));
    }

    let mut header_market = header
        .get("trd_market")
        .map(parse_rest_read_trd_market)
        .transpose()?;
    if !header.contains_key("trd_market")
        && let Some(value) = remove_first(c2s, &["trd_market", "market", "order_market"])
    {
        let trd_market = parse_rest_read_trd_market(&value)?;
        header.insert("trd_market".to_string(), Value::Number(trd_market.into()));
        header_market = Some(trd_market);
    } else if header_market.is_some() {
        c2s.remove("trd_market");
        c2s.remove("market");
    }

    if !header.is_empty() {
        c2s.insert("header".to_string(), Value::Object(header));
    }
    Ok(header_market)
}

fn normalize_history_order_filter_aliases(
    c2s: &mut serde_json::Map<String, Value>,
    header_market: Option<i32>,
) -> Result<(), String> {
    let mut filter = c2s
        .remove("filter_conditions")
        .map(|v| match v {
            Value::Object(map) => map,
            other => {
                let mut map = serde_json::Map::new();
                map.insert("invalid_filter_conditions".to_string(), other);
                map
            }
        })
        .unwrap_or_default();

    move_alias_if_missing(
        c2s,
        &mut filter,
        "begin_time",
        &["begin_time", "begin", "start"],
    );
    move_alias_if_missing(c2s, &mut filter, "end_time", &["end_time", "end"]);
    move_alias_if_missing(c2s, &mut filter, "code_list", &["code_list", "codes"]);
    move_alias_if_missing(c2s, &mut filter, "id_list", &["id_list"]);
    move_alias_if_missing(c2s, &mut filter, "order_id_ex_list", &["order_id_ex_list"]);

    if !filter.contains_key("filter_market") {
        if let Some(value) = remove_first(c2s, &["filter_market", "order_market"]) {
            let filter_market = parse_rest_read_trd_market(&value)?;
            filter.insert(
                "filter_market".to_string(),
                Value::Number(filter_market.into()),
            );
        } else if let Some(market) = header_market {
            filter.insert("filter_market".to_string(), Value::Number(market.into()));
        }
    }

    if !filter.is_empty() {
        c2s.insert("filter_conditions".to_string(), Value::Object(filter));
    }
    Ok(())
}

fn move_alias_if_missing(
    from: &mut serde_json::Map<String, Value>,
    to: &mut serde_json::Map<String, Value>,
    canonical: &str,
    aliases: &[&str],
) {
    if to.contains_key(canonical) {
        for alias in aliases {
            if *alias != canonical {
                from.remove(*alias);
            }
        }
        return;
    }
    if let Some(value) = remove_first(from, aliases) {
        to.insert(canonical.to_string(), value);
    }
}

fn remove_first(map: &mut serde_json::Map<String, Value>, aliases: &[&str]) -> Option<Value> {
    for alias in aliases {
        if let Some(value) = map.remove(*alias) {
            return Some(value);
        }
    }
    None
}

fn normalize_cancel_order_id_aliases(
    c2s: &mut serde_json::Map<String, Value>,
) -> Result<(), String> {
    let Some(value) = c2s.get_mut("order_id") else {
        return Ok(());
    };
    let Some(raw) = value.as_str() else {
        return Ok(());
    };
    let raw = raw.trim();
    if raw.is_empty() {
        return Ok(());
    }
    let parsed = raw
        .parse::<u64>()
        .map_err(|_| "invalid order_id; expected numeric order_id or order_id_ex".to_string())?;
    *value = Value::Number(parsed.into());
    Ok(())
}

fn normalize_cancel_order_header_aliases(
    map: &mut serde_json::Map<String, Value>,
) -> Result<(), String> {
    if !map.contains_key("trd_market")
        && let Some(value) = map.remove("market")
    {
        let trd_market = parse_rest_write_trd_market(&value)?;
        map.insert("trd_market".to_string(), Value::Number(trd_market.into()));
    } else {
        map.remove("market");
    }
    Ok(())
}

fn normalize_cancel_order_op(c2s: &mut serde_json::Map<String, Value>) -> Result<(), String> {
    let canonical = c2s.remove("modify_order_op");
    let alias = c2s.remove("op");
    for value in canonical.iter().chain(alias.iter()) {
        let op = parse_rest_modify_order_op(value)?;
        if op != trade_parsing::MODIFY_ORDER_OP_CANCEL {
            return Err(format!(
                "/api/cancel-order only accepts cancel operation (2/CANCEL), got {op}"
            ));
        }
    }
    c2s.insert(
        "modify_order_op".to_string(),
        Value::Number(trade_parsing::MODIFY_ORDER_OP_CANCEL.into()),
    );
    Ok(())
}

fn parse_rest_trd_env(value: &Value) -> Result<i32, String> {
    if let Some(n) = value.as_i64() {
        return match n {
            0 | 1 => Ok(n as i32),
            _ => Err(format!(
                "invalid env {n}; expected real|simulate|sim or 1|0"
            )),
        };
    }
    let Some(raw) = value.as_str() else {
        return Err("invalid env; expected real|simulate|sim or 1|0".to_string());
    };
    if let Ok(n) = raw.trim().parse::<i64>() {
        return match n {
            0 | 1 => Ok(n as i32),
            _ => Err(format!(
                "invalid env {n}; expected real|simulate|sim or 1|0"
            )),
        };
    }
    trade_parsing::parse_trd_env_id(raw).ok_or_else(|| {
        format!(
            "invalid env {raw:?}; expected {}",
            trade_parsing::TRD_ENV_PARSE_CHOICES
        )
    })
}

fn parse_rest_write_trd_market(value: &Value) -> Result<i32, String> {
    if let Some(n) = value.as_i64() {
        let n = i32::try_from(n).map_err(|_| {
            format!(
                "invalid market {n}; expected {}",
                trade_market::TRD_MARKET_NON_FUND_PARSE_CHOICES
            )
        })?;
        return trade_market::is_trd_market_id(n)
            .then_some(n)
            .filter(|market| trade_market::canonical_fund_trd_market_label(*market).is_none())
            .ok_or_else(|| {
                format!(
                    "invalid market {n}; expected {}",
                    trade_market::TRD_MARKET_NON_FUND_PARSE_CHOICES
                )
            });
    }
    let Some(raw) = value.as_str() else {
        return Err(format!(
            "invalid market; expected {}",
            trade_market::TRD_MARKET_NON_FUND_PARSE_CHOICES
        ));
    };
    trade_market::parse_non_fund_trd_market_id(raw).ok_or_else(|| {
        format!(
            "invalid market {raw:?}; expected {}",
            trade_market::TRD_MARKET_NON_FUND_PARSE_CHOICES
        )
    })
}

fn parse_rest_read_trd_market(value: &Value) -> Result<i32, String> {
    if let Some(n) = value.as_i64() {
        let n = i32::try_from(n).map_err(|_| {
            format!(
                "invalid market {n}; expected {}",
                trade_market::TRD_MARKET_PARSE_CHOICES
            )
        })?;
        return trade_market::is_trd_market_id(n)
            .then_some(n)
            .ok_or_else(|| {
                format!(
                    "invalid market {n}; expected {}",
                    trade_market::TRD_MARKET_PARSE_CHOICES
                )
            });
    }
    let Some(raw) = value.as_str() else {
        return Err(format!(
            "invalid market; expected {}",
            trade_market::TRD_MARKET_PARSE_CHOICES
        ));
    };
    trade_market::parse_trd_market_id(raw).ok_or_else(|| {
        format!(
            "invalid market {raw:?}; expected {}",
            trade_market::TRD_MARKET_PARSE_CHOICES
        )
    })
}

fn parse_rest_modify_order_op(value: &Value) -> Result<i32, String> {
    if let Some(n) = value.as_i64() {
        return i32::try_from(n).map_err(|_| {
            format!(
                "invalid op {n}; expected {}",
                trade_parsing::MODIFY_OP_PARSE_CHOICES
            )
        });
    }
    let Some(raw) = value.as_str() else {
        return Err(format!(
            "invalid op; expected {}",
            trade_parsing::MODIFY_OP_PARSE_CHOICES
        ));
    };
    if let Ok(n) = raw.trim().parse::<i32>() {
        return Ok(n);
    }
    trade_parsing::parse_modify_op_id(raw).ok_or_else(|| {
        format!(
            "invalid op {raw:?}; expected {}",
            trade_parsing::MODIFY_OP_PARSE_CHOICES
        )
    })
}

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
    )
}

fn supports_max_ack_kl_num_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_REQUEST_HISTORY_EVENT_CONTRACT_KL
    )
}

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