futucli/cmd/

account.rs

//! `futucli account` / `position` / `order` / `deal` — 只读账户查询
//!
//! 本模块只承载账户/持仓/订单/成交查询；下单、改单、撤单等写命令在
//! `trade_ext.rs`，并由 CLI 层的 `--confirm` / env / scope guard 控制误操作风险。

use anyhow::{Result, bail};
use serde::Serialize;
use tabled::Tabled;

use crate::common::connect_gateway;
use crate::output::OutputFormat;
use crate::trd_sdk_adapter;
use futu_core::trade_currency::funds_currency_mismatch_warning;
use futu_core::{trade_market, trade_parsing};
use futu_trd::{
    currency,
    types::{TrdEnv, TrdHeader, TrdMarket},
};

mod list;
#[cfg(test)]
mod tests;

#[cfg(test)]
pub(crate) use list::read_private_account_id_file;
#[cfg(test)]
use list::{
    AccJson, account_matches_sdk_filter, app_visible_card_num_resolution,
    parse_account_market_filter, parse_account_security_firm_filter,
};
pub use list::{list_accounts, resolve_account_locator};

// ========== 共享：参数解析 ==========

/// v1.4.102 codex 27 F7 (P1) fix: write path 专用 parser, 显式拒 fund market.
///
/// `place-order` / `modify-order` / `cancel-order` / `cancel-all-order` 等
/// CLI 写命令应用此 fn (不直接用 `parse_trd_market`). fund markets
/// 仅 view-only read endpoints 支持. read 命令 (`positions` / `funds` /
/// `cash-log` 等) 仍用 `parse_trd_market`.
pub fn parse_trd_market_for_write(s: &str) -> Result<TrdMarket> {
    let m = parse_trd_market(s)?;
    if let Some(label) = trade_market::canonical_fund_trd_market_label(m as i32) {
        bail!(
            "trd market {label} 仅支持 view-only read commands \
             (positions/funds/cash-log/history-orders/history-fills); \
             write commands (place-order/modify-order/cancel-order/cancel-all-order) \
             用对应主市场, daemon 自动按持仓 broker 路由. v1.4.102 audit 27 F7 fix"
        )
    }
    // v1.8.0 Task 12 Reviewer A1: the shared core allowlist
    // (`TRD_MARKET_NON_FUND_INT_VALUES`) is the write-path contract. KRX=18 is
    // read-visible but only the typed batch-close-positions contract may write
    // it (Desktop `PositionCloseUtil.cpp:159-184`); the fund-label filter above
    // alone let it through (pitfall #54 parser drift).
    if !trade_market::TRD_MARKET_NON_FUND_INT_VALUES.contains(&(m as i32)) {
        bail!(
            "trd market {} ({}) 不在普通 write/calculation 市场 allowlist 内 ({}); \
             KRX=18 仅通过 batch-close-positions 原子合同放行, 普通 write 命令 fail closed",
            m as i32,
            s.trim().to_ascii_uppercase(),
            trade_market::TRD_MARKET_NON_FUND_PARSE_CHOICES
        )
    }
    Ok(m)
}

pub fn parse_trd_market(s: &str) -> Result<TrdMarket> {
    let market = trade_market::parse_trd_market_id(s).ok_or_else(|| {
        anyhow::anyhow!(
            "unknown trd market {:?} ({})",
            s.trim().to_ascii_uppercase(),
            trade_market::TRD_MARKET_PARSE_CHOICES
        )
    })?;
    trd_sdk_adapter::trd_market_from_id(market).ok_or_else(|| {
        anyhow::anyhow!("unknown trd market id {market} after core parser accepted it")
    })
}

pub fn parse_trd_env(s: &str) -> Result<TrdEnv> {
    let env = trade_parsing::parse_trd_env_id(s).ok_or_else(|| {
        anyhow::anyhow!(
            "unknown trd env {:?} ({})",
            s.trim().to_ascii_lowercase(),
            trade_parsing::TRD_ENV_PARSE_CHOICES
        )
    })?;
    trd_sdk_adapter::trd_env_from_id(env)
        .ok_or_else(|| anyhow::anyhow!("unknown trd env id {env} after core parser accepted it"))
}

fn build_header(env: TrdEnv, acc_id: u64, market: TrdMarket) -> TrdHeader {
    TrdHeader {
        trd_env: env,
        acc_id,
        trd_market: market,
        jp_acc_type: None,
    }
}

