futu_rest/routes/trd/

flow_summary.rs

//! REST `/api/flow-summary` 路由与 date-range fanout。
//!
//! 这是 Trd_FlowSummary 的 endpoint-specific 聚合逻辑：单日请求直接转发，
//! date-range 请求在 REST 层按日 fanout 后聚合，避免把业务 fanout 放进通用 adapter。

use std::sync::Arc;

use axum::Json;
use axum::extract::{Extension, State};
use axum::http::StatusCode;
use serde_json::Value;

use futu_auth::KeyRecord;
use futu_core::proto_id;
use futu_proto::trd_flow_summary;

use crate::adapter::{self, RestState};

use super::ApiResult;
use super::card_num::normalize_and_resolve_card_num_for_route;
use super::validation::{
    read_handler_acc_id_check, validate_header_trd_env_present, validate_header_trd_market,
};

/// POST /api/flow-summary — 账户资金流水（v1.4.30 P2）
///
/// **v1.4.93 Jackie feedback Problem 1 (date-range support)**:
/// proto `Trd_FlowSummary` 一次只接一天 (`clearing_date`). 之前 CLI v1.4.32
/// `--date-range` 已实装客户端循环, REST 层之前未暴露 → jackie 报告需 10 次
/// 单日 call. 本版加 REST adapter 层客户端循环, 接受:
///
/// ```json
/// // v1 单日 (向后兼容)
/// {"c2s":{"header":{...},"clearing_date":"2026-04-22"}}
///
/// // v2 范围 (v1.4.93 新加, 等价 CLI --date-range)
/// {"c2s":{"header":{...},"begin_date":"2026-04-15","end_date":"2026-04-22"}}
/// ```
///
/// 范围模式: 跳周末, 31 天上限 (防 bot 脚本无意打几百天被服务端 rate-limit),
/// 循环 fetch 单日 → 聚合 `flow_summary_info_list` 返一个 response.
/// `direction` (`cash_flow_direction`) 顶层 c2s 字段透传到每天调用.
///
/// 防 backend 无 native range 接口 — 这是 client-side fanout, 与 proto 一致.
pub async fn get_flow_summary(
    State(state): State<RestState>,
    rec: Option<Extension<Arc<KeyRecord>>>,
    Json(mut body): Json<Value>,
) -> ApiResult {
    normalize_and_resolve_card_num_for_route(&state, &rec, &mut body, "/api/flow-summary")?;
    // v1.4.102 codex 32 F2 (P2) fix: flow-summary 也加 trd_env / market 预校验.
    // 之前漏挂 → fanout 把缺 trd_env 包成 partial/all-failed silent. 与 BUG-005 +
    // 26 F1 read endpoint 同步.
    validate_header_trd_market(&body, "/api/flow-summary")?;
    validate_header_trd_env_present(&body, "/api/flow-summary")?;
    read_handler_acc_id_check(
        &state,
        rec.as_deref().map(|r| r.as_ref()),
        &body,
        "/api/flow-summary",
    )?;
    // v1.4.93 Jackie #1: 检测 date_range 模式 (begin_date + end_date)
    if let Some(range_resp) = maybe_handle_flow_summary_date_range(&state, &body).await? {
        return Ok(range_resp);
    }
    adapter::proto_request::<trd_flow_summary::Request, trd_flow_summary::Response>(
        &state,
        proto_id::TRD_FLOW_SUMMARY,
        Some(body),
    )
    .await
}

