refactor(saas): 架构重构 + 性能优化 — 借鉴 loco-rs 模式

Phase 0: 知识库 - docs/knowledge-base/loco-rs-patterns.md — loco-rs 10 个可借鉴模式研究 Phase 1: 数据层重构 - crates/zclaw-saas/src/models/ — 15 个 FromRow 类型化模型 - Login 3 次查询合并为 1 次 AccountLoginRow 查询 - 所有 service 文件从元组解构迁移到 FromRow 结构体 Phase 2: Worker + Scheduler 系统 - crates/zclaw-saas/src/workers/ — Worker trait + 5 个具体实现 - crates/zclaw-saas/src/scheduler.rs — TOML 声明式调度器 - crates/zclaw-saas/src/tasks/ — CLI 任务系统 Phase 3: 性能修复 - Relay N+1 查询 → 精准 SQL (relay/handlers.rs) - Config RwLock → AtomicU32 无锁 rate limit (state.rs, middleware.rs) - SSE std::sync::Mutex → tokio::sync::Mutex (relay/service.rs) - /auth/refresh 阻塞清理 → Scheduler 定期执行 Phase 4: 多环境配置 - config/saas-{development,production,test}.toml - ZCLAW_ENV 环境选择 + ZCLAW_SAAS_CONFIG 精确覆盖 - scheduler 配置集成到 TOML
2026-03-29 19:21:48 +08:00
parent 5fdf96c3f5
commit 8b9d506893
64 changed files with 3348 additions and 520 deletions
--- a/crates/zclaw-saas/src/model_config/service.rs
+++ b/crates/zclaw-saas/src/model_config/service.rs
@@ -4,6 +4,7 @@ use sqlx::{PgPool, Row};
 use crate::error::{SaasError, SaasResult};
 use crate::common::{PaginatedResponse, normalize_pagination};
 use crate::crypto;
+use crate::models::{ProviderRow, ModelRow, AccountApiKeyRow, UsageByModelRow, UsageByDayRow};
 use super::types::*;

 // ============ Providers ============
@@ -33,7 +34,7 @@ pub async fn list_providers(
        sqlx::query_as(count_sql).fetch_one(db).await?
    };

