futu_rest/routes/qot/

misc.rs

//! Split from routes/qot.rs: misc.

use axum::extract::{Extension, Json, State};
use axum::http::StatusCode;
use futu_auth::KeyRecord;
use serde_json::Value;
use std::sync::Arc;

use crate::caller_context::CallerContext;
use futu_core::proto_id;

use super::*;

use super::subscribe::body_requests_unsub_all;

pub(super) fn normalize_financial_calendar_rest_body_for_internal_proto(body: Value) -> Value {
    match body {
        Value::Object(mut obj) if obj.len() == 1 => match obj.remove("c2s") {
            Some(Value::Object(c2s)) => Value::Object(c2s),
            Some(c2s) => {
                let mut restored = serde_json::Map::new();
                restored.insert("c2s".to_string(), c2s);
                Value::Object(restored)
            }
            None => Value::Object(obj),
        },
        other => other,
    }
}

/// POST /api/unsubscribe-all — 反订阅（或 unsub_all）
///
/// 复用 qot_sub proto，需要用户传 `is_sub_or_un_sub=false` 或
/// `is_unsub_all=true`。这是给 REST 直接调用者的便捷端点。
///
/// **v1.4.90 P0-B fix**: 用 `REST_SHARED_CONN` 替代 `state.next_conn_id()` —
/// 必须与 subscribe path 用同一 conn_id, 否则 SubscriptionManager 找不到任何
/// 挂载, unsubscribe 静默 no-op, quota 永不释放.
///
/// **v1.4.104 codex round 3 F1 (P1) fix**: `/api/unsubscribe` 是 sibling
/// route 也复用 QOT_SUB proto + REST_SHARED_CONN, 之前 F5 fix 只在
/// `subscribe()` 加 `body_requests_unsub_all()` reject — 用户切到
/// `/api/unsubscribe` 仍可 process-wide unsub all REST callers' subs.
/// 真 runtime path bypass. 现在两条 REST 路径**统一**走相同 reject.
pub async fn unsubscribe(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(body): Json<Value>,
) -> RawApiResult {
    // codex round 3 F1: 拒绝 REST is_unsub_all=true (process-wide cross-caller
    // 影响, REST_SHARED_CONN 共享 bucket). 与 subscribe() route 行为一致.
    if body_requests_unsub_all(&body) {
        return Err((
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": "/api/unsubscribe with is_unsub_all=true is **REST process-wide** — \
                          all REST callers share REST_SHARED_CONN (v1.4.90 P0-B), so \
                          清掉一个 = 清掉**所有 REST clients** 的 qot 订阅 (跨 caller \
                          影响). v1.4.104 codex round 3 F1 P1 fix: 默认 reject (与 \
                          /api/subscribe is_unsub_all reject 一致, 防 sibling-route bypass). \
                          替代方案:\n  \
                          (a) 单 symbol unsubscribe: 列具体 sec_list + sub_type_list + \
                              is_sub_or_un_sub=false (per-key safe);\n  \
                          (b) MCP / gRPC / WS surface 调 unsub_all (各 caller 有自己 conn_id). \
                          REST 当前没有 process-wide opt-in 或 admin clear endpoint.",
                "v1.4.104_audit_round3_f1_fix": true,
                "alternatives": [
                    "use explicit security_list + sub_type_list + is_sub_or_un_sub=false",
                    "use MCP / gRPC / WS for per-caller unsub_all",
                ],
            })),
        ));
    }
    // codex 0522 F3 v1.4.106: build CallerContext per-call.
    let ctx = CallerContext::from_key_record(rec.as_deref().map(|r| r.as_ref()));
    proto_request_shared_conn_raw::<qot_sub::Request, qot_sub::Response>(
        &state,
        proto_id::QOT_SUB,
        Some(body),
        Some(&ctx),
    )
    .await
}

