futu_trd/

order.rs

use std::sync::atomic::{AtomicU32, Ordering};

use futu_core::error::{FutuError, Result};
use futu_core::proto_id;
use futu_net::client::FutuClient;

use crate::types::{ModifyOrderOp, OrderType};
use crate::types::{
    ModifyOrderParams, PlaceOrderOptions, PlaceOrderParams, PlaceOrderResult,
    PlaceOrderResultWithIdentity,
};

/// 全局唯一的 packet ID 生成器（防重放攻击）
static PACKET_SERIAL: AtomicU32 = AtomicU32::new(1);

fn client_conn_id(client: &FutuClient) -> Result<u64> {
    client.conn_id().ok_or(FutuError::NotInitialized)
}

fn next_packet_id(conn_id: u64) -> futu_proto::common::PacketId {
    let serial = PACKET_SERIAL.fetch_add(1, Ordering::Relaxed);
    futu_proto::common::PacketId {
        // Echo InitConnect S2C connID like C++ FTAPI clients. The gateway
        // replay guard checks this against the actual TCP connection id.
        conn_id,
        serial_no: serial,
    }
}

/// v1.4.39 (external reviewer exhaustive report 修): 把幂等键映射到 `Common.PacketID`，让 daemon 端
/// 的 packet_id fallback（`idempotency.rs` 90s TTL cache）能识别"同一键 = 同一请求"。
///
/// **设计**：conn_id = u64 hash(key)，serial_no = 0 固定。daemon 端把 packet_id
/// 格式化为 `"tcp-pkt-{conn_id}-{serial_no}"`，所以不同 key → 不同 conn_id → 不同
/// cache entry；相同 key → 相同 conn_id → 命中 cache。
fn packet_id_for_idempotency_key(key: &str) -> futu_proto::common::PacketId {
    use std::collections::hash_map::DefaultHasher;
    use std::hash::{Hash, Hasher};
    let mut hasher = DefaultHasher::new();
    key.hash(&mut hasher);
    futu_proto::common::PacketId {
        conn_id: hasher.finish(),
        serial_no: 0,
    }
}

/// 下单
///
/// 向 FutuOpenD 发送下单请求。
/// 注意：需要先解锁交易 (`unlock_trade`)。
/// v1.4.48 #8 修（external reviewer 验收报告 §9 Test 2）：客户端侧（futucli → daemon / futucli → C++ OpenD）
/// 的 `Trd_PlaceOrder.C2S.sec_market` 之前硬编码 `None`，external reviewer wire-level A/B 抓包
/// 证伪"proto 里有就自动填"—— C++ OpenD 直接拒 `missing Transaction Securities
/// Market`。
///
/// 此 helper 复用 daemon 端同一个 canonical `futu_core::trade_security`
/// 派生规则。对齐 `Trd_Common.TrdSecMarket` enum：HK=1 / US=2 /
/// CN_SH=31 / CN_SZ=32 / SG=41 / JP=51 / AU=61 / MY=71 / CA=81 /
/// CC=101。
///
/// 规则：
/// 1. 显式 code prefix / 期货 ticker 先于 SDK market metadata；
/// 2. 再按 trd_market 推导（7=Crypto → 101）；
/// 3. 无法推导时返回 0 (Unknown)。
fn derive_sec_market_client(trd_market: i32, code: &str) -> i32 {
    futu_core::trade_security::derive_trd_sec_market_like_cpp(
        futu_core::trade_security::TrdSecMarketInput {
            ftapi_sec_market: 0,
            trd_market,
            code,
        },
    )
}

fn parse_place_order_response_body(body: &[u8]) -> Result<PlaceOrderResultWithIdentity> {
    let resp: futu_proto::trd_place_order::Response =
        prost::Message::decode(body).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 PlaceOrder".into()))?;

    let order_id = s2c.order_id.ok_or_else(|| {
        // Ref: APIServer_Trd_PlaceOrder.cpp:856-864 sets orderID before success.
        FutuError::Codec("missing orderID in successful PlaceOrder response".into())
    })?;
    let order_id_ex = s2c
        .order_id_ex
        .filter(|value| !value.is_empty())
        .ok_or_else(|| {
            // Ref: APIServer_Trd_PlaceOrder.cpp:1034-1053 sets both orderID
            // and orderIDEx for every successful response.
            FutuError::Codec("missing orderIDEx in successful PlaceOrder response".into())
        })?;

    Ok(PlaceOrderResultWithIdentity {
        order_id,
        order_id_ex,
    })
}

fn request_validation_error(msg: impl Into<String>) -> FutuError {
    FutuError::ServerError {
        ret_type: -1,
        msg: msg.into(),
    }
}

