futu_trd/

account.rs

use futu_core::account_locator::{self, AccountCardRecord, AccountVisibilityRecord};
use futu_core::error::{FutuError, Result};
use futu_core::proto_id;
use futu_net::client::FutuClient;

use crate::read_plan;
use crate::types::{Funds, Position, TrdHeader};

/// 查询账户资金 (向后兼容入口, 不传 currency).
///
/// 高层 gateway 会在用户未传 currency 时按券商派生默认资金视图币种
/// (FutuHK=HKD / FutuInc=USD / FutuCA=CAD 等)。直连底层 client 的调用者
/// 若需要指定币种，可改用 [`get_funds_with_currency`]。
pub async fn get_funds(client: &FutuClient, header: &TrdHeader) -> Result<Funds> {
    get_funds_with_currency(client, header, None).await
}

/// v1.4.103 (deger 反馈 P1 — 综合账户币种不一致): 查询账户资金, 显式传
/// currency 参数 (proto enum int: 1=HKD / 2=USD / 3=CNH / 4=JPY / 5=SGD /
/// 6=AUD / 7=CAD / 8=MYR).
///
/// **综合账户 (uniCardNum 非空)**: gateway 会在缺省时按券商派生默认币种；
/// 显式传 currency 时则要求 backend/cache 返回同币种视图。
///
/// **普通账户 (HK-only / US-only)**: currency 字段被 backend 忽略, 传不传
/// 行为相同.
pub async fn get_funds_with_currency(
    client: &FutuClient,
    header: &TrdHeader,
    currency: Option<i32>,
) -> Result<Funds> {
    let req = futu_proto::trd_get_funds::Request {
        c2s: futu_proto::trd_get_funds::C2s {
            header: header.to_proto(),
            refresh_cache: None,
            currency,
            asset_category: None,
        },
    };

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client.request(proto_id::TRD_GET_FUNDS, body).await?;

    let resp: futu_proto::trd_get_funds::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    let s2c = resp
        .s2c
        .ok_or(FutuError::Codec("missing s2c in GetFunds".into()))?;

    // proto 里 `s2c.funds` 就是 optional —— sim 账户 / 新开户 / 服务端没数据时
    // 可能不返回，返回空 Funds（所有字段 0.0）而不是 error。
    //
    // v1.4.27 修（BUG-2，加拿大同事 v1.4.26 回归测试发现）：v1.4.26 及之前
    // 直接 `.ok_or("missing funds in GetFunds")` 报错，导致 4 个 sim 账户
    // （sim_type 1+2 / HK+US）funds 查询全部失败。proto 本就是 optional，
    // 我们错当 required 处理。
    let funds = s2c.funds.unwrap_or_else(|| {
        tracing::warn!(
            trd_env = ?header.trd_env,
            acc_id = header.acc_id,
            trd_market = ?header.trd_market,
            "get_funds: s2c.funds is None (sim account or no data); returning empty Funds"
        );
        Default::default()
    });

    // 若 caller 显式传 currency, backend 仍可能按账户基准币种返回。对比
    // requested currency vs returned currency tag, 不一致时记录 warning；
    // 上层 surface 可选择把这个短提示返回给用户。
    if let Some(warn_msg) = read_plan::funds_currency_mismatch_warning(currency, funds.currency) {
        tracing::warn!(
            acc_id = header.acc_id,
            trd_market = ?header.trd_market,
            requested_currency = ?currency,
            returned_currency = ?funds.currency,
            warning = %warn_msg,
            "GetFunds: backend ignored requested currency and returned account base currency"
        );
    }

    Ok(Funds::from_proto(&funds))
}

/// 查询持仓列表
pub async fn get_position_list(client: &FutuClient, header: &TrdHeader) -> Result<Vec<Position>> {
    get_position_list_with_filter_market(client, header, None).await
}

