futu_rest/routes/trd/

read.rs

//! REST trade/account read routes.

use std::sync::Arc;

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

use futu_auth::KeyRecord;
use futu_core::proto_id;
use futu_proto::trd_get_combo_max_trd_qtys;
use futu_proto::trd_get_funds;
use futu_proto::trd_get_history_order_fill_list;
use futu_proto::trd_get_history_order_list;
use futu_proto::trd_get_margin_ratio;
use futu_proto::trd_get_max_trd_qtys;
use futu_proto::trd_get_order_fee;
use futu_proto::trd_get_order_fill_list;
use futu_proto::trd_get_order_list;
use futu_proto::trd_get_position_list;
use futu_trd::{currency, read_plan};

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,
    validate_header_trd_market_write,
};
use super::{ApiResult, RawApiResult};
use crate::adapter::{self, RestState};

/// POST /api/funds — 获取资金
pub async fn get_funds(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> ApiResult {
    // normalize + card_num -> acc_id 必须在 validate / allowed_acc_ids 之前完成。
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/funds")?;
    // v1.4.93 P0-4 (NEW-C-01): trd_market enum 白名单（防 silent misroute）
    validate_header_trd_market(&body, "/api/funds")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/funds")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/funds",
    )?;
    normalize_trd_currency_labels(&mut body).map_err(|e| {
        (
            axum::http::StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "ret_type": -1,
                "ret_msg": e,
                "error": e,
            })),
        )
    })?;

    // 记录 user 显式请求 currency, 用于 response post-process: 若 backend
    // 返回了不同币种, 对 REST caller 明确暴露短 warning。
    let requested_currency: Option<i32> = body
        .pointer("/c2s/currency")
        .or_else(|| body.pointer("/currency"))
        .and_then(|v| v.as_i64())
        .map(|v| v as i32);

    let mut resp = adapter::proto_request::<trd_get_funds::Request, trd_get_funds::Response>(
        &state,
        proto_id::TRD_GET_FUNDS,
        Some(body),
    )
    .await?;

    let response_currency = resp
        .0
        .pointer("/s2c/funds/currency")
        .and_then(|v| v.as_i64())
        .map(|v| v as i32);
    if let Some(warn_msg) =
        read_plan::funds_currency_mismatch_warning(requested_currency, response_currency)
        && let Some(obj) = resp.0.as_object_mut()
    {
        obj.insert(
            "currency_warning".to_string(),
            serde_json::Value::String(warn_msg.clone()),
        );
        // 也在 ret_msg 追加 hint (若已有 ret_msg 则前置 warning)
        let existing_msg = obj
            .get("ret_msg")
            .and_then(|v| v.as_str())
            .unwrap_or("")
            .to_string();
        let new_msg = if existing_msg.is_empty() {
            format!("⚠️  {warn_msg}")
        } else {
            format!("⚠️  {warn_msg}\n[既有] {existing_msg}")
        };
        obj.insert("ret_msg".to_string(), serde_json::Value::String(new_msg));
    }

    Ok(resp)
}

fn normalize_trd_currency_labels(body: &mut Value) -> Result<(), String> {
    for pointer in ["/c2s/currency", "/currency"] {
        let Some(value) = body.pointer_mut(pointer) else {
            continue;
        };
        let Value::String(label) = value else {
            continue;
        };
        let parsed = currency::parse_currency_label(label).map_err(|err| err.to_string())?;
        *value = Value::Number(serde_json::Number::from(parsed));
    }
    Ok(())
}

#[cfg(test)]
mod tests;

/// POST /api/positions — 获取持仓
pub async fn get_positions(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/positions")?;
    // v1.4.93 P0-4 (NEW-C-01): trd_market enum 白名单
    validate_header_trd_market(&body, "/api/positions")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/positions")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/positions",
    )?;
    normalize_trd_currency_labels(&mut body).map_err(|e| {
        (
            axum::http::StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "ret_type": -1,
                "ret_msg": e,
                "error": e,
            })),
        )
    })?;
    adapter::proto_request_raw::<trd_get_position_list::Request, trd_get_position_list::Response>(
        &state,
        proto_id::TRD_GET_POSITION_LIST,
        Some(body),
    )
    .await
}

/// POST /api/orders — 获取订单列表
pub async fn get_orders(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/orders")?;
    // v1.4.93 P0-4 (NEW-C-01): trd_market enum 白名单
    // v1.4.102 codex 32 F6 (P2): active order reads 用 write allowlist (无 fund markets, 未 verified)
    validate_header_trd_market_write(&body, "/api/orders")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/orders")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/orders",
    )?;
    adapter::proto_request_raw::<trd_get_order_list::Request, trd_get_order_list::Response>(
        &state,
        proto_id::TRD_GET_ORDER_LIST,
        Some(body),
    )
    .await
}

