feat: 扩展 Rust gateway 全功能模块，新增 billing/crypto/wallet crate 及完整数据层

- 新增 aether-billing、aether-crypto、aether-wallet 独立 crate
- aether-data 扩展 repository 层：announcements、auth_modules、billing、
  candidate_selection、gemini_file_mappings、global_models、management_tokens、
  oauth_providers、proxy_nodes、quota、users、wallet 等模块
- aether-gateway 新增 api/auth/billing/control/middleware/scheduler/usage/
  video_tasks/hooks/maintenance/model_fetch/provider_transport 等功能模块
- 重构 executor decision 和 gateway state 为模块目录结构
- 新增 gateway router、frontdoor 路由层及对应测试
- Python 侧 API 路由重构，新增 compat/support 模块
- 前端 Logo 组件更新及 Provider 管理页面调整

crates/aether-data/src/repository/wallet/memory.rs

@@ -0,0 +1,270 @@
+use std::collections::BTreeMap;
+use std::sync::RwLock;
+
+use async_trait::async_trait;
+
+use super::types::{
+    StoredUsageSettlement, StoredWalletSnapshot, UsageSettlementInput, WalletLookupKey,
+    WalletReadRepository, WalletWriteRepository,
+};
+use crate::DataLayerError;
+
+#[derive(Debug, Default)]
+pub struct InMemoryWalletRepository {
+    wallets_by_id: RwLock<BTreeMap<String, StoredWalletSnapshot>>,
+    provider_monthly_used: RwLock<BTreeMap<String, f64>>,
+}
+
+impl InMemoryWalletRepository {
+    pub fn seed<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 {
+            wallets_by_id: RwLock::new(wallets_by_id),
+            provider_monthly_used: RwLock::new(BTreeMap::new()),
+        }
+    }
+}
+
+#[async_trait]
+impl WalletReadRepository for InMemoryWalletRepository {
+    async fn find(
+        &self,
+        key: WalletLookupKey<'_>,
+    ) -> Result<Option<StoredWalletSnapshot>, DataLayerError> {
+        let wallets = self.wallets_by_id.read().expect("wallet repo lock");
+        Ok(match key {
+            WalletLookupKey::WalletId(wallet_id) => wallets.get(wallet_id).cloned(),
+            WalletLookupKey::UserId(user_id) => wallets
+                .values()
+                .find(|wallet| wallet.user_id.as_deref() == Some(user_id))
+                .cloned(),
+            WalletLookupKey::ApiKeyId(api_key_id) => wallets
+                .values()
+                .find(|wallet| wallet.api_key_id.as_deref() == Some(api_key_id))
+                .cloned(),
+        })
+    }
+
+    async fn list_wallets_by_user_ids(
+        &self,
+        user_ids: &[String],
+    ) -> Result<Vec<StoredWalletSnapshot>, DataLayerError> {
+        if user_ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        let user_set: std::collections::BTreeSet<&str> =
+            user_ids.iter().map(String::as_str).collect();
+        let wallets = self.wallets_by_id.read().expect("wallet repo lock");
+        Ok(wallets
+            .values()
+            .filter(|wallet| {
+                wallet
+                    .user_id
+                    .as_deref()
+                    .map(|user_id| user_set.contains(user_id))
+                    .unwrap_or(false)
+            })
+            .cloned()
+            .collect())
+    }
+
+    async fn list_wallets_by_api_key_ids(
+        &self,
+        api_key_ids: &[String],
+    ) -> Result<Vec<StoredWalletSnapshot>, DataLayerError> {
+        if api_key_ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        let key_set: std::collections::BTreeSet<&str> =
+            api_key_ids.iter().map(String::as_str).collect();
+        let wallets = self.wallets_by_id.read().expect("wallet repo lock");
+        Ok(wallets
+            .values()
+            .filter(|wallet| {
+                wallet
+                    .api_key_id
+                    .as_deref()
+                    .map(|api_key_id| key_set.contains(api_key_id))
+                    .unwrap_or(false)
+            })
+            .cloned()
+            .collect())
+    }
+}
+
+#[async_trait]
+impl WalletWriteRepository for InMemoryWalletRepository {
+    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 mut wallets = self.wallets_by_id.write().expect("wallet repo lock");
+        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 final_billing_status = if input.status == "completed" {
+            "settled"
+        } else {
+            "void"
+        };
+
+        let mut settlement = StoredUsageSettlement {
+            request_id: input.request_id,
+            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);
+        }
+
+        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::InMemoryWalletRepository;
+    use crate::repository::wallet::{
+        StoredWalletSnapshot, UsageSettlementInput, WalletLookupKey, WalletReadRepository,
+        WalletWriteRepository,
+    };
+
+    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 finds_wallet_by_owner() {
+        let repository = InMemoryWalletRepository::seed(vec![sample_wallet()]);
+        let wallet = repository
+            .find(WalletLookupKey::UserId("user-1"))
+            .await
+            .expect("lookup should succeed")
+            .expect("wallet should exist");
+        assert_eq!(wallet.id, "wallet-1");
+    }
+
+    #[tokio::test]
+    async fn settles_usage_against_wallet_and_provider_quota() {
+        let repository = InMemoryWalletRepository::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));
+    }
+}

