futu_rest/

server.rs

//! REST API HTTP 服务
//!
//! 使用 axum 构建，复用 OpenD 的 RequestRouter 处理请求。
//! 支持 WebSocket 推送: 客户端连接 /ws 可接收实时行情和交易推送。

use std::sync::Arc;

mod cors;

use axum::Router;
use axum::body::to_bytes;
use axum::http::{StatusCode, header};
use axum::middleware::Next;
use axum::response::{IntoResponse, Response};
use axum::routing::{get, post};
use futu_auth::{KeyStore, RuntimeCounters};
use tokio::sync::watch;

use futu_server::router::RequestRouter;

use crate::adapter::RestState;
use crate::auth::{AuthState, bearer_auth};
use crate::routes::{admin, qot, sys, trd};
use crate::ws::{self, WsBroadcaster};

/// REST admin/diagnostic extension hooks injected by `futu-opend`.
///
/// These hooks are a single surface-adapter bundle: the REST crate keeps the
/// HTTP routing shape, while `futu-opend` owns the gateway/cache providers.
#[derive(Default)]
pub struct RestAdminHooks {
    pub admin_status_provider: Option<crate::adapter::AdminStatusProvider>,
    pub admin_shutdown_handler: Option<crate::adapter::AdminShutdownHandler>,
    pub admin_reload_handler: Option<crate::adapter::AdminReloadHandler>,
    pub push_health_snapshot_provider: Option<crate::adapter::PushHealthSnapshotProvider>,
    pub card_num_resolver: Option<crate::adapter::CardNumResolver>,
}

/// v1.4.93 P0-5 (NEW-C-02): REST `/ws` legacy mode 的 startup WARN 文本。
///
/// 抽出 const 以便单测验证 warn 消息携带 "v2"/"reject" 等关键提示词，
/// 防止后续被误删（同模式 v1.4.86 SEC-003 Q4 已沉淀）。
pub(crate) const LEGACY_WS_WARN_MESSAGE: &str = "WS endpoint /ws also accepts unauthenticated connections in legacy mode — \
     same posture as REST mutating-blocked: legacy clients may push to /ws without auth. \
     Migrate to --rest-keys-file for production. v2 will default-reject.";

/// Prometheus `/metrics` handler —— **v1.4.106 codex 0542 F1 [P2 SECURITY]**:
/// 默认 scope-gated (`Scope::MetricsRead`).
///
/// **三态**:
///
/// 1) **`FUTU_METRICS_PUBLIC=1` env 设** → 完全公开 (无 auth + 明文 key_id), 回退 v1.4.105 行为. opt-out 路径 (老 dashboard / 运维 firewall-only).
/// 2) **legacy 模式** (KeyStore 未配 / `is_configured() == false`) → 公开 (向后兼容: 用户没配 keys.json 之前也能用 /metrics).
/// 3) **scope-mode** (KeyStore 配置) → 强制 `Authorization: Bearer <plaintext>` + `Scope::MetricsRead` (或 `Scope::Admin` 兼容). 缺 → 401 / 403. body 里 key_id 为 `kh_<8hex>` 短 SHA256 redact (除非 env opt-out).
///
/// **路由位置**: route 注册在 bearer_auth middleware **之外** (path 不以 `/api/`
/// 起头, middleware 不拦), 所以 auth check 在 handler 内自己做.
async fn metrics_handler(
    axum::extract::State(state): axum::extract::State<RestState>,
    headers: axum::http::HeaderMap,
) -> Response {
    // (1) opt-out env: 完全公开 (老行为)
    let env_public = std::env::var_os("FUTU_METRICS_PUBLIC").is_some();
    if env_public {
        return render_metrics_body();
    }
    // (2) legacy mode: 公开 (KeyStore 未配)
    if !state.key_store.is_configured() {
        return render_metrics_body();
    }
    // (3) scope-mode: 必须有 Bearer + Scope::MetricsRead/Admin
    let token = headers
        .get("authorization")
        .and_then(|v| v.to_str().ok())
        .and_then(|v| futu_auth_pipeline::parse_bearer_scheme(v).map(|t| t.to_string()));
    let Some(token) = token else {
        return (
            axum::http::StatusCode::UNAUTHORIZED,
            [(
                axum::http::header::WWW_AUTHENTICATE,
                "Bearer realm=\"futu-rest\"",
            )],
            axum::Json(serde_json::json!({
                "error": "missing Authorization: Bearer <api-key>",
                "hint": "/metrics requires Scope::MetricsRead in scope-mode. \
                        Either set FUTU_METRICS_PUBLIC=1 to revert v1.4.105 \
                        public-no-auth (firewall-controlled deploys), or \
                        `futucli gen-key --id prom --scopes metrics:read`."
            })),
        )
            .into_response();
    };
    let Some(rec) = state.key_store.verify(&token) else {
        return (
            axum::http::StatusCode::UNAUTHORIZED,
            axum::Json(serde_json::json!({"error": "invalid api key"})),
        )
            .into_response();
    };
    // 持 MetricsRead 或 Admin 任一即过 (Admin 是 superset, 兼容老 admin key
    // dashboard 抓取场景, 不强制单独发新 key).
    let has_metrics = rec.scopes.contains(&futu_auth::Scope::MetricsRead)
        || rec.scopes.contains(&futu_auth::Scope::Admin);
    if !has_metrics {
        // BUG-011 不泄 key_id / scope: 通用 forbidden, 不暗示 "你少哪个 scope"
        return (
            axum::http::StatusCode::FORBIDDEN,
            axum::Json(serde_json::json!({"error": "forbidden"})),
        )
            .into_response();
    }
    render_metrics_body()
}

