futu_mcp/tools/

trade_write.rs

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

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;

pub(crate) fn validate_unlock_trade_acc_ids(acc_ids: Option<&[u64]>) -> Result<(), String> {
    if let Some(ids) = acc_ids
        && let Some((idx, _)) = ids.iter().enumerate().find(|(_, id)| **id == 0)
    {
        return Err(format!(
            "futu_unlock_trade: acc_ids[{idx}] must be a positive non-zero acc_id; got 0"
        ));
    }
    Ok(())
}

#[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"
        );
        // 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,
                    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 outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), self.state.authed_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"
        );
        // 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,
                    idempotency_key: req.idempotency_key.clone(),
                },
            )
            .await,
        );
        // codex round 1 F4 (P2) v1.4.106: snapshot reuse — 见 place_order 同段注释.
        let outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), self.state.authed_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.idempotency_key.clone(),
            )
            .await,
        );
        // codex round 1 F4 (P2) v1.4.106: snapshot reuse — 见 place_order 同段注释.
        let outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), self.state.authed_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,
                },
            )
            .await,
        );
        let outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), self.state.authed_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 outcome_key_id =
            outcome_key_id_from_snapshot(caller_key_rec.as_ref(), self.state.authed_key.as_ref());
        guard::emit_trade_outcome(
            "futu_cancel_all_order",
            outcome_key_id,
            &args_hash,
            Self::result_as_str(&result),
        );
        result
    }

    #[tool(
        description = "⚠️ Opens a trade window for subsequent `futu_place_order` / `futu_modify_order` / `futu_cancel_order` / `futu_reconfirm_order` calls. Password is read from account-scoped OS keychain (via `futucli set-trade-pwd --account <login-account>` plus futu-mcp `--trade-pwd-account <login-account>`) or FUTU_TRADE_PWD env — NEVER pass it via tool args. Requires `trade:unlock` scope. **Lifetime**: once unlocked, all subsequent trade calls succeed without re-authenticating until gateway restart or an explicit `unlock=false` lock-back. Do NOT call this on every trade (server-side anti-abuse may throttle)."
    )]
    async fn futu_unlock_trade(
        &self,
        Parameters(req): Parameters<UnlockTradeReq>,
        req_ctx: RequestContext<RoleServer>,
    ) -> std::result::Result<String, String> {
        let args_hash = guard::args_short_hash(&req);
        tracing::warn!(
            target: futu_auth::audit::TARGET,
            iface = "mcp",
            endpoint = "futu_unlock_trade",
            unlock = req.unlock,
            args_hash = %args_hash,
            outcome = "request",
            "unlock_trade request received"
        );
        // v1.4.103 codex F5.3 (P1) round 5: 切到 caller-specific scope check.
        // 之前 require_tool_scope 只看 startup key, 受限 Bearer 仍可用 startup
        // key 的 trade:unlock scope 解锁所有账户.
        //
        // v1.4.104 阶段 7-5: 走 pipeline 做 caller-specific scope check + expiry
        // + audit. acc_ids 多元素白名单 enforcement 仍在本地 inline (special
        // semantic: 多 acc_id loop + "no acc_ids + restriction" reject; pipeline
        // 单一 explicit_acc_id 不足以覆盖).
        //
        // 流程:
        //   1. resolve caller credential (Bearer → verify, fail-closed; 无
        //      Bearer → fall back startup key PreVerified).
        //   2. pipeline: scope=TradeUnlock + audit_emit=true + commit_rate=false.
        //      Reject → return JSON error.
        //   3. inline per-acc_id whitelist enforcement (本节专属语义).
        let bearer_token = http_bearer_token(&req_ctx);
        let credential: futu_auth_pipeline::Credential<'_> = match bearer_token
            .as_deref()
            .filter(|s| !s.is_empty())
        {
            Some(t) => match self.state.key_store.verify(t) {
                Some(rec) => futu_auth_pipeline::Credential::PreVerified(rec),
                None => {
                    // codex F4 fail-closed: invalid Bearer → reject, 不 fall back
                    futu_auth::audit::reject(
                        "mcp",
                        "futu_unlock_trade",
                        "<bearer-invalid>",
                        "invalid Bearer (v1.4.103 codex F5.3 fail-closed)",
                    );
                    return Err(serde_json::json!({
                            "error": "futu_unlock_trade: invalid Bearer token (v1.4.103 codex F5.3 fail-closed)",
                            "status": "error",
                        })
                        .to_string());
                }
            },
            // v1.4.106 codex 0608 F2 (P1): startup fallback 用
            // `get_by_id_for_current_machine` 替代裸 `get_by_id`, 让 SIGHUP 收紧
            // allowed_machines 后能立即 reject (与 Bearer 路径 verify 行为对称).
            None => match self
                .state
                .authed_key
                .as_ref()
                .and_then(|k| self.state.key_store.get_by_id_for_current_machine(&k.id))
            {
                Some(rec) => futu_auth_pipeline::Credential::PreVerified(rec),
                None => futu_auth_pipeline::Credential::None,
            },
        };

        let unlock_env = futu_auth_pipeline::AuthEnvelope {
            surface: futu_auth_pipeline::SurfaceId::Mcp,
            endpoint: futu_auth_pipeline::Endpoint::McpTool("futu_unlock_trade"),
            needed_scope: Some(futu_auth::Scope::TradeUnlock),
            credential,
            proto_id: None,
            body: &[],
            explicit_acc_id: None, // multi-acc 白名单单独 inline enforce
            explicit_ctx: None,
            commit_rate: false, // unlock 不计 rate
            audit_emit: true,
        };
        let caller_key_for_unlock = match futu_auth_pipeline::authenticate_request(
            &self.state.key_store,
            &self.state.counters,
            unlock_env,
        ) {
            futu_auth_pipeline::AuthDecision::Allow { rec, .. } => rec,
            futu_auth_pipeline::AuthDecision::Reject {
                kind,
                reason,
                audit_key_id,
            } => {
                use futu_auth_pipeline::RejectKind;
                let err_msg = match kind {
                    RejectKind::Unauthenticated => {
                        format!("futu_unlock_trade: API key required or expired ({reason})")
                    }
                    RejectKind::Forbidden => format!(
                        "futu_unlock_trade: API key {audit_key_id:?} forbidden — needs trade:unlock scope ({reason})"
                    ),
                    _ => reason.clone(),
                };
                return Err(serde_json::json!({
                    "error": err_msg,
                    "status": "error",
                })
                .to_string());
            }
        };
        if let Err(err) = validate_unlock_trade_acc_ids(req.acc_ids.as_deref()) {
            return Err(serde_json::json!({
                "error": err,
                "status": "error",
            })
            .to_string());
        }
        // 若 caller 的 key 有 allowed_acc_ids 限制 + caller 显式传 acc_ids:
        //   每个 acc_id 必须 ∈ allowed_acc_ids
        // 若 caller 显式 acc_ids 为 None / empty + key 有限制:
        //   reject (ambiguous — 不让"unlock all" silent 解锁未授权账户)
        if let Some(ref rec) = caller_key_for_unlock
            && let Some(ref allowed) = rec.allowed_acc_ids
            && !allowed.is_empty()
        {
            match req.acc_ids.as_ref() {
                Some(ids) if !ids.is_empty() => {
                    for id in ids {
                        if !allowed.contains(id) {
                            futu_auth::audit::reject(
                                "mcp",
                                "futu_unlock_trade",
                                &rec.id,
                                &format!("acc_id {id} not in allowed list"),
                            );
                            return Err(serde_json::json!({
                                "error": format!(
                                    "futu_unlock_trade: API key {:?} not allowed to unlock acc_id {id} (allowed_acc_ids restriction)",
                                    rec.id
                                ),
                                "status": "error",
                            })
                            .to_string());
                        }
                    }
                }
                _ => {
                    // 没传 acc_ids + key 有限制 → 不允许 silent unlock all
                    return Err(serde_json::json!({
                        "error": format!(
                            "futu_unlock_trade: API key {:?} has allowed_acc_ids restriction \
                             but acc_ids not specified. Restricted keys must explicitly pass \
                             acc_ids; unlock-all is rejected to prevent unauthorized broker \
                             unlock side effects.",
                            rec.id
                        ),
                        "status": "error",
                        "hint": "pass acc_ids: [<your-allowed-acc-id>]",
                    })
                    .to_string());
                }
            }
        }

        // lock 不需要密码，unlock 要从账号级 keychain/env 读。
        // MCP 只连接 gateway，不能从本进程可靠推断 daemon login account；
        // 因此账号 hint 来自 `--trade-pwd-account` / FUTU_TRADE_PWD_ACCOUNT。
        let pwd_md5 = if req.unlock {
            match crate::trade_pwd::get_trade_password_md5_for_account(
                self.state.trade_pwd_account.as_deref(),
            ) {
                Ok(md5) => md5,
                Err(e) => {
                    let err = format!("unlock failed: {e}");
                    tracing::warn!(
                        target: futu_auth::audit::TARGET,
                        iface = "mcp",
                        endpoint = "futu_unlock_trade",
                        outcome = "failure",
                        reason = %err,
                        "unlock failed: no password source"
                    );
                    return Self::tool_err(err);
                }
            }
        } else {
            String::new()
        };

        let client = self.client_or_err().await?;
        let result = match futu_trd::account::unlock_trade(
            &client,
            &pwd_md5,
            req.unlock,
            req.otp.as_deref(),
            req.security_firm,
            req.acc_ids.clone().unwrap_or_default(),
        )
        .await
        {
            Ok(outcome) => {
                if outcome.need_otp {
                    // HIGH-2 修（code review）：need_otp=true 是 unlock 失败的错误
                    // 状态（用户需带 OTP 重试），应 set is_error=true 让 agent 通过
                    // top-level envelope 感知，不需要 parse JSON `ok` 字段。
                    // MED-NEW-1（2nd review）：加 `error` field 让 emit_trade_outcome
                    // 按 "failure" 记 audit log（之前 need_otp 会被错记 success）
                    Err(serde_json::json!({
                        "error": "unlock requires OTP (2FA token); pass otp= and retry",
                        "need_otp": true,
                        "message": outcome.message.unwrap_or_else(||
                            "此账号开启了令牌动态密码（2FA）。\
                             请重新调用 futu_unlock_trade 带 `otp` 参数（明文 OTP）".into()),
                        "failed_accounts": outcome.failed_accounts,
                        "status": "need_otp_retry",
                    })
                    .to_string())
                } else if !req.unlock {
                    Ok(
                        serde_json::json!({ "ok": true, "message": "trade locked on gateway" })
                            .to_string(),
                    )
                } else {
                    let msg = if outcome.total_unlocked < outcome.total_requested {
                        format!(
                            "部分账户解锁成功（{}/{}）。\
                             失败账户：{:?}（常见原因：品种权限未开通 / 影子子账户）",
                            outcome.total_unlocked,
                            outcome.total_requested,
                            outcome.failed_accounts
                        )
                    } else {
                        format!(
                            "trade unlocked ({} accounts); cipher cached until gateway restarts",
                            outcome.total_unlocked
                        )
                    };
                    if outcome.total_unlocked > 0 {
                        Ok(serde_json::json!({
                            "ok": true,
                            "need_otp": false,
                            "total_requested": outcome.total_requested,
                            "total_unlocked": outcome.total_unlocked,
                            "failed_accounts": outcome.failed_accounts,
                            "message": msg,
                        })
                        .to_string())
                    } else {
                        // MED-NEW-1（2nd review）：总失败时加 `error` 让 audit log 按
                        // failure 记录（不含则 emit_trade_outcome 错判 success）
                        Err(serde_json::json!({
                            "ok": false,
                            "error": "all accounts failed to unlock",
                            "need_otp": false,
                            "total_requested": outcome.total_requested,
                            "total_unlocked": outcome.total_unlocked,
                            "failed_accounts": outcome.failed_accounts,
                            "message": msg,
                        })
                        .to_string())
                    }
                }
            }
            Err(e) => Err(format!("unlock_trade RPC failed: {e}")),
        };
        // codex round 1 F5 (P2) v1.4.105 + v1.4.106 F4 alignment:
        // emit_trade_outcome 用 caller_key_for_unlock 的 key id (pipeline Allow
        // 时的 KeyRecord), **不**调 self.current_key_id(None) 重新 verify —
        // 防 HTTP per-request Bearer 调 unlock 时 outcome 被错归 startup key
        // (F5 root cause), 同时也防 SIGHUP race (F4 同模式 — dispatch 中途
        // SIGHUP revoke caller key, snapshot 仍 hold 住).
        //
        // legacy mode (caller_key_for_unlock = None, scope mode 关闭) → 退化
        // 到 startup authed_key (与 v1.4.103 兼容). authed_key 取 precheck 时
        // 的 ref (snapshot), 同样不重新查 KeyStore.
        let outcome_key_id = outcome_key_id_from_snapshot(
            caller_key_for_unlock.as_ref(),
            self.state.authed_key.as_ref(),
        );
        guard::emit_trade_outcome(
            "futu_unlock_trade",
            outcome_key_id,
            &args_hash,
            Self::result_as_str(&result),
        );
        result
    }
}