/// v1.4.93 Jackie #1: 客户端循环实装 `/api/flow-summary` 的 date-range 模式.
///
/// 检测 body 含 `begin_date` + `end_date` (顶层或 `c2s` 内, 兼容 normalize 前后)
/// → 跳周末 / 31 天上限 / 每日单调 fetch / 聚合返聚合 response.
///
/// 返 `Ok(Some(resp))` = range mode 处理完成; `Ok(None)` = 单日模式 (调用方继续
/// 走原 adapter 路径); `Err((status, body))` = 输入错误 (begin>end / 跨度过大).
///
/// 为什么不放 adapter 层: adapter 是通用 proto 转发, 客户端 fanout (聚合多次
/// proto call) 是 endpoint-specific 业务逻辑, 应在 endpoint handler.
async fn maybe_handle_flow_summary_date_range(
    state: &RestState,
    body: &Value,
) -> Result<Option<Json<Value>>, (StatusCode, Json<Value>)> {
    // 抽 begin_date / end_date — 兼容顶层 (flat) 和 c2s 内
    let pick = |key: &str| -> Option<String> {
        body.pointer(&format!("/c2s/{key}"))
            .or_else(|| body.pointer(&format!("/{key}")))
            .and_then(|v| v.as_str())
            .map(|s| s.to_string())
    };
    let (Some(begin), Some(end)) = (pick("begin_date"), pick("end_date")) else {
        return Ok(None); // 单日模式
    };
    let date_from = chrono::NaiveDate::parse_from_str(&begin, "%Y-%m-%d").map_err(|e| {
        (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": format!("begin_date 格式错: {e} (需 YYYY-MM-DD)")
            })),
        )
    })?;
    let date_to = chrono::NaiveDate::parse_from_str(&end, "%Y-%m-%d").map_err(|e| {
        (
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": format!("end_date 格式错: {e} (需 YYYY-MM-DD)")
            })),
        )
    })?;
    if date_to < date_from {
        return Err((
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": format!("end_date {date_to} 不能早于 begin_date {date_from}"),
            })),
        ));
    }
    let span_days = (date_to - date_from).num_days();
    if span_days > 31 {
        return Err((
            StatusCode::BAD_REQUEST,
            Json(serde_json::json!({
                "error": format!(
                    "date 范围跨度 {span_days} 天超过 31 天上限 (防 bot 误调用被服务端 \
                     rate-limit. 对齐 CLI --date-range). 请拆多次或用脚本循环."
                ),
            })),
        ));
    }
    // 提取 header + direction 备每日重用。
    //
    // v1.4.107: range fanout 必须接受 REST adapter 支持的 4 种 body shape:
    // - {"c2s":{"header":{...}}}
    // - {"header":{...}}
    // - {"c2s":{"acc_id":...,"trd_env":...,"trd_market":...}}
    // - {"acc_id":...,"trd_env":...,"trd_market":...}
    //
    // 旧实现只复制前两种；flat body 已通过 validate/read_handler_acc_id_check,
    // 但 fanout 下游收到 header:null → daily fetch 全失败。
    let header = flow_summary_range_header_from_body(body);
    let direction = body
        .pointer("/c2s/cash_flow_direction")
        .or_else(|| body.pointer("/cash_flow_direction"))
        .or_else(|| body.pointer("/c2s/direction"))
        .or_else(|| body.pointer("/direction"))
        .cloned();

    use chrono::Datelike;
    let mut day = date_from;
    let mut all_entries: Vec<Value> = Vec::new();
    let mut s2c_header: Value = Value::Null;
    let mut failed_days: Vec<String> = Vec::new();
    let mut success_days = 0usize; // v1.4.102 codex 45 F1: 成功但空 ≠ 失败
    while day <= date_to {
        if matches!(day.weekday(), chrono::Weekday::Sat | chrono::Weekday::Sun) {
            if !flow_summary_advance_day(&mut day, date_to).map_err(|e| {
                (
                    StatusCode::BAD_REQUEST,
                    Json(serde_json::json!({ "error": e })),
                )
            })? {
                break;
            }
            continue;
        }
        let date_str = day.format("%Y-%m-%d").to_string();
        let mut single_body = serde_json::json!({
            "c2s": {
                "header": header.clone(),
                "clearing_date": date_str.clone(),
            }
        });
        if let Some(dir) = direction.clone() {
            single_body["c2s"]["cash_flow_direction"] = dir;
        }
        match adapter::proto_request::<trd_flow_summary::Request, trd_flow_summary::Response>(
            state,
            proto_id::TRD_FLOW_SUMMARY,
            Some(single_body),
        )
        .await
        {
            Ok(Json(resp)) => {
                let ret = resp.get("ret_type").and_then(|v| v.as_i64()).unwrap_or(-1);
                if ret == 0 {
                    // v1.4.102 codex 45 F1: 成功的 daily fetch 也可能合法返
                    // 空 flow_summary_info_list (假日 / 真无流水), 必须算
                    // success_day 不能用 entries 数推断成败.
                    success_days += 1;
                    if s2c_header == Value::Null
                        && let Some(h) = resp.pointer("/s2c/header")
                    {
                        s2c_header = h.clone();
                    }
                    if let Some(arr) = resp
                        .pointer("/s2c/flow_summary_info_list")
                        .and_then(|v| v.as_array())
                    {
                        all_entries.extend(arr.iter().cloned());
                    }
                } else {
                    failed_days.push(date_str.clone());
                }
            }
            Err(_) => {
                failed_days.push(date_str.clone());
            }
        }
        if !flow_summary_advance_day(&mut day, date_to).map_err(|e| {
            (
                StatusCode::BAD_REQUEST,
                Json(serde_json::json!({ "error": e })),
            )
        })? {
            break;
        }
    }

    // v1.4.102 codex 32 F1 + v1.4.102 codex 45 F1 (P2) fix:
    // 全失败时不再 silent ret_type=0 + 不再用 entries 数推断成败.
    // silent-success anti-pattern (CLAUDE.md 反模式 D / 坑 #45).
    //
    // 真正 all-failed: success_days == 0 + failed_days 非空 (没有任何一天 succeed).
    //   - 之前 codex 32 F1 用 `failed_days 非空 && all_entries.is_empty()`
    //     → 部分成功但成功日恰好无流水 (假日 / 无活动) → 误判 all-failed.
    //   - codex 45 F1 修: 用 success_days 真实计数; 0 success = 真 all-failed.
    let all_failed = success_days == 0 && !failed_days.is_empty();
    let (ret_type, ret_msg): (i32, Option<String>) = if all_failed {
        (
            -1,
            Some(format!(
                "flow-summary: 所有 {} 个 daily fetch 都失败 (failed_days: {:?}). \
                 检查 trd_env / acc_id / trd_market / backend 连接. \
                 v1.4.102 codex 32 F1 fix: 不再 silent ret_type=0.",
                failed_days.len(),
                failed_days
            )),
        )
    } else if !failed_days.is_empty() {
        (
            0,
            Some(format!(
                "flow-summary: partial success ({} entries from successful days), \
                 但有 {} 天失败 (见 s2c.date_range.failed_days). v1.4.102 codex 32 F1.",
                all_entries.len(),
                failed_days.len()
            )),
        )
    } else {
        (0, None)
    };
    let resp = serde_json::json!({
        "ret_type": ret_type,
        "ret_msg": ret_msg,
        "err_code": null,
        "s2c": {
            "header": s2c_header,
            "flow_summary_info_list": all_entries,
            "date_range": {
                "begin_date": begin,
                "end_date": end,
                "failed_days": failed_days,
            },
        },
    });
    Ok(Some(Json(resp)))
}