/// Render the actual prometheus body (no auth check). Pulled out so all 3
/// success branches in `metrics_handler` share rendering.
fn render_metrics_body() -> Response {
    let body = futu_auth::metrics::global()
        .map(|r| r.render_prometheus())
        .unwrap_or_else(|| {
            concat!(
                "# HELP futu_metrics_registry_installed Whether futu_auth metrics registry is installed (1=yes, 0=no)\n",
                "# TYPE futu_metrics_registry_installed gauge\n",
                "futu_metrics_registry_installed{state=\"metrics registry not installed\"} 0\n"
            )
            .to_string()
        });
    (
        axum::http::StatusCode::OK,
        [(
            axum::http::header::CONTENT_TYPE,
            "text/plain; version=0.0.4",
        )],
        body,
    )
        .into_response()
}

/// `/health` liveness probe handler —— 200 OK + body "ok"
///
/// 故意做得很轻：只要 axum 还能 schedule 任务返回响应就算"alive"。**不**检查
/// 网关连接 / DB / 下游依赖（那是 readiness 的活，运维真要可以另写一个
/// `/ready`）。LB / k8s liveness probe 直接打这个端点，bind_auth 不拦。
async fn health_handler() -> impl IntoResponse {
    (axum::http::StatusCode::OK, "ok")
}

/// `/readyz` readiness probe handler —— 200 OK if gateway dispatch ready, else 503
///
/// v1.4.27（UX-1，加拿大同事 v1.4.26 回归测试发现）：冷启动 ~30~60s 期间
/// `/api/quote` 返空 list、`/api/history-kline` 报 `no backend connection`，
/// 用户看不到就绪信号以为坏了。`/health` 只反映进程 alive（axum 能响应就
/// 算通），但用户真正想知道的是 "gateway dispatch 层是否 ready 接收业务
/// 请求"。
///
/// 实现：内部 dispatch 一次 `GET_GLOBAL_STATE`，能成功 decode 出响应就算
/// ready；否则 503。k8s readinessProbe / LB 直接打这个端点。
async fn readyz_handler(
    axum::extract::State(state): axum::extract::State<RestState>,
) -> impl IntoResponse {
    use bytes::Bytes;
    use futu_codec::header::ProtoFmtType;
    use futu_core::proto_id;
    use futu_proto::get_global_state;
    use futu_server::conn::IncomingRequest;
    use prost::Message;

    let req = get_global_state::Request {
        c2s: get_global_state::C2s { user_id: 0 },
    };
    let incoming = IncomingRequest::builder(
        state.next_conn_id(),
        proto_id::GET_GLOBAL_STATE,
        state.next_serial(),
        ProtoFmtType::Protobuf,
        Bytes::from(req.encode_to_vec()),
    )
    .build();
    let Some(resp_bytes) = state.router.dispatch(incoming.conn_id, &incoming).await else {
        return (
            axum::http::StatusCode::SERVICE_UNAVAILABLE,
            "gateway dispatch not ready",
        );
    };
    let Ok(resp) = get_global_state::Response::decode(Bytes::from(resp_bytes)) else {
        return (
            axum::http::StatusCode::SERVICE_UNAVAILABLE,
            "gateway response decode failed",
        );
    };
    if resp.ret_type != 0 {
        return (
            axum::http::StatusCode::SERVICE_UNAVAILABLE,
            "gateway not ready",
        );
    }
    (axum::http::StatusCode::OK, "ready")
}

/// 构建 legacy read-only REST API 路由（KeyStore 为空）。
///
/// 这是 crate 内测试/兼容入口：只读 endpoint 保持无鉴权兼容，写交易/admin
/// 仍由 middleware 拦截。生产 daemon 必须走 `build_router_with_auth*` /
/// `start_with_auth_full_admin_until_shutdown`，避免误接无 key legacy 模式。
#[cfg(test)]
pub(crate) fn build_legacy_readonly_router(
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
) -> Router {
    build_router_with_auth(
        router,
        ws_broadcaster,
        Arc::new(KeyStore::empty()),
        Arc::new(RuntimeCounters::new()),
    )
}