fn format_pl_ratio_percent(ratio_value: f64) -> String {
    // Gateway/JSON keep C++ APIServer numeric `Position.plRatio` unchanged.
    // CLI shows the user-facing percent form: `0.6078` -> `+60.78%`.
    let percent = ratio_value * 100.0;
    if percent > 0.0 {
        format!("+{percent:.2}%")
    } else {
        format!("{percent:.2}%")
    }
}

// ========== account funds ==========

#[derive(Tabled)]
struct FundsRow {
    #[tabled(rename = "Metric")]
    name: &'static str,
    #[tabled(rename = "Value")]
    value: String,
}

#[derive(Serialize)]
struct FundsJson {
    power: f64,
    total_assets: f64,
    cash: f64,
    market_val: f64,
    frozen_cash: f64,
    debt_cash: f64,
    avl_withdrawal_cash: f64,
    #[serde(skip_serializing_if = "Option::is_none")]
    crypto_mv: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    exposure_level: Option<i32>,
    #[serde(skip_serializing_if = "Option::is_none")]
    exposure_limit: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    used_limit: Option<f64>,
    #[serde(skip_serializing_if = "Option::is_none")]
    remaining_limit: Option<f64>,
    /// v1.4.96 BUG #012 hotfix (external reviewer double-tester report 2026-04-26):
    /// 账户主币种 (HKD / USD / CNH / 等), 之前 CLI 漏打印, 与 REST `/api/funds` +
    /// MCP `futu_get_funds` 3-surface 不一致.
    #[serde(skip_serializing_if = "Option::is_none")]
    currency: Option<&'static str>,
    /// v1.4.103 (external reviewer 反馈 P1): 综合账户多币种 cash 细分.
    /// `[{currency: "USD", cash: 208532.79, available_balance: ..., net_cash_power: ...}, ...]`
    #[serde(skip_serializing_if = "Vec::is_empty")]
    cash_info_list: Vec<CashInfoJson>,
    /// v1.4.103 (external reviewer 反馈 P1): 综合账户多市场 assets 细分.
    /// `[{market: "US", assets: 8151509.8}, ...]`
    #[serde(skip_serializing_if = "Vec::is_empty")]
    market_info_list: Vec<MarketInfoJson>,
    /// 用户显式传 currency, 但 backend 按账户基准币种返回时的提示。
    #[serde(skip_serializing_if = "Option::is_none")]
    currency_warning: Option<String>,
}

/// v1.4.103 (external reviewer P1): 单币种 cash detail (for cash_info_list).
#[derive(Serialize)]
struct CashInfoJson {
    currency: &'static str,
    cash: f64,
    available_balance: f64,
    net_cash_power: f64,
}

/// v1.4.103 (external reviewer P1): 单市场 assets detail (for market_info_list).
#[derive(Serialize)]
struct MarketInfoJson {
    market: &'static str,
    assets: f64,
}

/// v1.4.103: trd_market enum int → 字符串.
fn trd_market_int_to_str(m: Option<i32>) -> &'static str {
    m.and_then(trade_market::trd_market_label).unwrap_or("?")
}

