futu_rest/routes/trd/

tier_m.rs

//! REST Tier M / mobile-driven trade account endpoints.
//!
//! 这些 endpoint 使用 mobile backend proto 与专用 cmd，和标准 FTAPI trade query
//! 路径不同；集中到本模块后，主 trade route 不再混入 mobile-driven proto 细节。

use std::sync::Arc;

use axum::Json;
use axum::extract::{Extension, State};
use serde_json::Value;

use futu_auth::KeyRecord;
use futu_backend::proto_internal::realtime_asset_log;
use futu_core::proto_id;

use crate::adapter::{self, RestState};

use super::RawApiResult;
use super::card_num::normalize_and_resolve_card_num_for_route;
use super::validation::{
    read_handler_acc_id_check, validate_header_trd_env_present, validate_header_trd_market,
};

// v1.4.94 Tier M (mobile-driven extension): 资金明细 / cash log
//
// 来源: ftcnnproto/.../realtime_asset_log.proto + FLCltProtocol.h:123
// (clt_cmd_trade_cash_log = 3000). Daemon 主动扩展, OpenD 没暴露此 cmd 给
// FTAPI, 但 mobile 用同一 cmd 直连 backend, daemon 也走同 channel.
// ============================================================================

/// POST /api/cash-log — 资金明细查询 (mobile-driven, 比 /api/flow-summary 更全字段)
///
/// 参数 (body 顶层平铺, REST adapter 自动 wrap 到 c2s):
/// - acc_id (u64, 必填): 账户 ID
/// - trd_env (i32, 0=sim 1=real): 必填
/// - inner.market / inner.account_id: daemon 从已鉴权 acc_id 派生，client-provided 值会被忽略
/// - inner.begin_time / inner.end_time (epoch 秒, 时间范围)
/// - inner.biz_group_id / inner.biz_sub_group_id: 业务分组过滤
/// - inner.in_out: 1=入账, 2=出账, 0=全部
/// - inner.keyword / inner.symbol / inner.stock_id: 搜索
/// - inner.currency: 货币过滤
/// - inner.log_id: cursor 分页 (上次响应的 next_log_id)
/// - inner.max_cnt: 每页上限
///
/// 响应: ret_type / ret_msg / s2c.inner (含 monthly_log_list / has_more / next_log_id)
///
/// **Pitfall #42 backend-semantic risk**: 真 backend 接受我们的 proto 序列化
/// 是 **未真机 verify** 假设. 真机 fail 时 ret_type=-1 + clear hint.
pub async fn get_cash_log(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 (P2): Tier M REST 同 funds/positions 走完整
    // pre-flight (normalize → trd_market 白名单 → trd_env 必填 → acc_id check)
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/cash-log")?;
    validate_header_trd_market(&body, "/api/cash-log")?;
    validate_header_trd_env_present(&body, "/api/cash-log")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/cash-log",
    )?;
    adapter::proto_request_raw::<
        realtime_asset_log::DaemonGetCashLogReq,
        realtime_asset_log::DaemonGetCashLogRsp,
    >(&state, proto_id::TRD_GET_CASH_LOG, Some(body))
    .await
}

/// POST /api/cash-detail — 单条资金流水详情
///
/// 参数:
/// - acc_id (u64, 必填), trd_env
/// - inner.log_id (string, 必填): 从 GetCashLog 响应里取
/// - inner.market / inner.account_id: daemon 从已鉴权 acc_id 派生，client-provided 值会被忽略
pub async fn get_cash_detail(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 / 40 F1+F2: Tier M normalize-first +
    // 完整 pre-flight (避免 raw ACC_ID 绕过 auth-limit + 缺 trd_env silent default)
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/cash-detail")?;
    validate_header_trd_market(&body, "/api/cash-detail")?;
    validate_header_trd_env_present(&body, "/api/cash-detail")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/cash-detail",
    )?;
    adapter::proto_request_raw::<
        realtime_asset_log::DaemonGetCashDetailReq,
        realtime_asset_log::DaemonGetCashDetailRsp,
    >(&state, proto_id::TRD_GET_CASH_DETAIL, Some(body))
    .await
}

