futu_rest/

server.rs

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

use std::sync::Arc;

mod cors;
mod metrics;
mod probes;
mod startup;

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

use metrics::metrics_handler;
use probes::{health_handler, readyz_handler};
pub use startup::{
    start_with_auth, start_with_auth_and_admin, start_with_auth_full_admin,
    start_with_auth_full_admin_until_shutdown,
};

/// 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.";

/// 构建 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/quote-capability", get(sys::get_quote_capability))
        .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/financial-calendar", post(qot::get_financial_calendar))
        .route(
            "/api/financial-calendar-target",
            post(qot::search_target_financial_calendar),
        )
        .route("/api/earnings-calendar", post(qot::get_earnings_calendar))
        .route(
            "/api/macro-indicator-list",
            post(qot::get_macro_indicator_list),
        )
        .route(
            "/api/macro-indicator-history",
            post(qot::get_macro_indicator_history),
        )
        .route(
            "/api/fed-watch-target-rate",
            post(qot::get_fed_watch_target_rate),
        )
        .route("/api/fed-watch-dot-plot", post(qot::get_fed_watch_dot_plot))
        .route("/api/earnings-beat-rank", post(qot::get_earnings_beat_rank))
        .route("/api/dividend-rank", post(qot::get_dividend_rank))
        .route("/api/dividend-calendar", post(qot::get_dividend_calendar))
        .route("/api/economic-calendar", post(qot::get_economic_calendar))
        .route("/api/us-pre-market-rank", post(qot::get_us_pre_market_rank))
        .route(
            "/api/us-after-hours-rank",
            post(qot::get_us_after_hours_rank),
        )
        .route("/api/us-overnight-rank", post(qot::get_us_overnight_rank))
        .route("/api/top-movers-rank", post(qot::get_top_movers_rank))
        .route("/api/hot-list", post(qot::get_hot_list))
        .route("/api/short-selling-rank", post(qot::get_short_selling_rank))
        .route("/api/period-change-rank", post(qot::get_period_change_rank))
        .route(
            "/api/high-dividend-soe-rank",
            post(qot::get_high_dividend_soe_rank),
        )
        .route("/api/institution-list", post(qot::get_institution_list))
        .route(
            "/api/institution-profile",
            post(qot::get_institution_profile),
        )
        .route(
            "/api/institution-distribution",
            post(qot::get_institution_distribution),
        )
        .route(
            "/api/institution-holding-change",
            post(qot::get_institution_holding_change),
        )
        .route(
            "/api/institution-holding-list",
            post(qot::get_institution_holding_list),
        )
        .route("/api/ark-fund-holding", post(qot::get_ark_fund_holding))
        .route("/api/ark-stock-dynamic", post(qot::get_ark_stock_dynamic))
        .route(
            "/api/ark-active-transaction",
            post(qot::get_ark_active_transaction),
        )
        .route("/api/rating-change", post(qot::get_rating_change))
        .route(
            "/api/industrial-chain-list",
            post(qot::get_industrial_chain_list),
        )
        .route(
            "/api/industrial-chain-detail",
            post(qot::get_industrial_chain_detail),
        )
        .route(
            "/api/industrial-chain-by-plate",
            post(qot::get_industrial_chain_by_plate),
        )
        .route(
            "/api/industrial-plate-info",
            post(qot::get_industrial_plate_info),
        )
        .route(
            "/api/industrial-plate-stock",
            post(qot::get_industrial_plate_stock),
        )
        .route("/api/heat-map-data", post(qot::get_heat_map_data))
        .route(
            "/api/rise-fall-distribution",
            post(qot::get_rise_fall_distribution),
        )
        .route("/api/user-security", post(qot::get_user_security))
        .route(
            "/api/user-security-groups",
            post(qot::get_user_security_group),
        )
        .route("/api/stock-filter", post(qot::stock_filter))
        .route("/api/ipo-list", post(qot::get_ipo_list))
        .route("/api/ipo-calendar", post(qot::get_ipo_calendar))
        .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))
        .route("/api/cancel-order", post(trd::cancel_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 /api/ipo-calendar /api/financial-calendar /api/financial-calendar-target",
                "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-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/quote-capability /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()
}

#[cfg(test)]
mod tests;