fn flow_summary_range_header_from_body(body: &Value) -> Value {
    if let Some(header) = body
        .pointer("/c2s/header")
        .or_else(|| body.pointer("/header"))
    {
        return header.clone();
    }

    let mut header = serde_json::Map::new();
    for key in ["acc_id", "trd_env", "trd_market", "jp_acc_type"] {
        if let Some(v) = body
            .pointer(&format!("/c2s/{key}"))
            .or_else(|| body.pointer(&format!("/{key}")))
        {
            header.insert(key.to_string(), v.clone());
        }
    }
    Value::Object(header)
}

fn flow_summary_advance_day(
    day: &mut chrono::NaiveDate,
    date_to: chrono::NaiveDate,
) -> Result<bool, String> {
    if *day >= date_to {
        return Ok(false);
    }
    let next = day
        .succ_opt()
        .ok_or_else(|| format!("flow-summary date range cannot advance beyond {day}"))?;
    *day = next;
    Ok(true)
}

/// v1.4.93 Jackie #1 unit tests — date-range mode for `/api/flow-summary`.
///
/// 测 `maybe_handle_flow_summary_date_range` validation 路径 (输入错误检测).
/// HTTP fanout 路径 (实际跨日 fetch + 聚合) 走真机 verify (essentials/2026-04-26
/// jackie feedback report).
#[cfg(test)]
mod tests_v1_4_93_jackie_1_flow_summary_range;

// ============================================================================