pub async fn funds(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: Option<&str>,
    currency: Option<&str>,
    format: OutputFormat,
) -> Result<()> {
    // v1.4.106 ergonomics: --market 改 optional. 不传时 trd_market 设
    // `TrdMarket::Unknown=0`, daemon `GetFundsHandler` 按 `acc_id` cache 推断
    // (lookup `acc.trd_market` 作 currency derive 兜底; 不依赖 header.trd_market
    // 做主路由 filter, 见 `crates/futu-gateway-trd/src/handlers/trd/query.rs:88+`).
    // 普通账户 (HK-only/US-only) 主市场由 cache.acc_entry.trd_market 决定;
    // 综合账户 (uniCardNum 非空) acc_id 路径已经 cross-market view, market
    // 参数对结果无影响.
    let trd_market = match market {
        Some(m) => parse_trd_market(m)?,
        None => TrdMarket::Unknown,
    };
    let header = build_header(parse_trd_env(env)?, acc_id, trd_market);
    let (client, _push_rx) = connect_gateway(gateway, "futucli-funds").await?;

    // v1.4.103 (external reviewer P1): parse currency if provided, pass to backend.
    let currency_int: Option<i32> = match currency {
        Some(s) => Some(currency::parse_currency_label(s)?),
        None => None,
    };

    let f = futu_trd::account::get_funds_with_currency(&client, &header, currency_int).await?;

    // FX sanity check lives in the shared trade-read domain; CLI only decides
    // whether to print it on stderr and include it in JSON output.
    let currency_warning = funds_currency_mismatch_warning(currency_int, f.currency);
    if let Some(ref warn) = currency_warning {
        eprintln!("⚠️  {warn}");
    }

    // v1.4.96 BUG #012: 显示账户主币种 (与 REST/MCP 对齐)
    let currency = currency::known_currency_label(f.currency);
    // v1.4.106 codex 1612 Candidate A: `Cash` label 太泛, 用户误把
    // top-level summary cash 当作"所有 cash_info_list 跨币种相加".
    // 改 `CashSummary(<cur>)` 让 user 知道这是 backend 直传的单一币种
    // summary, 不等于 cash_info_list.sum() (跨币种不能无汇率相加). backend
    // 未下 top-level currency 时不伪造 `?` 标签，避免让用户误以为整张表
    // 已有明确币种。
    let cash_summary_label: String = currency
        .map(|cur| format!("CashSummary({cur})"))
        .unwrap_or_else(|| "CashSummary".to_string());
    let mut rows = vec![
        FundsRow {
            name: "Power",
            value: format!("{:.2}", f.power),
        },
        FundsRow {
            name: "TotalAssets",
            value: format!("{:.2}", f.total_assets),
        },
        FundsRow {
            name: Box::leak(cash_summary_label.into_boxed_str()),
            value: format!("{:.2}", f.cash),
        },
        FundsRow {
            name: "MarketVal",
            value: format!("{:.2}", f.market_val),
        },
        FundsRow {
            name: "FrozenCash",
            value: format!("{:.2}", f.frozen_cash),
        },
        FundsRow {
            name: "DebtCash",
            value: format!("{:.2}", f.debt_cash),
        },
        FundsRow {
            name: "AvlWithdrawalCash",
            value: format!("{:.2}", f.avl_withdrawal_cash),
        },
    ];
    // v1.4.96 BUG #012: 加 Currency 列 (-) 当 backend 未返时
    rows.push(FundsRow {
        name: "Currency",
        value: currency
            .map(|s| s.to_string())
            .unwrap_or_else(|| "-".into()),
    });
    if let Some(value) = f.crypto_mv {
        rows.push(FundsRow {
            name: "CryptoMv",
            value: format!("{value:.2}"),
        });
    }
    if let Some(value) = f.exposure_level {
        rows.push(FundsRow {
            name: "ExposureLevel",
            value: value.to_string(),
        });
    }
    if let Some(value) = f.exposure_limit {
        rows.push(FundsRow {
            name: "ExposureLimit",
            value: format!("{value:.2}"),
        });
    }
    if let Some(value) = f.used_limit {
        rows.push(FundsRow {
            name: "UsedLimit",
            value: format!("{value:.2}"),
        });
    }
    if let Some(value) = f.remaining_limit {
        rows.push(FundsRow {
            name: "RemainingLimit",
            value: format!("{value:.2}"),
        });
    }

    // v1.4.103 (external reviewer 反馈 P1): 综合账户多币种 / 多市场细分.
    // 当 cash_info_list / market_info_list 非空 (综合账户) 时, 展开 sub-rows
    // 让用户看到细分数据 — 之前只显示 7 字段 top-level, 综合账户用户根本不知
    // 道 USD market 下面有 208K USD cash / 1.05M USD assets.
    if !f.cash_info_list.is_empty() {
        rows.push(FundsRow {
            name: "── CashByCurrency ──",
            value: String::new(),
        });
        for ci in &f.cash_info_list {
            let cur_str = currency::known_currency_label(ci.currency).unwrap_or("?");
            rows.push(FundsRow {
                name: Box::leak(format!("  {} cash", cur_str).into_boxed_str()),
                value: format!("{:.2}", ci.cash.unwrap_or(0.0)),
            });
            let ncp = ci.net_cash_power.unwrap_or(0.0);
            if ncp.abs() > 0.001 {
                rows.push(FundsRow {
                    name: Box::leak(format!("  {} netCashPower", cur_str).into_boxed_str()),
                    value: format!("{:.2}", ncp),
                });
            }
        }
    }
    if !f.market_info_list.is_empty() {
        rows.push(FundsRow {
            name: "── AssetsByMarket ──",
            value: String::new(),
        });
        for mi in &f.market_info_list {
            // 只显示非零 assets (省得过长)
            let assets = mi.assets.unwrap_or(0.0);
            if assets.abs() < 0.001 {
                continue;
            }
            let mkt_str = trd_market_int_to_str(mi.trd_market);
            rows.push(FundsRow {
                name: Box::leak(format!("  {} assets", mkt_str).into_boxed_str()),
                value: format!("{:.2}", assets),
            });
        }
    }

    // v1.4.103 (external reviewer P1): JSON output 也含细分 list (与表格视图一致).
    let cash_info_jsons: Vec<CashInfoJson> = f
        .cash_info_list
        .iter()
        .map(|ci| CashInfoJson {
            currency: currency::known_currency_label(ci.currency).unwrap_or("UNKNOWN"),
            cash: ci.cash.unwrap_or(0.0),
            available_balance: ci.available_balance.unwrap_or(0.0),
            net_cash_power: ci.net_cash_power.unwrap_or(0.0),
        })
        .collect();
    let market_info_jsons: Vec<MarketInfoJson> = f
        .market_info_list
        .iter()
        .map(|mi| MarketInfoJson {
            market: trd_market_int_to_str(mi.trd_market),
            assets: mi.assets.unwrap_or(0.0),
        })
        .collect();
    let jsons = vec![FundsJson {
        power: f.power,
        total_assets: f.total_assets,
        cash: f.cash,
        market_val: f.market_val,
        frozen_cash: f.frozen_cash,
        debt_cash: f.debt_cash,
        avl_withdrawal_cash: f.avl_withdrawal_cash,
        crypto_mv: f.crypto_mv,
        exposure_level: f.exposure_level,
        exposure_limit: f.exposure_limit,
        used_limit: f.used_limit,
        remaining_limit: f.remaining_limit,
        currency,
        cash_info_list: cash_info_jsons,
        market_info_list: market_info_jsons,
        currency_warning,
    }];

    format.print_rows(&rows, &jsons)?;
    Ok(())
}