crates/aether-data/src/repository/wallet/mod.rs

@@ -0,0 +1,10 @@
+mod memory;
+mod sql;
+mod types;
+
+pub use memory::InMemoryWalletRepository;
+pub use sql::SqlxWalletRepository;
+pub use types::{
+    StoredUsageSettlement, StoredWalletSnapshot, UsageSettlementInput, WalletLookupKey,
+    WalletReadRepository, WalletRepository, WalletWriteRepository,
+};

crates/aether-data/src/repository/wallet/sql.rs

@@ -0,0 +1,485 @@
+use async_trait::async_trait;
+use sqlx::{PgPool, Row};
+
+use super::types::{
+    StoredUsageSettlement, StoredWalletSnapshot, UsageSettlementInput, WalletLookupKey,
+    WalletReadRepository, WalletWriteRepository,
+};
+use crate::postgres::PostgresTransactionRunner;
+use crate::DataLayerError;
+use std::collections::BTreeMap;
+
+const FIND_BY_WALLET_ID_SQL: &str = r#"
+SELECT
+  id,
+  user_id,
+  api_key_id,
+  CAST(balance AS DOUBLE PRECISION) AS balance,
+  CAST(gift_balance AS DOUBLE PRECISION) AS gift_balance,
+  limit_mode,
+  currency,
+  status,
+  CAST(total_recharged AS DOUBLE PRECISION) AS total_recharged,
+  CAST(total_consumed AS DOUBLE PRECISION) AS total_consumed,
+  CAST(total_refunded AS DOUBLE PRECISION) AS total_refunded,
+  CAST(total_adjusted AS DOUBLE PRECISION) AS total_adjusted,
+  CAST(EXTRACT(EPOCH FROM updated_at) AS BIGINT) AS updated_at_unix_secs
+FROM wallets
+WHERE id = $1
+LIMIT 1
+"#;
+
+const FIND_BY_USER_ID_SQL: &str = r#"
+SELECT
+  id,
+  user_id,
+  api_key_id,
+  CAST(balance AS DOUBLE PRECISION) AS balance,
+  CAST(gift_balance AS DOUBLE PRECISION) AS gift_balance,
+  limit_mode,
+  currency,
+  status,
+  CAST(total_recharged AS DOUBLE PRECISION) AS total_recharged,
+  CAST(total_consumed AS DOUBLE PRECISION) AS total_consumed,
+  CAST(total_refunded AS DOUBLE PRECISION) AS total_refunded,
+  CAST(total_adjusted AS DOUBLE PRECISION) AS total_adjusted,
+  CAST(EXTRACT(EPOCH FROM updated_at) AS BIGINT) AS updated_at_unix_secs
+FROM wallets
+WHERE user_id = $1
+LIMIT 1
+"#;
+
+const FIND_BY_API_KEY_ID_SQL: &str = r#"
+SELECT
+  id,
+  user_id,
+  api_key_id,
+  CAST(balance AS DOUBLE PRECISION) AS balance,
+  CAST(gift_balance AS DOUBLE PRECISION) AS gift_balance,
+  limit_mode,
+  currency,
+  status,
+  CAST(total_recharged AS DOUBLE PRECISION) AS total_recharged,
+  CAST(total_consumed AS DOUBLE PRECISION) AS total_consumed,
+  CAST(total_refunded AS DOUBLE PRECISION) AS total_refunded,
+  CAST(total_adjusted AS DOUBLE PRECISION) AS total_adjusted,
+  CAST(EXTRACT(EPOCH FROM updated_at) AS BIGINT) AS updated_at_unix_secs
+FROM wallets
+WHERE api_key_id = $1
+LIMIT 1
+"#;
+
+const LIST_BY_USER_IDS_SQL: &str = r#"
+SELECT
+  id,
+  user_id,
+  api_key_id,
+  CAST(balance AS DOUBLE PRECISION) AS balance,
+  CAST(gift_balance AS DOUBLE PRECISION) AS gift_balance,
+  limit_mode,
+  currency,
+  status,
+  CAST(total_recharged AS DOUBLE PRECISION) AS total_recharged,
+  CAST(total_consumed AS DOUBLE PRECISION) AS total_consumed,
+  CAST(total_refunded AS DOUBLE PRECISION) AS total_refunded,
+  CAST(total_adjusted AS DOUBLE PRECISION) AS total_adjusted,
+  CAST(EXTRACT(EPOCH FROM updated_at) AS BIGINT) AS updated_at_unix_secs
+FROM wallets
+WHERE user_id = ANY($1)
+"#;
+
+const LIST_BY_API_KEY_IDS_SQL: &str = r#"
+SELECT
+  id,
+  user_id,
+  api_key_id,
+  CAST(balance AS DOUBLE PRECISION) AS balance,
+  CAST(gift_balance AS DOUBLE PRECISION) AS gift_balance,
+  limit_mode,
+  currency,
+  status,
+  CAST(total_recharged AS DOUBLE PRECISION) AS total_recharged,
+  CAST(total_consumed AS DOUBLE PRECISION) AS total_consumed,
+  CAST(total_refunded AS DOUBLE PRECISION) AS total_refunded,
+  CAST(total_adjusted AS DOUBLE PRECISION) AS total_adjusted,
+  CAST(EXTRACT(EPOCH FROM updated_at) AS BIGINT) AS updated_at_unix_secs
+FROM wallets
+WHERE api_key_id = ANY($1)
+"#;
+
+const FINALIZE_USAGE_BILLING_SQL: &str = r#"
+UPDATE "usage"
+SET
+  billing_status = $2,
+  finalized_at = TO_TIMESTAMP($3::double precision)
+WHERE request_id = $1
+"#;
+
+#[derive(Debug, Clone)]
+pub struct SqlxWalletRepository {
+    pool: PgPool,
+    tx_runner: PostgresTransactionRunner,
+}
+
+impl SqlxWalletRepository {
+    pub fn new(pool: PgPool) -> Self {
+        let tx_runner = PostgresTransactionRunner::new(pool.clone());
+        Self { pool, tx_runner }
+    }
+}
+
+#[async_trait]
+impl WalletReadRepository for SqlxWalletRepository {
+    async fn find(
+        &self,
+        key: WalletLookupKey<'_>,
+    ) -> Result<Option<StoredWalletSnapshot>, DataLayerError> {
+        let query = match key {
+            WalletLookupKey::WalletId(_) => FIND_BY_WALLET_ID_SQL,
+            WalletLookupKey::UserId(_) => FIND_BY_USER_ID_SQL,
+            WalletLookupKey::ApiKeyId(_) => FIND_BY_API_KEY_ID_SQL,
+        };
+        let bind = match key {
+            WalletLookupKey::WalletId(value)
+            | WalletLookupKey::UserId(value)
+            | WalletLookupKey::ApiKeyId(value) => value,
+        };
+        let row = sqlx::query(query)
+            .bind(bind)
+            .fetch_optional(&self.pool)
+            .await?;
+        row.as_ref().map(map_wallet_row).transpose()
+    }
+    async fn list_wallets_by_user_ids(
+        &self,
+        user_ids: &[String],
+    ) -> Result<Vec<StoredWalletSnapshot>, DataLayerError> {
+        if user_ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        let mut ids_map = BTreeMap::new();
+        for (index, id) in user_ids.iter().enumerate() {
+            ids_map.entry(id).or_insert_with(Vec::new).push(index);
+        }
+        let rows = sqlx::query(LIST_BY_USER_IDS_SQL)
+            .bind(user_ids)
+            .fetch_all(&self.pool)
+            .await?;
+        let mut wallets = Vec::with_capacity(rows.len());
+        for row in rows {
+            let wallet = map_wallet_row(&row)?;
+            wallets.push(wallet);
+        }
+        Ok(wallets)
+    }
+    async fn list_wallets_by_api_key_ids(
+        &self,
+        api_key_ids: &[String],
+    ) -> Result<Vec<StoredWalletSnapshot>, DataLayerError> {
+        if api_key_ids.is_empty() {
+            return Ok(Vec::new());
+        }
+        let rows = sqlx::query(LIST_BY_API_KEY_IDS_SQL)
+            .bind(api_key_ids)
+            .fetch_all(&self.pool)
+            .await?;
+        let mut wallets = Vec::with_capacity(rows.len());
+        for row in rows {
+            let wallet = map_wallet_row(&row)?;
+            wallets.push(wallet);
+        }
+        Ok(wallets)
+    }
+}
+
+#[async_trait]
+impl WalletWriteRepository for SqlxWalletRepository {
+    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
+    }
+}
+
+fn map_wallet_row(row: &sqlx::postgres::PgRow) -> Result<StoredWalletSnapshot, DataLayerError> {
+    StoredWalletSnapshot::new(
+        row.try_get("id")?,
+        row.try_get("user_id")?,
+        row.try_get("api_key_id")?,
+        row.try_get("balance")?,
+        row.try_get("gift_balance")?,
+        row.try_get("limit_mode")?,
+        row.try_get("currency")?,
+        row.try_get("status")?,
+        row.try_get("total_recharged")?,
+        row.try_get("total_consumed")?,
+        row.try_get("total_refunded")?,
+        row.try_get("total_adjusted")?,
+        row.try_get("updated_at_unix_secs")?,
+    )
+}
+
+#[cfg(test)]
+mod tests {
+    use super::SqlxWalletRepository;
+    use crate::postgres::{PostgresPoolConfig, PostgresPoolFactory};
+
+    #[tokio::test]
+    async fn repository_constructs_from_lazy_pool() {
+        let factory = PostgresPoolFactory::new(PostgresPoolConfig {
+            database_url: "postgres://localhost/aether".to_string(),
+            min_connections: 1,
+            max_connections: 4,
+            acquire_timeout_ms: 1_000,
+            idle_timeout_ms: 5_000,
+            max_lifetime_ms: 30_000,
+            statement_cache_capacity: 64,
+            require_ssl: false,
+        })
+        .expect("factory should build");
+
+        let pool = factory.connect_lazy().expect("pool should build");
+        let _repository = SqlxWalletRepository::new(pool);
+    }
+
+    #[test]
+    fn wallet_usage_finalize_sql_does_not_require_usage_updated_at_column() {
+        assert!(!super::FINALIZE_USAGE_BILLING_SQL.contains("updated_at"));
+    }
+}

