refactor: 拆分 gateway 单体为独立 crate，新增 systemd 部署方案

将 gateway 内部的 model-fetch、provider-transport、scheduler-core、 usage-runtime、video-tasks-core 模块提取为独立 crate；重构 gateway 内部模块结构（state/router/cache/data/query 等）；移除大量遗留模块文件；新增 systemd 二进制部署骨架及相关文档；更新前端 usage 相关 API 和组件。
2026-09-02 17:30:23 +08:00 · 2026-04-05 20:23:16 +08:00
parent cbc811f6ce
commit 763ff03a7b
777 changed files with 42659 additions and 21469 deletions
--- a/crates/aether-data/src/repository/settlement/memory.rs
+++ b/crates/aether-data/src/repository/settlement/memory.rs
@@ -0,0 +1,228 @@
+use std::collections::BTreeMap;
+use std::sync::{Arc, RwLock};
+
+use async_trait::async_trait;
+
+use super::types::{SettlementWriteRepository, StoredUsageSettlement, UsageSettlementInput};
+use crate::repository::wallet::{InMemoryWalletRepository, StoredWalletSnapshot};
+use crate::DataLayerError;
+
+#[derive(Debug)]
+enum InMemorySettlementWalletStore {
+    Owned(RwLock<BTreeMap<String, StoredWalletSnapshot>>),
+    Shared(Arc<InMemoryWalletRepository>),
+}
+
+impl Default for InMemorySettlementWalletStore {
+    fn default() -> Self {
+        Self::Owned(RwLock::new(BTreeMap::new()))
+    }
+}
+
+impl InMemorySettlementWalletStore {
+    fn seeded<I>(items: I) -> Self
+    where
+        I: IntoIterator<Item = StoredWalletSnapshot>,
+    {
+        let mut wallets_by_id = BTreeMap::new();
+        for item in items {
+            wallets_by_id.insert(item.id.clone(), item);
+        }
+        Self::Owned(RwLock::new(wallets_by_id))
+    }
+
+    fn with_mut<R>(&self, f: impl FnOnce(&mut BTreeMap<String, StoredWalletSnapshot>) -> R) -> R {
+        match self {
+            Self::Owned(wallets_by_id) => {
+                let mut wallets = wallets_by_id.write().expect("settlement repo lock");
+                f(&mut wallets)
+            }
+            Self::Shared(repository) => repository.with_wallets_mut(f),
+        }
+    }
+}
+
+#[derive(Debug, Default)]
+pub struct InMemorySettlementRepository {
+    wallets: InMemorySettlementWalletStore,
+    provider_monthly_used: RwLock<BTreeMap<String, f64>>,
+}
+
+impl InMemorySettlementRepository {
+    pub fn seed<I>(items: I) -> Self
+    where
+        I: IntoIterator<Item = StoredWalletSnapshot>,
+    {
+        Self {
+            wallets: InMemorySettlementWalletStore::seeded(items),
+            provider_monthly_used: RwLock::new(BTreeMap::new()),
+        }
+    }
+
+    pub fn from_wallet_repository(wallet_repository: Arc<InMemoryWalletRepository>) -> Self {
+        Self {
+            wallets: InMemorySettlementWalletStore::Shared(wallet_repository),
+            provider_monthly_used: RwLock::new(BTreeMap::new()),
+        }
+    }
+}
+
+#[async_trait]
+impl SettlementWriteRepository for InMemorySettlementRepository {
+    async fn settle_usage(
+        &self,
+        input: UsageSettlementInput,
+    ) -> Result<Option<StoredUsageSettlement>, DataLayerError> {
+        input.validate()?;
+        if input.billing_status != "pending" {
+            return Ok(Some(StoredUsageSettlement {
+                request_id: input.request_id,
+                wallet_id: None,
+                billing_status: input.billing_status,
+                wallet_balance_before: None,
+                wallet_balance_after: None,
+                wallet_recharge_balance_before: None,
+                wallet_recharge_balance_after: None,
+                wallet_gift_balance_before: None,
+                wallet_gift_balance_after: None,
+                provider_monthly_used_usd: None,
+                finalized_at_unix_secs: input.finalized_at_unix_secs,
+            }));
+        }
+
+        let final_billing_status = if input.status == "completed" {
+            "settled"
+        } else {
+            "void"
+        };
+        let mut settlement = self.wallets.with_mut(|wallets| {
+            let wallet_id = input
+                .api_key_id
+                .as_deref()
+                .and_then(|api_key_id| {
+                    wallets
+                        .values()
+                        .find(|wallet| wallet.api_key_id.as_deref() == Some(api_key_id))
+                        .map(|wallet| wallet.id.clone())
+                })
+                .or_else(|| {
+                    input.user_id.as_deref().and_then(|user_id| {
+                        wallets
+                            .values()
+                            .find(|wallet| wallet.user_id.as_deref() == Some(user_id))
+                            .map(|wallet| wallet.id.clone())
+                    })
+                });
+            let wallet = wallet_id
+                .as_deref()
+                .and_then(|wallet_id| wallets.get_mut(wallet_id));
+
+            let mut settlement = StoredUsageSettlement {
+                request_id: input.request_id.clone(),
+                wallet_id: None,
+                billing_status: final_billing_status.to_string(),
+                wallet_balance_before: None,
+                wallet_balance_after: None,
+                wallet_recharge_balance_before: None,
+                wallet_recharge_balance_after: None,
+                wallet_gift_balance_before: None,
+                wallet_gift_balance_after: None,
+                provider_monthly_used_usd: None,
+                finalized_at_unix_secs: input.finalized_at_unix_secs,
+            };
+
+            if let Some(wallet) = wallet {
+                let before_recharge = wallet.balance;
+                let before_gift = wallet.gift_balance;
+                let before_total = before_recharge + before_gift;
+                settlement.wallet_id = Some(wallet.id.clone());
+                settlement.wallet_balance_before = Some(before_total);
+                settlement.wallet_recharge_balance_before = Some(before_recharge);
+                settlement.wallet_gift_balance_before = Some(before_gift);
+
+                if final_billing_status == "settled" {
+                    if wallet.limit_mode.eq_ignore_ascii_case("unlimited") {
+                        wallet.total_consumed += input.total_cost_usd;
+                    } else {
+                        let gift_deduction = before_gift.max(0.0).min(input.total_cost_usd);
+                        let recharge_deduction = input.total_cost_usd - gift_deduction;
+                        wallet.gift_balance = before_gift - gift_deduction;
+                        wallet.balance = before_recharge - recharge_deduction;
+                        wallet.total_consumed += input.total_cost_usd;
+                    }
+                }
+
+                settlement.wallet_recharge_balance_after = Some(wallet.balance);
+                settlement.wallet_gift_balance_after = Some(wallet.gift_balance);
+                settlement.wallet_balance_after = Some(wallet.balance + wallet.gift_balance);
+            }
+
+            settlement
+        });
+
+        if final_billing_status == "settled" {
+            if let Some(provider_id) = input.provider_id {
+                let mut quotas = self
+                    .provider_monthly_used
+                    .write()
+                    .expect("provider quota lock");
+                let value = quotas.entry(provider_id).or_insert(0.0);
+                *value += input.actual_total_cost_usd;
+                settlement.provider_monthly_used_usd = Some(*value);
+            }
+        }
+
+        Ok(Some(settlement))
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::InMemorySettlementRepository;
+    use crate::repository::settlement::{SettlementWriteRepository, UsageSettlementInput};
+    use crate::repository::wallet::StoredWalletSnapshot;
+
+    fn sample_wallet() -> StoredWalletSnapshot {
+        StoredWalletSnapshot::new(
+            "wallet-1".to_string(),
+            Some("user-1".to_string()),
+            Some("key-1".to_string()),
+            10.0,
+            2.0,
+            "finite".to_string(),
+            "USD".to_string(),
+            "active".to_string(),
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            100,
+        )
+        .expect("wallet should build")
+    }
+
+    #[tokio::test]
+    async fn settles_usage_against_wallet_and_provider_quota() {
+        let repository = InMemorySettlementRepository::seed(vec![sample_wallet()]);
+        let settlement = repository
+            .settle_usage(UsageSettlementInput {
+                request_id: "req-1".to_string(),
+                user_id: Some("user-1".to_string()),
+                api_key_id: Some("key-1".to_string()),
+                provider_id: Some("provider-1".to_string()),
+                status: "completed".to_string(),
+                billing_status: "pending".to_string(),
+                total_cost_usd: 3.0,
+                actual_total_cost_usd: 1.5,
+                finalized_at_unix_secs: Some(200),
+            })
+            .await
+            .expect("settlement should succeed")
+            .expect("settlement should exist");
+
+        assert_eq!(settlement.billing_status, "settled");
+        assert_eq!(settlement.wallet_balance_before, Some(12.0));
+        assert_eq!(settlement.wallet_balance_after, Some(9.0));
+        assert_eq!(settlement.provider_monthly_used_usd, Some(1.5));
+    }
+}
--- a/crates/aether-data/src/repository/settlement/mod.rs
+++ b/crates/aether-data/src/repository/settlement/mod.rs
@@ -0,0 +1,9 @@
+mod memory;
+mod sql;
+mod types;
+
+pub use memory::InMemorySettlementRepository;
+pub use sql::SqlxSettlementRepository;
+pub use types::{
+    SettlementRepository, SettlementWriteRepository, StoredUsageSettlement, UsageSettlementInput,
+};
--- a/crates/aether-data/src/repository/settlement/sql.rs
+++ b/crates/aether-data/src/repository/settlement/sql.rs
@@ -0,0 +1,279 @@
+use async_trait::async_trait;
+use sqlx::{PgPool, Row};
+
+use super::types::{SettlementWriteRepository, StoredUsageSettlement, UsageSettlementInput};
+use crate::postgres::PostgresTransactionRunner;
+use crate::DataLayerError;
+
+const FINALIZE_USAGE_BILLING_SQL: &str = r#"
+UPDATE "usage"
+SET
+  billing_status = $2,
+  finalized_at = COALESCE(finalized_at, to_timestamp($3))
+WHERE request_id = $1
+"#;
+
+#[derive(Debug, Clone)]
+pub struct SqlxSettlementRepository {
+    tx_runner: PostgresTransactionRunner,
+}
+
+impl SqlxSettlementRepository {
+    pub fn new(pool: PgPool) -> Self {
+        let tx_runner = PostgresTransactionRunner::new(pool);
+        Self { tx_runner }
+    }
+}
+
+#[async_trait]
+impl SettlementWriteRepository for SqlxSettlementRepository {
+    async fn settle_usage(
+        &self,
+        input: UsageSettlementInput,
+    ) -> Result<Option<StoredUsageSettlement>, DataLayerError> {
+        input.validate()?;
+        self.tx_runner
+            .run_read_write(|tx| {
+                Box::pin(async move {
+                    let row = sqlx::query(
+                        r#"
+SELECT
+  request_id,
+  wallet_id,
+  billing_status,
+  CAST(wallet_balance_before AS DOUBLE PRECISION) AS wallet_balance_before,
+  CAST(wallet_balance_after AS DOUBLE PRECISION) AS wallet_balance_after,
+  CAST(wallet_recharge_balance_before AS DOUBLE PRECISION) AS wallet_recharge_balance_before,
+  CAST(wallet_recharge_balance_after AS DOUBLE PRECISION) AS wallet_recharge_balance_after,
+  CAST(wallet_gift_balance_before AS DOUBLE PRECISION) AS wallet_gift_balance_before,
+  CAST(wallet_gift_balance_after AS DOUBLE PRECISION) AS wallet_gift_balance_after,
+  provider_id,
+  CAST(EXTRACT(EPOCH FROM finalized_at) AS BIGINT) AS finalized_at_unix_secs
+FROM "usage"
+WHERE request_id = $1
+FOR UPDATE
+                        "#,
+                    )
+                    .bind(&input.request_id)
+                    .fetch_optional(&mut **tx)
+                    .await?;
+
+                    let Some(usage_row) = row else {
+                        return Ok(None);
+                    };
+
+                    let current_billing_status: String = usage_row.try_get("billing_status")?;
+                    if current_billing_status == "settled" || current_billing_status == "void" {
+                        return Ok(Some(StoredUsageSettlement {
+                            request_id: usage_row.try_get("request_id")?,
+                            wallet_id: usage_row.try_get("wallet_id")?,
+                            billing_status: current_billing_status,
+                            wallet_balance_before: usage_row.try_get("wallet_balance_before")?,
+                            wallet_balance_after: usage_row.try_get("wallet_balance_after")?,
+                            wallet_recharge_balance_before: usage_row
+                                .try_get("wallet_recharge_balance_before")?,
+                            wallet_recharge_balance_after: usage_row
+                                .try_get("wallet_recharge_balance_after")?,
+                            wallet_gift_balance_before: usage_row
+                                .try_get("wallet_gift_balance_before")?,
+                            wallet_gift_balance_after: usage_row
+                                .try_get("wallet_gift_balance_after")?,
+                            provider_monthly_used_usd: None,
+                            finalized_at_unix_secs: usage_row
+                                .try_get::<Option<i64>, _>("finalized_at_unix_secs")?
+                                .map(|value| value as u64),
+                        }));
+                    }
+
+                    let final_billing_status = if input.status == "completed" {
+                        "settled"
+                    } else {
+                        "void"
+                    };
+                    let finalized_at =
+                        i64::try_from(input.finalized_at_unix_secs.unwrap_or_else(|| {
+                            std::time::SystemTime::now()
+                                .duration_since(std::time::UNIX_EPOCH)
+                                .unwrap_or_default()
+                                .as_secs()
+                        }))
+                        .map_err(|_| {
+                            DataLayerError::InvalidInput("finalized_at overflow".to_string())
+                        })?;
+
+                    let mut settlement = StoredUsageSettlement {
+                        request_id: input.request_id.clone(),
+                        wallet_id: None,
+                        billing_status: final_billing_status.to_string(),
+                        wallet_balance_before: None,
+                        wallet_balance_after: None,
+                        wallet_recharge_balance_before: None,
+                        wallet_recharge_balance_after: None,
+                        wallet_gift_balance_before: None,
+                        wallet_gift_balance_after: None,
+                        provider_monthly_used_usd: None,
+                        finalized_at_unix_secs: Some(finalized_at as u64),
+                    };
+
+                    if final_billing_status == "settled" {
+                        let wallet_row = if let Some(api_key_id) = input
+                            .api_key_id
+                            .as_deref()
+                            .filter(|value| !value.is_empty())
+                        {
+                            sqlx::query(
+                                r#"
+SELECT
+  id,
+  CAST(balance AS DOUBLE PRECISION) AS balance,
+  CAST(gift_balance AS DOUBLE PRECISION) AS gift_balance,
+  limit_mode
+FROM wallets
+WHERE api_key_id = $1
+FOR UPDATE
+LIMIT 1
+                                "#,
+                            )
+                            .bind(api_key_id)
+                            .fetch_optional(&mut **tx)
+                            .await?
+                        } else {
+                            None
+                        };
+
+                        let wallet_row = if wallet_row.is_some() {
+                            wallet_row
+                        } else if let Some(user_id) =
+                            input.user_id.as_deref().filter(|value| !value.is_empty())
+                        {
+                            sqlx::query(
+                                r#"
+SELECT
+  id,
+  CAST(balance AS DOUBLE PRECISION) AS balance,
+  CAST(gift_balance AS DOUBLE PRECISION) AS gift_balance,
+  limit_mode
+FROM wallets
+WHERE user_id = $1
+FOR UPDATE
+LIMIT 1
+                                "#,
+                            )
+                            .bind(user_id)
+                            .fetch_optional(&mut **tx)
+                            .await?
+                        } else {
+                            None
+                        };
+
+                        if let Some(wallet_row) = wallet_row {
+                            let wallet_id: String = wallet_row.try_get("id")?;
+                            let before_recharge: f64 = wallet_row.try_get("balance")?;
+                            let before_gift: f64 = wallet_row.try_get("gift_balance")?;
+                            let limit_mode: String = wallet_row.try_get("limit_mode")?;
+                            let before_total = before_recharge + before_gift;
+                            let mut after_recharge = before_recharge;
+                            let mut after_gift = before_gift;
+                            if !limit_mode.eq_ignore_ascii_case("unlimited") {
+                                let gift_deduction = before_gift.max(0.0).min(input.total_cost_usd);
+                                let recharge_deduction = input.total_cost_usd - gift_deduction;
+                                after_gift = before_gift - gift_deduction;
+                                after_recharge = before_recharge - recharge_deduction;
+                            }
+                            sqlx::query(
+                                r#"
+UPDATE wallets
+SET
+  balance = $2,
+  gift_balance = $3,
+  total_consumed = CAST(total_consumed AS DOUBLE PRECISION) + $4,
+  updated_at = NOW()
+WHERE id = $1
+                                "#,
+                            )
+                            .bind(&wallet_id)
+                            .bind(after_recharge)
+                            .bind(after_gift)
+                            .bind(input.total_cost_usd)
+                            .execute(&mut **tx)
+                            .await?;
+
+                            settlement.wallet_id = Some(wallet_id.clone());
+                            settlement.wallet_balance_before = Some(before_total);
+                            settlement.wallet_balance_after = Some(after_recharge + after_gift);
+                            settlement.wallet_recharge_balance_before = Some(before_recharge);
+                            settlement.wallet_recharge_balance_after = Some(after_recharge);
+                            settlement.wallet_gift_balance_before = Some(before_gift);
+                            settlement.wallet_gift_balance_after = Some(after_gift);
+
+                            sqlx::query(
+                                r#"
+UPDATE "usage"
+SET
+  wallet_id = $2,
+  wallet_balance_before = $3,
+  wallet_balance_after = $4,
+  wallet_recharge_balance_before = $5,
+  wallet_recharge_balance_after = $6,
+  wallet_gift_balance_before = $7,
+  wallet_gift_balance_after = $8
+WHERE request_id = $1
+                                "#,
+                            )
+                            .bind(&input.request_id)
+                            .bind(&wallet_id)
+                            .bind(before_total)
+                            .bind(after_recharge + after_gift)
+                            .bind(before_recharge)
+                            .bind(after_recharge)
+                            .bind(before_gift)
+                            .bind(after_gift)
+                            .execute(&mut **tx)
+                            .await?;
+                        }
+
+                        if let Some(provider_id) = input
+                            .provider_id
+                            .as_deref()
+                            .filter(|value| !value.is_empty())
+                        {
+                            let quota_row = sqlx::query(
+                                r#"
+UPDATE providers
+SET
+  monthly_used_usd = COALESCE(monthly_used_usd, 0) + $2,
+  updated_at = NOW()
+WHERE id = $1
+RETURNING CAST(monthly_used_usd AS DOUBLE PRECISION) AS monthly_used_usd
+                                "#,
+                            )
+                            .bind(provider_id)
+                            .bind(input.actual_total_cost_usd)
+                            .fetch_optional(&mut **tx)
+                            .await?;
+                            settlement.provider_monthly_used_usd =
+                                quota_row.and_then(|row| row.try_get("monthly_used_usd").ok());
+                        }
+                    }
+
+                    sqlx::query(FINALIZE_USAGE_BILLING_SQL)
+                        .bind(&input.request_id)
+                        .bind(final_billing_status)
+                        .bind(finalized_at)
+                        .execute(&mut **tx)
+                        .await?;
+
+                    Ok(Some(settlement))
+                })
+            })
+            .await
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    #[test]
+    fn finalize_usage_billing_sql_does_not_require_usage_updated_at_column() {
+        assert!(!super::FINALIZE_USAGE_BILLING_SQL.contains("updated_at"));
+    }
+}
--- a/crates/aether-data/src/repository/settlement/types.rs
+++ b/crates/aether-data/src/repository/settlement/types.rs
@@ -0,0 +1,83 @@
+use async_trait::async_trait;
+
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct UsageSettlementInput {
+    pub request_id: String,
+    pub user_id: Option<String>,
+    pub api_key_id: Option<String>,
+    pub provider_id: Option<String>,
+    pub status: String,
+    pub billing_status: String,
+    pub total_cost_usd: f64,
+    pub actual_total_cost_usd: f64,
+    pub finalized_at_unix_secs: Option<u64>,
+}
+
+impl UsageSettlementInput {
+    pub fn validate(&self) -> Result<(), crate::DataLayerError> {
+        if self.request_id.trim().is_empty() {
+            return Err(crate::DataLayerError::InvalidInput(
+                "settlement request_id cannot be empty".to_string(),
+            ));
+        }
+        if self.status.trim().is_empty() || self.billing_status.trim().is_empty() {
+            return Err(crate::DataLayerError::InvalidInput(
+                "settlement status cannot be empty".to_string(),
+            ));
+        }
+        if !self.total_cost_usd.is_finite() || !self.actual_total_cost_usd.is_finite() {
+            return Err(crate::DataLayerError::InvalidInput(
+                "settlement cost must be finite".to_string(),
+            ));
+        }
+        Ok(())
+    }
+}
+
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct StoredUsageSettlement {
+    pub request_id: String,
+    pub wallet_id: Option<String>,
+    pub billing_status: String,
+    pub wallet_balance_before: Option<f64>,
+    pub wallet_balance_after: Option<f64>,
+    pub wallet_recharge_balance_before: Option<f64>,
+    pub wallet_recharge_balance_after: Option<f64>,
+    pub wallet_gift_balance_before: Option<f64>,
+    pub wallet_gift_balance_after: Option<f64>,
+    pub provider_monthly_used_usd: Option<f64>,
+    pub finalized_at_unix_secs: Option<u64>,
+}
+
+#[async_trait]
+pub trait SettlementWriteRepository: Send + Sync {
+    async fn settle_usage(
+        &self,
+        input: UsageSettlementInput,
+    ) -> Result<Option<StoredUsageSettlement>, crate::DataLayerError>;
+}
+
+pub trait SettlementRepository: SettlementWriteRepository + Send + Sync {}
+
+impl<T> SettlementRepository for T where T: SettlementWriteRepository + Send + Sync {}
+
+#[cfg(test)]
+mod tests {
+    use super::UsageSettlementInput;
+
+    #[test]
+    fn rejects_invalid_settlement_input() {
+        let input = UsageSettlementInput {
+            request_id: "".to_string(),
+            user_id: None,
+            api_key_id: None,
+            provider_id: None,
+            status: "completed".to_string(),
+            billing_status: "pending".to_string(),
+            total_cost_usd: 0.1,
+            actual_total_cost_usd: 0.1,
+            finalized_at_unix_secs: None,
+        };
+        assert!(input.validate().is_err());
+    }
+}