/// POST /api/order-fills — 获取成交列表
pub async fn get_order_fills(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/order-fills")?;
    // v1.4.93 P0-4 (NEW-C-01): trd_market enum 白名单
    // v1.4.102 codex 32 F6 (P2): active order reads 用 write allowlist (无 fund markets, 未 verified)
    validate_header_trd_market_write(&body, "/api/order-fills")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/order-fills")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/order-fills",
    )?;
    adapter::proto_request_raw::<
        trd_get_order_fill_list::Request,
        trd_get_order_fill_list::Response,
    >(
        &state,
        proto_id::TRD_GET_ORDER_FILL_LIST,
        Some(body),
    )
    .await
}

/// POST /api/max-trd-qtys — 获取最大交易数量
pub async fn get_max_trd_qtys(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/max-trd-qtys")?;
    // v1.4.93 P0-4 (NEW-C-01): trd_market enum 白名单
    // v1.4.102 codex 29 F3 / 31 F5 (P2): trade-calculation endpoint 用 write allowlist (无 fund markets)
    validate_header_trd_market_write(&body, "/api/max-trd-qtys")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/max-trd-qtys")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/max-trd-qtys",
    )?;
    adapter::proto_request_raw::<trd_get_max_trd_qtys::Request, trd_get_max_trd_qtys::Response>(
        &state,
        proto_id::TRD_GET_MAX_TRD_QTYS,
        Some(body),
    )
    .await
}

/// POST /api/combo-max-trd-qtys — 获取组合订单最大交易数量
pub async fn get_combo_max_trd_qtys(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/combo-max-trd-qtys")?;
    validate_header_trd_market_write(&body, "/api/combo-max-trd-qtys")?;
    validate_header_trd_env_present(&body, "/api/combo-max-trd-qtys")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/combo-max-trd-qtys",
    )?;
    adapter::proto_request_raw::<
        trd_get_combo_max_trd_qtys::Request,
        trd_get_combo_max_trd_qtys::Response,
    >(&state, proto_id::TRD_GET_COMBO_MAX_TRD_QTYS, Some(body))
    .await
}

/// POST /api/history-orders — 获取历史订单
pub async fn get_history_orders(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    adapter::normalize_json_keys_snake_case(&mut body);
    adapter::normalize_endpoint_local_request_aliases_for_rest_path(
        "/api/history-orders",
        &mut body,
    )
    .map_err(history_order_alias_error)?;
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/history-orders")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/history-orders",
    )?;
    // v1.4.96 BUG #003 hotfix (external reviewer matrix-double-confirmed): trd_market=999
    // 之前 silent accept 200 OK, broker routing 风险.
    validate_header_trd_market(&body, "/api/history-orders")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/history-orders")?;
    adapter::proto_request_raw::<
        trd_get_history_order_list::Request,
        trd_get_history_order_list::Response,
    >(&state, proto_id::TRD_GET_HISTORY_ORDER_LIST, Some(body))
    .await
}

/// POST /api/history-order-fills — 获取历史成交
pub async fn get_history_order_fills(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    adapter::normalize_json_keys_snake_case(&mut body);
    adapter::normalize_endpoint_local_request_aliases_for_rest_path(
        "/api/history-order-fills",
        &mut body,
    )
    .map_err(history_order_alias_error)?;
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/history-order-fills")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/history-order-fills",
    )?;
    // v1.4.96 BUG #003 hotfix (external reviewer matrix-double-confirmed)
    validate_header_trd_market(&body, "/api/history-order-fills")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/history-order-fills")?;
    adapter::proto_request_raw::<
        trd_get_history_order_fill_list::Request,
        trd_get_history_order_fill_list::Response,
    >(
        &state,
        proto_id::TRD_GET_HISTORY_ORDER_FILL_LIST,
        Some(body),
    )
    .await
}

fn history_order_alias_error(message: String) -> (StatusCode, Json<Value>) {
    (
        StatusCode::BAD_REQUEST,
        Json(serde_json::json!({
            "ret_type": -1,
            "ret_msg": message,
            "error": message,
        })),
    )
}

/// POST /api/margin-ratio — 获取融资融券比率
pub async fn get_margin_ratio(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/margin-ratio")?;
    // v1.4.93 P0-4 (NEW-C-01): trd_market enum 白名单
    // v1.4.102 codex 29 F3 / 31 F5 (P2): trade-calculation endpoint 用 write allowlist (无 fund markets)
    validate_header_trd_market_write(&body, "/api/margin-ratio")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/margin-ratio")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/margin-ratio",
    )?;
    adapter::proto_request_raw::<trd_get_margin_ratio::Request, trd_get_margin_ratio::Response>(
        &state,
        proto_id::TRD_GET_MARGIN_RATIO,
        Some(body),
    )
    .await
}

/// POST /api/order-fee — 获取订单费用
pub async fn get_order_fee(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/order-fee")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/order-fee",
    )?;
    // v1.4.96 BUG #003 hotfix (external reviewer matrix-double-confirmed)
    // v1.4.102 codex 29 F3 / 31 F5 (P2): trade-calculation endpoint 用 write allowlist (无 fund markets)
    validate_header_trd_market_write(&body, "/api/order-fee")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/order-fee")?;
    adapter::proto_request_raw::<trd_get_order_fee::Request, trd_get_order_fee::Response>(
        &state,
        proto_id::TRD_GET_ORDER_FEE,
        Some(body),
    )
    .await
}