futu_rest/routes/trd/

write.rs

//! REST trade write routes.

use std::sync::Arc;

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

use futu_auth::{CheckCtx, KeyRecord};
use futu_core::proto_id;
use futu_proto::trd_modify_order;
use futu_proto::trd_place_combo_order;
use futu_proto::trd_place_order;
use futu_proto::trd_reconfirm_order;

use super::ApiResult;
use super::card_num::{
    extract_and_resolve_card_num_into_acc_id, normalize_and_resolve_card_num_for_route,
};
use super::validation::{
    read_handler_acc_id_check, rest_handler_limit_check, trd_market_str,
    validate_header_trd_env_present, validate_header_trd_market_write,
};
use crate::adapter::{self, RestState};

/// POST /api/order — 下单
///
/// v1.2：在 dispatch 之前先解析 JSON 提取 CheckCtx，跑 `check_full_skip_rate`
/// 做 market/symbol/value/side/daily 细粒度检查（auth 层已做 rate/hours 闸门）。
/// `Extension<Arc<KeyRecord>>` 来自 bearer_auth middleware；scope 模式下必有，
/// legacy 模式下没有该 extension → 跳过 handler 层检查（保持旧行为）。
pub async fn place_order(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    headers: HeaderMap,
    Json(mut body): Json<Value>,
) -> ApiResult {
    // v1.4.45: normalize camelCase → snake_case（兼容 FTAPI 官方文档字段名）
    crate::adapter::normalize_json_keys_snake_case(&mut body);
    // v1.4.105 D12 (Phase 2): 提取 card_num 字段 (top-level / c2s.header) →
    // resolve via trd_cache → 写进 c2s.header.acc_id. user 可用 4 位末尾或
    // 16 位完整卡号代替 acc_id (App 显示的便利)。**必须在 trd_market /
    // trd_env validate 之前**, 因为 promote_flat / acc_id 写入要在 validate
    // 之前完成 — 但实际上 placeholder header 字段在 validate 后, 我们这里
    // 把 card_num strip + acc_id 填回不会影响 trd_market validation 顺序.
    //
    // v1.4.105 contract-hardening 补丁: 传 rec 让 helper 同步做 string-level
    // allowed_card_nums whitelist 校验 (UX 清晰).
    let rec_ref_for_card_num = rec.as_ref().map(|Extension(r)| r.as_ref());
    extract_and_resolve_card_num_into_acc_id(
        &state,
        rec_ref_for_card_num,
        &mut body,
        "/api/order",
    )?;
    // v1.4.93 P0-4 (NEW-C-01): trd_market enum 白名单（在 normalize 后做，保证看到 snake_case）
    // v1.4.102 codex 26 F1 (P1): write 路径用更窄 allowlist (无 fund markets)
    validate_header_trd_market_write(&body, "/api/order")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/order")?;
    if let Some(Extension(rec)) = rec {
        // 解析 JSON → trd_place_order::Request 提取 CheckCtx
        match serde_json::from_value::<trd_place_order::Request>(body.clone()) {
            Ok(parsed) => rest_handler_limit_check(&state, &rec, &parsed)?,
            Err(_) => {
                // 反序列化失败时不挡，让下游 dispatch 报真正的 400/格式错误
                // （limits 不该挡格式问题）
            }
        }
    }
    // v1.4.38 Phase 4: 提取 `Idempotency-Key` header（客户端显式 opt-in）。
    // 无 header → 透传不加幂等保护（backward-compat）。
    let idem_key = headers
        .get("idempotency-key")
        .and_then(|v| v.to_str().ok())
        .map(|s| s.to_string());
    adapter::proto_request_with_idempotency::<trd_place_order::Request, trd_place_order::Response>(
        &state,
        proto_id::TRD_PLACE_ORDER,
        Some(body),
        idem_key,
    )
    .await
}

