futu_mcp/handlers/

analysis.rs

//! 行情分析 / 关联参考域 handler。
//!
//! v1.4.25 3 个简单实用的：capital_flow / capital_distribution / market_state
//! v1.4.26 补 4 个核心参考类：history_kline / owner_plate / reference / option_chain
//! 后续参考域工具已拆到 `handlers/reference/*` 与对应 `tools/reference*`
//! 模块；本文件保留早期 capital / kline / owner-plate / option-chain 等入口。
//!
//! 命名映射到 Futu 官方 Python SDK（py-futu-api）：
//! - `get_capital_flow` → `OpenQuoteContext.get_capital_flow`
//! - `get_capital_distribution` → `OpenQuoteContext.get_capital_distribution`
//! - `get_market_state` → `OpenQuoteContext.get_market_state`
//! - `get_history_kline` → `OpenQuoteContext.request_history_kline`
//! - `get_owner_plate` → `OpenQuoteContext.get_owner_plate`
//! - `get_reference` → `OpenQuoteContext.get_referencestock_list`
//! - `get_option_chain` → `OpenQuoteContext.get_option_chain`

use std::sync::Arc;

use anyhow::{Result, anyhow, bail};
use futu_core::qot_subscription;
use futu_net::client::FutuClient;
use futu_qot::types::{KLType, RehabType};
use futu_surface_spec::input::{parse_rehab_type_id, validate_history_session_id};
use prost::Message;
use serde::Serialize;

use crate::qot_sdk_adapter;
use crate::state::parse_symbol;

fn market_prefix(m: i32) -> &'static str {
    futu_core::market::qot_market_display_prefix(futu_core::market::QotMarketId::new(m))
        .unwrap_or("UNK")
}

#[cfg(test)]
mod tests;

// ============================================================
// get_capital_flow / `Qot_GetCapitalFlow` (CMD 3211)
// ============================================================