/// 构建 REST API 路由，携带 KeyStore 做 Bearer Token 鉴权 + RuntimeCounters 做限额
///
/// `key_store.is_configured() == false` 时等价于 crate-local
/// `build_legacy_readonly_router`（保持旧行为）。
/// `counters` 应由 main 全进程共享：REST / gRPC / MCP 共用一个实例才能保证
/// rate limit / 日累计跨接口一致
pub fn build_router_with_auth(
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
) -> Router {
    build_router_with_auth_and_admin(router, ws_broadcaster, key_store, counters, None)
}

/// v1.4.32+ 扩展：额外传入 admin_status_provider，`/api/admin/status` 用。
/// 旧 `build_router_with_auth` 内部委托到此，`admin_status_provider = None`
/// 时行为与之前完全一致（admin_status endpoint 返 503）。
/// `push_health_snapshot_provider` 同理只在 full-admin hooks 入口注入；
/// 未注入时 `/api/push-subscriber-info` 返 503，避免把 wiring 缺口伪装成
/// `ret_type=0` 的真实健康快照。
pub fn build_router_with_auth_and_admin(
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
    admin_status_provider: Option<crate::adapter::AdminStatusProvider>,
) -> Router {
    build_router_with_auth_full_admin(
        router,
        ws_broadcaster,
        key_store,
        counters,
        RestAdminHooks {
            admin_status_provider,
            ..RestAdminHooks::default()
        },
    )
}

