futu_mcp/tool_enums/

mod.rs

//! v1.4.84 §5 B2: 结构化 MCP tool enum 类型 + 泛型 int/string 双接 deserializer
//!
//! **背景**: v1.4.83 在 `tools.rs` 加了 `deser_int_or_order_type_str` 单一
//! deserializer，让 OrderType 字段接受 int OR string enum。本模块把该 pattern
//! **泛化**到多个 enum 类型：
//!
//! | Enum | proto | variants |
//! |---|---|---|
//! | [`MarketEnum`] | `Qot_Common.QotMarket` | 10 (legacy/test guard only) |
//! | [`SubTypeEnum`] | `Qot_Common.SubType` | 17 |
//! | [`OrderTypeEnum`] | `Trd_Common.OrderType` | 19 (含 v1.4.53 条件单) |
//! | [`PriceReminderOpEnum`] | `Qot_SetPriceReminder.SetPriceReminderOp` | 6 |
//!
//! **设计要点**:
//!
//! - 所有 enum impl [`ToolEnum`] trait，统一 `from_i32 / from_str / as_i32 /
//!   all_int_values / all_string_values` 接口
//! - [`deser_int_or_enum_str`] 泛型 deserializer：`T: ToolEnum`，接受 JSON
//!   integer OR string
//! - Serialize 为 i32（backward-compat，旧 int-based 客户端不破坏）
//! - String 名对齐 proto 枚举 suffix（`OrderBook` / `KL_Day` / `NORMAL` 等），
//!   方便 LLM agent 对照 proto docs；同时接受合理 alias
//!
//! **当前接入状态**:
//!
//! 现有 MCP tool arg structs 已在 `tool_args/` 下按需接入这些 wrapper：
//! `sub_type_list` / `trd_market` / `order_type` 等字段可接受 int 或 string。
//! QOT `market` 字段不再统一复用 [`MarketEnum`]，因为 C++ 对 IPO /
//! StockFilter / PriceReminder 等 endpoint 使用不同 market bucket；这类字段
//! 应在对应 request struct 附近使用 endpoint-local parser。
//!
//! # dead_code allow 原因
//!
//! 部分 wrapper 只被特定 feature/test matrix 间接触发；保留集中 enum module
//! 能让 schema/runtime drift guard 在一个位置覆盖所有 MCP enum parser。
//!
use serde::Deserialize;

// v1.4.93 C3 (Option D): runtime-delegate to prost-generated `from_str_name` so
// that canonical proto names (e.g. `"TrdMarket_HK"` / `"OrderType_Stop"`) are
// always accepted without re-listing them in hand-written `from_str` match arms.
// Hand-written arms still cover **short-name aliases** (`"HK"` / `"MIT"`) that
// LLM agents naturally produce. See pitfall #54 and the `option_d_*` tests.

// ========== ToolEnum trait ==========

/// v1.4.84 §5 B2: 统一 MCP tool enum 接口，让 [`deser_int_or_enum_str`] 可泛型化。
pub trait ToolEnum: Sized + Copy {
    /// 用于 error message 的人类可读类型名（如 `"market"` / `"order_type"`）
    fn type_name() -> &'static str;

    /// 按 proto int 值查 enum variant；未定义 → None
    fn from_i32(v: i32) -> Option<Self>;

    /// 按 string 名 / 别名查 enum variant；未定义 → None
    ///
    /// 实装应 trim + 大小写灵活匹配（canonical 名 + 常见 alias）
    fn from_str(s: &str) -> Option<Self>;

    /// 返 proto int 值（用于 serialize / handler 下游）
    fn as_i32(self) -> i32;

    /// 列举所有合法 int 值（用于 error message）
    fn all_int_values() -> Vec<i32>;

    /// 列举所有 canonical string 名（用于 error message / schema hints）
    fn all_string_values() -> Vec<&'static str>;
}

// ========== 泛型双接 deserializer ==========