-    let rows: Vec<(String, String, String, String, String, bool, Option<i64>, Option<i64>, String, String)> =
+    let rows: Vec<ProviderRow> =
        if let Some(en) = enabled_filter {
            sqlx::query_as(data_sql)
                .bind(en).bind(ps as i64).bind(offset)
@@ -44,15 +45,15 @@ pub async fn list_providers(
                .fetch_all(db).await?
        };

-    let items = rows.into_iter().map(|(id, name, display_name, base_url, api_protocol, enabled, rpm, tpm, created_at, updated_at)| {
-        ProviderInfo { id, name, display_name, base_url, api_protocol, enabled, rate_limit_rpm: rpm, rate_limit_tpm: tpm, created_at, updated_at }
+    let items = rows.into_iter().map(|r| {
+        ProviderInfo { id: r.id, name: r.name, display_name: r.display_name, base_url: r.base_url, api_protocol: r.api_protocol, enabled: r.enabled, rate_limit_rpm: r.rate_limit_rpm, rate_limit_tpm: r.rate_limit_tpm, created_at: r.created_at, updated_at: r.updated_at }
    }).collect();

    Ok(PaginatedResponse { items, total: total.0, page: p, page_size: ps })
 }

 pub async fn get_provider(db: &PgPool, provider_id: &str) -> SaasResult<ProviderInfo> {
-    let row: Option<(String, String, String, String, String, bool, Option<i64>, Option<i64>, String, String)> =
+    let row: Option<ProviderRow> =
        sqlx::query_as(
            "SELECT id, name, display_name, base_url, api_protocol, enabled, rate_limit_rpm, rate_limit_tpm, created_at, updated_at
             FROM providers WHERE id = $1"
@@ -61,10 +62,9 @@ pub async fn get_provider(db: &PgPool, provider_id: &str) -> SaasResult<Provider
        .fetch_optional(db)
        .await?;

-    let (id, name, display_name, base_url, api_protocol, enabled, rpm, tpm, created_at, updated_at) =
-        row.ok_or_else(|| SaasError::NotFound(format!("Provider {} 不存在", provider_id)))?;
+    let r = row.ok_or_else(|| SaasError::NotFound(format!("Provider {} 不存在", provider_id)))?;

-    Ok(ProviderInfo { id, name, display_name, base_url, api_protocol, enabled, rate_limit_rpm: rpm, rate_limit_tpm: tpm, created_at, updated_at })
+    Ok(ProviderInfo { id: r.id, name: r.name, display_name: r.display_name, base_url: r.base_url, api_protocol: r.api_protocol, enabled: r.enabled, rate_limit_rpm: r.rate_limit_rpm, rate_limit_tpm: r.rate_limit_tpm, created_at: r.created_at, updated_at: r.updated_at })
 }

 pub async fn create_provider(db: &PgPool, req: &CreateProviderRequest, enc_key: &[u8; 32]) -> SaasResult<ProviderInfo> {
@@ -175,14 +175,14 @@ pub async fn list_models(
        sqlx::query_as(count_sql).fetch_one(db).await?
    };

-    let mut query = sqlx::query_as::<_, (String, String, String, String, i64, i64, bool, bool, bool, f64, f64, String, String)>(data_sql);
+    let mut query = sqlx::query_as::<_, ModelRow>(data_sql);
    if let Some(pid) = provider_id {
        query = query.bind(pid);
    }
    let rows = query.bind(ps as i64).bind(offset).fetch_all(db).await?;

-    let items = rows.into_iter().map(|(id, provider_id, model_id, alias, ctx, max_out, streaming, vision, enabled, pi, po, created_at, updated_at)| {
-        ModelInfo { id, provider_id, model_id, alias, context_window: ctx, max_output_tokens: max_out, supports_streaming: streaming, supports_vision: vision, enabled, pricing_input: pi, pricing_output: po, created_at, updated_at }
+    let items = rows.into_iter().map(|r| {
+        ModelInfo { id: r.id, provider_id: r.provider_id, model_id: r.model_id, alias: r.alias, context_window: r.context_window, max_output_tokens: r.max_output_tokens, supports_streaming: r.supports_streaming, supports_vision: r.supports_vision, enabled: r.enabled, pricing_input: r.pricing_input, pricing_output: r.pricing_output, created_at: r.created_at, updated_at: r.updated_at }
    }).collect();

    Ok(PaginatedResponse { items, total: total.0, page: p, page_size: ps })
@@ -227,7 +227,7 @@ pub async fn create_model(db: &PgPool, req: &CreateModelRequest) -> SaasResult<M
 }

 pub async fn get_model(db: &PgPool, model_id: &str) -> SaasResult<ModelInfo> {
-    let row: Option<(String, String, String, String, i64, i64, bool, bool, bool, f64, f64, String, String)> =
+    let row: Option<ModelRow> =
        sqlx::query_as(
            "SELECT id, provider_id, model_id, alias, context_window, max_output_tokens, supports_streaming, supports_vision, enabled, pricing_input, pricing_output, created_at, updated_at
             FROM models WHERE id = $1"
@@ -236,10 +236,9 @@ pub async fn get_model(db: &PgPool, model_id: &str) -> SaasResult<ModelInfo> {
        .fetch_optional(db)
        .await?;

-    let (id, provider_id, model_id, alias, ctx, max_out, streaming, vision, enabled, pi, po, created_at, updated_at) =
-        row.ok_or_else(|| SaasError::NotFound(format!("模型 {} 不存在", model_id)))?;
+    let r = row.ok_or_else(|| SaasError::NotFound(format!("模型 {} 不存在", model_id)))?;

-    Ok(ModelInfo { id, provider_id, model_id, alias, context_window: ctx, max_output_tokens: max_out, supports_streaming: streaming, supports_vision: vision, enabled, pricing_input: pi, pricing_output: po, created_at, updated_at })
+    Ok(ModelInfo { id: r.id, provider_id: r.provider_id, model_id: r.model_id, alias: r.alias, context_window: r.context_window, max_output_tokens: r.max_output_tokens, supports_streaming: r.supports_streaming, supports_vision: r.supports_vision, enabled: r.enabled, pricing_input: r.pricing_input, pricing_output: r.pricing_output, created_at: r.created_at, updated_at: r.updated_at })
 }

 pub async fn update_model(
@@ -319,17 +318,17 @@ pub async fn list_account_api_keys(
        sqlx::query_as(count_sql).bind(account_id).fetch_one(db).await?
    };

-    let mut query = sqlx::query_as::<_, (String, String, Option<String>, String, bool, Option<String>, String, String)>(data_sql)
+    let mut query = sqlx::query_as::<_, AccountApiKeyRow>(data_sql)
        .bind(account_id);
    if let Some(pid) = provider_id {
        query = query.bind(pid);
    }
    let rows = query.bind(ps as i64).bind(offset).fetch_all(db).await?;

-    let items = rows.into_iter().map(|(id, provider_id, key_label, perms, enabled, last_used, created_at, key_value)| {
-        let permissions: Vec<String> = serde_json::from_str(&perms).unwrap_or_default();
-        let masked = mask_api_key(&key_value);
-        AccountApiKeyInfo { id, provider_id, key_label, permissions, enabled, last_used_at: last_used, created_at, masked_key: masked }
+    let items = rows.into_iter().map(|r| {
+        let permissions: Vec<String> = serde_json::from_str(&r.permissions).unwrap_or_default();
+        let masked = mask_api_key(&r.key_value);
+        AccountApiKeyInfo { id: r.id, provider_id: r.provider_id, key_label: r.key_label, permissions, enabled: r.enabled, last_used_at: r.last_used_at, created_at: r.created_at, masked_key: masked }
    }).collect();

    Ok(PaginatedResponse { items, total: total.0, page: p, page_size: ps })
@@ -445,34 +444,36 @@ pub async fn get_usage_stats(

    // 按模型统计
    let by_model_sql = format!(
-        "SELECT provider_id, model_id, COUNT(*)::bigint, COALESCE(SUM(input_tokens), 0), COALESCE(SUM(output_tokens), 0)
+        "SELECT provider_id, model_id, COUNT(*)::bigint AS request_count, COALESCE(SUM(input_tokens), 0) AS input_tokens, COALESCE(SUM(output_tokens), 0) AS output_tokens
         FROM usage_records WHERE {} GROUP BY provider_id, model_id ORDER BY COUNT(*) DESC LIMIT 20",
        where_sql
    );
-    let mut by_model_query = sqlx::query_as::<_, (String, String, i64, i64, i64)>(&by_model_sql);
+    let mut by_model_query = sqlx::query_as::<_, UsageByModelRow>(&by_model_sql);
    for p in &params {
        by_model_query = by_model_query.bind(p);
    }
    let by_model_rows = by_model_query.fetch_all(db).await?;
    let by_model: Vec<ModelUsage> = by_model_rows.into_iter()
-        .map(|(provider_id, model_id, count, input, output)| {
-            ModelUsage { provider_id, model_id, request_count: count, input_tokens: input, output_tokens: output }
+        .map(|r| {
+            ModelUsage { provider_id: r.provider_id, model_id: r.model_id, request_count: r.request_count, input_tokens: r.input_tokens, output_tokens: r.output_tokens }
        }).collect();

    // 按天统计 (使用 days 参数或默认 30 天)
    let days = query.days.unwrap_or(30).min(365).max(1) as i64;
-    let from_days = (chrono::Utc::now() - chrono::Duration::days(days)).format("%Y-%m-%d").to_string() + "T00:00:00Z";
-    let daily_sql = format!(
-        "SELECT SUBSTRING(created_at, 1, 10) as day, COUNT(*)::bigint, COALESCE(SUM(input_tokens), 0), COALESCE(SUM(output_tokens), 0)
+    let from_days = (chrono::Utc::now() - chrono::Duration::days(days))
+        .date_naive()
+        .and_hms_opt(0, 0, 0).unwrap()
+        .and_utc()
+        .to_rfc3339();
+    let daily_sql = "SELECT SUBSTRING(created_at, 1, 10) as day, COUNT(*)::bigint AS request_count, COALESCE(SUM(input_tokens), 0) AS input_tokens, COALESCE(SUM(output_tokens), 0) AS output_tokens
         FROM usage_records WHERE account_id = $1 AND created_at >= $2
-         GROUP BY SUBSTRING(created_at, 1, 10) ORDER BY day DESC LIMIT $3"
-    );
-    let daily_rows: Vec<(String, i64, i64, i64)> = sqlx::query_as(&daily_sql)
+         GROUP BY SUBSTRING(created_at, 1, 10) ORDER BY day DESC LIMIT $3";
+    let daily_rows: Vec<UsageByDayRow> = sqlx::query_as(daily_sql)
        .bind(account_id).bind(&from_days).bind(days as i32)
        .fetch_all(db).await?;
    let by_day: Vec<DailyUsage> = daily_rows.into_iter()
-        .map(|(date, count, input, output)| {
-            DailyUsage { date, request_count: count, input_tokens: input, output_tokens: output }
+        .map(|r| {
+            DailyUsage { date: r.day, request_count: r.request_count, input_tokens: r.input_tokens, output_tokens: r.output_tokens }
        }).collect();

    // 按 group_by 过滤返回