/// v1.4.32+ 完整扩展：同时接 status provider + reload handler。
///
/// v1.4.83 §9 Phase 2 F5: 加 `push_health_snapshot_provider` 参数支持
/// `/api/push-subscriber-info` 返真实 push 通道健康 state。
pub fn build_router_with_auth_full_admin(
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
    hooks: RestAdminHooks,
) -> Router {
    let RestAdminHooks {
        admin_status_provider,
        admin_shutdown_handler,
        admin_reload_handler,
        push_health_snapshot_provider,
        card_num_resolver,
    } = hooks;
    let mut state = RestState::with_auth(
        router,
        ws_broadcaster,
        Arc::clone(&key_store),
        Arc::clone(&counters),
    );
    if let Some(p) = admin_status_provider {
        state = state.with_admin_status_provider(p);
    }
    if let Some(h) = admin_shutdown_handler {
        state = state.with_admin_shutdown_handler(h);
    }
    if let Some(h) = admin_reload_handler {
        state = state.with_admin_reload_handler(h);
    }
    if let Some(p) = push_health_snapshot_provider {
        state = state.with_push_health_snapshot_provider(p);
    }
    if let Some(r) = card_num_resolver {
        state = state.with_card_num_resolver(r);
    }
    let auth_state = AuthState::new(Arc::clone(&key_store), Arc::clone(&counters));

    let cors = cors::build_cors_layer(&key_store);

    Router::new()
        // ── WebSocket 推送 ──
        .route("/ws", get(ws::ws_handler))
        // ── 系统 ──
        .route("/api/global-state", get(sys::get_global_state))
        .route("/api/user-info", get(sys::get_user_info))
        .route("/api/quote-rights", get(sys::get_quote_rights))
        .route(
            "/api/delay-statistics",
            get(sys::get_delay_statistics).post(sys::get_delay_statistics_post),
        )
        // v1.4.74 A2 BUG-013 fix: 7 missing REST endpoints（对齐 MCP tools）
        .route("/api/ping", get(sys::ping))
        .route("/api/push-subscriber-info", get(sys::push_subscriber_info))
        .route("/api/unsub-acc-push", post(sys::unsub_acc_push))
        // v1.4.98 T2-8 (mobile-source-audit Phase 2): NN+MM token state query
        .route(
            "/api/token-state",
            get(sys::get_token_state).post(sys::get_token_state),
        )
        // ── 行情 ──
        .route("/api/subscribe", post(qot::subscribe))
        .route("/api/sub-info", get(qot::get_sub_info))
        // v1.4.74 A2 BUG-013 fix: query-subscription (POST 版，可传 is_req_all_conn)
        .route("/api/query-subscription", post(qot::query_subscription))
        // v1.4.74 A2 BUG-013 fix: list-plates alias（对齐 MCP `futu_list_plates`）
        .route("/api/list-plates", post(qot::list_plates))
        .route("/api/quote", post(qot::get_basic_qot))
        .route("/api/kline", post(qot::get_kl))
        .route("/api/orderbook", post(qot::get_order_book))
        .route("/api/broker", post(qot::get_broker))
        .route("/api/ticker", post(qot::get_ticker))
        .route("/api/rt", post(qot::get_rt))
        .route("/api/snapshot", post(qot::get_snapshot))
        .route("/api/static-info", post(qot::get_static_info))
        .route("/api/plate-set", post(qot::get_plate_set))
        .route("/api/plate-security", post(qot::get_plate_security))
        .route("/api/reference", post(qot::get_reference))
        // v1.4.74 A2 BUG-013 fix: get-reference alias（对齐 MCP `futu_get_reference`）
        .route("/api/get-reference", post(qot::get_reference))
        .route("/api/owner-plate", post(qot::get_owner_plate))
        .route("/api/option-chain", post(qot::get_option_chain))
        .route("/api/warrant", post(qot::get_warrant))
        .route("/api/capital-flow", post(qot::get_capital_flow))
        .route(
            "/api/capital-distribution",
            post(qot::get_capital_distribution),
        )
        .route("/api/company-profile", post(qot::get_company_profile))
        .route("/api/company-executives", post(qot::get_company_executives))
        .route(
            "/api/company-executive-background",
            post(qot::get_company_executive_background),
        )
        .route(
            "/api/company-operational-efficiency",
            post(qot::get_company_operational_efficiency),
        )
        .route(
            "/api/financials-earnings-price-move",
            post(qot::get_financials_earnings_price_move),
        )
        .route(
            "/api/financials-earnings-price-history",
            post(qot::get_financials_earnings_price_history),
        )
        .route(
            "/api/financials-statements",
            post(qot::get_financials_statements),
        )
        .route(
            "/api/financials-revenue-breakdown",
            post(qot::get_financials_revenue_breakdown),
        )
        .route(
            "/api/research-analyst-consensus",
            post(qot::get_research_analyst_consensus),
        )
        .route(
            "/api/research-rating-summary",
            post(qot::get_research_rating_summary),
        )
        .route(
            "/api/research-morningstar-report",
            post(qot::get_research_morningstar_report),
        )
        .route("/api/valuation-detail", post(qot::get_valuation_detail))
        .route(
            "/api/valuation-plate-stock-list",
            post(qot::get_valuation_plate_stock_list),
        )
        .route(
            "/api/corporate-actions-buybacks",
            post(qot::get_corporate_actions_buybacks),
        )
        .route(
            "/api/corporate-actions-dividends",
            post(qot::get_corporate_actions_dividends),
        )
        .route(
            "/api/corporate-actions-stock-splits",
            post(qot::get_corporate_actions_stock_splits),
        )
        .route("/api/daily-short-volume", post(qot::get_daily_short_volume))
        .route("/api/short-interest", post(qot::get_short_interest))
        .route(
            "/api/top-ten-buy-sell-brokers",
            post(qot::get_top_ten_buy_sell_brokers),
        )
        .route(
            "/api/shareholders-overview",
            post(qot::get_shareholders_overview),
        )
        .route(
            "/api/shareholders-holding-changes",
            post(qot::get_shareholders_holding_changes),
        )
        .route(
            "/api/shareholders-holder-detail",
            post(qot::get_shareholders_holder_detail),
        )
        .route(
            "/api/shareholders-institutional",
            post(qot::get_shareholders_institutional),
        )
        .route(
            "/api/insider-holder-list",
            post(qot::get_insider_holder_list),
        )
        .route("/api/insider-trade-list", post(qot::get_insider_trade_list))
        .route("/api/option-volatility", post(qot::get_option_volatility))
        .route(
            "/api/option-exercise-probability",
            post(qot::get_option_exercise_probability),
        )
        .route("/api/option-quote", post(qot::get_option_quote))
        .route("/api/option-strategy", post(qot::get_option_strategy))
        .route(
            "/api/option-strategy-analysis",
            post(qot::get_option_strategy_analysis),
        )
        .route(
            "/api/option-strategy-spread",
            post(qot::get_option_strategy_spread),
        )
        .route("/api/stock-screen", post(qot::stock_screen))
        .route("/api/option-screen", post(qot::option_screen))
        .route("/api/warrant-screen", post(qot::warrant_screen))
        .route("/api/technical-unusual", post(qot::get_technical_unusual))
        .route("/api/financial-unusual", post(qot::get_financial_unusual))
        .route("/api/derivative-unusual", post(qot::get_derivative_unusual))
        .route("/api/user-security", post(qot::get_user_security))
        .route("/api/stock-filter", post(qot::stock_filter))
        .route("/api/ipo-list", post(qot::get_ipo_list))
        .route("/api/future-info", post(qot::get_future_info))
        .route("/api/market-state", post(qot::get_market_state))
        .route("/api/history-kline", post(qot::request_history_kl))
        // v1.4.30
        .route("/api/trading-days", post(qot::request_trading_days))
        .route("/api/rehab", post(qot::request_rehab))
        .route("/api/suspend", post(qot::get_suspend))
        // v1.4.30 P2（100% 覆盖）
        .route("/api/history-kl-quota", post(qot::request_history_kl_quota))
        .route("/api/used-quota", post(qot::get_used_quota))
        .route("/api/holding-change", post(qot::get_holding_change))
        .route("/api/modify-user-security", post(qot::modify_user_security))
        .route("/api/code-change", post(qot::get_code_change))
        .route("/api/set-price-reminder", post(qot::set_price_reminder))
        .route("/api/price-reminder", post(qot::get_price_reminder))
        .route(
            "/api/option-expiration-date",
            post(qot::get_option_expiration_date),
        )
        .route("/api/unsubscribe", post(qot::unsubscribe))
        // v1.4.98 T2-2 (mobile-source-audit Phase 2): risk-free rate (期权定价)
        .route(
            "/api/risk-free-rate",
            get(qot::get_risk_free_rate).post(qot::get_risk_free_rate),
        )
        // v1.4.98 T2-1: 摆盘步长 (价位表)
        .route(
            "/api/spread-table",
            get(qot::get_spread_table).post(qot::get_spread_table),
        )
        // v1.4.98 T2-3: 逐笔统计
        .route("/api/ticker-statistic", post(qot::get_ticker_statistic))
        // v1.4.106 codex 0500 ζ23-redo: 逐笔统计 Detail (价位级分布)
        .route(
            "/api/ticker-statistic-detail",
            post(qot::get_ticker_statistic_detail),
        )
        .route("/api/flow-summary", post(trd::get_flow_summary))
        // v1.4.51 (external reviewer v1.4.48 pre-existing): `/api/acc-cash-flow` 404 —— CLI
        // 命令名 / MCP tool 名都是 `acc-cash-flow`，REST 之前只注册 `/api/flow-summary`
        // 别名。加 alias 让两种 URL 都 work（向后兼容 + 对齐 CLI/MCP 直觉）。
        .route("/api/acc-cash-flow", post(trd::get_flow_summary))
        // v1.4.94 Tier M (mobile-driven extension): 资金明细 / cash log
        // 来源: ftcnnproto/.../realtime_asset_log.proto + FLCltProtocol.h:123
        // (clt_cmd_trade_cash_log = 3000). 比 /api/flow-summary 字段更全 +
        // cursor 分页 + 多维过滤. 见 docs/protocol/cash-log.md.
        .route("/api/cash-log", post(trd::get_cash_log))
        .route("/api/cash-detail", post(trd::get_cash_detail))
        .route("/api/biz-group", post(trd::get_biz_group))
        // v1.4.95 U2-D Tier M (mobile-driven extension): per-account margin info
        // 来源: ftcnnproto/.../risk_user_account_info.proto + FLCltProtocol.h
        // (clt_cmd_hk_margin_info=3101 / us=3102 / cn_ah=3107). 与 /api/margin-ratio
        // (per-security ratio) 互补: 本 endpoint 给 per-account 全景 (购买力 / 杠杆
        // / 风险等级 / 流动性 / HK-specific 港股保证金).
        .route("/api/margin-info", post(trd::get_margin_info))
        // v1.4.95 U2-A Tier M (mobile-driven extension): account compliance flags
        // 来源: ftcnnproto/.../account_flag.proto + NN cmd 5281. 查询账户合规
        // 状态 (产品准入 / 风险评估 / opt-in 标志). 高级交易准入强制要求.
        .route("/api/account-flag", post(trd::get_account_flag))
        // v1.4.95 U2-B Tier M (mobile-driven extension): bond holdings + trade prep
        // 来源: ftcnnproto/.../bond_client_view.proto + FLCltProtocol.h
        // 5 endpoint × 5 cmd_id (9373/9374/9375/10043/10057), 共享 acc_id +
        // trd_env + market("HK"/"US"/"SG"). 仅 HK / US / SG 债券账户有数据.
        .route("/api/bond-total-asset", post(trd::get_bond_total_asset))
        .route("/api/bond-single-asset", post(trd::get_bond_single_asset))
        .route("/api/bond-position-list", post(trd::get_bond_position_list))
        .route("/api/bond-answer-state", post(trd::get_bond_answer_state))
        .route(
            "/api/bond-trade-reminder",
            post(trd::get_bond_trade_reminder),
        )
        // ── 交易 ──
        .route("/api/accounts", get(trd::get_acc_list))
        // v1.4.74 A2 BUG-013 fix: list-accounts alias（对齐 MCP `futu_list_accounts`）
        .route("/api/list-accounts", get(trd::get_acc_list))
        .route("/api/unlock-trade", post(trd::unlock_trade))
        .route("/api/sub-acc-push", post(trd::sub_acc_push))
        .route("/api/funds", post(trd::get_funds))
        .route("/api/positions", post(trd::get_positions))
        .route("/api/orders", post(trd::get_orders))
        .route("/api/order", post(trd::place_order))
        .route("/api/combo-order", post(trd::place_combo_order))
        .route("/api/modify-order", post(trd::modify_order))
        // v1.4.30: cancel_all_order 便捷端点（= modify_order 带 for_all=true + op=Cancel）
        .route("/api/cancel-all-order", post(trd::cancel_all_order))
        .route("/api/order-fills", post(trd::get_order_fills))
        .route("/api/max-trd-qtys", post(trd::get_max_trd_qtys))
        .route("/api/combo-max-trd-qtys", post(trd::get_combo_max_trd_qtys))
        // v1.4.40 #4 fix: expose reconfirm-order endpoint（daemon handler 已注册但 REST 缺路由）
        .route("/api/reconfirm-order", post(trd::reconfirm_order))
        .route("/api/history-orders", post(trd::get_history_orders))
        .route(
            "/api/history-order-fills",
            post(trd::get_history_order_fills),
        )
        .route("/api/margin-ratio", post(trd::get_margin_ratio))
        .route("/api/order-fee", post(trd::get_order_fee))
        // ── v1.4.32+ daemon admin（Scope::Admin）──
        // 注意：admin endpoint 走 bearer_auth，scope 不对会被拒；未配置
        // key_store 的 legacy 模式也会返回 401。只读非 admin endpoint 才保留
        // legacy unauth 兼容。
        //
        // v1.4.106 codex 0554 F4 [P3] runtime context note:
        // - status: 同步生成 snapshot, <1ms, 无 I/O.
        // - shutdown: 同步 200 + 调 daemon 注入的 shutdown handler, 走 phase4
        //   统一 surface shutdown / await.
        // - reload: 同步阶段清 cipher + bump cipher_state_version (<10ms);
        //   后台 tokio::spawn 跑 refresh_credentials_on_disk 网络 I/O, 写
        //   bridge.last_reload_refresh; ops 看 /api/admin/status 的
        //   last_reload_refresh 字段监控. 自 v1.4.106 起 reload response 不
        //   再 hang 几秒 (老版 await 模式已 retire).
        //
        // POST body 校验: shutdown + reload 仅接受 empty/{}/null,
        // strict_fields::validate_admin_empty_body. 任何 user-supplied 字段
        // 返 400 (handler 完全不读 body, 防 silent-accept).
        .route("/api/admin/status", get(admin::admin_status))
        .route("/api/admin/shutdown", post(admin::admin_shutdown))
        .route("/api/admin/reload", post(admin::admin_reload))
        // v1.4.93 P0-2 (BUG-002): strict field validation for 7 critical
        // endpoints. Runs AFTER bearer_auth (axum layer ordering: this `.layer()`
        // is added BEFORE `.layer(bearer_auth)` -> strict is INNER -> auth runs
        // first). Pre-auth callers can't probe valid field names. Non-strict
        // paths and non-POST methods pass through unmodified.
        .layer(axum::middleware::from_fn(
            crate::strict_fields::strict_field_validation_middleware,
        ))
        .layer(axum::middleware::from_fn_with_state(
            auth_state,
            bearer_auth,
        ))
        .layer(axum::middleware::from_fn(rest_error_envelope_middleware))
        // `/metrics` + `/health` + `/readyz` 都在 bearer_auth 之外
        // （middleware 只过 /api/*）
        //   - `/metrics`：Prometheus 抓取；handler 内自管三态鉴权
        //     (legacy/public 无 token，scope-mode 要 metrics:read/admin)
        //   - `/health`：liveness probe —— 进程 alive 就 200
        //   - `/readyz`：readiness probe —— gateway dispatch ready 才 200，
        //     冷启动期间返 503 避免 LB 打流量进来（v1.4.27 新加）
        .route("/metrics", get(metrics_handler))
        .route("/health", get(health_handler))
        .route("/readyz", get(readyz_handler))
        // v1.4.96 BUG #009 sym 4 hotfix (external reviewer double-tester report 2026-04-26):
        // 之前 unmatched /api/foobar 返默认 axum "Not Found" 纯文本, 用户 /
        // LLM agent 完全不知有哪些 endpoint. v1.4.96 加 fallback handler 返
        // JSON + 列出可用 endpoint 类目 + 文档 URL.
        //
        // 注意: scope-mode 下 bearer_auth 已 fail-closed 拦 /api/* 未注册路径
        // 返 404 + JSON. 本 fallback 兜底 legacy mode + non-/api 路径.
        .fallback(unknown_route_fallback)
        .layer(cors)
        .with_state(state)
}

