futu_mcp/handlers/trade/

cash_log.rs

use std::sync::Arc;

use anyhow::{Result, bail};
use futu_backend::proto_internal::realtime_asset_log;
use futu_net::client::FutuClient;
use prost::Message as _;
use serde::Serialize;

use super::parse_trd_env;

// ============================================================================
// v1.4.95 U1 (Tier M MCP tools): cash log mobile-driven extension
//
// 来源: v1.4.94 M1 ship 了 REST + gRPC FTAPI endpoints (cmd 3000/3001/3002),
// 但 MCP wrapper 推迟到 v1.4.95. 现在补齐 3 个 MCP tools.
//
// 架构:
//   client → MCP `futu_get_cash_log` → handler → FutuClient FTAPI proto_id
//   22701 (TRD_GET_CASH_LOG) → daemon CashLogHandler → backend cmd 3000
//
// 与 REST `/api/cash-log` 平行: 两条路径走同 daemon handler (CashLogHandler),
// 同 backend cmd 3000.
// ============================================================================

#[derive(Serialize)]
struct CashLogLabelOut {
    label: String,
    label_desc: String,
}

#[derive(Serialize)]
struct CashLogEntryOut {
    log_id: String,
    title: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    label: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    label_desc: Option<String>,
    created_time: String,
    created_timestamp: u32,
    cash_change: String,
    balance: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    stock_name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    icon_url: Option<String>,
    symbol_code: String,
    symbol_name: String,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    label_list: Vec<CashLogLabelOut>,
    #[serde(skip_serializing_if = "Option::is_none")]
    stock_id: Option<u64>,
    #[serde(skip_serializing_if = "Vec::is_empty")]
    stock_name_label_list: Vec<CashLogLabelOut>,
    biz_type_id: u32,
    #[serde(skip_serializing_if = "Option::is_none")]
    contract_direction: Option<i32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    contract_direction_label: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    contract_symbol_name: Option<String>,
    #[serde(skip_serializing_if = "Option::is_none")]
    currency: Option<String>,
}

fn cash_log_label_out_from_proto(label: realtime_asset_log::Label) -> CashLogLabelOut {
    CashLogLabelOut {
        label: label.label.unwrap_or_default(),
        label_desc: label.label_desc.unwrap_or_default(),
    }
}

fn cash_log_entry_out_from_proto(c: realtime_asset_log::CashLog) -> CashLogEntryOut {
    CashLogEntryOut {
        log_id: c.log_id.unwrap_or_default(),
        title: c.title.unwrap_or_default(),
        label: c.label,
        label_desc: c.label_desc,
        created_time: c.created_time.unwrap_or_default(),
        created_timestamp: c.created_timestamp.unwrap_or(0),
        cash_change: c.cash_change.unwrap_or_default(),
        balance: c.balance.unwrap_or_default(),
        stock_name: c.stock_name,
        icon_url: c.icon_url,
        symbol_code: c.symbol_code.unwrap_or_default(),
        symbol_name: c.symbol_name.unwrap_or_default(),
        label_list: c
            .label_list
            .into_iter()
            .map(cash_log_label_out_from_proto)
            .collect(),
        stock_id: c.stock_id,
        stock_name_label_list: c
            .stock_name_label_list
            .into_iter()
            .map(cash_log_label_out_from_proto)
            .collect(),
        biz_type_id: c.biz_type_id.unwrap_or(0),
        contract_direction: c.contract_direction,
        contract_direction_label: c.contract_direction_label,
        contract_symbol_name: c.contract_symbol_name,
        currency: c.currency,
    }
}

#[derive(Serialize)]
struct CashLogMonthlyOut {
    period_desc: String,
    in_value: String,
    out_value: String,
    entries: Vec<CashLogEntryOut>,
}

#[derive(Serialize)]
struct CashLogOut {
    monthly_logs: Vec<CashLogMonthlyOut>,
    has_more: bool,
    next_log_id: String,
}