pub async fn get_capital_flow(
    client: &Arc<FutuClient>,
    symbol: &str,
    period_type: Option<i32>,
    begin_time: Option<String>,
    end_time: Option<String>,
) -> Result<String> {
    let sec = parse_symbol(symbol)?;
    let req = futu_proto::qot_get_capital_flow::Request {
        c2s: futu_proto::qot_get_capital_flow::C2s {
            security: futu_proto::qot_common::Security {
                market: sec.market as i32,
                code: sec.code,
            },
            period_type,
            begin_time,
            end_time,
            header: None, // v1.4.110 codex Slice 1 schema 占位
        },
    };
    let body = req.encode_to_vec();
    let frame = client
        .request(futu_core::proto_id::QOT_GET_CAPITAL_FLOW, body)
        .await?;
    let resp = futu_proto::qot_get_capital_flow::Response::decode(frame.body.as_ref())
        .map_err(|e| anyhow!("decode capital_flow: {e}"))?;
    if resp.ret_type != 0 {
        bail!(
            "capital_flow ret_type={} msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    let s2c = resp.s2c.ok_or_else(|| anyhow!("missing s2c"))?;
    // v1.4.98 T1-7: expose CapitalFlowItem 全 9 字段 (之前只读 in_flow +
    // timestamp, 漏 main / super / big / mid / sml in_flow + time string).
    // 主力 / 特大 / 大 / 中 / 小单细分 = LLM agent smart-money 信号常用.
    // 来源: proto/Qot_GetCapitalFlow.proto:17-26 已 generated, 仅 expose 层加.
    let raw_json = serde_json::to_string_pretty(&serde_json::json!({
        "flow_item_list": s2c.flow_item_list.iter().map(|f| {
            serde_json::json!({
                "in_flow": f.in_flow,
                "time": f.time,
                "timestamp": f.timestamp,
                "main_in_flow": f.main_in_flow,
                "super_in_flow": f.super_in_flow,
                "big_in_flow": f.big_in_flow,
                "mid_in_flow": f.mid_in_flow,
                "sml_in_flow": f.sml_in_flow,
            })
        }).collect::<Vec<_>>(),
        "last_valid_time": s2c.last_valid_time,
        "last_valid_timestamp": s2c.last_valid_timestamp,
        "symbol": symbol,
    }))?;
    Ok(raw_json)
}

// ============================================================
// get_capital_distribution / `Qot_GetCapitalDistribution` (CMD 3212)
// ============================================================

#[derive(Serialize)]
struct CapitalDistributionOut {
    capital_in_super: f64,
    capital_in_big: f64,
    capital_in_mid: f64,
    capital_in_small: f64,
    capital_out_super: f64,
    capital_out_big: f64,
    capital_out_mid: f64,
    capital_out_small: f64,
    update_time: String,
}

pub async fn get_capital_distribution(client: &Arc<FutuClient>, symbol: &str) -> Result<String> {
    let sec = parse_symbol(symbol)?;
    let req = futu_proto::qot_get_capital_distribution::Request {
        c2s: futu_proto::qot_get_capital_distribution::C2s {
            security: futu_proto::qot_common::Security {
                market: sec.market as i32,
                code: sec.code,
            },
            header: None, // v1.4.110 codex Slice 1 schema 占位
        },
    };
    let body = req.encode_to_vec();
    let frame = client
        .request(futu_core::proto_id::QOT_GET_CAPITAL_DISTRIBUTION, body)
        .await?;
    let resp = futu_proto::qot_get_capital_distribution::Response::decode(frame.body.as_ref())
        .map_err(|e| anyhow!("decode capital_distribution: {e}"))?;
    if resp.ret_type != 0 {
        bail!(
            "capital_distribution ret_type={} msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    let s = resp.s2c.ok_or_else(|| anyhow!("missing s2c"))?;
    let out = CapitalDistributionOut {
        capital_in_super: s.capital_in_super.unwrap_or(0.0),
        capital_in_big: s.capital_in_big,
        capital_in_mid: s.capital_in_mid,
        capital_in_small: s.capital_in_small,
        capital_out_super: s.capital_out_super.unwrap_or(0.0),
        capital_out_big: s.capital_out_big,
        capital_out_mid: s.capital_out_mid,
        capital_out_small: s.capital_out_small,
        update_time: s.update_time.unwrap_or_default(),
    };
    Ok(serde_json::to_string_pretty(&out)?)
}

// ============================================================
// get_market_state / `Qot_GetMarketState` (CMD 3223)
// ============================================================

#[derive(Serialize)]
struct MarketStateOut {
    code: String,
    name: String,
    market_state: i32,
}

pub async fn get_market_state(client: &Arc<FutuClient>, symbols: &[String]) -> Result<String> {
    // v1.4.106 codex 0641 F1 (P2): 列表型 input 契约 — 空列表 / 任一非法
    // symbol → 整体 reject (default ON 严格语义), 不再 silent drop 无效项
    // 用显式 for-loop + map_err 保留非法项的 index/symbol, 让调用方看到准确原因.
    //
    // 之前行为: ["HK.00700", "GARBAGE", "US.AAPL"] → silent drop "GARBAGE"
    //   → backend 收到 2 项, 用户看 3 项响应 (但其实 1 项 silent miss).
    // 现在行为: 同样输入 → 整体 reject + 明确指出 "GARBAGE" 解析失败.
    if symbols.is_empty() {
        bail!("market_state: symbols empty (必须至少传入 1 个 MARKET.CODE)");
    }
    let mut sec_list: Vec<futu_proto::qot_common::Security> = Vec::with_capacity(symbols.len());
    for (i, s) in symbols.iter().enumerate() {
        let sec = parse_symbol(s).map_err(|e| {
            anyhow!(
                "market_state: symbols[{i}] invalid ({s:?}): {e} — 整体 reject, 不 partial-success"
            )
        })?;
        sec_list.push(futu_proto::qot_common::Security {
            market: sec.market as i32,
            code: sec.code,
        });
    }
    // 经 futu_qot::symbol_list helper 二次校验 (market != 0, code != "")
    // — parse_symbol 已挡 bad case, 此 call 等价 invariant assert.
    let _parsed = futu_qot::symbol_list::parse_required_symbol_list(&sec_list)
        .map_err(|e| anyhow!("market_state: {e}"))?;
    let req = futu_proto::qot_get_market_state::Request {
        c2s: futu_proto::qot_get_market_state::C2s {
            security_list: sec_list,
            header: None,
        },
    };
    let body = req.encode_to_vec();
    let frame = client
        .request(futu_core::proto_id::QOT_GET_MARKET_STATE, body)
        .await?;
    let resp = futu_proto::qot_get_market_state::Response::decode(frame.body.as_ref())
        .map_err(|e| anyhow!("decode market_state: {e}"))?;
    if resp.ret_type != 0 {
        bail!(
            "market_state ret_type={} msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    let s = resp.s2c.ok_or_else(|| anyhow!("missing s2c"))?;
    let out: Vec<MarketStateOut> = s
        .market_info_list
        .iter()
        .map(|m| MarketStateOut {
            code: format!("{}.{}", market_prefix(m.security.market), m.security.code),
            name: m.name.clone(),
            market_state: m.market_state,
        })
        .collect();
    Ok(serde_json::to_string_pretty(&out)?)
}

// ============================================================
// v1.4.26 新增：history_kline / owner_plate / reference / option_chain
// ============================================================

// ===== get_history_kline / `Qot_RequestHistoryKL` (CMD 3103) =====

fn parse_kl_type_local(s: &str) -> Result<KLType> {
    let Some(t) = qot_subscription::qot_kl_type_from_str_alias(s)
        .and_then(qot_sdk_adapter::kl_type_from_public_id)
    else {
        let other = s.trim().to_ascii_lowercase();
        bail!(
            "unknown kl_type {other:?} \
             (day|week|month|quarter|year|1min|3min|5min|10min|15min|30min|60min|120min|180min|240min)"
        );
    };
    Ok(t)
}

fn parse_rehab_type(s: &str) -> Result<RehabType> {
    let rehab_type = parse_rehab_type_id(s)
        .map_err(|error| anyhow!("unknown rehab_type {:?}: {error}", error.raw()))?;
    qot_sdk_adapter::rehab_type_from_id(rehab_type)
        .ok_or_else(|| anyhow!("unsupported shared rehab_type id {rehab_type}"))
}

#[derive(Serialize)]
struct HistoryKLineOut {
    time: String,
    timestamp: f64,
    open: f64,
    high: f64,
    low: f64,
    close: f64,
    volume: i64,
    turnover: f64,
    pe: f64,
    change_rate: f64,
    turnover_rate: f64,
}

/// 历史 K 线（对齐 py-futu-api `OpenQuoteContext.request_history_kline`）。
///
/// 和 `futu_get_kline`（`handlers::market::get_kline`）的区别：
/// - 支持显式 `rehab_type`（前复权/后复权/不复权），`get_kline` 默认 None
/// - `max_count` 可设大数值拉 1000+ 条（`get_kline` 有 lookback 估算限制）
pub async fn get_history_kline(
    client: &Arc<FutuClient>,
    symbol: &str,
    kl_type_str: &str,
    rehab_type_str: &str,
    begin: &str,
    end: &str,
    max_count: Option<i32>,
    need_kl_fields_flag: Option<i64>,
    extended_time: Option<bool>,
    session: Option<i32>,
    next_req_key: Option<&[u8]>,
) -> Result<String> {
    let sec = parse_symbol(symbol)?;
    let kl_type = parse_kl_type_local(kl_type_str)?;
    let rehab_type = parse_rehab_type(rehab_type_str)?;
    let session = validate_history_session_id(session)
        .map_err(|error| anyhow!("invalid history_kline session: {error}"))?;
    let result = futu_qot::history_kl::request_history_kl(
        client,
        &futu_qot::history_kl::RequestHistoryKLParams {
            security: &sec,
            rehab_type,
            kl_type,
            begin_time: begin,
            end_time: end,
            max_num: max_count,
            need_kl_fields_flag,
            next_req_key,
            extended_time,
            session,
        },
    )
    .await?;
    let out: Vec<HistoryKLineOut> = result
        .kl_list
        .iter()
        .map(|k| HistoryKLineOut {
            time: k.time.clone(),
            timestamp: k.timestamp,
            open: k.open_price,
            high: k.high_price,
            low: k.low_price,
            close: k.close_price,
            volume: k.volume,
            turnover: k.turnover,
            pe: k.pe,
            change_rate: k.change_rate,
            turnover_rate: k.turnover_rate,
        })
        .collect();
    let next_req_key = result.next_req_key.as_ref().map(|key| {
        use base64::Engine as _;
        base64::engine::general_purpose::STANDARD.encode(key)
    });
    Ok(serde_json::to_string_pretty(&serde_json::json!({
        "symbol": symbol,
        "kl_type": kl_type_str,
        "rehab_type": rehab_type_str,
        "extended_time": extended_time,
        "session": session,
        "need_kl_fields_flag": need_kl_fields_flag,
        "next_req_key": next_req_key,
        "kl_list": out,
    }))?)
}

// ===== get_owner_plate / `Qot_GetOwnerPlate` (CMD 3207) =====

#[derive(Serialize)]
struct OwnerPlateOut {
    symbol: String,
    plates: Vec<PlateInfo>,
}

#[derive(Serialize)]
struct PlateInfo {
    code: String,
    name: String,
    plate_type: i32,
}

/// 股票所属板块（一只票可能属于多个板块，如行业/概念/地域）。
pub async fn get_owner_plate(client: &Arc<FutuClient>, symbols: &[String]) -> Result<String> {
    if symbols.is_empty() {
        bail!("empty symbols");
    }
    let sec_list: Vec<_> = symbols
        .iter()
        .map(|s| parse_symbol(s))
        .collect::<Result<Vec<_>>>()?;
    let s2c = futu_qot::market_misc::get_owner_plate(client, &sec_list).await?;
    let out: Vec<OwnerPlateOut> = s2c
        .owner_plate_list
        .iter()
        .map(|entry| {
            let sym = format!("{:?}.{}", entry.security.market, entry.security.code);
            OwnerPlateOut {
                symbol: sym,
                plates: entry
                    .plate_info_list
                    .iter()
                    .map(|p| PlateInfo {
                        code: p.plate.code.clone(),
                        name: p.name.clone(),
                        plate_type: p.plate_type.unwrap_or(0),
                    })
                    .collect(),
            }
        })
        .collect();
    Ok(serde_json::to_string_pretty(&out)?)
}

// ===== get_reference / `Qot_GetReference` (CMD 3206) =====

fn parse_reference_type(s: &str) -> Result<i32> {
    // 对齐 Qot_Common.ReferenceType enum
    // 1=Warrant 涡轮，2=Future 期货，3=Option 期权
    match s.trim().to_ascii_lowercase().as_str() {
        "warrant" => Ok(1),
        "future" | "futures" => Ok(2),
        "option" => Ok(3),
        other => bail!("unknown reference_type {other:?} (warrant|future|option)"),
    }
}

#[derive(Serialize)]
struct ReferenceOut {
    code: String,
    name: String,
    lot_size: i32,
    sec_type: i32,
}

/// 获取关联证券（正股↔涡轮/期货/期权）。
///
/// 例：`get_reference("HK.00700", "warrant")` 返回腾讯所有涡轮。
pub async fn get_reference(
    client: &Arc<FutuClient>,
    symbol: &str,
    reference_type_str: &str,
) -> Result<String> {
    let sec = parse_symbol(symbol)?;
    let ref_type = parse_reference_type(reference_type_str)?;
    let list = futu_qot::market_misc::get_reference(client, &sec, ref_type).await?;
    let out: Vec<ReferenceOut> = list
        .iter()
        .map(|s| ReferenceOut {
            code: s.security.code.clone(),
            name: s.name.clone(),
            lot_size: s.lot_size,
            sec_type: s.sec_type,
        })
        .collect();
    Ok(serde_json::to_string_pretty(&out)?)
}

// ===== get_option_chain / `Qot_GetOptionChain` (CMD 3209) =====

/// v1.4.98 T1-3 (mobile-source-audit): 单条期权 (call+put 配对, 同 strike).
/// 之前 OptionChainEntry 只返 strike_time + Vec<String> symbol 字符串 →
/// 期权 trader 必须额外调 N 次 get_snapshot 拿 strike_price / IV / Greeks.
/// 现透传 OptionStaticExData (proto/Qot_Common.proto:711-723) 全 6 静态字段
/// (strike_price 是 trader 第一关心), 让单次 chain query 拿全静态数据.
///
/// **Note**: Greeks (delta/gamma/theta/vega/rho/IV) 是 live-data 在 snapshot
/// (proto OptionSnapshotExData v1.4.94 M3 已 expose), chain 只含 static.
/// 完整 Greek 仍需 batch get_snapshot (1 次 N symbols).
#[derive(Serialize)]
struct OptionRow {
    /// 行权价 (期权 trader 第一关心字段)
    strike_price: f64,
    /// 看涨合约 symbol (None = 此 strike 无 call)
    call_symbol: Option<String>,
    /// 看跌合约 symbol (None = 此 strike 无 put)
    put_symbol: Option<String>,
    /// 是否停牌 (call 优先, fallback put)
    suspend: Option<bool>,
    /// 发行市场名 (e.g. "HKEX" / "OPRA")
    market: Option<String>,
    /// 指数期权类型 (仅指数期权有, IndexOptionType enum)
    index_option_type: Option<i32>,
    /// 交割周期 (ExpirationCycle: Weekly/Monthly/Quarterly)
    expiration_cycle: Option<i32>,
    /// 标准期权 (OptionStandardType enum)
    option_standard_type: Option<i32>,
    /// 结算方式 (OptionSettlementMode enum)
    option_settlement_mode: Option<i32>,
}

#[derive(Serialize)]
struct OptionChainEntry {
    strike_time: String,
    /// v1.4.98 T1-3: 升级为 Vec<OptionRow> 每条含 strike_price + 静态字段.
    /// 旧 call_symbols / put_symbols 字段保留 for 向后兼容 (重复信息).
    options: Vec<OptionRow>,
    /// **deprecated** (v1.4.98 T1-3): 用 `options[].call_symbol` 代替.
    /// 保留只为向后兼容, 下版可删.
    call_symbols: Vec<String>,
    /// **deprecated** (v1.4.98 T1-3): 用 `options[].put_symbol` 代替.
    put_symbols: Vec<String>,
}

/// 期权链（看涨/看跌合约列表）。
///
/// - `owner_symbol`: 正股（如 `HK.00700` / `US.AAPL`）
/// - `begin_time` / `end_time`: 到期日范围，格式 `YYYY-MM-DD`
/// - `option_type_str`: "all" / "call" / "put"
/// - `data_filter`: v1.4.38 Phase 3 新增，Greek server-side filter；`None` → v1.4.37 行为
pub struct OptionChainInput<'a> {
    pub owner_symbol: &'a str,
    pub begin_time: &'a str,
    pub end_time: &'a str,
    pub option_type_str: Option<&'a str>,
    pub data_filter: Option<futu_proto::qot_get_option_chain::DataFilter>,
}

pub async fn get_option_chain(
    client: &Arc<FutuClient>,
    input: OptionChainInput<'_>,
) -> Result<String> {
    let owner = parse_symbol(input.owner_symbol)?;
    let option_type = match input.option_type_str.map(str::trim) {
        Some("all") | None => Some(0), // OptionType_ALL
        Some("call") => Some(1),
        Some("put") => Some(2),
        Some(other) => bail!("unknown option_type {other:?} (all|call|put)"),
    };
    let s2c = futu_qot::market_misc::get_option_chain(
        client,
        &owner,
        input.begin_time,
        input.end_time,
        option_type,
        None,
        input.data_filter,
    )
    .await?;
    // OptionItem 的 `call` / `put` 都是 Option<SecurityStaticInfo>，单条 item
    // 表示一对同行权价的看涨+看跌合约；我们按到期日（strike_time）聚合
    let out: Vec<OptionChainEntry> = s2c
        .option_chain
        .iter()
        .map(|entry| {
            let mut calls = Vec::new();
            let mut puts = Vec::new();
            // v1.4.98 T1-3: per-row OptionRow 含 strike_price + 6 static fields.
            // OptionStaticExData 在 SecurityStaticInfo.option_ex_data 上;
            // call/put 同 strike, 优先取 call 的 ex_data, fallback put.
            let mut option_rows: Vec<OptionRow> = Vec::new();
            for item in &entry.option {
                if let Some(c) = &item.call {
                    calls.push(c.basic.security.code.clone());
                }
                if let Some(p) = &item.put {
                    puts.push(p.basic.security.code.clone());
                }
                let ex = item
                    .call
                    .as_ref()
                    .and_then(|c| c.option_ex_data.as_ref())
                    .or_else(|| item.put.as_ref().and_then(|p| p.option_ex_data.as_ref()));
                if let Some(ex) = ex {
                    option_rows.push(OptionRow {
                        strike_price: ex.strike_price,
                        call_symbol: item.call.as_ref().map(|c| c.basic.security.code.clone()),
                        put_symbol: item.put.as_ref().map(|p| p.basic.security.code.clone()),
                        suspend: Some(ex.suspend),
                        market: Some(ex.market.clone()),
                        index_option_type: ex.index_option_type,
                        expiration_cycle: ex.expiration_cycle,
                        option_standard_type: ex.option_standard_type,
                        option_settlement_mode: ex.option_settlement_mode,
                    });
                }
            }
            OptionChainEntry {
                strike_time: entry.strike_time.clone(),
                options: option_rows,
                call_symbols: calls,
                put_symbols: puts,
            }
        })
        .collect();
    Ok(serde_json::to_string_pretty(&out)?)
}