fn ensure_positive_finite(value: f64, field: &'static str) -> Result<()> {
    if value.is_finite() && value > 0.0 {
        Ok(())
    } else {
        Err(request_validation_error(format!(
            "{field} must be finite and > 0 (C++ APIServer trade request validation)"
        )))
    }
}

fn order_type_requires_price(order_type: OrderType) -> bool {
    matches!(
        order_type,
        OrderType::Normal
            | OrderType::AbsoluteLimit
            | OrderType::AuctionLimit
            | OrderType::SpecialLimit
            | OrderType::SpecialLimitAll
            | OrderType::StopLimit
            | OrderType::LimitifTouched
            | OrderType::TrailingStopLimit
            | OrderType::TwapLimit
            | OrderType::VwapLimit
    )
}

fn validate_optional_positive_price(price: Option<f64>, field: &'static str) -> Result<()> {
    if let Some(price) = price {
        ensure_positive_finite(price, field)?;
    }
    Ok(())
}

fn validate_place_order_params(params: &PlaceOrderParams) -> Result<()> {
    // Ref: APIServer_Trd_PlaceOrder.cpp:226/244/251/258 and
    // _APIServer_Trd_Comm.cpp:1121-1163. C++ rejects non-positive qty before
    // building backend OrderNewReq; do the same at SDK layer so all surfaces
    // (REST/MCP/CLI/gRPC/raw TCP) share one fail-closed boundary.
    ensure_positive_finite(params.qty, "place_order.qty")?;

    if params.order_type == OrderType::Moc {
        if params.price.is_some() || params.aux_price.is_some() {
            return Err(request_validation_error(
                "place_order MOC does not accept price or aux_price",
            ));
        }
        if params
            .idempotency_key
            .as_deref()
            .map(str::trim)
            .filter(|key| !key.is_empty())
            .is_none()
        {
            return Err(request_validation_error(
                "place_order MOC requires a non-empty idempotency_key",
            ));
        }
    }

    if order_type_requires_price(params.order_type) {
        let price = params.price.ok_or_else(|| {
            request_validation_error("place_order.price is required for price-based order types")
        })?;
        ensure_positive_finite(price, "place_order.price")?;
    } else {
        validate_optional_positive_price(params.price, "place_order.price")?;
    }

    validate_optional_positive_price(params.aux_price, "place_order.aux_price")?;
    Ok(())
}

fn validate_modify_order_params(params: &ModifyOrderParams) -> Result<()> {
    if params.modify_order_op == ModifyOrderOp::Normal {
        let qty = params.qty.ok_or_else(|| {
            request_validation_error("modify_order.qty is required for normal modify")
        })?;
        ensure_positive_finite(qty, "modify_order.qty")?;
        validate_optional_positive_price(params.price, "modify_order.price")?;
    }
    Ok(())
}

fn build_place_order_request(
    packet_id: futu_proto::common::PacketId,
    params: &PlaceOrderParams,
    options: &PlaceOrderOptions,
) -> futu_proto::trd_place_order::Request {
    futu_proto::trd_place_order::Request {
        c2s: futu_proto::trd_place_order::C2s {
            packet_id,
            header: params.header.to_proto(),
            trd_side: params.trd_side as i32,
            order_type: params.order_type as i32,
            code: params.code.clone(),
            qty: params.qty,
            price: params.price,
            adjust_price: params.adjust_price,
            adjust_side_and_limit: params.adjust_side_and_limit,
            sec_market: Some(derive_sec_market_client(
                params.header.trd_market as i32,
                &params.code,
            )),
            remark: None,
            time_in_force: options.time_in_force,
            fill_outside_rth: options.fill_outside_rth,
            // v1.4.53 F1 条件单：透传 aux_price / trail_* 到 FTAPI
            aux_price: params.aux_price,
            trail_type: params.trail_type,
            trail_value: params.trail_value,
            trail_spread: params.trail_spread,
            session: options.session,
            position_id: None,
            expire_time: options.expire_time.clone(),
            amount: options.amount,
            pred_side: options.pred_side,
            extension_version: (params.order_type == OrderType::Moc).then_some(1),
        },
    }
}

pub async fn place_order(
    client: &FutuClient,
    params: &PlaceOrderParams,
) -> Result<PlaceOrderResult> {
    place_order_with_options(client, params, &PlaceOrderOptions::default()).await
}

/// 下单并返回 numeric `orderID` 与无损 `orderIDEx`。
///
/// 参照版本在成功响应中同时返回二者。新调用者需要把订单身份跨 JSON、脚本或
/// modify/cancel 流程传递时应使用本函数；既有 [`place_order`] 保持原返回类型。
pub async fn place_order_with_identity(
    client: &FutuClient,
    params: &PlaceOrderParams,
) -> Result<PlaceOrderResultWithIdentity> {
    place_order_with_options_and_identity(client, params, &PlaceOrderOptions::default()).await
}