/// v1.4.95 U1: MCP tool `futu_get_cash_log` — 资金明细 (mobile-driven).
///
/// 比 `futu_get_acc_cash_flow` 字段更全 (10+ vs 3): 时间范围 / 业务分组 /
/// 货币 / 关键词 / 股票 / 方向 多维过滤 + cursor 分页.
///
/// 与 REST `/api/cash-log` 共用 daemon handler，gateway 层统一派生 native
/// account/market 并补齐移动端默认分页字段。
pub struct CashLogInput<'a> {
    pub env: &'a str,
    pub acc_id: u64,
    pub begin_time: Option<u64>,
    pub end_time: Option<u64>,
    pub biz_group_id: Option<u32>,
    pub biz_sub_group_id: Option<u32>,
    pub in_out: Option<u32>,
    pub keyword: Option<String>,
    pub symbol: Option<String>,
    pub stock_id: Option<u64>,
    pub log_id: Option<String>,
    pub max_cnt: Option<u32>,
    pub currency: Option<String>,
}

pub async fn get_cash_log(client: &Arc<FutuClient>, input: CashLogInput<'_>) -> Result<String> {
    let trd_env = parse_trd_env(input.env)?;
    if input.acc_id == 0 {
        bail!("acc_id 必填 (call futu_list_accounts to discover)");
    }

    // v1.4.102 codex 38 F1 (P1): 不预填 inner.market / inner.account_id —
    // 让 daemon derive_cash_log_market(acc_id, cache) 走 verified translation
    // (HKFUND=113 → HK=1; USFUND=123 → US=2 per real-machine). MCP 直传
    // header.trd_market 为 113/123 时旧 wrapper 写 raw 113 进 inner.market →
    // 绕过 daemon 翻译 → backend 看 fund market enum 返空. 现在 None 让
    // daemon 用 cache.trd_market + acc_id high bits 走中央 helper.
    let inner = realtime_asset_log::GetCashLogReq {
        market: None,     // codex 38 F1: daemon 派生
        account_id: None, // codex 38 F1: daemon 派生 (低 32 位 acc_id)
        biz_group_id: input.biz_group_id,
        in_out: input.in_out,
        begin_time: input.begin_time,
        end_time: input.end_time,
        need_stock_name: Some(true),
        log_id: input.log_id,
        max_cnt: input.max_cnt,
        keyword: input.keyword,
        biz_sub_group_id: input.biz_sub_group_id,
        currency: input.currency,
        symbol: input.symbol,
        stock_id: input.stock_id,
    };

    // Wrap in daemon FTAPI envelope
    let req = realtime_asset_log::DaemonGetCashLogReq {
        c2s: realtime_asset_log::daemon_get_cash_log_req::C2s {
            header: realtime_asset_log::DaemonGetCashLogHeader {
                acc_id: input.acc_id,
                trd_env: Some(trd_env as i32),
            },
            inner: Some(inner),
        },
    };

    let body = req.encode_to_vec();
    let frame = client
        .request(futu_core::proto_id::TRD_GET_CASH_LOG, body)
        .await?;
    let resp =
        <realtime_asset_log::DaemonGetCashLogRsp as prost::Message>::decode(frame.body.as_ref())
            .map_err(|e| anyhow::anyhow!("decode DaemonGetCashLogRsp: {e}"))?;
    if resp.ret_type != 0 {
        bail!(
            "GetCashLog ret_type={} msg={:?} (fallback: try futu_get_acc_cash_flow)",
            resp.ret_type,
            resp.ret_msg
        );
    }

    let inner_rsp = resp
        .s2c
        .and_then(|s| s.inner)
        .ok_or_else(|| anyhow::anyhow!("empty s2c.inner in GetCashLogRsp"))?;

    let monthly_logs: Vec<CashLogMonthlyOut> = inner_rsp
        .monthly_log_list
        .into_iter()
        .map(|m| CashLogMonthlyOut {
            period_desc: m
                .monthly_info
                .as_ref()
                .map(|mi| mi.period_desc.clone().unwrap_or_default())
                .unwrap_or_default(),
            in_value: m
                .monthly_info
                .as_ref()
                .map(|mi| mi.in_value.clone().unwrap_or_default())
                .unwrap_or_default(),
            out_value: m
                .monthly_info
                .as_ref()
                .map(|mi| mi.out_value.clone().unwrap_or_default())
                .unwrap_or_default(),
            entries: m
                .cash_log_list
                .into_iter()
                .map(cash_log_entry_out_from_proto)
                .collect(),
        })
        .collect();

    let out = CashLogOut {
        monthly_logs,
        has_more: inner_rsp.has_more.unwrap_or(false),
        next_log_id: inner_rsp.next_log_id.unwrap_or_default(),
    };
    Ok(serde_json::to_string_pretty(&out)?)
}

