futu_rest/

server.rs

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

use std::sync::Arc;

use axum::Router;
use axum::body::to_bytes;
use axum::http::request::Parts;
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 tower_http::cors::{Any, CorsLayer};

/// v1.4.102 BUG-008 + codex 25 F5 / 30 F3 / 31 F6 (P2/P3) refine: loopback
/// origin predicate, 严格 URL parsing.
///
/// 之前手写 strip + split, 接受 `http://[::1].evil.com` (前缀 `[::1]` 被 split
/// 后第一段是 `[`, 但 starts_with("[::1]") 返 true). 改用 url crate 严格
/// parse host, 比对完整 host 而非 prefix.
///
/// **接受**: `http://127.0.0.1[:port]` / `http://localhost[:port]` /
/// `http://[::1][:port]` / `https://` 同等. 不接受 fragment / path / userinfo
/// 等其他形态.
///
/// **不接受**: `http://[::1].evil.com` / `http://localhost.evil.com` /
/// `http://127.0.0.1.evil.com`.
fn is_loopback_origin(origin: &axum::http::HeaderValue, _request_parts: &Parts) -> bool {
    let Ok(s) = origin.to_str() else {
        return false;
    };
    is_loopback_origin_str(s)
}

/// v1.4.102 codex 25 F5 / 30 F3 / 31 F6 strict parser (REST + WS 共用).
/// 严格匹配 host, 不接受 prefix / suffix-混入的 evil hosts.
///
/// 实装策略 (避免引新 url crate dep): 1) strip scheme; 2) 剩下部分必须
/// 完全等于 "127.0.0.1[:port]" / "localhost[:port]" / "[::1][:port]";
/// 3) port 必须纯 ASCII digit 1-5 位; 4) 不允许 / ? # 任何 path / query /
/// fragment / 其他字符.
pub(crate) fn is_loopback_origin_str(s: &str) -> bool {
    let after_scheme = match s
        .strip_prefix("http://")
        .or_else(|| s.strip_prefix("https://"))
    {
        Some(rest) => rest,
        None => return false,
    };
    // 不允许任何 path / query / fragment 或 userinfo 形式 (origin 不应有这些)
    if after_scheme.contains('/')
        || after_scheme.contains('?')
        || after_scheme.contains('#')
        || after_scheme.contains('@')
    {
        return false;
    }
    // 拆出 host 和 optional port. IPv6 [::1] 形式特殊处理.
    // **port 区分 None (无 :) vs Some("") (有 : 但空)** — 两者不一样:
    //   - "http://localhost" → port = None (no separator) → OK 用默认 80/443
    //   - "http://localhost:" → port = Some("") (有 : 但空) → 拒 (用户写错)
    //   - "http://localhost:8080" → port = Some("8080") → 校验 1..=65535
    let (host, port_opt): (&str, Option<&str>) =
        if let Some(rest) = after_scheme.strip_prefix("[::1]") {
            if rest.is_empty() {
                ("[::1]", None)
            } else if let Some(p) = rest.strip_prefix(':') {
                ("[::1]", Some(p))
            } else {
                return false;
            }
        } else if let Some((h, p)) = after_scheme.rsplit_once(':') {
            (h, Some(p))
        } else {
            (after_scheme, None)
        };
    if !matches!(host, "127.0.0.1" | "localhost" | "[::1]") {
        return false;
    }
    // v1.4.102 codex 41 F4 (P3): port 必须 (a) 缺 OR (b) 解析为 1..=65535.
    // 之前用 port_str.is_empty() 判断, 但分不出 "http://localhost" (None) vs
    // "http://localhost:" (Some("")) — 两者都 port_str="". 现在 None 接受,
    // Some("") / Some("0") / Some("99999") / 非数字 全拒.
    if let Some(port_str) = port_opt {
        match port_str.parse::<u16>() {
            Ok(p) if p >= 1 => {} // 1..=65535 OK
            _ => return false,    // 空 / 0 / 非数字 / 超 u16 → 拒
        }
    }
    true
}

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_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")
}