/// v1.4.96 BUG #009 sym 4 hotfix: 给所有 unmatched 路由返 helpful JSON 404,
/// 列出可用 endpoint 类目 + futuapi.com 文档 URL.
async fn unknown_route_fallback(req: axum::extract::Request) -> impl IntoResponse {
    let path = req.uri().path().to_string();
    let method = req.method().to_string();
    (
        axum::http::StatusCode::NOT_FOUND,
        [(axum::http::header::CONTENT_TYPE, "application/json")],
        axum::Json(serde_json::json!({
            "error": format!("unknown route {method} {path:?}"),
            "hint": "see categories below or full reference at https://www.futuapi.com/reference/rest-api/",
            "categories": {
                "qot (行情)": "/api/quote /api/snapshot /api/kline /api/orderbook /api/ticker /api/option-chain /api/option-quote /api/option-strategy /api/option-strategy-analysis /api/option-strategy-spread /api/history-kline /api/static-info /api/subscribe /api/sub-info /api/market-state /api/capital-flow /api/option-expiration-date /api/warrant /api/ipo-list",
                "trd (交易, scope=acc:read or trade:*)": "/api/accounts /api/funds /api/positions /api/orders /api/order-fills /api/history-orders /api/history-order-fills /api/max-trd-qtys /api/combo-max-trd-qtys /api/margin-ratio /api/order-fee /api/sub-acc-push /api/flow-summary /api/order /api/combo-order /api/modify-order /api/cancel-all-order /api/unlock-trade /api/reconfirm-order",
                "tier-m (mobile-driven, v1.4.94+)": "/api/cash-log /api/cash-detail /api/biz-group /api/margin-info /api/account-flag /api/bond-total-asset /api/bond-single-asset /api/bond-position-list /api/bond-answer-state /api/bond-trade-reminder",
                "sys": "/api/global-state /api/user-info /api/quote-rights /api/delay-statistics /api/ping /api/push-subscriber-info /api/admin/status (admin scope)",
                "infra": "/health (liveness) /readyz (readiness) /metrics (Prometheus) /ws (WebSocket push)"
            },
            "method_hint": "most endpoints are POST with JSON body; /api/accounts /api/list-accounts /api/health /api/global-state are GET. Check the doc URL for exact verb."
        })),
    )
}