/// v1.4.74 A2 BUG-013 fix: POST /api/query-subscription — 查订阅状态
///
/// 对齐 MCP `futu_query_subscription`。body 可含 `is_req_all_conn: bool` 决定
/// 查当前连接 or 所有连接。
///
/// **v1.4.83 §7 fix**（双 tester v1.4.81 §7 tracking 撒谎根治）：**REST 默认
/// `is_req_all_conn=true`**（REST stateless，每次请求分配新 virtual conn_id，
/// 只查当前 conn_id 的订阅总是空 → silent confusing）。用户显式传
/// `{"is_req_all_conn": false}` 限制到当前 conn_id。
///
/// 对齐 v1.4.78 B3 `/api/sub-info` 文档化：sub-info per-conn by design；
/// query-subscription **推荐生产用**，因为 REST 用户没有长期 conn_id 概念.
///
/// 返回结构与 `/api/sub-info` 类似，但 `/api/sub-info` 是 GET 不传 body
/// （v1.4.83 起 GET 也默认 all-conn），POST query-subscription 更灵活。
pub async fn query_subscription(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> RawApiResult {
    inject_default_is_req_all_conn(&mut body, true);
    // v1.4.90 P0-B: 用 REST_SHARED_CONN — is_req_all_conn=false 时返本 conn_id
    // 订阅, 必须与 subscribe 用同一 conn_id 才有非空结果.
    // codex 0522 F3 v1.4.106: 接 ctx 让 handler 识别 caller key.
    let ctx = CallerContext::from_key_record(rec.as_deref().map(|r| r.as_ref()));
    proto_request_shared_conn_raw::<qot_get_sub_info::Request, qot_get_sub_info::Response>(
        &state,
        proto_id::QOT_GET_SUB_INFO,
        Some(body),
        Some(&ctx),
    )
    .await
}

/// v1.4.83 §7: inject default `is_req_all_conn=true` 到 body 的 c2s 嵌套层。
/// 若用户已显式传（任何值），保留用户值不覆盖。
pub(super) fn inject_default_is_req_all_conn(body: &mut Value, default: bool) {
    let obj = match body.as_object_mut() {
        Some(o) => o,
        None => return, // 非 object body (比如 null / 数组) 不动
    };
    // 优先处理 c2s 嵌套
    if let Some(Value::Object(c2s)) = obj.get_mut("c2s") {
        c2s.entry("is_req_all_conn").or_insert(Value::Bool(default));
        return;
    }
    // flat body (adapter maybe_wrap_flat_body_as_c2s 之前状态): 直接在顶层
    // 加 is_req_all_conn, 稍后 wrap 时会进入 c2s
    obj.entry("is_req_all_conn").or_insert(Value::Bool(default));
}

/// v1.4.74 A2 BUG-013 fix: POST /api/list-plates — 列板块
///
/// 是 `/api/plate-set` 的 alias（REST 早期 endpoint 名，对齐 MCP `futu_list_plates`）。
pub async fn list_plates(State(state): State<RestState>, Json(body): Json<Value>) -> RawApiResult {
    adapter::proto_request_raw::<
        futu_proto::qot_get_plate_set::Request,
        futu_proto::qot_get_plate_set::Response,
    >(&state, proto_id::QOT_GET_PLATE_SET, Some(body))
    .await
}

// ===================================================================
// v1.4.98 (mobile-source-audit Phase 2) — quote 类新 endpoint REST routes
// ===================================================================

/// v1.4.98 T2-2: 无风险利率 (期权定价).
///
/// **POST /api/risk-free-rate** (无 body / 可选 `c2s.rate_time`).
///
/// 返 HK/US/JP 3 市场无风险利率 (百分比 + raw uint64). backend cmd 20231
/// (注释明标"无加密"). 期权 trader 做 Black-Scholes 定价必备数据.
pub async fn get_risk_free_rate(
    State(state): State<RestState>,
    body: Option<Json<Value>>,
) -> RawApiResult {
    let body_val = body.map(|Json(v)| v);
    adapter::proto_request_raw::<
        futu_backend::proto_internal::risk_free_rate::DaemonGetRiskFreeRateReq,
        futu_backend::proto_internal::risk_free_rate::DaemonGetRiskFreeRateRsp,
    >(&state, proto_id::QOT_GET_RISK_FREE_RATE, body_val)
    .await
}

/// v1.4.115: 财报日历视图 (mobile/moomoo read-only extension).
///
/// **POST /api/financial-calendar** with
/// `financial_calendar::GetFinancialStatementCalendarViewReq` JSON shape.
/// `begin_date <= financial date < end_date`; dates use `YYYYMMDD`.
pub async fn get_financial_calendar(
    State(state): State<RestState>,
    Json(body): Json<Value>,
) -> RawApiResult {
    adapter::proto_request_raw_spec_body::<
        futu_backend::proto_internal::financial_calendar::GetFinancialStatementCalendarViewReq,
        futu_backend::proto_internal::financial_calendar::GetFinancialStatementCalendarViewRsp,
    >(
        &state,
        futu_core::proto_id::QOT_GET_FINANCIAL_CALENDAR_VIEW_INTERNAL,
        Some(normalize_financial_calendar_rest_body_for_internal_proto(
            body,
        )),
    )
    .await
}

/// v1.4.115: 指定股票财报日历搜索 (mobile/moomoo read-only extension).
///
/// **POST /api/financial-calendar-target** with
/// `financial_calendar::SearchTargetStockFinancialCalendarReq` JSON shape.
pub async fn search_target_financial_calendar(
    State(state): State<RestState>,
    Json(body): Json<Value>,
) -> RawApiResult {
    adapter::proto_request_raw_spec_body::<
        futu_backend::proto_internal::financial_calendar::SearchTargetStockFinancialCalendarReq,
        futu_backend::proto_internal::financial_calendar::SearchTargetStockFinancialCalendarRsp,
    >(
        &state,
        futu_core::proto_id::QOT_SEARCH_TARGET_FINANCIAL_CALENDAR,
        Some(normalize_financial_calendar_rest_body_for_internal_proto(
            body,
        )),
    )
    .await
}

/// v1.4.98 T2-1: 摆盘步长 SpreadTable (cmd 6503).
///
/// **POST /api/spread-table** (无 body / 可选 reserved). 返全部价位表 list,
/// 每条含 spread_code + spread_item_list (price_from/to + value, 价格已 / 1e9
/// 还原成 f64). 客户端 ModifyOrder/PlaceOrder 校验价格合法性必备.
pub async fn get_spread_table(
    State(state): State<RestState>,
    body: Option<Json<Value>>,
) -> RawApiResult {
    let body_val = body.map(|Json(v)| v);
    adapter::proto_request_raw::<
        futu_backend::proto_internal::spread_table_6503::DaemonGetSpreadTableReq,
        futu_backend::proto_internal::spread_table_6503::DaemonGetSpreadTableRsp,
    >(&state, proto_id::QOT_GET_SPREAD_TABLE, body_val)
    .await
}

/// v1.4.98 T2-3: 逐笔统计 TickerStatistic (cmd 6365).
///
/// **POST /api/ticker-statistic** (`{"c2s": {"symbol": "HK.00700", ...}}`).
/// daemon 内部 static_cache 解析 stock_id, 然后调 backend cmd 6365. 返均价 /
/// 成交量 / 主买/主卖/中性量等统计概览.
///
/// **前置**: symbol 必须先 subscribe / get_static_info 触发 static_cache 填充.
pub async fn get_ticker_statistic(
    State(state): State<RestState>,
    Json(body): Json<Value>,
) -> RawApiResult {
    adapter::proto_request_raw::<
        futu_backend::proto_internal::ticker_statistic_daemon::DaemonGetTickerStatisticReq,
        futu_backend::proto_internal::ticker_statistic_daemon::DaemonGetTickerStatisticRsp,
    >(&state, proto_id::QOT_GET_TICKER_STATISTIC, Some(body))
    .await
}

/// v1.4.106 codex 0500 ζ23-redo: 逐笔统计 Detail (cmd 6366).
///
/// **POST /api/ticker-statistic-detail** (`{"c2s": {"symbol": "HK.00700",
/// "ticker_time": <u64 from /api/ticker-statistic>, "select_num": 0,
/// "data_from": 0, "data_max_count": 20, ...}}`).
/// daemon 内部 static_cache 解析 stock_id, 然后调 backend cmd 6366 拿
/// 价位级 detail 列表 (DetailItem with price / volume / ratio).
///
/// **前置**: symbol 必须先 subscribe / get_static_info 触发 static_cache 填充.
/// 配套 cmd 6365: 客户端先 call /api/ticker-statistic 拿 ticker_time,
/// 再 call /api/ticker-statistic-detail 同 ticker_time 拿这个时点的价位
/// 分布. 也可省略 ticker_time 用 backend 默认 (latest available).
pub async fn get_ticker_statistic_detail(
    State(state): State<RestState>,
    Json(body): Json<Value>,
) -> RawApiResult {
    adapter::proto_request_raw::<
        futu_backend::proto_internal::ticker_statistic_daemon::DaemonGetTickerStatisticDetailReq,
        futu_backend::proto_internal::ticker_statistic_daemon::DaemonGetTickerStatisticDetailRsp,
    >(
        &state,
        proto_id::QOT_GET_TICKER_STATISTIC_DETAIL,
        Some(body),
    )
    .await
}