/// POST /api/biz-group — 业务分类元数据 (供前端构造业务分组下拉)
///
/// 参数:
/// - acc_id (u64, 必填), trd_env
/// - inner.market (默认从 acc_id 派生)
///
/// 响应: biz_group_list (业务类型) / currency_config_list (货币) / direction_list (方向)
pub async fn get_biz_group(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 / 40 F1+F2: Tier M normalize-first +
    // 完整 pre-flight
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/biz-group")?;
    validate_header_trd_market(&body, "/api/biz-group")?;
    validate_header_trd_env_present(&body, "/api/biz-group")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/biz-group",
    )?;
    adapter::proto_request_raw::<
        realtime_asset_log::DaemonGetBizGroupReq,
        realtime_asset_log::DaemonGetBizGroupRsp,
    >(&state, proto_id::TRD_GET_BIZ_GROUP, Some(body))
    .await
}

// ============================================================================
// v1.4.95 U2-D Tier M (mobile-driven extension): margin account info per market
//
// 来源: ftcnnproto/.../risk_user_account_info.proto + FLCltProtocol.h
// (clt_cmd_hk_margin_info=3101 / us=3102 / cn_ah=3107).
// ============================================================================

/// POST /api/margin-info — per-account margin info (mobile-driven, by market)
///
/// 与 `/api/margin-ratio` (per-security ratio) 互补: 本 endpoint 给账户全景.
///
/// 参数:
/// - acc_id (u64, 必填)
/// - trd_env (i32, 0=sim 1=real, default 1)
/// - market (string, 必填): "HK" / "US" / "CN_AH" (其他市场 → 400 with hint)
/// - inner.req_flag (uint32, optional): 1 = 过滤新股中签干扰
///
/// 响应: ret_type / ret_msg / s2c.inner.user_margin_info[] (含 12 字段子集
/// 的 MarginInfo: 购买力 / 余额 / 净值 / 保证金 / 流动性 / 风险等级 / HK-specific)
///
/// **Pitfall #42 backend-semantic risk**: backend 接受我们 12 字段子集是
/// **未真机 verify** 假设. 真机 fail 时 ret_type=-1 + clear hint 指 fallback
/// `/api/margin-ratio` per-security ratio.
pub async fn get_margin_info(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 / 40 F1+F2: Tier M normalize-first
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/margin-info")?;
    validate_header_trd_market(&body, "/api/margin-info")?;
    validate_header_trd_env_present(&body, "/api/margin-info")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/margin-info",
    )?;
    adapter::proto_request_raw::<
        futu_backend::proto_internal::risk_user_account_info::DaemonGetMarginInfoReq,
        futu_backend::proto_internal::risk_user_account_info::DaemonGetMarginInfoRsp,
    >(&state, proto_id::TRD_GET_MARGIN_INFO, Some(body))
    .await
}

// ============================================================================
// v1.4.95 U2-A Tier M (mobile-driven extension): account compliance flags
//
// 来源: ftcnnproto/.../account_flag.proto + NN cmd 5281.
// ============================================================================