crates/aether-data/src/repository/wallet/types.rs

@@ -0,0 +1,215 @@
+use async_trait::async_trait;
+
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub enum WalletLookupKey<'a> {
+    WalletId(&'a str),
+    UserId(&'a str),
+    ApiKeyId(&'a str),
+}
+
+#[derive(Debug, Clone, PartialEq, serde::Serialize, serde::Deserialize)]
+pub struct StoredWalletSnapshot {
+    pub id: String,
+    pub user_id: Option<String>,
+    pub api_key_id: Option<String>,
+    pub balance: f64,
+    pub gift_balance: f64,
+    pub limit_mode: String,
+    pub currency: String,
+    pub status: String,
+    pub total_recharged: f64,
+    pub total_consumed: f64,
+    pub total_refunded: f64,
+    pub total_adjusted: f64,
+    pub updated_at_unix_secs: u64,
+}
+
+impl StoredWalletSnapshot {
+    #[allow(clippy::too_many_arguments)]
+    pub fn new(
+        id: String,
+        user_id: Option<String>,
+        api_key_id: Option<String>,
+        balance: f64,
+        gift_balance: f64,
+        limit_mode: String,
+        currency: String,
+        status: String,
+        total_recharged: f64,
+        total_consumed: f64,
+        total_refunded: f64,
+        total_adjusted: f64,
+        updated_at_unix_secs: i64,
+    ) -> Result<Self, crate::DataLayerError> {
+        if id.trim().is_empty() {
+            return Err(crate::DataLayerError::UnexpectedValue(
+                "wallet.id is empty".to_string(),
+            ));
+        }
+        if limit_mode.trim().is_empty() {
+            return Err(crate::DataLayerError::UnexpectedValue(
+                "wallet.limit_mode is empty".to_string(),
+            ));
+        }
+        if currency.trim().is_empty() {
+            return Err(crate::DataLayerError::UnexpectedValue(
+                "wallet.currency is empty".to_string(),
+            ));
+        }
+        if status.trim().is_empty() {
+            return Err(crate::DataLayerError::UnexpectedValue(
+                "wallet.status is empty".to_string(),
+            ));
+        }
+        if !balance.is_finite()
+            || !gift_balance.is_finite()
+            || !total_recharged.is_finite()
+            || !total_consumed.is_finite()
+            || !total_refunded.is_finite()
+            || !total_adjusted.is_finite()
+        {
+            return Err(crate::DataLayerError::UnexpectedValue(
+                "wallet numeric value is not finite".to_string(),
+            ));
+        }
+        Ok(Self {
+            id,
+            user_id,
+            api_key_id,
+            balance,
+            gift_balance,
+            limit_mode,
+            currency,
+            status,
+            total_recharged,
+            total_consumed,
+            total_refunded,
+            total_adjusted,
+            updated_at_unix_secs: u64::try_from(updated_at_unix_secs).map_err(|_| {
+                crate::DataLayerError::UnexpectedValue(
+                    "wallet.updated_at_unix_secs is negative".to_string(),
+                )
+            })?,
+        })
+    }
+}
+
+#[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(
+                "wallet 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(
+                "wallet 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(
+                "wallet 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 WalletReadRepository: Send + Sync {
+    async fn find(
+        &self,
+        key: WalletLookupKey<'_>,
+    ) -> Result<Option<StoredWalletSnapshot>, crate::DataLayerError>;
+
+    async fn list_wallets_by_user_ids(
+        &self,
+        user_ids: &[String],
+    ) -> Result<Vec<StoredWalletSnapshot>, crate::DataLayerError>;
+
+    async fn list_wallets_by_api_key_ids(
+        &self,
+        api_key_ids: &[String],
+    ) -> Result<Vec<StoredWalletSnapshot>, crate::DataLayerError>;
+}
+
+#[async_trait]
+pub trait WalletWriteRepository: Send + Sync {
+    async fn settle_usage(
+        &self,
+        input: UsageSettlementInput,
+    ) -> Result<Option<StoredUsageSettlement>, crate::DataLayerError>;
+}
+
+pub trait WalletRepository: WalletReadRepository + WalletWriteRepository + Send + Sync {}
+
+impl<T> WalletRepository for T where T: WalletReadRepository + WalletWriteRepository + Send + Sync {}
+
+#[cfg(test)]
+mod tests {
+    use super::{StoredWalletSnapshot, UsageSettlementInput};
+
+    #[test]
+    fn rejects_invalid_wallet_snapshot() {
+        assert!(StoredWalletSnapshot::new(
+            "".to_string(),
+            None,
+            None,
+            1.0,
+            0.0,
+            "finite".to_string(),
+            "USD".to_string(),
+            "active".to_string(),
+            0.0,
+            0.0,
+            0.0,
+            0.0,
+            1,
+        )
+        .is_err());
+    }
+
+    #[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());
+    }
+}