// ========== position list ==========

#[derive(Tabled)]
struct PosRow {
    #[tabled(rename = "Code")]
    code: String,
    #[tabled(rename = "Name")]
    name: String,
    #[tabled(rename = "Qty")]
    qty: String,
    #[tabled(rename = "Sellable")]
    sellable: String,
    #[tabled(rename = "Cost")]
    cost: String,
    #[tabled(rename = "Price")]
    price: String,
    #[tabled(rename = "Val")]
    val: String,
    #[tabled(rename = "PL")]
    pl: String,
    #[tabled(rename = "PL%")]
    pl_pct: String,
}

#[derive(Serialize)]
struct PosJson {
    position_id: u64,
    position_side: i32,
    code: String,
    name: String,
    qty: f64,
    can_sell_qty: f64,
    price: f64,
    cost_price: f64,
    val: f64,
    pl_val: f64,
    pl_ratio: f64,
}

pub async fn positions(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: &str,
    currency_arg: Option<&str>,
    option_strategy_view: bool,
    format: OutputFormat,
) -> Result<()> {
    let header = build_header(parse_trd_env(env)?, acc_id, parse_trd_market(market)?);
    let (client, _push_rx) = connect_gateway(gateway, "futucli-position").await?;
    let currency_int = match currency_arg {
        Some(s) => Some(currency::parse_currency_label(s)?),
        None => None,
    };
    let list = futu_trd::account::get_position_list_with_options(
        &client,
        &header,
        futu_trd::account::PositionListOptions {
            filter_market: Some(header.trd_market as i32),
            currency: currency_int,
            option_strategy_view: option_strategy_view.then_some(true),
        },
    )
    .await?;

    let rows: Vec<PosRow> = list
        .iter()
        .map(|p| PosRow {
            code: p.code.clone(),
            name: p.name.clone(),
            qty: format!("{:.0}", p.qty),
            sellable: format!("{:.0}", p.can_sell_qty),
            cost: format!("{:.3}", p.cost_price),
            price: format!("{:.3}", p.price),
            val: format!("{:.2}", p.val),
            pl: format!("{:.2}", p.pl_val),
            pl_pct: format_pl_ratio_percent(p.pl_ratio),
        })
        .collect();

    let jsons: Vec<PosJson> = list
        .iter()
        .map(|p| PosJson {
            position_id: p.position_id,
            position_side: p.position_side,
            code: p.code.clone(),
            name: p.name.clone(),
            qty: p.qty,
            can_sell_qty: p.can_sell_qty,
            price: p.price,
            cost_price: p.cost_price,
            val: p.val,
            pl_val: p.pl_val,
            pl_ratio: p.pl_ratio,
        })
        .collect();

    format.print_rows(&rows, &jsons)?;
    Ok(())
}

// ========== order list ==========

#[derive(Tabled)]
struct OrderRow {
    #[tabled(rename = "OrderID")]
    order_id: String,
    #[tabled(rename = "Code")]
    code: String,
    #[tabled(rename = "Side")]
    side: String,
    #[tabled(rename = "Type")]
    order_type: i32,
    #[tabled(rename = "Status")]
    status: i32,
    #[tabled(rename = "Qty")]
    qty: String,
    #[tabled(rename = "Price")]
    price: String,
    #[tabled(rename = "FillQty")]
    fill_qty: String,
    #[tabled(rename = "FillAvg")]
    fill_avg: String,
    #[tabled(rename = "Updated")]
    update_time: String,
}