#[derive(Serialize)]
struct CashDetailOut {
    title: String,
    sub_title: String,
    #[serde(skip_serializing_if = "Option::is_none")]
    title_detail: Option<DetailItemOut>,
    #[serde(skip_serializing_if = "Option::is_none")]
    sub_title_detail: Option<DetailItemOut>,
    sections: Vec<Vec<DetailItemOut>>,
    external_links: Vec<DetailItemOut>,
}

#[derive(Clone, Debug, Serialize)]
struct DetailItemOut {
    title: String,
    value: String,
    url: String,
    old_value: String,
    icon_url_id: String,
    type_id: u32,
}

fn detail_item_out_from_proto(d: realtime_asset_log::Detail) -> Option<DetailItemOut> {
    let title = d.title.unwrap_or_default();
    if title.is_empty() {
        return None;
    }
    Some(DetailItemOut {
        title,
        value: d.value.unwrap_or_default(),
        url: d.url.unwrap_or_default(),
        old_value: d.old_value.unwrap_or_default(),
        icon_url_id: d.icon_url_id.unwrap_or_default(),
        type_id: d.type_id.unwrap_or_default(),
    })
}

fn cash_detail_out_from_inner_rsp(
    inner_rsp: realtime_asset_log::GetCashDetailRsp,
) -> CashDetailOut {
    let title_detail = inner_rsp.detail_title.and_then(detail_item_out_from_proto);
    let sub_title_detail = inner_rsp
        .sub_detail_title
        .and_then(detail_item_out_from_proto);

    let title_str = title_detail
        .as_ref()
        .map(|d| d.title.clone())
        .unwrap_or_default();
    let sub_title_str = sub_title_detail
        .as_ref()
        .map(|d| d.title.clone())
        .unwrap_or_default();

    let sections: Vec<Vec<DetailItemOut>> = inner_rsp
        .section_list
        .into_iter()
        .filter_map(|s| {
            let details: Vec<DetailItemOut> = s
                .detail_list
                .into_iter()
                .filter_map(detail_item_out_from_proto)
                .collect();
            if details.is_empty() {
                None
            } else {
                Some(details)
            }
        })
        .collect();

    let mut external_links: Vec<DetailItemOut> = inner_rsp
        .all_external_link
        .into_iter()
        .filter_map(detail_item_out_from_proto)
        .collect();
    if external_links.is_empty()
        && let Some(single) = inner_rsp.external_link.and_then(detail_item_out_from_proto)
    {
        external_links.push(single);
    }

    CashDetailOut {
        title: title_str,
        sub_title: sub_title_str,
        title_detail,
        sub_title_detail,
        sections,
        external_links,
    }
}