/// releasegate f18fc66da BUG-RG-001: axum extractor rejections (empty JSON
/// body, missing/invalid Content-Type, malformed body at extractor layer)
/// happen before our route handlers run, so they used to escape as
/// `text/plain`. Normalize those framework-level failures to the same machine
/// envelope used by handler-level validation.
async fn rest_error_envelope_middleware(req: axum::extract::Request, next: Next) -> Response {
    let resp = next.run(req).await;
    let status = resp.status();
    if !matches!(
        status,
        StatusCode::BAD_REQUEST | StatusCode::UNSUPPORTED_MEDIA_TYPE
    ) {
        return resp;
    }
    let content_type = resp
        .headers()
        .get(header::CONTENT_TYPE)
        .and_then(|v| v.to_str().ok())
        .unwrap_or("");
    if !content_type.starts_with("text/plain") {
        return resp;
    }

    let bytes = match to_bytes(resp.into_body(), 64 * 1024).await {
        Ok(bytes) => bytes,
        Err(err) => {
            let msg =
                format!("REST request body parse error: failed to read rejection body: {err}");
            return (
                status,
                axum::Json(serde_json::json!({
                    "ret_type": -1,
                    "ret_msg": msg,
                    "error": msg,
                })),
            )
                .into_response();
        }
    };
    let raw = String::from_utf8_lossy(&bytes);
    let msg = format!("REST request body parse error: {}", raw.trim());
    (
        status,
        axum::Json(serde_json::json!({
            "ret_type": -1,
            "ret_msg": msg,
            "error": msg,
        })),
    )
        .into_response()
}