/// 查询持仓列表，可显式携带 `TrdFilterConditions.filterMarket`。
///
/// C++ `APIServer_Trd_GetPositionList.cpp:45-51` 对持仓列表只在
/// `filterConditions` 存在时调用 `FilterConditions_IsIncludeParams`，而
/// `_APIServer_Trd_Comm.cpp:2932-2960` 才会使用 `filterMarket` 排除跨市场持仓。
/// 因此 mixed-market 账户的 surface 若展示“指定市场”视图，必须显式传本字段。
pub async fn get_position_list_with_filter_market(
    client: &FutuClient,
    header: &TrdHeader,
    filter_market: Option<i32>,
) -> Result<Vec<Position>> {
    let req = build_get_position_list_request(header, filter_market);

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client
        .request(proto_id::TRD_GET_POSITION_LIST, body)
        .await?;

    let resp: futu_proto::trd_get_position_list::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    let s2c = resp
        .s2c
        .ok_or(FutuError::Codec("missing s2c in GetPositionList".into()))?;

    Ok(s2c.position_list.iter().map(Position::from_proto).collect())
}

fn build_get_position_list_request(
    header: &TrdHeader,
    filter_market: Option<i32>,
) -> futu_proto::trd_get_position_list::Request {
    futu_proto::trd_get_position_list::Request {
        c2s: futu_proto::trd_get_position_list::C2s {
            header: header.to_proto(),
            filter_conditions: filter_market.map(|market| {
                futu_proto::trd_common::TrdFilterConditions {
                    code_list: vec![],
                    id_list: vec![],
                    begin_time: None,
                    end_time: None,
                    order_id_ex_list: vec![],
                    filter_market: Some(market),
                }
            }),
            filter_pl_ratio_min: None,
            filter_pl_ratio_max: None,
            refresh_cache: None,
            asset_category: None,
        },
    }
}

/// 解锁交易结果
#[derive(Debug, Clone, Default)]
pub struct UnlockTradeOutcome {
    /// 所有 broker 合计请求的账户数
    pub total_requested: usize,
    /// 所有 broker 合计成功解锁的账户数
    pub total_unlocked: usize,
    /// 服务端是否要求 OTP（首次调用可能返 true，用户应重传 `otp`）
    pub need_otp: bool,
    /// 如果 `need_otp = true`，这里列出需要 OTP 的账户
    pub failed_accounts: Vec<u64>,
    /// 服务端返回的信息（partial failure 时 daemon 会带详情）
    pub message: Option<String>,
}