/// v1.4.95 U1: MCP tool `futu_get_cash_detail` — 单条资金流水详情.
pub async fn get_cash_detail(
    client: &Arc<FutuClient>,
    env: &str,
    acc_id: u64,
    log_id: String,
) -> Result<String> {
    if log_id.is_empty() {
        bail!("log_id 必填 (从 futu_get_cash_log 响应里取)");
    }
    let trd_env = parse_trd_env(env)?;
    if acc_id == 0 {
        bail!("acc_id 必填");
    }

    // v1.4.102 codex 38 F1 (P1): 不预填 inner.market / inner.account_id,
    // 让 daemon 走 verified translation.
    let inner = realtime_asset_log::GetCashDetailReq {
        market: None,
        account_id: None,
        log_id: Some(log_id),
    };
    let req = realtime_asset_log::DaemonGetCashDetailReq {
        c2s: realtime_asset_log::daemon_get_cash_detail_req::C2s {
            header: realtime_asset_log::DaemonGetCashLogHeader {
                acc_id,
                trd_env: Some(trd_env as i32),
            },
            inner: Some(inner),
        },
    };

    let body = req.encode_to_vec();
    let frame = client
        .request(futu_core::proto_id::TRD_GET_CASH_DETAIL, body)
        .await?;
    let resp =
        <realtime_asset_log::DaemonGetCashDetailRsp as prost::Message>::decode(frame.body.as_ref())
            .map_err(|e| anyhow::anyhow!("decode DaemonGetCashDetailRsp: {e}"))?;
    if resp.ret_type != 0 {
        bail!(
            "GetCashDetail ret_type={} msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }

    let inner_rsp = resp
        .s2c
        .and_then(|s| s.inner)
        .ok_or_else(|| anyhow::anyhow!("empty s2c.inner"))?;

    let out = cash_detail_out_from_inner_rsp(inner_rsp);
    Ok(serde_json::to_string_pretty(&out)?)
}

#[derive(Serialize)]
struct BizGroupItemOut {
    id: u32,
    name: String,
    sub_groups: Vec<BizSubGroupOut>,
}

#[derive(Serialize)]
struct BizSubGroupOut {
    id: u32,
    name: String,
}

#[derive(Serialize)]
struct CurrencyConfigOut {
    currency: String,
    name: String,
}

#[derive(Serialize)]
struct DirectionOut {
    side: u32,
    name: String,
}

#[derive(Serialize)]
struct BizGroupOut {
    biz_groups: Vec<BizGroupItemOut>,
    currencies: Vec<CurrencyConfigOut>,
    directions: Vec<DirectionOut>,
}

/// v1.4.95 U1: MCP tool `futu_get_biz_group` — 业务分类元数据.
///
/// 给 client 构造 cash log 过滤下拉菜单用 (业务分组 / 货币 / 方向).
pub async fn get_biz_group(client: &Arc<FutuClient>, env: &str, acc_id: u64) -> Result<String> {
    let trd_env = parse_trd_env(env)?;
    if acc_id == 0 {
        bail!("acc_id 必填");
    }

    // v1.4.102 codex 38 F1 (P1): 不预填 inner.market, 让 daemon 派生 verified.
    let inner = realtime_asset_log::GetBizGroupReq { market: None };
    let req = realtime_asset_log::DaemonGetBizGroupReq {
        c2s: realtime_asset_log::daemon_get_biz_group_req::C2s {
            header: realtime_asset_log::DaemonGetCashLogHeader {
                acc_id,
                trd_env: Some(trd_env as i32),
            },
            inner: Some(inner),
        },
    };

    let body = req.encode_to_vec();
    let frame = client
        .request(futu_core::proto_id::TRD_GET_BIZ_GROUP, body)
        .await?;
    let resp =
        <realtime_asset_log::DaemonGetBizGroupRsp as prost::Message>::decode(frame.body.as_ref())
            .map_err(|e| anyhow::anyhow!("decode DaemonGetBizGroupRsp: {e}"))?;
    if resp.ret_type != 0 {
        bail!(
            "GetBizGroup ret_type={} msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }

    let inner_rsp = resp
        .s2c
        .and_then(|s| s.inner)
        .ok_or_else(|| anyhow::anyhow!("empty s2c.inner"))?;

    let biz_groups: Vec<BizGroupItemOut> = inner_rsp
        .biz_group_list
        .into_iter()
        .map(|g| BizGroupItemOut {
            id: g.id.unwrap_or(0),
            name: g.name.unwrap_or_default(),
            sub_groups: g
                .biz_sub_group_list
                .into_iter()
                .map(|s| BizSubGroupOut {
                    id: s.id.unwrap_or(0),
                    name: s.name.unwrap_or_default(),
                })
                .collect(),
        })
        .collect();

    let currencies: Vec<CurrencyConfigOut> = inner_rsp
        .currency_config_list
        .into_iter()
        .map(|c| CurrencyConfigOut {
            currency: c.currency.unwrap_or_default(),
            name: c.name.unwrap_or_default(),
        })
        .collect();

    let directions: Vec<DirectionOut> = inner_rsp
        .direction_list
        .into_iter()
        .map(|d| DirectionOut {
            side: d.side.unwrap_or(0),
            name: d.name.unwrap_or_default(),
        })
        .collect();

    let out = BizGroupOut {
        biz_groups,
        currencies,
        directions,
    };
    Ok(serde_json::to_string_pretty(&out)?)
}

#[cfg(test)]
mod tests;