/// POST /api/combo-order — 组合期权下单
pub async fn place_combo_order(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    headers: HeaderMap,
    Json(mut body): Json<Value>,
) -> ApiResult {
    crate::adapter::normalize_json_keys_snake_case(&mut body);
    let rec_ref_for_card_num = rec.as_ref().map(|Extension(r)| r.as_ref());
    extract_and_resolve_card_num_into_acc_id(
        &state,
        rec_ref_for_card_num,
        &mut body,
        "/api/combo-order",
    )?;
    validate_header_trd_market_write(&body, "/api/combo-order")?;
    validate_header_trd_env_present(&body, "/api/combo-order")?;
    if let Some(Extension(rec)) = rec
        && let Ok(parsed) = serde_json::from_value::<trd_place_combo_order::Request>(body.clone())
    {
        let market = trd_market_str(parsed.c2s.header.trd_market);
        let symbol = parsed
            .c2s
            .combo_legs
            .first()
            .map(|leg| leg.security.code.as_str())
            .filter(|code| !market.is_empty() && !code.is_empty())
            .map(|code| format!("{market}.{code}"))
            .unwrap_or_default();
        let ctx = CheckCtx {
            market: market.to_string(),
            symbol,
            order_value: parsed.c2s.price.map(|price| price * parsed.c2s.qty),
            trd_side: None,
            acc_id: Some(parsed.c2s.header.acc_id),
            mutation_no_exposure: false,
            currency: futu_auth::market_to_currency(market).map(String::from),
        };
        let now = chrono::Utc::now();
        let outcome = state
            .counters
            .check_full_skip_rate(&rec.id, &rec.limits(), &ctx, now);
        if let Some(reason) = outcome.reason() {
            futu_auth::audit::reject(
                "rest",
                "/api/combo-order",
                &rec.id,
                &format!("limit: {reason}"),
            );
            let status = StatusCode::from_u16(outcome.http_status_code())
                .unwrap_or(StatusCode::TOO_MANY_REQUESTS);
            return Err((
                status,
                Json(serde_json::json!({
                    "error": format!("limit check failed: {reason}")
                })),
            ));
        }
    }
    let idem_key = headers
        .get("idempotency-key")
        .and_then(|v| v.to_str().ok())
        .map(|s| s.to_string());
    adapter::proto_request_with_idempotency::<
        trd_place_combo_order::Request,
        trd_place_combo_order::Response,
    >(
        &state,
        proto_id::TRD_PLACE_COMBO_ORDER,
        Some(body),
        idem_key,
    )
    .await
}

