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_core::trade_currency::{funds_currency_mismatch_warning, parse_currency_label};
use futu_core::trade_security::{
    TrdSecMarketInput, derive_trd_sec_market_like_cpp, strip_market_prefix,
};
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 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) = 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 = parse_currency_label(label)?;
        *value = Value::Number(serde_json::Number::from(parsed));
    }
    Ok(())
}

fn normalize_max_trd_qtys_for_rest(body: &mut Value) -> Result<(), String> {
    let nested = matches!(body.get("c2s"), Some(Value::Object(_)));
    let c2s = if nested {
        body.get_mut("c2s")
            .and_then(Value::as_object_mut)
            .ok_or_else(|| "max-trd-qtys c2s must be a JSON object".to_string())?
    } else {
        body.as_object_mut()
            .ok_or_else(|| "max-trd-qtys request body must be a JSON object".to_string())?
    };

    let code = c2s
        .get("code")
        .and_then(Value::as_str)
        .ok_or_else(|| "max-trd-qtys code is required to derive sec_market".to_string())?
        .to_string();
    let has_explicit_sec_market = c2s.get("sec_market").is_some_and(|value| !value.is_null());
    let trd_market = if nested {
        c2s.get("header")
            .and_then(Value::as_object)
            .and_then(|header| header.get("trd_market"))
            .and_then(Value::as_i64)
    } else {
        c2s.get("trd_market").and_then(Value::as_i64)
    }
    .and_then(|value| i32::try_from(value).ok())
    .unwrap_or(0);

    if !has_explicit_sec_market {
        let sec_market = derive_trd_sec_market_like_cpp(TrdSecMarketInput {
            ftapi_sec_market: 0,
            trd_market,
            code: &code,
        });
        if sec_market == 0 {
            return Err(format!(
                "max-trd-qtys cannot derive sec_market from trd_market={trd_market} and code"
            ));
        }
        c2s.insert(
            "sec_market".to_string(),
            Value::Number(serde_json::Number::from(sec_market)),
        );
    }

    let bare_code = strip_market_prefix(&code);
    if bare_code != code {
        c2s.insert("code".to_string(), Value::String(bare_code));
    }
    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",
    )?;
    normalize_max_trd_qtys_for_rest(&mut body).map_err(|error| {
        (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "ret_type": -1,
                "ret_msg": error,
                "error": error,
            })),
        )
    })?;
    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(trade_read_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(trade_read_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 trade_read_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")?;
    adapter::normalize_endpoint_local_request_aliases_for_rest_path("/api/margin-ratio", &mut body)
        .map_err(trade_read_alias_error)?;
    // 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
}