futucli/cmd/

tier_m.rs

//! `futucli` Tier M (mobile-driven extension) commands — v1.4.94 M1 + v1.4.95 U2-A/D/B
//!
//! 11 subcommand 镜像 REST + MCP:
//!
//! | subcommand              | proto_id | mobile cmd | 用途                       |
//! |-------------------------|----------|------------|----------------------------|
//! | `cash-log`              | 22701    | 3000       | 资金明细查询 (M1)          |
//! | `cash-detail`           | 22702    | 3001       | 单条资金详情 (M1)          |
//! | `biz-group`             | 22703    | 3002       | 业务分类元数据 (M1)        |
//! | `margin-info`           | 22704    | 3101/02/07 | per-account margin (U2-D)  |
//! | `account-flag`          | 22705    | 5281       | 账户合规标志 (U2-A)        |
//! | `bond-total-asset`      | 22706    | 9373       | 债券账户总持仓 (U2-B)      |
//! | `bond-single-asset`     | 22707    | 9374       | 单只债券持仓 (U2-B)        |
//! | `bond-position-list`    | 22708    | 9375       | 债券持仓列表 (U2-B)        |
//! | `bond-answer-state`     | 22709    | 10043      | 是否需答题 (U2-B)          |
//! | `bond-trade-reminder`   | 22710    | 10057      | 交易提醒 (U2-B)            |
//!
//! ## 架构
//!
//! 直接 `connect_gateway` + `client.request(proto_id, body)`, decode Daemon
//! FTAPI wrapper, JSON pretty print. 不走 futu-trd 高层 helper (Tier M
//! handler proto 在 futu-backend::proto_internal 直接定义, 没必要再 wrap 一层).
//!
//! ## 输出格式
//!
//! 默认 JSON pretty (`OutputFormat::Json` 或 `OutputFormat::Table`).
//! 11 endpoint 字段较多 + 嵌套结构 (notice_list / margin_info), table view
//! 不易表达, 统一用 JSON. Table format 也 fallback 到 JSON.

use anyhow::{Context, Result, bail};
use prost::Message;

use crate::common::connect_gateway;
use crate::output::OutputFormat;
use futu_backend::proto_internal::{
    account_flag, bond_client_view, realtime_asset_log, risk_user_account_info,
};
use futu_core::proto_id;

/// 共用 helper: env 字符串 → trd_env int (0=sim / 1=real).
///
/// v1.4.102 codex 42 F2 (P2): typo (e.g. "prod" / "reel") 现 reject —
/// 之前 "non-real => 0" silent 把 typo 当 sim, 违 BUG-005 精神.
/// 接受: "real" / "REAL" / "sim" / "simulate" / "SIM" / "" (空 → 默认 real).
fn parse_env_int(env: &str) -> Result<i32> {
    match env.trim().to_ascii_lowercase().as_str() {
        "real" => Ok(1),
        "sim" | "simulate" => Ok(0),
        // 空字符串 = clap default-not-given (cli `--env` 默认值);
        // 历史行为是 "默认 real". 保持兼容 (Tier M 多数 default 实盘).
        "" => Ok(1),
        other => Err(anyhow::anyhow!(
            "unknown env {other:?} (expected: real / sim / simulate). \
             v1.4.102 codex 42 F2 fix: typo 拒, 不 silent 当 sim"
        )),
    }
}

/// 共用 helper: 调 daemon + decode generic
async fn dispatch<RspT: prost::Message + Default>(
    gateway: &str,
    client_id: &str,
    proto_id: u32,
    body: Vec<u8>,
) -> Result<RspT> {
    let (client, _push_rx) = connect_gateway(gateway, client_id).await?;
    let frame = client
        .request(proto_id, body)
        .await
        .with_context(|| format!("request proto_id {proto_id}"))?;
    RspT::decode(frame.body.as_ref())
        .with_context(|| format!("decode response for proto_id {proto_id}"))
}