/// POST /api/modify-order — 改单/撤单
///
/// v1.2：和 `place_order` 类似但 ModifyOrder protobuf 给不出 symbol/qty/value
/// （只有 order_id），只能做 market 白名单 + hours 检查；symbol/value/side
/// 留空让 `check_full_skip_rate` 自动跳过。
///
/// **响应语义**（v1.4.111 P2-5 doc 沉淀,对齐 C++ APIServer_Trd_ModifyOrder by-design):
/// `ret_type=0` 仅表示 backend 接受了 modify 操作 (operation ACK), **不**保证 `/api/orders`
/// 立即可见新 price/qty/status. 客户端**不应**调完 modify-order 就立即 query `/api/orders`
/// 期望看到改动 — race window 通常 < 2s (backend push 异步同步 daemon orders cache).
///
/// **正确 client pattern** (ack-based):
/// 1. modify-order 返 `ret_type=0` → assume backend 接受
/// 2. wait push event (REST `/ws` 订阅 trade notify) 或 sleep 1-2s 后 retry query
/// 3. 若 2s+ 仍看不到更新 → v1.4.109 stub TTL guard fallback 会主动 refresh orders
///    (post_ack.rs:50-80, 默认 14.5s TTL 兜底)
///
/// **不修原因**: C++ OpenD 同条件也只返 operation ACK (modify_order.rs:809 注释),
/// Rust 同 C++ 行为 = by-design 对齐 (pitfall #51 "对齐 C++ = 减法, 不超越").
pub async fn modify_order(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    headers: HeaderMap,
    Json(mut body): Json<Value>,
) -> ApiResult {
    // v1.4.45: normalize camelCase → snake_case
    crate::adapter::normalize_json_keys_snake_case(&mut body);
    // v1.4.105 D12 (Phase 2): card_num → acc_id 解析 (与 place_order 一致).
    // v1.4.105 D12 contract-hardening 补丁: 同 place_order, 加 rec 做 string-level
    // allowed_card_nums whitelist 校验.
    let rec_ref_for_card_num = rec.as_ref().map(|Extension(r)| r.as_ref());
    extract_and_resolve_card_num_into_acc_id(
        &state,
        rec_ref_for_card_num,
        &mut body,
        "/api/modify-order",
    )?;
    // v1.4.96 BUG #003 hotfix (external reviewer double-tester report 2026-04-26):
    // 之前漏 validate, trd_market=999 silent accept. 加 validate 让 modify-order
    // 与 place-order 校验对齐.
    // v1.4.102 codex 26 F1 (P1): write 路径用更窄 allowlist (无 fund markets)
    validate_header_trd_market_write(&body, "/api/modify-order")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/modify-order")?;
    if let Some(Extension(rec)) = rec
        && let Ok(parsed) = serde_json::from_value::<trd_modify_order::Request>(body.clone())
    {
        let market = trd_market_str(parsed.c2s.header.trd_market);
        // v1.4.106 codex 0538 F2 (P2): ModifyOrder Normal (op=1) 改价/改量 →
        // 新 exposure delta, 算 qty*price 进 daily counter; Cancel/Disable/
        // Enable/Delete 标 mutation_no_exposure=true 跳 daily counter.
        const MODIFY_OP_NORMAL: i32 = 1;
        let (order_value, mutation_no_exposure) = if parsed.c2s.modify_order_op == MODIFY_OP_NORMAL
        {
            let v = match (parsed.c2s.qty, parsed.c2s.price) {
                (Some(q), Some(pr)) => Some(q * pr),
                _ => None, // MARKET 单 / proto 不全 → 跳金额检查
            };
            (v, false)
        } else {
            (None, true)
        };
        let ctx = CheckCtx {
            market: market.to_string(),
            symbol: String::new(),
            order_value,
            trd_side: None,
            acc_id: Some(parsed.c2s.header.acc_id), // v1.4.35
            mutation_no_exposure,
            // v1.4.106 F4 (P3): 派生 per-market currency
            currency: futu_auth::market_to_currency(market).map(String::from),
        };
        let now = chrono::Utc::now();
        // v1.4.36 Bug #1：Whitelist → 403
        let outcome = state
            .counters
            .check_full_skip_rate(&rec.id, &rec.limits(), &ctx, now);
        if let Some(reason) = outcome.reason() {
            futu_auth::audit::reject(
                "rest",
                "/api/modify-order",
                &rec.id,
                &format!("limit: {reason}"),
            );
            let status = StatusCode::from_u16(outcome.http_status_code())
                .unwrap_or(StatusCode::TOO_MANY_REQUESTS);
            return Err((
                status,
                Json(serde_json::json!({
                    "error": format!("limit check failed: {reason}")
                })),
            ));
        }
    }
    let idem_key = headers
        .get("idempotency-key")
        .and_then(|v| v.to_str().ok())
        .map(|s| s.to_string());
    adapter::proto_request_with_idempotency::<trd_modify_order::Request, trd_modify_order::Response>(
        &state,
        proto_id::TRD_MODIFY_ORDER,
        Some(body),
        idem_key,
    )
    .await
}

/// v1.4.40 #4 fix (external reviewer exhaustive report): 暴露 `/api/reconfirm-order` endpoint。
///
/// daemon 内部一直注册了 `TRD_RECONFIRM_ORDER` (proto_id 2237) 的 handler，但 REST
/// 层没路由过来，用户无法通过 REST 重新确认订单（比如美股下 day-trade 订单需要
/// 用户显式确认才会真正提交）。v1.4.40 补上此 endpoint。
///
/// POST /api/reconfirm-order — 重新确认订单（美股 PDT 规则下的二次确认路径）
pub async fn reconfirm_order(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> ApiResult {
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/reconfirm-order")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/reconfirm-order",
    )?;
    // v1.4.96 BUG #003 hotfix
    // v1.4.102 codex 26 F1 (P1): write 路径用更窄 allowlist (无 fund markets)
    validate_header_trd_market_write(&body, "/api/reconfirm-order")?;
    // v1.4.102 BUG-005: 缺 trd_env 直接 400 (避免 "Nonexisting acc_id" 误导)
    validate_header_trd_env_present(&body, "/api/reconfirm-order")?;
    adapter::proto_request::<trd_reconfirm_order::Request, trd_reconfirm_order::Response>(
        &state,
        proto_id::TRD_RECONFIRM_ORDER,
        Some(body),
    )
    .await
}