/// POST /api/account-flag — 查询账户合规标志 (mobile-driven)
///
/// 用户:
/// - 高级交易准入 (期权 / 衍生品 / OTC / CFD 等) 必须 flag=1
/// - LLM agent 检查用户是否完成 KYC / 风披 / opt-in 等
///
/// 参数:
/// - acc_id (u64, 必填): per-broker 路由
/// - trd_env (i32, 0=sim 1=real, default 1)
/// - flag_id (uint32, 必填): 标志 id (常用值 5=US 期权确认, 22=衍生品风批,
///   10=基金 KYC, 16=PDT, 23=OTC; 详见 proto 头部 36+ 项 flag_id 列表)
///
/// 响应: ret_type / ret_msg / s2c.inner.item (general_flag: uid / flag_id /
/// flag_value / updated_time). flag_value 通常 0=未确认 / 1=已确认 / 部分用 version.
///
/// **Pitfall #42**: backend 接受度仍属 real-machine-required；未拿到真机
/// positive evidence 前保持 UNVERIFIED。
pub async fn get_account_flag(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 / 40 F1+F2: Tier M normalize-first
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/account-flag")?;
    validate_header_trd_market(&body, "/api/account-flag")?;
    validate_header_trd_env_present(&body, "/api/account-flag")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/account-flag",
    )?;
    adapter::proto_request_raw::<
        futu_backend::proto_internal::account_flag::DaemonGetAccountFlagReq,
        futu_backend::proto_internal::account_flag::DaemonGetAccountFlagRsp,
    >(&state, proto_id::TRD_GET_ACCOUNT_FLAG, Some(body))
    .await
}

// ============================================================================
// v1.4.95 U2-B Tier M (mobile-driven extension): bond holdings + trade prep
//
// 来源: ftcnnproto/.../bond_client_view.proto + FLCltProtocol.h
// 5 endpoint × 5 cmd_id (9373/9374/9375/10043/10057), 共享 DaemonBondHeader
// (acc_id + trd_env + market: "HK"/"US"/"SG").
//
// **市场覆盖**: 仅 HK / US / SG 债券账户; 其他账户 backend 自动返空.
//
// **Pitfall #42 backend-semantic risk**: backend 接受度仍属
// real-machine-required；未拿到真机 positive evidence 前保持 UNVERIFIED。
// ============================================================================

/// POST /api/bond-total-asset — 账户债券总持仓 (P&L 汇总, mobile cmd 9373)
///
/// 参数:
/// - acc_id (u64, 必填)
/// - trd_env (i32, 0=sim 1=real, default 1)
/// - market (string, 必填): "HK" / "US" / "SG"
///
/// 响应字段 (s2c.inner): total_asset / position_incomes / today_incomes /
/// accrued_interest / show_flag / ccy.
pub async fn get_bond_total_asset(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 / 40 F1+F2: Tier M normalize-first
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/bond-total-asset")?;
    validate_header_trd_market(&body, "/api/bond-total-asset")?;
    validate_header_trd_env_present(&body, "/api/bond-total-asset")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/bond-total-asset",
    )?;
    adapter::proto_request_raw::<
        futu_backend::proto_internal::bond_client_view::DaemonGetBondTotalAssetReq,
        futu_backend::proto_internal::bond_client_view::DaemonGetBondTotalAssetRsp,
    >(&state, proto_id::TRD_GET_BOND_TOTAL_ASSET, Some(body))
    .await
}

/// POST /api/bond-single-asset — 单只债券持仓 (mobile cmd 9374)
///
/// 参数:
/// - acc_id (u64, 必填)
/// - trd_env (i32, 0=sim 1=real, default 1)
/// - market (string, 必填): "HK" / "US" / "SG"
/// - symbol (string, 必填): 债券代码
///
/// 响应字段 (s2c.inner): market_value / today_incomes / position_incomes /
/// quantity / cost / expired_time / next_dividend_time / dividend_type /
/// accrued_interest / dividend_option / notice_list / ccy / coupon_cash /
/// position_cost / price.
pub async fn get_bond_single_asset(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 / 40 F1+F2: Tier M normalize-first
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/bond-single-asset")?;
    validate_header_trd_market(&body, "/api/bond-single-asset")?;
    validate_header_trd_env_present(&body, "/api/bond-single-asset")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/bond-single-asset",
    )?;
    adapter::proto_request_raw::<
        futu_backend::proto_internal::bond_client_view::DaemonGetBondSingleAssetReq,
        futu_backend::proto_internal::bond_client_view::DaemonGetBondSingleAssetRsp,
    >(&state, proto_id::TRD_GET_BOND_SINGLE_ASSET, Some(body))
    .await
}