/// 解锁交易（v1.4.31+ 支持 OTP 二步）
///
/// 下单前需要先解锁。daemon 会按 broker 分组账户，per-broker 独立发 CMD2900。
///
/// - `pwd_md5`: 交易密码 MD5（32 位小写 hex）。lock 时可空。
/// - `is_unlock`: true=解锁 / false=锁回
/// - `otp`: OTP / 令牌动态密码明文（仅在首次 unlock 返回 `need_otp=true` 或
///   服务端返 `TRADE_AUTH_NEED_AUTH_TOKEN(-8)` 时才需要传；普通账号留 `None`）
///
/// **返回 Ok(outcome)** 时表示 daemon 成功收到并处理了响应（可能 partial
/// failure，看 outcome.total_unlocked vs total_requested）。
/// **返回 Err** 表示完全失败（密码错 / 通道断等）。
pub async fn unlock_trade(
    client: &FutuClient,
    pwd_md5: &str,
    is_unlock: bool,
    otp: Option<&str>,
    security_firm: Option<i32>,
    // v1.4.34: 只解锁 acc_ids 列表里的账户（空 Vec = 不 per-account filter）。
    // 解决同 broker 内影子账户拖垮主账户的场景。和 security_firm 同时传时取交集。
    acc_ids: Vec<u64>,
) -> Result<UnlockTradeOutcome> {
    let req = futu_proto::trd_unlock_trade::Request {
        c2s: futu_proto::trd_unlock_trade::C2s {
            unlock: is_unlock,
            pwd_md5: Some(pwd_md5.to_string()),
            security_firm,
            sec_otp: otp.map(String::from),
            acc_ids,
        },
    };

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client.request(proto_id::TRD_UNLOCK_TRADE, body).await?;

    let resp: futu_proto::trd_unlock_trade::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    // need_otp=true 的特殊分支：ret_type=-1 + err_code=-8 但逻辑上不是 hard error
    if resp.ret_type != 0 {
        let s2c_ref = resp.s2c.as_ref();
        let need_otp = s2c_ref.and_then(|s| s.need_otp).unwrap_or(false);
        if need_otp {
            let failed = s2c_ref
                .map(|s| s.account_result_list.iter().map(|a| a.acc_id).collect())
                .unwrap_or_default();
            return Ok(UnlockTradeOutcome {
                total_requested: s2c_ref.map(|s| s.account_result_list.len()).unwrap_or(0),
                total_unlocked: 0,
                need_otp: true,
                failed_accounts: failed,
                message: resp.ret_msg,
            });
        }
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    // 成功路径（含 partial success —— ret_type=0 但 daemon 会在 ret_msg 里说明）
    let s2c_ref = resp.s2c.as_ref();
    let list = s2c_ref.map(|s| &s.account_result_list[..]).unwrap_or(&[]);
    let total_requested = list.len();
    let total_unlocked = list.iter().filter(|a| a.success).count();
    let failed_accounts: Vec<u64> = list
        .iter()
        .filter(|a| !a.success)
        .map(|a| a.acc_id)
        .collect();
    Ok(UnlockTradeOutcome {
        total_requested,
        total_unlocked,
        need_otp: false,
        failed_accounts,
        message: resp.ret_msg,
    })
}

/// 获取账户列表（C++ 默认语义）。
///
/// `Trd_GetAccList.C2S.needGeneralSecAccount` 在 C++ OpenD 默认缺省为 false：
/// HK/US/SG/AU 综合账户体系下 `enTrdMkt == 6` 的证券账户默认隐藏。需要
/// discovery 视图的 caller（例如 `futucli account`）应显式调用
/// [`get_acc_list_with_options`] 并传 `need_general_sec_account=true`。
pub async fn get_acc_list(client: &FutuClient) -> Result<Vec<TrdAcc>> {
    get_acc_list_with_options(client, None, false).await
}

/// 用户侧账户发现视图。
///
/// C++ `APIServer_Trd_GetAccList.cpp:102-108` 默认隐藏综合账户体系下
/// `enTrdMkt == NN_TrdMarket_SG` 的证券账户，只有
/// `needGeneralSecAccount=true` 时才返回。CLI / MCP / REST 账户发现应返回同一份
/// 完整业务账户集合，因此这里不设置 `trdCategory`，避免把期货、长期激励、
/// crypto 等已开通账户按证券品类过滤掉。底层 SDK 默认 [`get_acc_list`]
/// 继续保持 C++ 缺省行为。
pub async fn get_acc_list_for_account_discovery(client: &FutuClient) -> Result<Vec<TrdAcc>> {
    get_acc_list_with_options(client, None, true).await
}

/// 用户可见账户发现投影。
///
/// daemon/cache 保留完整已开通业务账户，供路由、鉴权和排障使用；CLI / MCP /
/// REST 默认只展示 App 会作为独立账户露出的集合。期货-only 行在 App 里包在综合
/// 账户下，不默认展示；crypto / 长期激励 / IPO route 这类 backend 明确标记的
/// 业务账户即使没有 `TrdMarket` 权限列表也要展示。`paper_trade` 是 Rust
/// 展示层派生的模拟账户标签，不代表 App 独立业务账户，不能绕过 futures-only
/// 过滤。CLI `--all` 仍可看 raw discovery 全集。
pub fn is_app_visible_account(acc: &TrdAcc) -> bool {
    account_locator::is_app_visible_account(acc)
}

pub fn app_visible_accounts(accs: Vec<TrdAcc>) -> Vec<TrdAcc> {
    account_locator::app_visible_accounts(accs)
}

/// 获取账户列表，可显式指定 C++ `Trd_GetAccList.C2S` 过滤选项。
pub async fn get_acc_list_with_options(
    client: &FutuClient,
    trd_category: Option<i32>,
    need_general_sec_account: bool,
) -> Result<Vec<TrdAcc>> {
    let req = build_get_acc_list_request(trd_category, need_general_sec_account);

    let body = prost::Message::encode_to_vec(&req);
    let resp_frame = client.request(proto_id::TRD_GET_ACC_LIST, body).await?;

    let resp: futu_proto::trd_get_acc_list::Response =
        prost::Message::decode(resp_frame.body.as_ref()).map_err(FutuError::Proto)?;

    if resp.ret_type != 0 {
        return Err(crate::server_err(
            resp.ret_type,
            resp.ret_msg,
            resp.err_code,
        ));
    }

    let s2c = resp
        .s2c
        .ok_or(FutuError::Codec("missing s2c in GetAccList".into()))?;

    Ok(s2c
        .acc_list
        .iter()
        .map(|a| TrdAcc {
            trd_env: a.trd_env,
            acc_id: a.acc_id,
            trd_market_auth_list: a.trd_market_auth_list.clone(),
            acc_type: a.acc_type,
            card_num: a.card_num.clone(),
            security_firm: a.security_firm,
            sim_acc_type: a.sim_acc_type,
            uni_card_num: a.uni_card_num.clone(),
            acc_status: a.acc_status,
            acc_role: a.acc_role,
            acc_label: a.acc_label.clone(),
            jp_acc_type: a.jp_acc_type.clone(),
        })
        .collect())
}

fn build_get_acc_list_request(
    trd_category: Option<i32>,
    need_general_sec_account: bool,
) -> futu_proto::trd_get_acc_list::Request {
    futu_proto::trd_get_acc_list::Request {
        c2s: futu_proto::trd_get_acc_list::C2s {
            user_id: 0,
            trd_category,
            need_general_sec_account: Some(need_general_sec_account),
        },
    }
}

/// 业务账户 —— 和官方 Futu `Trd_Common.TrdAcc` proto 一一对应（12 字段）。
///
/// v1.4.26 前只存 3 字段（trd_env / acc_id / trd_market_auth_list），
/// 导致 CLI `futucli account` 表格只有 3 列，用户看不到 `security_firm` /
/// `acc_type` / `card_num` 等重要信息。现在对齐 proto 完整保留。
#[derive(Debug, Clone, Default)]
pub struct TrdAcc {
    /// 0=simulate, 1=real, 2=fund（对齐 `Trd_Common.TrdEnv`）
    pub trd_env: i32,
    /// 业务账号
    pub acc_id: u64,
    /// 账户支持的交易市场权限（`Trd_Common.TrdMarket` enum: 1=HK 2=US 3=CN ...）
    pub trd_market_auth_list: Vec<i32>,
    /// 账户类型（`Trd_Common.TrdAccType`: 0=未知 1=现金 2=保证金 3=期货）
    pub acc_type: Option<i32>,
    /// 账户卡号（人读标识，比如 "8105" 这样的短号）
    pub card_num: Option<String>,
    /// 所属券商（`Trd_Common.SecurityFirm`: 1=FutuSecurities(HK) 2=FutuInc(US)
    /// 3=FutuSG 4=FutuAU 5=FutuCA 6=FutuMY 7=FutuJP）
    pub security_firm: Option<i32>,
    /// 模拟交易子类型（仅 trd_env=0 时有值，`Trd_Common.SimAccType`）
    pub sim_acc_type: Option<i32>,
    /// 综合账户卡号（子账户归属的父综合账户的 card_num）
    pub uni_card_num: Option<String>,
    /// 账户状态（`Trd_Common.TrdAccStatus`: 0=active 1=disabled）
    pub acc_status: Option<i32>,
    /// 账号分类（`Trd_Common.TrdAccRole`: 主/子账号）
    pub acc_role: Option<i32>,
    /// Daemon-derived user-visible account label (`crypto`,
    /// `equity_incentive`, `ipo_route`, ...). Treat unknown values as opaque
    /// display strings.
    pub acc_label: Option<String>,
    /// JP 子账户类型（日本账号特殊，`Trd_Common.TrdSubAccType`）
    pub jp_acc_type: Vec<i32>,
}

impl AccountCardRecord for TrdAcc {
    fn acc_id(&self) -> u64 {
        self.acc_id
    }

    fn card_num(&self) -> Option<&str> {
        self.card_num.as_deref()
    }

    fn uni_card_num(&self) -> Option<&str> {
        self.uni_card_num.as_deref()
    }
}

impl AccountVisibilityRecord for TrdAcc {
    fn trd_market_auth_list(&self) -> &[i32] {
        &self.trd_market_auth_list
    }

    fn acc_label(&self) -> Option<&str> {
        self.acc_label.as_deref()
    }
}

#[cfg(test)]
mod tests;