/// 下单（带官方 FTAPI optional 字段）。
///
/// `PlaceOrderOptions` 只透传 `Trd_PlaceOrder.C2S` 已定义字段，不改变 gateway
/// 的 C++ 对齐校验。普通用户继续用 [`place_order`]；需要美股盘前/盘后、GTD
/// 等语义时调用本函数。
pub async fn place_order_with_options(
    client: &FutuClient,
    params: &PlaceOrderParams,
    options: &PlaceOrderOptions,
) -> Result<PlaceOrderResult> {
    let result = place_order_with_options_and_identity(client, params, options).await?;
    Ok(PlaceOrderResult {
        order_id: result.order_id,
    })
}

/// 下单（带官方 FTAPI optional 字段）并返回 numeric/string 双订单身份。
pub async fn place_order_with_options_and_identity(
    client: &FutuClient,
    params: &PlaceOrderParams,
    options: &PlaceOrderOptions,
) -> Result<PlaceOrderResultWithIdentity> {
    // v1.4.102 codex 28 F3 (P1) fix: SDK 层也拒 fund market 写入.
    //
    // **历史**: REST/MCP/CLI wrapper 都加了 fund market reject (codex 26 F1
    // / 27 F7), 但直接 Rust SDK / gRPC / direct proto caller 仍可构造
    // `header.trd_market = 113/123/124/125/126` 调用本 fn. `derive_sec_market_client`
    // 把 fund market 归到主市场后, backend 看到 normal write 不会拒 → 用户
    // 用 fund 账户号下单 → silent 误路由风险.
    //
    // **修法**: SDK fn 入口拒 canonical fund markets, 让所有 caller (REST/MCP/CLI/gRPC/
    // direct SDK) 共享同一 runtime contract.
    let trd_market = params.header.trd_market;
    if let Some(label) = crate::market::canonical_fund_trd_market_label(trd_market) {
        return Err(FutuError::ServerError {
            ret_type: -1,
            msg: format!(
                "place_order: trd_market {label} 仅支持 view-only read endpoints; \
                 write 路径 (place_order) 用对应主市场. v1.4.102 audit 28 F3 fix."
            ),
        });
    }
    validate_place_order_params(params)?;

    let packet_id = params
        .idempotency_key
        .as_deref()
        .map(packet_id_for_idempotency_key)
        .map(Ok)
        .unwrap_or_else(|| client_conn_id(client).map(next_packet_id))?;
    let req = build_place_order_request(packet_id, params, options);

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

    parse_place_order_response_body(resp_frame.body.as_ref())
}

/// 修改/撤销订单
pub async fn modify_order(client: &FutuClient, params: &ModifyOrderParams) -> Result<u64> {
    // v1.4.102 codex 28 F3 (P1) fix: SDK 层 modify_order 也拒 fund market.
    let trd_market = params.header.trd_market;
    if let Some(label) = crate::market::canonical_fund_trd_market_label(trd_market) {
        return Err(FutuError::ServerError {
            ret_type: -1,
            msg: format!(
                "modify_order: trd_market {label} 仅支持 view-only read endpoints; \
                 write 路径用对应主市场. v1.4.102 audit 28 F3 fix."
            ),
        });
    }
    validate_modify_order_params(params)?;

    let packet_id = params
        .idempotency_key
        .as_deref()
        .map(packet_id_for_idempotency_key)
        .map(Ok)
        .unwrap_or_else(|| client_conn_id(client).map(next_packet_id))?;
    let req = futu_proto::trd_modify_order::Request {
        c2s: futu_proto::trd_modify_order::C2s {
            packet_id,
            header: params.header.to_proto(),
            order_id: params.order_id,
            modify_order_op: params.modify_order_op as i32,
            for_all: params.for_all,
            trd_market: None,
            qty: params.qty,
            price: params.price,
            adjust_price: None,
            adjust_side_and_limit: None,
            aux_price: None,
            trail_type: None,
            trail_value: None,
            trail_spread: None,
            order_id_ex: params.order_id_ex.clone(),
        },
    };

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

    let resp: futu_proto::trd_modify_order::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 ModifyOrder".into()))?;

    Ok(s2c.order_id)
}

/// 撤单（modify_order 的便捷封装）
pub async fn cancel_order(
    client: &FutuClient,
    header: &crate::types::TrdHeader,
    order_id: u64,
) -> Result<u64> {
    modify_order(
        client,
        &ModifyOrderParams {
            header: header.clone(),
            order_id,
            order_id_ex: None,
            modify_order_op: crate::types::ModifyOrderOp::Cancel,
            qty: None,
            price: None,
            for_all: None,
            idempotency_key: None,
        },
    )
    .await
}

#[cfg(test)]
mod order_response_contract_tests;