/// POST /api/bond-position-list — 账户债券持仓列表 (mobile cmd 9375)
///
/// 参数:
/// - acc_id (u64, 必填)
/// - trd_env (i32, 0=sim 1=real, default 1)
/// - market (string, 必填): "HK" / "US" / "SG"
///
/// 响应字段 (s2c.inner): total / bond_list[] (PositionBondItem: name /
/// symbol / market_value / quantity / price / cost / today_incomes /
/// today_incomes_rate / position_incomes / position_incomes_rate /
/// accrued_interest / make_for_call_flag / ccy).
pub async fn get_bond_position_list(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 / 40 F1+F2: Tier M normalize-first
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/bond-position-list")?;
    validate_header_trd_market(&body, "/api/bond-position-list")?;
    validate_header_trd_env_present(&body, "/api/bond-position-list")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/bond-position-list",
    )?;
    adapter::proto_request_raw::<
        futu_backend::proto_internal::bond_client_view::DaemonGetBondPositionListReq,
        futu_backend::proto_internal::bond_client_view::DaemonGetBondPositionListRsp,
    >(&state, proto_id::TRD_GET_BOND_POSITION_LIST, Some(body))
    .await
}

/// POST /api/bond-answer-state — 是否需要答题 (合规性, mobile cmd 10043)
///
/// 参数:
/// - acc_id (u64, 必填)
/// - trd_env (i32, 0=sim 1=real, default 1)
/// - market (string, 必填): "HK" / "US" / "SG"
/// - symbol (string, 必填): 债券 symbol (类似 11000018)
///
/// 响应字段 (s2c.inner): need_to_answer (bool) / notice (CltActionOpenURL
/// 提示弹窗: title / content / confirm_button_title / confirm_url 等).
pub async fn get_bond_answer_state(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 / 40 F1+F2: Tier M normalize-first
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/bond-answer-state")?;
    validate_header_trd_market(&body, "/api/bond-answer-state")?;
    validate_header_trd_env_present(&body, "/api/bond-answer-state")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/bond-answer-state",
    )?;
    adapter::proto_request_raw::<
        futu_backend::proto_internal::bond_client_view::DaemonGetBondAnswerStateReq,
        futu_backend::proto_internal::bond_client_view::DaemonGetBondAnswerStateRsp,
    >(&state, proto_id::TRD_GET_BOND_ANSWER_STATE, Some(body))
    .await
}

/// POST /api/bond-trade-reminder — 交易提醒 (mobile cmd 10057)
///
/// 参数:
/// - acc_id (u64, 必填)
/// - trd_env (i32, 0=sim 1=real, default 1)
/// - market (string, 必填): "HK" / "US" / "SG"
/// - symbol (string, 必填): 债券 symbol
///
/// 响应字段 (s2c.inner): tradeable / complex_product / high_risk /
/// sell_tradeable / pre_qualification (各 ReminderItem: value / title /
/// text / reminder_level / url_id).
pub async fn get_bond_trade_reminder(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    // v1.4.102 codex 37 F2 / 38 F3 / 40 F1+F2: Tier M normalize-first
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/bond-trade-reminder")?;
    validate_header_trd_market(&body, "/api/bond-trade-reminder")?;
    validate_header_trd_env_present(&body, "/api/bond-trade-reminder")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/bond-trade-reminder",
    )?;
    adapter::proto_request_raw::<
        futu_backend::proto_internal::bond_client_view::DaemonGetBondTradeReminderReq,
        futu_backend::proto_internal::bond_client_view::DaemonGetBondTradeReminderRsp,
    >(&state, proto_id::TRD_GET_BOND_TRADE_REMINDER, Some(body))
    .await
}