#[derive(Serialize)]
struct OrderJson {
    order_id: u64,
    order_id_ex: String,
    trd_side: i32,
    order_type: i32,
    order_status: i32,
    code: String,
    name: String,
    qty: f64,
    price: f64,
    create_time: String,
    update_time: String,
    fill_qty: f64,
    fill_avg_price: f64,
    last_err_msg: String,
}

fn trd_side_label(d: i32) -> &'static str {
    match d {
        1 => "BUY",
        2 => "SELL",
        3 => "SELL_SHORT",
        4 => "BUY_BACK",
        _ => "?",
    }
}

pub async fn orders(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: &str,
    format: OutputFormat,
) -> Result<()> {
    let header = build_header(
        parse_trd_env(env)?,
        acc_id,
        parse_trd_market_for_write(market)?,
    );
    let (client, _push_rx) = connect_gateway(gateway, "futucli-order").await?;
    let list = futu_trd::query::get_order_list(&client, &header).await?;

    let rows: Vec<OrderRow> = list
        .iter()
        .map(|o| OrderRow {
            order_id: o.order_id.to_string(),
            code: o.code.clone(),
            side: trd_side_label(o.trd_side).to_string(),
            order_type: o.order_type,
            status: o.order_status,
            qty: format!("{:.0}", o.qty),
            price: format!("{:.3}", o.price),
            fill_qty: format!("{:.0}", o.fill_qty),
            fill_avg: format!("{:.3}", o.fill_avg_price),
            update_time: o.update_time.clone(),
        })
        .collect();

    let jsons: Vec<OrderJson> = list
        .iter()
        .map(|o| OrderJson {
            order_id: o.order_id,
            order_id_ex: o.order_id_ex.clone(),
            trd_side: o.trd_side,
            order_type: o.order_type,
            order_status: o.order_status,
            code: o.code.clone(),
            name: o.name.clone(),
            qty: o.qty,
            price: o.price,
            create_time: o.create_time.clone(),
            update_time: o.update_time.clone(),
            fill_qty: o.fill_qty,
            fill_avg_price: o.fill_avg_price,
            last_err_msg: o.last_err_msg.clone(),
        })
        .collect();

    format.print_rows(&rows, &jsons)?;
    Ok(())
}

// ========== deal (fill) list ==========

#[derive(Tabled)]
struct DealRow {
    #[tabled(rename = "FillID")]
    fill_id: String,
    #[tabled(rename = "OrderID")]
    order_id: String,
    #[tabled(rename = "Code")]
    code: String,
    #[tabled(rename = "Side")]
    side: String,
    #[tabled(rename = "Qty")]
    qty: String,
    #[tabled(rename = "Price")]
    price: String,
    #[tabled(rename = "Time")]
    time: String,
}

#[derive(Serialize)]
struct DealJson {
    fill_id: u64,
    fill_id_ex: String,
    order_id: u64,
    trd_side: i32,
    code: String,
    name: String,
    qty: f64,
    price: f64,
    create_time: String,
}

pub async fn deals(
    gateway: &str,
    env: &str,
    acc_id: u64,
    market: &str,
    format: OutputFormat,
) -> Result<()> {
    let header = build_header(
        parse_trd_env(env)?,
        acc_id,
        parse_trd_market_for_write(market)?,
    );
    let (client, _push_rx) = connect_gateway(gateway, "futucli-deal").await?;
    let list = futu_trd::query::get_order_fill_list(&client, &header).await?;

    let rows: Vec<DealRow> = list
        .iter()
        .map(|f| DealRow {
            fill_id: f.fill_id.to_string(),
            order_id: f.order_id.to_string(),
            code: f.code.clone(),
            side: trd_side_label(f.trd_side).to_string(),
            qty: format!("{:.0}", f.qty),
            price: format!("{:.3}", f.price),
            time: f.create_time.clone(),
        })
        .collect();

    let jsons: Vec<DealJson> = list
        .iter()
        .map(|f| DealJson {
            fill_id: f.fill_id,
            fill_id_ex: f.fill_id_ex.clone(),
            order_id: f.order_id,
            trd_side: f.trd_side,
            code: f.code.clone(),
            name: f.name.clone(),
            qty: f.qty,
            price: f.price,
            create_time: f.create_time.clone(),
        })
        .collect();

    format.print_rows(&rows, &jsons)?;
    Ok(())
}