futu_mcp/tools/

trade_write.rs

//! MCP trade-write tools (place/modify/cancel/reconfirm).

use futu_auth::CheckCtx;
use rmcp::{
    RoleServer, handler::server::wrapper::Parameters, service::RequestContext, tool, tool_router,
};

use crate::guard;
use crate::handlers;
use crate::tool_args::*;
use crate::tool_auth::{http_bearer_token, outcome_key_id_from_snapshot};

use super::FutuServer;

#[tool_router(router = trade_write_tool_router, vis = "pub(crate)")]
impl FutuServer {
    // ------- 交易写入（需 --enable-trading） -------

    #[tool(
        description = "⚠️ REAL MONEY when env=real. Place an order on a live brokerage account. REQUIRES futu-mcp started with --enable-trading; real env additionally requires --allow-real-trading; gateway must have been unlocked via `futu_unlock_trade` first. **Market hours requirement**: OpenD does NOT pre-submit orders during closed hours — call during active session (HK 09:30-16:00 HKT, US 09:30-16:00 ET, etc.). Off-hours: use Futu/moomoo mobile APP (separate queue), not this tool. Changing `order_type` (AUCTION / fill_outside_rth) does NOT bypass this — server refuses identically."
    )]
    async fn futu_place_order(
        &self,
        Parameters(req): Parameters<PlaceOrderReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        // per-call key 优先级：tool args `api_key` > HTTP Authorization Bearer > startup key
        let header_token = http_bearer_token(&req_ctx);
        let override_key = req.api_key.as_deref().or(header_token.as_deref());
        let args_hash = guard::args_short_hash(&req);
        tracing::warn!(
            target: futu_auth::audit::TARGET,
            iface = "mcp",
            endpoint = "futu_place_order",
            env = %req.env,
            market = %req.market,
            acc_id = req.acc_id.unwrap_or(0), // v1.4.105 T-D1: Option<u64> → u64 for audit log
            card_num_provided = req.card_num.is_some(),
            side = %req.side,
            order_type = %req.order_type,
            code = %req.code,
            qty = req.qty,
            // v1.4.90 P2-C: Option<f64> → f64 NaN sentinel; was `?req.price`
            // 之前 record_debug 把 Some(400.0) 编为 string "Some(400.0)" 让下游 jq 数值聚合炸
            price = crate::state::audit_fmt::opt_f64(req.price),
            args_hash = %args_hash,
            outcome = "request",
            "place_order request received"
        );
        req.validate()?;
        // codex round 1 F2 (P2) v1.4.105: caller key strict pre-check FIRST,
        // **再** client_or_err + resolve. invalid Bearer 在此 fail-closed,
        // 不再触发 daemon GetAccList + startup-key allowed_card_nums leak.
        let caller_key_rec = match self.require_caller_key_strict("futu_place_order", override_key)
        {
            Ok(rec) => rec,
            Err(reject_json) => return Err(reject_json),
        };
        // codex round 2 F1 (P2) v1.4.105: 早期 trade-scope 校验 — 在
        // `client_or_err` + `resolve_acc_id_with_card_num` 之前. 防 valid
        // 但**非-trade** key (e.g. qot:read only) 触发 daemon GetAccList +
        // card_num 探测 not-found/ambiguous/existence timing.
        if let Some(reject) =
            self.require_trading_scope_only("futu_place_order", &req.env, caller_key_rec.as_ref())
        {
            return Err(reject);
        }
        // v1.4.105 D12 (Phase 2): resolve card_num → acc_id 在 scope check 前.
        // require_trading 的 CheckCtx 需要 final acc_id 做 allowed_acc_ids 校验,
        // 所以必须 client_or_err + resolve 提前. card_num resolve 多花 1 次
        // GetAccList RPC (~10ms 本地 daemon).
        let client = self.client_or_err().await?;
        // v1.4.105 D12 contract-hardening 补丁: 同步传 allowed_card_nums 做 string-level
        // whitelist 校验 (resolve 前). caller key 配置非空时, user 输 card_num
        // 必须 ∈ 白名单 — UX clear.
        // codex F2: 用 caller_key_rec (require_caller_key_strict 已验) 而非
        // current_key_rec(override_key) 重新查 — 避免 silent fallback startup.
        let allowed_card_nums = caller_key_rec
            .as_ref()
            .and_then(|r| r.allowed_card_nums.as_deref());
        // v1.4.106 codex round 2 F1 case 2 (P1) fix: caller-snapshot acc_id
        // 早过滤 — 受限 key 不再能 enumerate 其他用户的 acc_id (timing leak
        // via 0-match/1-match/N-match 差异).
        let caller_allowed_acc_ids = caller_key_rec
            .as_ref()
            .and_then(|r| r.allowed_acc_ids.as_ref());
        let resolved_acc_id = match handlers::trade_write::resolve_acc_id_with_card_num(
            &client,
            req.acc_id.unwrap_or(0),
            req.card_num.as_deref(),
            allowed_card_nums,
            caller_allowed_acc_ids,
        )
        .await
        {
            Ok(id) => id,
            Err(msg) => return Self::tool_err(msg),
        };
        let ctx = CheckCtx {
            market: req.market.trim().to_ascii_uppercase(),
            symbol: format!(
                "{}.{}",
                req.market.trim().to_ascii_uppercase(),
                req.code.trim()
            ),
            order_value: req.price.map(|p| p * req.qty),
            trd_side: Some(req.side.trim().to_ascii_uppercase()),
            acc_id: Some(resolved_acc_id), // v1.4.35; v1.4.105 D12: resolved
            mutation_no_exposure: false,
            currency: None,
        };
        if let Some(rej) =
            self.require_trading("futu_place_order", &req.env, Some(ctx), override_key)
        {
            // MED-2: scope 拒绝 → Err（rmcp set is_error=true）
            return Err(rej);
        }
        let result = Self::wrap_result(
            handlers::trade_write::place_order(
                &client,
                handlers::trade_write::PlaceOrderInput {
                    env: &req.env,
                    acc_id: resolved_acc_id,
                    market: &req.market,
                    side: &req.side,
                    order_type: &req.order_type,
                    code: &req.code,
                    qty: req.qty,
                    price: req.price,
                    jp_acc_type: req.jp_acc_type,
                    idempotency_key: req.idempotency_key.clone(),
                    // v1.4.53 F1 条件单
                    stop_price: req.stop_price,
                    trail_type: req.trail_type,
                    trail_value: req.trail_value,
                    trail_spread: req.trail_spread,
                },
            )
            .await,
        );
        // codex round 1 F4 (P2) v1.4.106: emit_trade_outcome 用 caller_key_rec
        // snapshot (require_caller_key_strict 已 lock 住), **不**调
        // current_key_id(override_key) 重新 verify — 防 SIGHUP reload 在
        // daemon dispatch 中途 revoke/narrow per-call key, audit 记录被误归
        // 属到 startup key 或 fallback. snapshot reuse pattern 与 unlock_trade
        // (codex round 1 F5) / list_accounts (codex round 1 F3) 一致.
        let startup_key = self.state.authed_key();
        let outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), startup_key.as_ref());
        guard::emit_trade_outcome(
            "futu_place_order",
            outcome_key_id,
            &args_hash,
            Self::result_as_str(&result),
        );
        result
    }

    #[tool(
        description = "⚠️ REAL MONEY when env=real. Modify an existing live order (change qty/price, cancel, disable/enable/delete). REQUIRES --enable-trading; real env needs --allow-real-trading. For simple cancel, prefer `futu_cancel_order`. **Market hours requirement**: same as `futu_place_order` — off-hours hit server-side refusal regardless of `op`."
    )]
    async fn futu_modify_order(
        &self,
        Parameters(req): Parameters<ModifyOrderReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let header_token = http_bearer_token(&req_ctx);
        let override_key = req.api_key.as_deref().or(header_token.as_deref());
        let args_hash = guard::args_short_hash(&req);
        tracing::warn!(
            target: futu_auth::audit::TARGET,
            iface = "mcp",
            endpoint = "futu_modify_order",
            env = %req.env,
            market = %req.market,
            acc_id = req.acc_id.unwrap_or(0), // v1.4.105 T-D1: Option<u64> → u64 for audit log
            card_num_provided = req.card_num.is_some(),
            order_id = %req.order_id,
            op = %req.op,
            // v1.4.90 P2-C: Option<f64> → f64 NaN sentinel
            qty = crate::state::audit_fmt::opt_f64(req.qty),
            price = crate::state::audit_fmt::opt_f64(req.price),
            args_hash = %args_hash,
            outcome = "request",
            "modify_order request received"
        );
        req.validate()?;
        // codex round 1 F2 (P2) v1.4.105: caller key strict pre-check FIRST.
        let caller_key_rec = match self.require_caller_key_strict("futu_modify_order", override_key)
        {
            Ok(rec) => rec,
            Err(reject_json) => return Err(reject_json),
        };
        // codex round 2 F1 (P2) v1.4.105: 早期 trade-scope 校验 (同 place_order).
        if let Some(reject) =
            self.require_trading_scope_only("futu_modify_order", &req.env, caller_key_rec.as_ref())
        {
            return Err(reject);
        }
        // v1.4.105 D12: client_or_err + resolve card_num → acc_id 提前 (scope check 用)
        let client = self.client_or_err().await?;
        // v1.4.105 D12 contract-hardening 补丁: 同步传 allowed_card_nums 做 string-level
        // whitelist 校验 (resolve 前). caller key 配置非空时, user 输 card_num
        // 必须 ∈ 白名单 — UX clear.
        // codex F2: 用 caller_key_rec (require_caller_key_strict 已验) 而非
        // current_key_rec(override_key) 重新查.
        let allowed_card_nums = caller_key_rec
            .as_ref()
            .and_then(|r| r.allowed_card_nums.as_deref());
        // v1.4.106 codex round 2 F1 case 2 (P1) fix: caller-snapshot acc_id
        // 早过滤 (同 place_order).
        let caller_allowed_acc_ids = caller_key_rec
            .as_ref()
            .and_then(|r| r.allowed_acc_ids.as_ref());
        let resolved_acc_id = match handlers::trade_write::resolve_acc_id_with_card_num(
            &client,
            req.acc_id.unwrap_or(0),
            req.card_num.as_deref(),
            allowed_card_nums,
            caller_allowed_acc_ids,
        )
        .await
        {
            Ok(id) => id,
            Err(msg) => return Self::tool_err(msg),
        };
        // modify 改单 API 只给 order_id，symbol/金额/side 都推不出来 → 填空 ctx
        // 好让 market 白名单 / 时段 / 速率限制照样生效（symbol / 单笔 / 日累计 / side
        // 这几项在 limits.rs 里都已 skip-empty-ctx）
        let mutation_ctx = CheckCtx {
            market: req.market.trim().to_ascii_uppercase(),
            symbol: String::new(),
            order_value: None,
            trd_side: None,
            acc_id: Some(resolved_acc_id), // v1.4.35; v1.4.105 D12: resolved
            mutation_no_exposure: false,
            currency: None,
        };
        if let Some(rej) = self.require_trading(
            "futu_modify_order",
            &req.env,
            Some(mutation_ctx),
            override_key,
        ) {
            // MED-2: scope 拒绝 → Err（rmcp set is_error=true）
            return Err(rej);
        }
        let result = Self::wrap_result(
            handlers::trade_write::modify_order(
                &client,
                handlers::trade_write::ModifyOrderInput {
                    env: &req.env,
                    acc_id: resolved_acc_id,
                    market: &req.market,
                    order_id: &req.order_id,
                    op: &req.op,
                    qty: req.qty,
                    price: req.price,
                    jp_acc_type: req.jp_acc_type,
                    idempotency_key: req.idempotency_key.clone(),
                },
            )
            .await,
        );
        // codex round 1 F4 (P2) v1.4.106: snapshot reuse — 见 place_order 同段注释.
        let startup_key = self.state.authed_key();
        let outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), startup_key.as_ref());
        guard::emit_trade_outcome(
            "futu_modify_order",
            outcome_key_id,
            &args_hash,
            Self::result_as_str(&result),
        );
        result
    }

    #[tool(
        description = "⚠️ REAL MONEY when env=real. Cancel a live order by order_id. REQUIRES --enable-trading; real env needs --allow-real-trading. Convenience wrapper over `futu_modify_order` with op=CANCEL. Same market-hours requirement as `futu_place_order`."
    )]
    async fn futu_cancel_order(
        &self,
        Parameters(req): Parameters<CancelOrderReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let header_token = http_bearer_token(&req_ctx);
        let override_key = req.api_key.as_deref().or(header_token.as_deref());
        let args_hash = guard::args_short_hash(&req);
        tracing::warn!(
            target: futu_auth::audit::TARGET,
            iface = "mcp",
            endpoint = "futu_cancel_order",
            env = %req.env,
            market = %req.market,
            acc_id = req.acc_id.unwrap_or(0), // v1.4.105 T-D1: Option<u64> → u64 for audit log
            card_num_provided = req.card_num.is_some(),
            order_id = %req.order_id,
            args_hash = %args_hash,
            outcome = "request",
            "cancel_order request received"
        );
        // codex round 1 F2 (P2) v1.4.105: caller key strict pre-check FIRST.
        let caller_key_rec = match self.require_caller_key_strict("futu_cancel_order", override_key)
        {
            Ok(rec) => rec,
            Err(reject_json) => return Err(reject_json),
        };
        // codex round 2 F1 (P2) v1.4.105: 早期 trade-scope 校验 (同 place_order).
        if let Some(reject) =
            self.require_trading_scope_only("futu_cancel_order", &req.env, caller_key_rec.as_ref())
        {
            return Err(reject);
        }
        // v1.4.105 D12: client_or_err + resolve card_num → acc_id 提前 (scope check 用)
        let client = self.client_or_err().await?;
        // v1.4.105 D12 contract-hardening 补丁: 同步传 allowed_card_nums 做 string-level
        // whitelist 校验 (resolve 前). caller key 配置非空时, user 输 card_num
        // 必须 ∈ 白名单 — UX clear.
        // codex F2: 用 caller_key_rec (require_caller_key_strict 已验) 而非
        // current_key_rec(override_key) 重新查.
        let allowed_card_nums = caller_key_rec
            .as_ref()
            .and_then(|r| r.allowed_card_nums.as_deref());
        // v1.4.106 codex round 2 F1 case 2 (P1) fix: caller-snapshot acc_id
        // 早过滤 (同 place_order).
        let caller_allowed_acc_ids = caller_key_rec
            .as_ref()
            .and_then(|r| r.allowed_acc_ids.as_ref());
        let resolved_acc_id = match handlers::trade_write::resolve_acc_id_with_card_num(
            &client,
            req.acc_id.unwrap_or(0),
            req.card_num.as_deref(),
            allowed_card_nums,
            caller_allowed_acc_ids,
        )
        .await
        {
            Ok(id) => id,
            Err(msg) => return Self::tool_err(msg),
        };
        let mutation_ctx = CheckCtx {
            market: req.market.trim().to_ascii_uppercase(),
            symbol: String::new(),
            order_value: None,
            trd_side: None,
            acc_id: Some(resolved_acc_id), // v1.4.35; v1.4.105 D12: resolved
            mutation_no_exposure: false,
            currency: None,
        };
        if let Some(rej) = self.require_trading(
            "futu_cancel_order",
            &req.env,
            Some(mutation_ctx),
            override_key,
        ) {
            // MED-2: scope 拒绝 → Err（rmcp set is_error=true）
            return Err(rej);
        }
        let result = Self::wrap_result(
            handlers::trade_write::cancel_order(
                &client,
                &req.env,
                resolved_acc_id,
                &req.market,
                &req.order_id,
                req.jp_acc_type,
                req.idempotency_key.clone(),
            )
            .await,
        );
        // codex round 1 F4 (P2) v1.4.106: snapshot reuse — 见 place_order 同段注释.
        let startup_key = self.state.authed_key();
        let outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), startup_key.as_ref());
        guard::emit_trade_outcome(
            "futu_cancel_order",
            outcome_key_id,
            &args_hash,
            Self::result_as_str(&result),
        );
        result
    }

    #[tool(
        description = "⚠️ REAL MONEY when env=real. Reconfirm a pending high-risk or price-warning order by numeric order_id. REQUIRES --enable-trading; real env needs --allow-real-trading; gateway must have been unlocked via `futu_unlock_trade` first. Use only for orders that the backend explicitly asked to reconfirm."
    )]
    async fn futu_reconfirm_order(
        &self,
        Parameters(req): Parameters<ReconfirmOrderReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let header_token = http_bearer_token(&req_ctx);
        let override_key = req.api_key.as_deref().or(header_token.as_deref());
        let args_hash = guard::args_short_hash(&req);
        tracing::warn!(
            target: futu_auth::audit::TARGET,
            iface = "mcp",
            endpoint = "futu_reconfirm_order",
            env = %req.env,
            market = %req.market,
            acc_id = req.acc_id.unwrap_or(0),
            card_num_provided = req.card_num.is_some(),
            order_id = %req.order_id,
            reason = req.reason,
            args_hash = %args_hash,
            outcome = "request",
            "reconfirm_order request received"
        );
        let caller_key_rec =
            match self.require_caller_key_strict("futu_reconfirm_order", override_key) {
                Ok(rec) => rec,
                Err(reject_json) => return Err(reject_json),
            };
        if let Some(reject) = self.require_trading_scope_only(
            "futu_reconfirm_order",
            &req.env,
            caller_key_rec.as_ref(),
        ) {
            return Err(reject);
        }
        let client = self.client_or_err().await?;
        let allowed_card_nums = caller_key_rec
            .as_ref()
            .and_then(|r| r.allowed_card_nums.as_deref());
        let caller_allowed_acc_ids = caller_key_rec
            .as_ref()
            .and_then(|r| r.allowed_acc_ids.as_ref());
        let resolved_acc_id = match handlers::trade_write::resolve_acc_id_with_card_num(
            &client,
            req.acc_id.unwrap_or(0),
            req.card_num.as_deref(),
            allowed_card_nums,
            caller_allowed_acc_ids,
        )
        .await
        {
            Ok(id) => id,
            Err(msg) => return Self::tool_err(msg),
        };
        let mutation_ctx = CheckCtx {
            market: req.market.trim().to_ascii_uppercase(),
            symbol: String::new(),
            order_value: None,
            trd_side: None,
            acc_id: Some(resolved_acc_id),
            mutation_no_exposure: false,
            currency: None,
        };
        if let Some(rej) = self.require_trading(
            "futu_reconfirm_order",
            &req.env,
            Some(mutation_ctx),
            override_key,
        ) {
            return Err(rej);
        }
        let result = Self::wrap_result(
            handlers::trade_write::reconfirm_order(
                &client,
                handlers::trade_write::ReconfirmOrderInput {
                    env: &req.env,
                    acc_id: resolved_acc_id,
                    market: &req.market,
                    order_id: &req.order_id,
                    reason: req.reason,
                    jp_acc_type: req.jp_acc_type,
                },
            )
            .await,
        );
        let startup_key = self.state.authed_key();
        let outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), startup_key.as_ref());
        guard::emit_trade_outcome(
            "futu_reconfirm_order",
            outcome_key_id,
            &args_hash,
            Self::result_as_str(&result),
        );
        result
    }

    #[tool(
        description = "Cancel all pending orders for an account in a specific market. `market` is REQUIRED (HK / US / HKCC / A_SH / A_SZ / SG / JP / AU / CA). Python SDK: OpenTradeContext.cancel_all_order. REQUIRES --enable-trading. Real env requires --allow-real-trading. DANGER: unrecoverable — cancels every pending order in the specified market immediately."
    )]
    async fn futu_cancel_all_order(
        &self,
        Parameters(req): Parameters<CancelAllOrderReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let header_token = http_bearer_token(&req_ctx);
        let override_key = req.api_key.as_deref().or(header_token.as_deref());
        let args_hash = guard::args_short_hash(&req);
        tracing::warn!(
            target: futu_auth::audit::TARGET,
            iface = "mcp",
            endpoint = "futu_cancel_all_order",
            env = %req.env,
            market = %req.market,
            acc_id = req.acc_id,
            args_hash = %args_hash,
            outcome = "request",
            "cancel_all_order request received"
        );
        // v1.4.34 MCP-3b 修：market 是必填，空字符串下发到后端会炸
        // `unknown trd market ""` —— 这是个模糊的内部错误，LLM 客户端没法自修。
        // 在 tool 层前置校验给清晰的必填提示 + 合法值列表。
        // v1.4.84 §5 B4: 用集中的 validate() (其他 tool 也复用类似模式)
        req.validate()?;
        // codex round 1 F4 (P2) v1.4.106: lock caller key snapshot **早**
        // (在 require_trading + daemon dispatch 之前), 用于 emit_trade_outcome
        // 防 SIGHUP race. 与 place/modify/cancel_order 的 require_caller_key_strict
        // 同语义 — invalid override 立即 fail-closed, scope mode 关闭则 Ok(None).
        let caller_key_rec =
            match self.require_caller_key_strict("futu_cancel_all_order", override_key) {
                Ok(rec) => rec,
                Err(reject_json) => return Err(reject_json),
            };
        let market_trimmed = req.market.trim();
        let mutation_ctx = CheckCtx {
            market: market_trimmed.to_ascii_uppercase(),
            symbol: String::new(),
            order_value: None,
            trd_side: None,
            acc_id: Some(req.acc_id), // v1.4.35
            mutation_no_exposure: false,
            currency: None,
        };
        if let Some(rej) = self.require_trading(
            "futu_cancel_all_order",
            &req.env,
            Some(mutation_ctx),
            override_key,
        ) {
            // MED-2: scope 拒绝 → Err（rmcp set is_error=true）
            return Err(rej);
        }
        let client = self.client_or_err().await?;
        let result = Self::wrap_result(
            handlers::trade_write::cancel_all_order(&client, &req.env, req.acc_id, &req.market)
                .await,
        );
        // codex round 1 F4 (P2) v1.4.106: snapshot reuse — 见 place_order 同段注释.
        let startup_key = self.state.authed_key();
        let outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), startup_key.as_ref());
        guard::emit_trade_outcome(
            "futu_cancel_all_order",
            outcome_key_id,
            &args_hash,
            Self::result_as_str(&result),
        );
        result
    }
}