/// 构建 REST API 路由（无鉴权，向后兼容）
pub fn build_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` 时等价于 `build_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）。
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_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_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));

    // v1.4.102 BUG-008 fix (P1, leaf v1.4.100 报告): protected REST endpoint
    // 默认不再返 wildcard `Access-Control-Allow-Origin: *`. 历史: 任何 evil
    // origin 都能通过 CORS preflight 拿 200, 配合 cookie / token 暴露链接
    // 增加浏览器侧攻击面.
    //
    // **新策略**:
    //   1. `FUTU_REST_ALLOWED_ORIGINS=https://app.example.com,http://localhost:3000`
    //      显式 allowlist (推荐).
    //   2. key_store.is_configured() (auth enabled) + 未设 env → loopback only
    //      (http://127.0.0.1, http://localhost, http://[::1] + 任意端口).
    //   3. legacy unauth + 未设 env → 仍 wildcard (保持 backward compat,
    //      但启动 warn 推荐配置 allowlist).
    use axum::http::HeaderValue;
    use tower_http::cors::AllowOrigin;
    let cors_allow_origin: AllowOrigin = match std::env::var("FUTU_REST_ALLOWED_ORIGINS") {
        Ok(raw) if !raw.trim().is_empty() => {
            // v1.4.104 eli P1-004 (P1) fix: 用户传 FUTU_REST_ALLOWED_ORIGINS='*'
            // 触发 tower-http panic (CorsLayer::list 不接受 '*' as Origin), panic
            // 被 global hook 吞 → REST task 死, 但 gRPC/TCP/WS/telnet 在同毫秒
            // 内继续 bind 成功 → daemon "half-dead" silent failure (用户 /health
            // 不通以为整 daemon 死, 实际其他 surface 在响应).
            //
            // 修法: 检测 '*' / 'any' / 'all' 字符串作 wildcard 意图早期, 直接
            // 用 AllowOrigin::any() 而不是 AllowOrigin::list([*]) (后者 panic).
            let raw_trimmed = raw.trim();
            if matches!(
                raw_trimmed.to_ascii_lowercase().as_str(),
                "*" | "any" | "all"
            ) {
                tracing::warn!(
                    raw = raw_trimmed,
                    "REST CORS: FUTU_REST_ALLOWED_ORIGINS='{}' detected as wildcard; \
                     falling through to AllowOrigin::any() (v1.4.104 eli P1-004 P1 fix \
                     防 tower-http panic). 推荐改 explicit origins (e.g. \
                     'https://app.example.com'). 仅当 daemon 确认对所有 origin 开放\
                     (development) 才用 wildcard.",
                    raw_trimmed
                );
                AllowOrigin::any()
            } else {
                let mut origins: Vec<HeaderValue> = Vec::new();
                let mut had_invalid = false;
                for s in raw.split(',').map(|s| s.trim()).filter(|s| !s.is_empty()) {
                    // v1.4.104 eli P1-004: 单元素是 '*' / 'any' 也提前拦
                    if matches!(s.to_ascii_lowercase().as_str(), "*" | "any" | "all") {
                        tracing::warn!(
                            origin = s,
                            "FUTU_REST_ALLOWED_ORIGINS: 单元素 wildcard '*' 不能与具体 origin \
                             混用 (tower-http panic). 整批 fallback 到 AllowOrigin::any() \
                             (v1.4.104 eli P1-004 P1 fix). 请改纯 explicit origins."
                        );
                        return Router::new(); // 不应到达, 防御
                    }
                    match HeaderValue::from_str(s) {
                        Ok(hv) => origins.push(hv),
                        Err(e) => {
                            had_invalid = true;
                            tracing::warn!(
                                origin = s,
                                error = %e,
                                "FUTU_REST_ALLOWED_ORIGINS: invalid origin string, skipped"
                            );
                        }
                    }
                }
                if origins.is_empty() {
                    tracing::warn!(
                        had_invalid,
                        "FUTU_REST_ALLOWED_ORIGINS env was set but no valid origins parsed; \
                         falling back to loopback default"
                    );
                    AllowOrigin::predicate(is_loopback_origin)
                } else {
                    tracing::info!(
                        count = origins.len(),
                        "REST CORS: allowlist from FUTU_REST_ALLOWED_ORIGINS env"
                    );
                    AllowOrigin::list(origins)
                }
            }
        }
        _ => {
            if key_store.is_configured() {
                tracing::info!(
                    "REST CORS: auth enabled + no FUTU_REST_ALLOWED_ORIGINS env → loopback only \
                     (http://127.0.0.1 / http://localhost / http://[::1], any port). \
                     Set FUTU_REST_ALLOWED_ORIGINS=https://app.example.com to allow browser \
                     UI from other origins (BUG-008 fix)."
                );
                AllowOrigin::predicate(is_loopback_origin)
            } else {
                tracing::warn!(
                    "REST CORS: legacy unauth + no FUTU_REST_ALLOWED_ORIGINS env → wildcard `*` \
                     (backward-compat). 推荐传 --rest-keys-file 启用 Bearer auth + \
                     FUTU_REST_ALLOWED_ORIGINS=<your-origin> 收紧 (BUG-008 fix)."
                );
                AllowOrigin::any()
            }
        }
    };
    let cors = CorsLayer::new()
        .allow_origin(cors_allow_origin)
        .allow_methods(Any)
        .allow_headers(Any);

    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/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 (eli 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/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))
        // 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 模式允许通过但日志 WARN。
        //
        // v1.4.106 codex 0554 F4 [P3] runtime context note:
        // - status: 同步生成 snapshot, <1ms, 无 I/O.
        // - shutdown: 同步 200 + tokio::spawn 1s 后 std::process::exit(0).
        // - 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 抓取（无需 token，运维用 firewall 控访问）
        //   - `/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 (eli 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/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/margin-ratio /api/order-fee /api/sub-acc-push /api/flow-summary /api/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 服务，返回 WsBroadcaster 供外部推送事件
pub async fn start(listen_addr: &str, router: Arc<RequestRouter>) -> std::io::Result<()> {
    let ws_broadcaster = Arc::new(WsBroadcaster::new(1024));
    let app = build_router(router, ws_broadcaster);
    let listener = tokio::net::TcpListener::bind(listen_addr).await?;
    tracing::info!(addr = %listen_addr, "REST API 服务已启动 (WebSocket: /ws)");
    axum::serve(listener, app).await
}

/// 启动 REST API 服务并返回 WsBroadcaster（供外部推送系统使用）
pub async fn start_with_broadcaster(
    listen_addr: &str,
    router: Arc<RequestRouter>,
    ws_broadcaster: Arc<WsBroadcaster>,
) -> std::io::Result<()> {
    let app = build_router(router, ws_broadcaster);
    let listener = tokio::net::TcpListener::bind(listen_addr).await?;
    tracing::info!(addr = %listen_addr, "REST API 服务已启动 (WebSocket: /ws)");
    axum::serve(listener, app).await
}

/// 同 `start_with_broadcaster`，但挂载 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` 能返回实时健康快照。
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 {
        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"
        );
    }
    axum::serve(listener, app).await
}

#[cfg(test)]
mod tests;