/// 启动 REST API 服务，挂载 KeyStore 做 Bearer Token 鉴权 +
/// RuntimeCounters 做限额。
pub async fn start_with_auth(
    listen_addr: &str,
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
) -> std::io::Result<()> {
    start_with_auth_and_admin(
        listen_addr,
        router,
        ws_broadcaster,
        key_store,
        counters,
        None,
    )
    .await
}

/// v1.4.32+ 同 `start_with_auth`，但额外接 admin_status_provider。
/// 让 `/api/admin/status` 能返回实时健康快照。
/// `push_health_snapshot_provider` 仍需走 `start_with_auth_full_admin` 注入；
/// 未注入时 `/api/push-subscriber-info` loud-fail 503。
pub async fn start_with_auth_and_admin(
    listen_addr: &str,
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
    admin_status_provider: Option<crate::adapter::AdminStatusProvider>,
) -> std::io::Result<()> {
    start_with_auth_full_admin(
        listen_addr,
        router,
        ws_broadcaster,
        key_store,
        counters,
        RestAdminHooks {
            admin_status_provider,
            ..RestAdminHooks::default()
        },
    )
    .await
}

/// v1.4.32+ 完整 admin 入口：同时接 status provider + reload handler。
///
/// v1.4.83 §9 Phase 2 F5: 加 `push_health_snapshot_provider` 参数支持
/// `/api/push-subscriber-info` 返真实 push 通道健康 state。
pub async fn start_with_auth_full_admin(
    listen_addr: &str,
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
    hooks: RestAdminHooks,
) -> std::io::Result<()> {
    let scope_mode = key_store.is_configured();
    let app = build_router_with_auth_full_admin(router, ws_broadcaster, key_store, counters, hooks);
    let listener = tokio::net::TcpListener::bind(listen_addr).await?;
    tracing::info!(
        addr = %listen_addr,
        scope_mode,
        "REST API 服务已启动 (WebSocket: /ws)"
    );
    if !scope_mode {
        warn_legacy_mode(listen_addr);
    }
    axum::serve(
        listener,
        app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
    )
    .await
}

