futu_backend/

main_link_contract.rs

// v1.4.106 codex F5: 期货主连合约真实合约解析 (CMD 6747).
//
// 对齐 C++ `APIServer_Trd_PlaceOrder.cpp:688-704` 的
// `INNBiz_Qot_SecList::ReqMainLinkContract(secInfo.nFutureOriginID)` —— 当
// PlaceOrder 收到主连合约 symbol (如 `HSImain` / `NQmain`) 时, 异步发 CMD 6747
// 拉真实月份合约的 stock_id, 用真实合约 code 替换 c2s.code 后下发 backend.
//
// **C++ 原始流程** (`NNBiz_Qot_SecList.cpp:216`):
// ```cpp
// ReqKey ReqMainLinkContract(u64_t nStockID) {
//     stock_list_sync_svr::StockQueryReq pbReq;
//     pbReq.add_stock_id(nStockID);
//     ReqKey nReqKey = SendTCPProto_ProtoBuf(NN_TCPProtoCategory_Quote,
//         NN_ProtoCmd_Qot_Pull_StaticInfo, pbReq);
//     m_setMainLinkReq.insert(nReqKey);
//     return nReqKey;
// }
// ```
//
// C++ 用 async event-driven 模型 (`OnOMEvent_Reply_PullMainContract`,
// `APIServer_Trd_PlaceOrder.cpp:785-820`): `p2=zhuli_id` 只用于失败判断,
// `p3=stock_id` 才传给 `GetAPIStock(p3)` 反查 code. Rust 改 sync `async/await`:
// caller 直接 `query_main_link_contract(broker, future_origin_id).await` 拿
// `stock_id` 后用 cache.id_to_key 反查 code.
//
// **proto 定义在 proto-internal/stock_list_sync.proto** (StockQueryReq +
// StockQueryRsp, 字段对齐 backend `stock_list_sync_svr` package).
//
// **CMD 6747 = NN_ProtoCmd_Qot_Pull_StaticInfo**, see C++
// `FutuOpenD/Src/NNBase/NNBase_Define_ProtoCmd.h:85`.
//
// **限制**: backend StockQueryReq 注释说"最多请求 50 只股票", 但 PlaceOrder
// 场景每次只查 1 个 future_origin_id, 远低于此限.

use crate::command_runtime::execute_qot_plaintext;
use crate::conn::BackendConn;
use crate::proto_internal::stock_list_sync_svr;
use bytes::Bytes;
use futu_core::error::{FutuError, Result};
use futu_domain_static_data::ensure_static_info_query_backend_success;
use prost::Message;
use std::sync::Arc;

/// CMD 6747: NN_ProtoCmd_Qot_Pull_StaticInfo
///
/// 拉一组 stock_id 的最新静态信息 (CSStockItem), 用于期货主连合约 ReqMainLinkContract
/// 路径返当前主力合约真实 stock_id + code.
pub use futu_command_spec::CMD_QOT_PULL_STATIC_INFO;

/// v1.4.106 codex F5: 期货主连合约 → 真实月份合约 stock_id 解析结果.
#[derive(Debug, Clone)]
pub struct MainLinkContractInfo {
    /// 真实月份合约 stock_id (C++ OMEvent `p3 = stock_id`).
    ///
    /// 主连 symbol (HSImain) 的 origin_id 是当前主力月份合约 stock_id.
    pub real_stock_id: u64,
    /// 真实月份合约 code (e.g. "HSI2604" / "NQ2606"), 从响应中 C++ 会作为
    /// `p3` 的那一项 `code` 字段读. 如果 backend 未带 code, 则为空 string ——
    /// caller 需要从本地 stock_list cache `id_to_key` 反查.
    pub real_code: String,
}

