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};

/// 全局唯一的 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 端 `derive_sec_market` 的客户端镜像（同逻辑，避免跨 crate
/// 依赖）。对齐 `Trd_Common.TrdSecMarket` enum：HK=1 / US=2 / CN_SH=31 / CN_SZ=32
/// / SG=41 / JP=51 / AU=61 / MY=71 / CA=81。
///
/// 规则：
/// 1. 按 trd_market 推（1/4=HK → 1; 2=US → 2; 3=CN 按 code 前缀分 SH/SZ; 6=SG → 41; ...）
/// 2. 无法推 → 0（Unknown，backend 可能拒 —— 至少比 None 好，有 diagnostic）
fn derive_sec_market_client(trd_market: i32, code: &str) -> i32 {
    match trd_market {
        1 | 4 | 113 => 1,  // HK / HKCC / HK_Fund → HK
        2 | 11 | 123 => 2, // US / Futures_US / US_Fund → US
        3 => {
            // CN: 按 code 前缀判 SH/SZ
            let bare = code
                .trim_start_matches("SH.")
                .trim_start_matches("SZ.")
                .trim_start_matches("CN.");
            match bare.chars().next() {
                Some('6') | Some('9') => 31,             // SH
                Some('0') | Some('2') | Some('3') => 32, // SZ
                _ => 31,                                 // default SH
            }
        }
        6 | 12 | 124 => 41, // SG / Futures_SG / SG_Fund
        8 => 61,            // AU
        // 注：trd_market=11 已在上面 `2 | 11 | 123 => 2` 分支（US）里 catch
        // （v1.4.47 P0.3 修：sim 账户 trd_market=11 按 US stock 处理）
        15 => 51,  // JP
        111 => 71, // MY
        112 => 81, // CA
        _ => 0,    // Unknown
    }
}

fn parse_place_order_response_body(body: &[u8]) -> Result<PlaceOrderResult> {
    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(|| {
        FutuError::Codec(
            "missing orderID in successful PlaceOrder response; C++ \
             APIServer_Trd_PlaceOrder.cpp:856-864 sets orderID before \
             returning success"
                .into(),
        )
    })?;

    Ok(PlaceOrderResult { order_id })
}

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 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 \
                 (C++ APIServer_Trd_PlaceOrder.cpp:323-344)",
            )
        })?;
        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 \
                 (C++ APIServer_Trd_ModifyOrder.cpp:27-37)",
            )
        })?;
        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(),
        },
    }
}

pub async fn place_order(
    client: &FutuClient,
    params: &PlaceOrderParams,
) -> Result<PlaceOrderResult> {
    place_order_with_options(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> {
    // 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 tests_v1_4_67_bug_3;