/// 同 [`start_with_auth_full_admin`]，但支持 daemon 统一 shutdown 信号。
pub async fn start_with_auth_full_admin_until_shutdown(
    listen_addr: &str,
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
    key_store: Arc<KeyStore>,
    counters: Arc<RuntimeCounters>,
    hooks: RestAdminHooks,
    shutdown_rx: watch::Receiver<bool>,
) -> std::io::Result<()> {
    let scope_mode = key_store.is_configured();
    let app = build_router_with_auth_full_admin(router, ws_broadcaster, key_store, counters, hooks);
    let listener = tokio::net::TcpListener::bind(listen_addr).await?;
    tracing::info!(
        addr = %listen_addr,
        scope_mode,
        "REST API 服务已启动 (WebSocket: /ws)"
    );
    if !scope_mode {
        warn_legacy_mode(listen_addr);
    }
    axum::serve(
        listener,
        app.into_make_service_with_connect_info::<std::net::SocketAddr>(),
    )
    .with_graceful_shutdown(rest_shutdown_requested(shutdown_rx))
    .await
}

fn warn_legacy_mode(listen_addr: &str) {
    tracing::warn!("REST API in legacy mode (no keys.json); mutating endpoints are blocked");
    // v1.4.93 P0-5 (NEW-C-02): WS 也对齐 mutating-blocked policy 的"loud
    // unauth"信号 — REST `/ws` route 在 legacy 模式接受 unauthenticated
    // handshake (no-token / wrong-bearer / bogus-query 都 HTTP 101)，未授权
    // 客户端可接收 live push。本版不 reject（保持向后兼容，未来 major 版
    // 默认 reject），但补 startup loud WARN + CHANGELOG 公告。
    tracing::warn!("{}", LEGACY_WS_WARN_MESSAGE);
    // v1.4.86 SEC-003 Q4 真 fix: legacy mode 下 mutating endpoint 硬门禁
    // (/api/order / modify-order / cancel-all-order / unlock-trade /
    // reconfirm-order / admin/*). 只读 endpoint 继续 legacy 允许.
    tracing::warn!(
        listen_addr = %listen_addr,
        readonly_endpoints = "qot/account/order-read",
        blocked_mutating_endpoints = "/api/order,/api/modify-order,/api/cancel-all-order,/api/unlock-trade,/api/reconfirm-order,/api/admin/*",
        ws_legacy_unauthenticated = true,
        migration = "futucli gen-key --id my-key --scopes qot:read,acc:read,trade:real; restart with --rest-keys-file /path/to/keys.json",
        "REST API legacy mode: no keys.json configured; read endpoints remain unauthenticated, mutating/admin endpoints return 401, /ws still accepts unauthenticated connections for compatibility and v2 will default-reject"
    );
}

async fn rest_shutdown_requested(mut shutdown_rx: watch::Receiver<bool>) {
    loop {
        if *shutdown_rx.borrow() {
            tracing::info!("REST API server stopped by shutdown signal");
            return;
        }
        if shutdown_rx.changed().await.is_err() {
            tracing::info!("REST API server stopped after shutdown sender dropped");
            return;
        }
    }
}

#[cfg(test)]
mod tests;