/// v1.4.84 §5 B2: 泛型 int-or-string enum deserializer。
///
/// 对齐 v1.4.83 `tools.rs::deser_int_or_order_type_str` pattern，泛化到任意
/// 实装 [`ToolEnum`] 的类型。
///
/// # Examples
///
/// ```ignore
/// use crate::tool_enums::{MarketEnum, deser_int_or_enum_str};
///
/// #[derive(serde::Deserialize)]
/// struct MyReq {
///     #[serde(deserialize_with = "deser_int_or_enum_str::<MarketEnum>")]
///     pub market: MarketEnum,
/// }
/// ```
pub fn deser_int_or_enum_str<'de, D, E>(deserializer: D) -> Result<E, D::Error>
where
    D: serde::Deserializer<'de>,
    E: ToolEnum,
{
    #[derive(Deserialize)]
    #[serde(untagged)]
    enum IntOrStr {
        Int(i32),
        Str(String),
    }
    match IntOrStr::deserialize(deserializer)? {
        IntOrStr::Int(i) => E::from_i32(i).ok_or_else(|| {
            serde::de::Error::custom(format!(
                "unknown {} int value {i}: valid = {:?}",
                E::type_name(),
                E::all_int_values()
            ))
        }),
        IntOrStr::Str(s) => {
            // 先 trim，再 try enum lookup；失败 fallback 尝试 parse 成 int
            let trimmed = s.trim();
            if let Some(e) = E::from_str(trimmed) {
                return Ok(e);
            }
            // fallback: 用户传 "1" 字符串也能用（和 v1.4.83 老 pattern 对齐）
            if let Ok(i) = trimmed.parse::<i32>()
                && let Some(e) = E::from_i32(i)
            {
                return Ok(e);
            }
            Err(serde::de::Error::custom(format!(
                "unknown {} string {s:?}: valid = {:?} or integer {:?}",
                E::type_name(),
                E::all_string_values(),
                E::all_int_values()
            )))
        }
    }
}

// ========== MarketEnum (Qot_Common.QotMarket) ==========
//
// Legacy/test-only helper for broad `Qot_Common.QotMarket` parsing. Production
// request structs should prefer endpoint-local market parsers because C++
// accepts different market buckets per endpoint.
//
// 对齐 `Qot_Common.QotMarket` 的常用证券市场，10 variants（跳 Unknown=0 /
// 废弃 HK_Future=2 / crypto=91）.
//
// String → variant 映射（见 `from_str` impl）:
//   HK=1 / US=11 / SH=21 (aka "CN") / SZ=22 / SG=31 / JP=41 / AU=51 /
//   MY=61 / CA=71 / FX=81.
//
// **注**: "CN" 映射到 SH=21（沪股）是因为 proto 没有单一 CN 市场 id,
// SH 是第一个 CN variant. 用户需要 SZ 应显式传 "SZ".
//
// ----------------------------------------------------------------------------
// v1.4.84 §5 B2 field migration wrappers live below for endpoint families
// that still share a full enum surface. QOT market-like fields are endpoint
// scoped in C++ (for example IPO / StockFilter / PriceReminder accept different
// HK future ids), so they intentionally use local parsers near request structs.