/// v1.4.106 codex F5: 发 CMD 6747 拉指定 future_origin_id 的主力合约真实信息.
///
/// **入参**: `origin_stock_id` 是主连合约 row 的 origin_id 字段
/// (`Ndt_Qot_SecInfo::nFutureOriginID`), 必须 > 0. 0 表示不是主连合约 — caller
/// 应该在调本 fn 前用 `info.future_origin_id != 0` 提前过滤.
///
/// **响应解析** (`StockQueryRsp.arry_items`):
/// 1. 找 stock_id == 入参 origin_stock_id 的 row。
/// 2. 读该 row 的 `zhuli_id`; C++ `OnReply_MainLinkContract` 把它放进
///    OMEvent `p2` 并只用作失败判断 (`p2 == 0` => UnknownStock)。
/// 3. 如果 zhuli_id == 0, 表示 backend 没识别该 stock_id 是主力链路, 返
///    `Err(FutuError::Codec("..."))` —— caller 应该 fallback 用原 symbol 下单
///    (loud failure, 不 silent).
/// 4. C++ 随后把同一 row 的 `stock_id` 放进 OMEvent `p3`, 并在
///    `APIServer_Trd_PlaceOrder.cpp:815-817` 用 `GetAPIStock(p3)` 反查 code。
///    因此 Rust 的 `real_stock_id` 必须取 row.stock_id, 不是 zhuli_id。
///
/// **超时**: 走 `BackendConn::request` 默认 10s timeout. 如果 backend 慢或
/// 不响应, PlaceOrder 整个流程会挂 10s 然后失败 —— 这是**故意选择**: 与 C++
/// 行为一致 (C++ 用 OMEvent push 模型, request 在 backend 反正会响应; Rust
/// sync await 简化但保留同样语义).
///
/// **错误**: 任何 backend 错误 / decode 失败 / future_origin_id 不是主力链路 →
/// `Err(...)`.
/// caller (PlaceOrder handler) 必须 propagate 让用户看到 loud error, 不 silent
/// 用原 symbol (违反主连合约判定就是 silent-success 反模式, CLAUDE.md 坑 #45).
pub async fn query_main_link_contract(
    backend: Arc<BackendConn>,
    origin_stock_id: u64,
) -> Result<MainLinkContractInfo> {
    if origin_stock_id == 0 {
        return Err(FutuError::Codec(
            "query_main_link_contract: origin_stock_id 必须 > 0 (主连合约 row \
             的 origin_id 必非 0)"
                .to_string(),
        ));
    }

    let req = stock_list_sync_svr::StockQueryReq {
        stock_id: vec![origin_stock_id],
    };
    let resp = execute_qot_plaintext(
        backend.as_ref(),
        CMD_QOT_PULL_STATIC_INFO,
        Bytes::from(req.encode_to_vec()),
        [0; 10],
    )
    .await?;

    let parsed: stock_list_sync_svr::StockQueryRsp =
        Message::decode(resp.body.as_ref()).map_err(|e| {
            FutuError::Codec(format!(
                "CMD 6747 (Qot_Pull_StaticInfo) StockQueryRsp decode 失败: {e}"
            ))
        })?;

    if let Err(err) = ensure_static_info_query_backend_success(parsed.result) {
        return Err(FutuError::Codec(format!(
            "CMD 6747 backend error result={} for origin_stock_id={}",
            match err {
                futu_domain_static_data::StaticInfoQueryBackendError::Result(result) => result,
            },
            origin_stock_id
        )));
    }

    // 找 queried row (stock_id == 入参). C++ `ReqMainLinkContract` 一次也只问
    // 这个 stock_id; `OnReply_MainLinkContract` 从 arry_items(0) 同时取
    // zhuli_id 和 stock_id.
    let origin_row = match parsed
        .arry_items
        .iter()
        .find(|item| item.stock_id == origin_stock_id)
    {
        Some(item) => item,
        None => {
            // backend 响应里没有这个 stock_id row — 不应发生 (我们只问了一个),
            // 但 backend 行为不能完全控制, 防御性处理
            return Err(FutuError::Codec(format!(
                "CMD 6747 响应未包含 origin_stock_id={} 对应 row \
                 (arry_items.len={})",
                origin_stock_id,
                parsed.arry_items.len()
            )));
        }
    };
    let zhuli_id = origin_row.zhuli_id.unwrap_or(0);

    if zhuli_id == 0 {
        return Err(FutuError::Codec(format!(
            "CMD 6747 origin_stock_id={} 对应 zhuli_id=0 \
             (backend 未识别为主连合约 / 该期货品种当前无主力月份)",
            origin_stock_id
        )));
    }

    // C++ OMEvent: p2 = zhuli_id (failure gate), p3 = stock_id (used by
    // APIServer_Trd_PlaceOrder.cpp:815 `GetAPIStock(p3)`). Keep that split.
    let real_stock_id = origin_row.stock_id;
    let real_code = origin_row.code.clone();

    Ok(MainLinkContractInfo {
        real_stock_id,
        real_code,
    })
}

#[cfg(test)]
mod tests;