/// 共用 helper: JSON pretty print (table format fallback to JSON for nested data)
fn print_json_pretty<T: serde::Serialize>(_format: OutputFormat, val: &T) -> Result<()> {
    let s = serde_json::to_string_pretty(val)?;
    println!("{s}");
    Ok(())
}

// ============================================================================
// v1.4.94 M1: cash log — cmd 3000/3001/3002
// ============================================================================

/// `futucli cash-log` — 资金明细查询 (mobile-driven, 比 acc-cash-flow 字段更全)
pub struct CashLogCommand<'a> {
    pub gateway: &'a str,
    pub env: &'a str,
    pub acc_id: u64,
    pub begin_time: u64,
    pub end_time: u64,
    pub log_id_cursor: Option<String>,
    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 max_cnt: Option<u32>,
    pub currency: Option<String>,
    pub format: OutputFormat,
}

pub async fn run_cash_log(input: CashLogCommand<'_>) -> Result<()> {
    if input.acc_id == 0 {
        bail!("--acc-id 必填 (call `futucli list-accounts` to discover)");
    }
    if input.end_time < input.begin_time {
        bail!(
            "--end-time {} 不能早于 --begin-time {}",
            input.end_time,
            input.begin_time
        );
    }
    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(parse_env_int(input.env)?),
            },
            // market + account_id 由 daemon 从 acc_id 自动派生 (cash_log handler)
            inner: Some(realtime_asset_log::GetCashLogReq {
                begin_time: Some(input.begin_time),
                end_time: Some(input.end_time),
                log_id: input.log_id_cursor,
                biz_group_id: input.biz_group_id,
                biz_sub_group_id: input.biz_sub_group_id,
                in_out: input.in_out,
                keyword: input.keyword,
                symbol: input.symbol,
                stock_id: input.stock_id,
                max_cnt: input.max_cnt,
                currency: input.currency,
                ..Default::default()
            }),
        },
    };
    let body = req.encode_to_vec();
    let resp: realtime_asset_log::DaemonGetCashLogRsp = dispatch(
        input.gateway,
        "futucli-cash-log",
        proto_id::TRD_GET_CASH_LOG,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetCashLog failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(input.format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

/// `futucli cash-detail` — 单条资金流水详情
pub async fn run_cash_detail(
    gateway: &str,
    env: &str,
    acc_id: u64,
    log_id: String,
    format: OutputFormat,
) -> Result<()> {
    if acc_id == 0 {
        bail!("--acc-id 必填");
    }
    if log_id.trim().is_empty() {
        bail!("--log-id 必填 (从 cash-log 返回的 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(parse_env_int(env)?),
            },
            // market + account_id 由 daemon auto-derive
            inner: Some(realtime_asset_log::GetCashDetailReq {
                log_id: Some(log_id),
                market: None,
                account_id: None,
            }),
        },
    };
    let body = req.encode_to_vec();
    let resp: realtime_asset_log::DaemonGetCashDetailRsp = dispatch(
        gateway,
        "futucli-cash-detail",
        proto_id::TRD_GET_CASH_DETAIL,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetCashDetail failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

/// `futucli biz-group` — 业务分类元数据
pub async fn run_biz_group(
    gateway: &str,
    env: &str,
    acc_id: u64,
    format: OutputFormat,
) -> Result<()> {
    if acc_id == 0 {
        bail!("--acc-id 必填");
    }
    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(parse_env_int(env)?),
            },
            // market 由 daemon auto-derive
            inner: Some(realtime_asset_log::GetBizGroupReq { market: None }),
        },
    };
    let body = req.encode_to_vec();
    let resp: realtime_asset_log::DaemonGetBizGroupRsp = dispatch(
        gateway,
        "futucli-biz-group",
        proto_id::TRD_GET_BIZ_GROUP,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetBizGroup failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

// ============================================================================
// v1.4.95 U2-D: per-account margin info — cmd 3101/3102/3107
// ============================================================================

/// `futucli margin-info` — per-account margin info (HK/US/CN_AH)
pub async fn run_margin_info(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: &str,
    format: OutputFormat,
) -> Result<()> {
    if acc_id == 0 {
        bail!("--acc-id 必填");
    }
    let market_clean = market.trim();
    if market_clean.is_empty() {
        bail!("--market 必填: HK / US / CN_AH");
    }
    let req = risk_user_account_info::DaemonGetMarginInfoReq {
        c2s: risk_user_account_info::daemon_get_margin_info_req::C2s {
            header: risk_user_account_info::DaemonMarginInfoHeader {
                acc_id,
                trd_env: Some(parse_env_int(env)?),
                market: market_clean.to_string(),
            },
            inner: None,
        },
    };
    let body = req.encode_to_vec();
    let resp: risk_user_account_info::DaemonGetMarginInfoRsp = dispatch(
        gateway,
        "futucli-margin-info",
        proto_id::TRD_GET_MARGIN_INFO,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetMarginInfo failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

// ============================================================================
// v1.4.95 U2-A: account compliance flag — cmd 5281
// ============================================================================

/// `futucli account-flag` — 账户合规标志查询
pub async fn run_account_flag(
    gateway: &str,
    env: &str,
    acc_id: u64,
    flag_id: u32,
    format: OutputFormat,
) -> Result<()> {
    if acc_id == 0 {
        bail!("--acc-id 必填");
    }
    if flag_id == 0 {
        bail!(
            "--flag-id 必填 (常用值: 5=US 期权确认, 22=衍生品风批, 10=基金 KYC, \
             16=PDT, 23=美股 OTC; 详见 proto 头部完整 36+ 项列表)"
        );
    }
    let req = account_flag::DaemonGetAccountFlagReq {
        c2s: account_flag::daemon_get_account_flag_req::C2s {
            header: account_flag::DaemonGetAccountFlagHeader {
                acc_id,
                trd_env: Some(parse_env_int(env)?),
                flag_id,
            },
        },
    };
    let body = req.encode_to_vec();
    let resp: account_flag::DaemonGetAccountFlagRsp = dispatch(
        gateway,
        "futucli-account-flag",
        proto_id::TRD_GET_ACCOUNT_FLAG,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetAccountFlag failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

// ============================================================================
// v1.4.95 U2-B: bond holdings + trade prep — cmd 9373/9374/9375/10043/10057
// ============================================================================

/// 共用 helper: parse market (HK/US/SG only)
fn validate_bond_market(market: &str) -> Result<String> {
    let m = market.trim();
    if m.is_empty() {
        bail!("--market 必填: HK / US / SG (债券业务仅 3 市场)");
    }
    let upper = m.to_ascii_uppercase();
    match upper.as_str() {
        "HK" | "US" | "USA" | "SG" | "SG_UNIVERSAL" => Ok(upper),
        _ => bail!(
            "unsupported market {m:?} (supported: HK / US / SG; \
             仅 HK/US/SG 债券账户有数据)"
        ),
    }
}

/// `futucli bond-total-asset` — 账户债券总持仓
pub async fn run_bond_total_asset(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: &str,
    format: OutputFormat,
) -> Result<()> {
    if acc_id == 0 {
        bail!("--acc-id 必填");
    }
    let market_upper = validate_bond_market(market)?;
    let req = bond_client_view::DaemonGetBondTotalAssetReq {
        c2s: bond_client_view::daemon_get_bond_total_asset_req::C2s {
            header: bond_client_view::DaemonBondHeader {
                acc_id,
                trd_env: Some(parse_env_int(env)?),
                market: market_upper,
            },
        },
    };
    let body = req.encode_to_vec();
    let resp: bond_client_view::DaemonGetBondTotalAssetRsp = dispatch(
        gateway,
        "futucli-bond-total-asset",
        proto_id::TRD_GET_BOND_TOTAL_ASSET,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetBondTotalAsset failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

/// `futucli bond-single-asset` — 单只债券持仓
pub async fn run_bond_single_asset(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: &str,
    symbol: &str,
    format: OutputFormat,
) -> Result<()> {
    if acc_id == 0 {
        bail!("--acc-id 必填");
    }
    if symbol.trim().is_empty() {
        bail!("--symbol 必填 (债券代码)");
    }
    let market_upper = validate_bond_market(market)?;
    let req = bond_client_view::DaemonGetBondSingleAssetReq {
        c2s: bond_client_view::daemon_get_bond_single_asset_req::C2s {
            header: bond_client_view::DaemonBondHeader {
                acc_id,
                trd_env: Some(parse_env_int(env)?),
                market: market_upper,
            },
            symbol: symbol.to_string(),
        },
    };
    let body = req.encode_to_vec();
    let resp: bond_client_view::DaemonGetBondSingleAssetRsp = dispatch(
        gateway,
        "futucli-bond-single-asset",
        proto_id::TRD_GET_BOND_SINGLE_ASSET,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetBondSingleAsset failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

/// `futucli bond-position-list` — 债券持仓列表
pub async fn run_bond_position_list(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: &str,
    format: OutputFormat,
) -> Result<()> {
    if acc_id == 0 {
        bail!("--acc-id 必填");
    }
    let market_upper = validate_bond_market(market)?;
    let req = bond_client_view::DaemonGetBondPositionListReq {
        c2s: bond_client_view::daemon_get_bond_position_list_req::C2s {
            header: bond_client_view::DaemonBondHeader {
                acc_id,
                trd_env: Some(parse_env_int(env)?),
                market: market_upper,
            },
        },
    };
    let body = req.encode_to_vec();
    let resp: bond_client_view::DaemonGetBondPositionListRsp = dispatch(
        gateway,
        "futucli-bond-position-list",
        proto_id::TRD_GET_BOND_POSITION_LIST,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetBondPositionList failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

/// `futucli bond-answer-state` — 是否需答题
pub async fn run_bond_answer_state(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: &str,
    symbol: &str,
    format: OutputFormat,
) -> Result<()> {
    if acc_id == 0 {
        bail!("--acc-id 必填");
    }
    if symbol.trim().is_empty() {
        bail!("--symbol 必填 (债券 symbol, 类似 11000018)");
    }
    let market_upper = validate_bond_market(market)?;
    let req = bond_client_view::DaemonGetBondAnswerStateReq {
        c2s: bond_client_view::daemon_get_bond_answer_state_req::C2s {
            header: bond_client_view::DaemonBondHeader {
                acc_id,
                trd_env: Some(parse_env_int(env)?),
                market: market_upper,
            },
            symbol: symbol.to_string(),
        },
    };
    let body = req.encode_to_vec();
    let resp: bond_client_view::DaemonGetBondAnswerStateRsp = dispatch(
        gateway,
        "futucli-bond-answer-state",
        proto_id::TRD_GET_BOND_ANSWER_STATE,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetBondAnswerState failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

/// `futucli bond-trade-reminder` — 交易提醒
pub async fn run_bond_trade_reminder(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: &str,
    symbol: &str,
    format: OutputFormat,
) -> Result<()> {
    if acc_id == 0 {
        bail!("--acc-id 必填");
    }
    if symbol.trim().is_empty() {
        bail!("--symbol 必填");
    }
    let market_upper = validate_bond_market(market)?;
    let req = bond_client_view::DaemonGetBondTradeReminderReq {
        c2s: bond_client_view::daemon_get_bond_trade_reminder_req::C2s {
            header: bond_client_view::DaemonBondHeader {
                acc_id,
                trd_env: Some(parse_env_int(env)?),
                market: market_upper,
            },
            symbol: symbol.to_string(),
        },
    };
    let body = req.encode_to_vec();
    let resp: bond_client_view::DaemonGetBondTradeReminderRsp = dispatch(
        gateway,
        "futucli-bond-trade-reminder",
        proto_id::TRD_GET_BOND_TRADE_REMINDER,
        body,
    )
    .await?;
    if resp.ret_type != 0 {
        bail!(
            "GetBondTradeReminder failed: ret_type={} ret_msg={:?}",
            resp.ret_type,
            resp.ret_msg
        );
    }
    print_json_pretty(format, &resp.s2c.and_then(|s| s.inner))?;
    Ok(())
}

#[cfg(test)]
mod tests;