/// v1.4.84 §5 B2: Vec<SubTypeEnum> 双接 (mixed int/string ok in same array)
/// → Vec<i32>.
pub fn deser_subtype_list_as_vec_i32<'de, D>(deserializer: D) -> Result<Vec<i32>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let raw: Vec<serde_json::Value> = Vec::deserialize(deserializer)?;
    raw.into_iter()
        .map(|v| {
            let e: SubTypeEnum = match v {
                serde_json::Value::Number(n) => {
                    let i = n.as_i64().ok_or_else(|| {
                        serde::de::Error::custom(format!("sub_type number invalid: {n}"))
                    })? as i32;
                    SubTypeEnum::from_i32(i).ok_or_else(|| {
                        serde::de::Error::custom(format!(
                            "unknown sub_type int {i}: valid = {:?}",
                            SubTypeEnum::all_int_values()
                        ))
                    })?
                }
                serde_json::Value::String(s) => {
                    let t = s.trim();
                    SubTypeEnum::from_str(t)
                        .or_else(|| t.parse::<i32>().ok().and_then(SubTypeEnum::from_i32))
                        .ok_or_else(|| {
                            serde::de::Error::custom(format!(
                                "unknown sub_type {s:?}: valid = {:?}",
                                SubTypeEnum::all_string_values()
                            ))
                        })?
                }
                _ => {
                    return Err(serde::de::Error::custom(format!(
                        "sub_type list element must be int or string, got: {v}"
                    )));
                }
            };
            Ok(e.as_i32())
        })
        .collect()
}

/// v1.4.84 §5 B2: PriceReminderOpEnum 双接 → i32.
pub fn deser_price_reminder_op_as_i32<'de, D>(deserializer: D) -> Result<i32, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let e: PriceReminderOpEnum = deser_int_or_enum_str(deserializer)?;
    Ok(e.as_i32())
}

// ========== v1.4.90 P0-E + P1-G: String-returning wrappers ==========
//
// **背景** (P0-E int-string drift): tools.rs 里 11 个 trd `market: String`
// 字段 + 1 个 PlaceOrderReq `order_type: String` 字段是 String 而非 i32 ——
// 这些字段当前**只接 String**，不接 int. 本节加 _as_string wrappers 让这些
// 已接入字段也能双接.
//
// **背景** (P1-G trd_market 缺 5 市场): v1.4.84 B2 没加 TrdMarketEnum (参与 B2
// 的 5 enum 是 QotMarket / SubType / OrderType / KlType / PriceReminderOp).
// 当时 TrdMarket 只列 HK/US/CN/HKCC; backend `Trd_Common.TrdMarket` proto 实际
// 还有 SG=6 / Crypto=7 / AU=8 / futures simulate 10..13 / JP=15 / MY=111 /
// CA=112 / fund 113/123/124/125/126. 本节暴露官方 proto 值；写路径在
// operation boundary 拒绝 view-only fund market.

/// v1.4.90 P0-E + P1-G: TrdMarketEnum 双接 (int OR string) → 标准大写 String.
///
/// 用于 tools.rs 里 `market: String` 字段 (TrdAccReq / PlaceOrderReq /
/// ModifyOrderReq / CancelOrderReq / MaxTrdQtysReq / OrderFeeReq /
/// MarginRatioReq / HistoryQueryReq / AccCashFlowReq / CancelAllOrderReq).
/// int 输入 → 转 canonical String; string 输入 → trim + uppercase + 通过
/// `TrdMarketEnum::from_str` 验证 → 返 canonical.
///
/// **runtime 对齐状态**: `handlers/trade.rs` 与 `handlers/trade_write.rs`
/// 已支持 HK/US/CN/HKCC/FUTURES/SG/CRYPTO/AU/JP/MY/CA 及 futures simulate 值。
/// Fund markets 仅 read/view-only endpoint 接受；trade-write handler 会 fail closed，
/// 避免 fund-market 写路径误路由。
pub fn deser_trd_market_as_string<'de, D>(deserializer: D) -> Result<String, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let e: TrdMarketEnum = deser_int_or_enum_str(deserializer)?;
    let i = e.as_i32();
    let names = TrdMarketEnum::all_string_values();
    let ints = TrdMarketEnum::all_int_values();
    let idx = ints.iter().position(|&v| v == i).ok_or_else(|| {
        serde::de::Error::custom(format!("trd_market i32 {i} has no canonical string"))
    })?;
    Ok(names[idx].to_string())
}

/// Optional TrdMarketEnum 双接 (int OR string) → Option<canonical String>.
///
/// 用于 legacy/compat 字段：调用 surface 仍可传旧 market 入参，但 runtime
/// 不再信任它做账户 market 派生。这里保持旧客户端的 int/string 兼容与输入校验；
/// 省略或 null 则返回 None。
pub fn deser_trd_market_as_option_string<'de, D>(
    deserializer: D,
) -> Result<Option<String>, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let opt: Option<serde_json::Value> = Option::deserialize(deserializer)?;
    let Some(v) = opt else {
        return Ok(None);
    };
    if v.is_null() {
        return Ok(None);
    }

    let e = match v {
        serde_json::Value::Number(n) => {
            let i = n.as_i64().ok_or_else(|| {
                serde::de::Error::custom(format!("trd_market number invalid: {n}"))
            })? as i32;
            TrdMarketEnum::from_i32(i).ok_or_else(|| {
                serde::de::Error::custom(format!(
                    "unknown trd_market int {i}: valid = {:?}",
                    TrdMarketEnum::all_int_values()
                ))
            })?
        }
        serde_json::Value::String(s) => {
            let trimmed = s.trim();
            TrdMarketEnum::from_str(trimmed)
                .or_else(|| {
                    trimmed
                        .parse::<i32>()
                        .ok()
                        .and_then(TrdMarketEnum::from_i32)
                })
                .ok_or_else(|| {
                    serde::de::Error::custom(format!(
                        "unknown trd_market string {s:?}: valid = {:?} or integer {:?}",
                        TrdMarketEnum::all_string_values(),
                        TrdMarketEnum::all_int_values()
                    ))
                })?
        }
        _ => {
            return Err(serde::de::Error::custom(format!(
                "trd_market must be int or string when present, got: {v}"
            )));
        }
    };

    let i = e.as_i32();
    let names = TrdMarketEnum::all_string_values();
    let ints = TrdMarketEnum::all_int_values();
    let idx = ints.iter().position(|&v| v == i).ok_or_else(|| {
        serde::de::Error::custom(format!("trd_market i32 {i} has no canonical string"))
    })?;
    Ok(Some(names[idx].to_string()))
}

/// v1.4.90 P0-E: OrderTypeEnum 双接 (int OR string) → 标准大写 String.
///
/// 用于 PlaceOrderReq.order_type: String. 让 LLM agent 传 STOP / STOP_LIMIT /
/// MIT / LIT / TRAILING_STOP 等 v1.4.53 条件单 String 也能在 MCP 层接到 +
/// 传 int (10/11/12/13/14/15/16/17/18/19) 也能解析.
///
/// **runtime 对齐状态**: `handlers/trade_write.rs::parse_order_type` 已支持
/// 17 个公开订单类型，包括 STOP / STOP_LIMIT / MIT / LIT / trailing stop
/// 以及 TWAP/VWAP。schema wrapper 与 runtime parser 不应再次分叉。
pub fn deser_order_type_as_string<'de, D>(deserializer: D) -> Result<String, D::Error>
where
    D: serde::Deserializer<'de>,
{
    let e: OrderTypeEnum = deser_int_or_enum_str(deserializer)?;
    let i = e.as_i32();
    let names = OrderTypeEnum::all_string_values();
    let ints = OrderTypeEnum::all_int_values();
    let idx = ints.iter().position(|&v| v == i).ok_or_else(|| {
        serde::de::Error::custom(format!("order_type i32 {i} has no canonical string"))
    })?;
    Ok(names[idx].to_string())
}

// Split: 1040 → 5 enum 子文件 + mod.rs head (ToolEnum trait + helpers)
mod market_enum;
mod order_type_enum;
mod price_reminder_op_enum;
mod subtype_enum;
mod trd_market_enum;

pub use order_type_enum::OrderTypeEnum;
pub use price_reminder_op_enum::PriceReminderOpEnum;
pub use subtype_enum::SubTypeEnum;
pub use trd_market_enum::TrdMarketEnum;

#[cfg(test)]
pub use market_enum::MarketEnum;

#[cfg(test)]
mod tests;