Merge remote-tracking branch 'upstream/main'

# Conflicts:
#	frontend/src/components/account/CreateAccountModal.vue

backend/internal/service/token_refresher_test.go

@@ -33,6 +33,13 @@ func TestClaudeTokenRefresher_NeedsRefresh(t *testing.T) {
 			},
 			wantRefresh: true,
 		},
+		{
+			name: "expires_at as RFC3339 - expired",
+			credentials: map[string]any{
+				"expires_at": "1970-01-01T00:00:00Z", // RFC3339 格式，已过期
+			},
+			wantRefresh: true,
+		},
 		{
 			name: "expires_at as string - far future",
 			credentials: map[string]any{
@@ -47,6 +54,13 @@ func TestClaudeTokenRefresher_NeedsRefresh(t *testing.T) {
 			},
 			wantRefresh: false,
 		},
+		{
+			name: "expires_at as RFC3339 - far future",
+			credentials: map[string]any{
+				"expires_at": "2099-12-31T23:59:59Z", // RFC3339 格式，远未来
+			},
+			wantRefresh: false,
+		},
 		{
 			name:        "expires_at missing",
 			credentials: map[string]any{},

backend/internal/service/turnstile_service.go

@@ -5,12 +5,13 @@ import (
 	"fmt"
 	"log"
 
-	infraerrors "github.com/Wei-Shaw/sub2api/internal/infrastructure/errors"
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
 )
 
 var (
 	ErrTurnstileVerificationFailed = infraerrors.BadRequest("TURNSTILE_VERIFICATION_FAILED", "turnstile verification failed")
 	ErrTurnstileNotConfigured      = infraerrors.ServiceUnavailable("TURNSTILE_NOT_CONFIGURED", "turnstile not configured")
+	ErrTurnstileInvalidSecretKey   = infraerrors.BadRequest("TURNSTILE_INVALID_SECRET_KEY", "invalid turnstile secret key")
 )
 
 // TurnstileVerifier 验证 Turnstile token 的接口
@@ -83,3 +84,22 @@ func (s *TurnstileService) VerifyToken(ctx context.Context, token string, remote
 func (s *TurnstileService) IsEnabled(ctx context.Context) bool {
 	return s.settingService.IsTurnstileEnabled(ctx)
 }
+
+// ValidateSecretKey 验证 Turnstile Secret Key 是否有效
+func (s *TurnstileService) ValidateSecretKey(ctx context.Context, secretKey string) error {
+	// 发送一个测试token的验证请求来检查secret_key是否有效
+	result, err := s.verifier.VerifyToken(ctx, secretKey, "test-validation", "")
+	if err != nil {
+		return fmt.Errorf("validate secret key: %w", err)
+	}
+
+	// 检查是否有 invalid-input-secret 错误
+	for _, code := range result.ErrorCodes {
+		if code == "invalid-input-secret" {
+			return ErrTurnstileInvalidSecretKey
+		}
+	}
+
+	// 其他错误（如 invalid-input-response）说明 secret key 是有效的
+	return nil
+}

backend/internal/service/usage_service.go

@@ -5,7 +5,7 @@ import (
 	"fmt"
 	"time"
 
-	infraerrors "github.com/Wei-Shaw/sub2api/internal/infrastructure/errors"
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/usagestats"
 )
@@ -186,22 +186,40 @@ func (s *UsageService) GetStatsByApiKey(ctx context.Context, apiKeyID int64, sta
 
 // GetStatsByAccount 获取账号的使用统计
 func (s *UsageService) GetStatsByAccount(ctx context.Context, accountID int64, startTime, endTime time.Time) (*UsageStats, error) {
-	logs, _, err := s.usageRepo.ListByAccountAndTimeRange(ctx, accountID, startTime, endTime)
+	stats, err := s.usageRepo.GetAccountStatsAggregated(ctx, accountID, startTime, endTime)
 	if err != nil {
-		return nil, fmt.Errorf("list usage logs: %w", err)
+		return nil, fmt.Errorf("get account stats: %w", err)
 	}
 
-	return s.calculateStats(logs), nil
+	return &UsageStats{
+		TotalRequests:     stats.TotalRequests,
+		TotalInputTokens:  stats.TotalInputTokens,
+		TotalOutputTokens: stats.TotalOutputTokens,
+		TotalCacheTokens:  stats.TotalCacheTokens,
+		TotalTokens:       stats.TotalTokens,
+		TotalCost:         stats.TotalCost,
+		TotalActualCost:   stats.TotalActualCost,
+		AverageDurationMs: stats.AverageDurationMs,
+	}, nil
 }
 
 // GetStatsByModel 获取模型的使用统计
 func (s *UsageService) GetStatsByModel(ctx context.Context, modelName string, startTime, endTime time.Time) (*UsageStats, error) {
-	logs, _, err := s.usageRepo.ListByModelAndTimeRange(ctx, modelName, startTime, endTime)
+	stats, err := s.usageRepo.GetModelStatsAggregated(ctx, modelName, startTime, endTime)
 	if err != nil {
-		return nil, fmt.Errorf("list usage logs: %w", err)
+		return nil, fmt.Errorf("get model stats: %w", err)
 	}
 
-	return s.calculateStats(logs), nil
+	return &UsageStats{
+		TotalRequests:     stats.TotalRequests,
+		TotalInputTokens:  stats.TotalInputTokens,
+		TotalOutputTokens: stats.TotalOutputTokens,
+		TotalCacheTokens:  stats.TotalCacheTokens,
+		TotalTokens:       stats.TotalTokens,
+		TotalCost:         stats.TotalCost,
+		TotalActualCost:   stats.TotalActualCost,
+		AverageDurationMs: stats.AverageDurationMs,
+	}, nil
 }
 
 // GetDailyStats 获取每日使用统计（最近N天）
@@ -209,80 +227,12 @@ func (s *UsageService) GetDailyStats(ctx context.Context, userID int64, days int
 	endTime := time.Now()
 	startTime := endTime.AddDate(0, 0, -days)
 
-	logs, _, err := s.usageRepo.ListByUserAndTimeRange(ctx, userID, startTime, endTime)
+	stats, err := s.usageRepo.GetDailyStatsAggregated(ctx, userID, startTime, endTime)
 	if err != nil {
-		return nil, fmt.Errorf("list usage logs: %w", err)
-	}
-
-	// 按日期分组统计
-	dailyStats := make(map[string]*UsageStats)
-	for _, log := range logs {
-		dateKey := log.CreatedAt.Format("2006-01-02")
-		if _, exists := dailyStats[dateKey]; !exists {
-			dailyStats[dateKey] = &UsageStats{}
-		}
-
-		stats := dailyStats[dateKey]
-		stats.TotalRequests++
-		stats.TotalInputTokens += int64(log.InputTokens)
-		stats.TotalOutputTokens += int64(log.OutputTokens)
-		stats.TotalCacheTokens += int64(log.CacheCreationTokens + log.CacheReadTokens)
-		stats.TotalTokens += int64(log.TotalTokens())
-		stats.TotalCost += log.TotalCost
-		stats.TotalActualCost += log.ActualCost
-
-		if log.DurationMs != nil {
-			stats.AverageDurationMs += float64(*log.DurationMs)
-		}
-	}
-
-	// 计算平均值并转换为数组
-	result := make([]map[string]any, 0, len(dailyStats))
-	for date, stats := range dailyStats {
-		if stats.TotalRequests > 0 {
-			stats.AverageDurationMs /= float64(stats.TotalRequests)
-		}
-
-		result = append(result, map[string]any{
-			"date":                date,
-			"total_requests":      stats.TotalRequests,
-			"total_input_tokens":  stats.TotalInputTokens,
-			"total_output_tokens": stats.TotalOutputTokens,
-			"total_cache_tokens":  stats.TotalCacheTokens,
-			"total_tokens":        stats.TotalTokens,
-			"total_cost":          stats.TotalCost,
-			"total_actual_cost":   stats.TotalActualCost,
-			"average_duration_ms": stats.AverageDurationMs,
-		})
+		return nil, fmt.Errorf("get daily stats: %w", err)
 	}
 
-	return result, nil
-}
-
-// calculateStats 计算统计数据
-func (s *UsageService) calculateStats(logs []UsageLog) *UsageStats {
-	stats := &UsageStats{}
-
-	for _, log := range logs {
-		stats.TotalRequests++
-		stats.TotalInputTokens += int64(log.InputTokens)
-		stats.TotalOutputTokens += int64(log.OutputTokens)
-		stats.TotalCacheTokens += int64(log.CacheCreationTokens + log.CacheReadTokens)
-		stats.TotalTokens += int64(log.TotalTokens())
-		stats.TotalCost += log.TotalCost
-		stats.TotalActualCost += log.ActualCost
-
-		if log.DurationMs != nil {
-			stats.AverageDurationMs += float64(*log.DurationMs)
-		}
-	}
-
-	// 计算平均持续时间
-	if stats.TotalRequests > 0 {
-		stats.AverageDurationMs /= float64(stats.TotalRequests)
-	}
-
-	return stats
+	return stats, nil
 }
 
 // Delete 删除使用日志（管理员功能，谨慎使用）

backend/internal/service/user_service.go

@@ -4,7 +4,7 @@ import (
 	"context"
 	"fmt"
 
-	infraerrors "github.com/Wei-Shaw/sub2api/internal/infrastructure/errors"
+	infraerrors "github.com/Wei-Shaw/sub2api/internal/pkg/errors"
 	"github.com/Wei-Shaw/sub2api/internal/pkg/pagination"
 )
 

backend/internal/service/wire.go

@@ -73,6 +73,15 @@ func ProvideDeferredService(accountRepo AccountRepository, timingWheel *TimingWh
 	return svc
 }
 
+// ProvideConcurrencyService creates ConcurrencyService and starts slot cleanup worker.
+func ProvideConcurrencyService(cache ConcurrencyCache, accountRepo AccountRepository, cfg *config.Config) *ConcurrencyService {
+	svc := NewConcurrencyService(cache)
+	if cfg != nil {
+		svc.StartSlotCleanupWorker(accountRepo, cfg.Gateway.Scheduling.SlotCleanupInterval)
+	}
+	return svc
+}
+
 // ProviderSet is the Wire provider set for all services
 var ProviderSet = wire.NewSet(
 	// Core services
@@ -94,6 +103,7 @@ var ProviderSet = wire.NewSet(
 	NewOAuthService,
 	NewOpenAIOAuthService,
 	NewGeminiOAuthService,
+	NewGeminiQuotaService,
 	NewAntigravityOAuthService,
 	NewGeminiTokenProvider,
 	NewGeminiMessagesCompatService,
@@ -107,7 +117,7 @@ var ProviderSet = wire.NewSet(
 	ProvideEmailQueueService,
 	NewTurnstileService,
 	NewSubscriptionService,
-	NewConcurrencyService,
+	ProvideConcurrencyService,
 	NewIdentityService,
 	NewCRSSyncService,
 	ProvideUpdateService,

backend/internal/setup/setup.go

@@ -11,7 +11,7 @@ import (
 	"strconv"
 	"time"
 
-	"github.com/Wei-Shaw/sub2api/internal/infrastructure"
+	"github.com/Wei-Shaw/sub2api/internal/repository"
 	"github.com/Wei-Shaw/sub2api/internal/service"
 
 	_ "github.com/lib/pq"
@@ -262,7 +262,7 @@ func initializeDatabase(cfg *SetupConfig) error {
 
 	migrationCtx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
 	defer cancel()
-	return infrastructure.ApplyMigrations(migrationCtx, db)
+	return repository.ApplyMigrations(migrationCtx, db)
 }
 
 func createAdminUser(cfg *SetupConfig) error {

backend/migrations/010_add_usage_logs_aggregated_indexes.sql

+-- 为聚合查询补充复合索引
+CREATE INDEX IF NOT EXISTS idx_usage_logs_account_created_at ON usage_logs(account_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_usage_logs_api_key_created_at ON usage_logs(api_key_id, created_at);
+CREATE INDEX IF NOT EXISTS idx_usage_logs_model_created_at ON usage_logs(model, created_at);

backend/migrations/011_remove_duplicate_unique_indexes.sql

+-- 011_remove_duplicate_unique_indexes.sql
+-- 移除重复的唯一索引
+-- 这些字段在 ent schema 的 Fields() 中已声明 .Unique()，
+-- 因此在 Indexes() 中再次声明 index.Fields("x").Unique() 会创建重复索引。
+-- 本迁移脚本清理这些冗余索引。
+
+-- 重复索引命名约定（由 Ent 自动生成/历史迁移遗留）:
+-- - 字段级 Unique() 创建的索引名: <table>_<field>_key
+-- - Indexes() 中的 Unique() 创建的索引名: <table>_<field>
+-- - 初始化迁移中的非唯一索引: idx_<table>_<field>
+
+-- 仅当索引存在时才删除（幂等操作）
+
+-- api_keys 表: key 字段
+DROP INDEX IF EXISTS apikey_key;
+DROP INDEX IF EXISTS api_keys_key;
+DROP INDEX IF EXISTS idx_api_keys_key;
+
+-- users 表: email 字段
+DROP INDEX IF EXISTS user_email;
+DROP INDEX IF EXISTS users_email;
+DROP INDEX IF EXISTS idx_users_email;
+
+-- settings 表: key 字段
+DROP INDEX IF EXISTS settings_key;
+DROP INDEX IF EXISTS idx_settings_key;
+
+-- redeem_codes 表: code 字段
+DROP INDEX IF EXISTS redeemcode_code;
+DROP INDEX IF EXISTS redeem_codes_code;
+DROP INDEX IF EXISTS idx_redeem_codes_code;
+
+-- groups 表: name 字段
+DROP INDEX IF EXISTS group_name;
+DROP INDEX IF EXISTS groups_name;
+DROP INDEX IF EXISTS idx_groups_name;
+
+-- 注意: 每个字段的唯一约束仍由字段级 Unique() 创建的约束保留，
+-- 如 api_keys_key_key、users_email_key 等。

backend/migrations/012_add_user_subscription_soft_delete.sql

+-- 012: 为 user_subscriptions 表添加软删除支持
+-- 任务：fix-medium-data-hygiene 1.1
+
+-- 添加 deleted_at 字段
+ALTER TABLE user_subscriptions
+ADD COLUMN IF NOT EXISTS deleted_at TIMESTAMPTZ DEFAULT NULL;
+
+-- 添加 deleted_at 索引以优化软删除查询
+CREATE INDEX IF NOT EXISTS usersubscription_deleted_at
+ON user_subscriptions (deleted_at);
+
+-- 注释：与其他使用软删除的实体保持一致
+COMMENT ON COLUMN user_subscriptions.deleted_at IS '软删除时间戳，NULL 表示未删除';

backend/migrations/013_log_orphan_allowed_groups.sql

+-- 013: 记录 users.allowed_groups 中的孤立 group_id
+-- 任务：fix-medium-data-hygiene 3.1
+--
+-- 目的：在删除 legacy allowed_groups 列前，记录所有引用了不存在 group 的孤立记录
+-- 这些记录可用于审计或后续数据修复
+
+-- 创建审计表存储孤立的 allowed_groups 记录
+CREATE TABLE IF NOT EXISTS orphan_allowed_groups_audit (
+    id          BIGSERIAL PRIMARY KEY,
+    user_id     BIGINT NOT NULL,
+    group_id    BIGINT NOT NULL,
+    recorded_at TIMESTAMPTZ NOT NULL DEFAULT NOW(),
+    UNIQUE (user_id, group_id)
+);
+
+-- 记录孤立的 group_id（存在于 users.allowed_groups 但不存在于 groups 表）
+INSERT INTO orphan_allowed_groups_audit (user_id, group_id)
+SELECT u.id, x.group_id
+FROM users u
+CROSS JOIN LATERAL unnest(u.allowed_groups) AS x(group_id)
+LEFT JOIN groups g ON g.id = x.group_id
+WHERE u.allowed_groups IS NOT NULL
+  AND g.id IS NULL
+ON CONFLICT (user_id, group_id) DO NOTHING;
+
+-- 添加索引便于查询
+CREATE INDEX IF NOT EXISTS idx_orphan_allowed_groups_audit_user_id
+ON orphan_allowed_groups_audit(user_id);
+
+-- 记录迁移完成信息
+COMMENT ON TABLE orphan_allowed_groups_audit IS
+'审计表：记录 users.allowed_groups 中引用的不存在的 group_id，用于数据清理前的审计';

backend/migrations/014_drop_legacy_allowed_groups.sql

+-- 014: 删除 legacy users.allowed_groups 列
+-- 任务：fix-medium-data-hygiene 3.3
+--
+-- 前置条件：
+--   - 迁移 007 已将数据回填到 user_allowed_groups 联接表
+--   - 迁移 013 已记录所有孤立的 group_id 到审计表
+--   - 应用代码已停止写入该列（3.2 完成）
+--
+-- 该列现已废弃，所有读写操作均使用 user_allowed_groups 联接表。
+
+-- 删除 allowed_groups 列
+ALTER TABLE users DROP COLUMN IF EXISTS allowed_groups;
+
+-- 添加注释记录删除原因
+COMMENT ON TABLE users IS '用户表。注：原 allowed_groups BIGINT[] 列已迁移至 user_allowed_groups 联接表';

backend/migrations/015_fix_settings_unique_constraint.sql

+-- 015_fix_settings_unique_constraint.sql
+-- 修复 settings 表 key 字段缺失的唯一约束
+-- 此约束是 ON CONFLICT ("key") DO UPDATE 语句所必需的
+
+-- 检查并添加唯一约束（如果不存在）
+DO $$
+BEGIN
+    -- 检查是否已存在唯一约束
+    IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conrelid = 'settings'::regclass
+        AND contype = 'u'
+        AND conname = 'settings_key_key'
+    ) THEN
+        -- 添加唯一约束
+        ALTER TABLE settings ADD CONSTRAINT settings_key_key UNIQUE (key);
+    END IF;
+END
+$$;

backend/migrations/016_soft_delete_partial_unique_indexes.sql

+-- 016_soft_delete_partial_unique_indexes.sql
+-- 修复软删除 + 唯一约束冲突问题
+-- 将普通唯一约束替换为部分唯一索引（WHERE deleted_at IS NULL）
+-- 这样软删除的记录不会占用唯一约束位置，允许删后重建同名/同邮箱/同订阅关系
+
+-- ============================================================================
+-- 1. users 表: email 字段
+-- ============================================================================
+
+-- 删除旧的唯一约束（可能的命名方式）
+ALTER TABLE users DROP CONSTRAINT IF EXISTS users_email_key;
+DROP INDEX IF EXISTS users_email_key;
+DROP INDEX IF EXISTS user_email_key;
+
+-- 创建部分唯一索引：只对未删除的记录建立唯一约束
+CREATE UNIQUE INDEX IF NOT EXISTS users_email_unique_active
+    ON users(email)
+    WHERE deleted_at IS NULL;
+
+-- ============================================================================
+-- 2. groups 表: name 字段
+-- ============================================================================
+
+-- 删除旧的唯一约束
+ALTER TABLE groups DROP CONSTRAINT IF EXISTS groups_name_key;
+DROP INDEX IF EXISTS groups_name_key;
+DROP INDEX IF EXISTS group_name_key;
+
+-- 创建部分唯一索引
+CREATE UNIQUE INDEX IF NOT EXISTS groups_name_unique_active
+    ON groups(name)
+    WHERE deleted_at IS NULL;
+
+-- ============================================================================
+-- 3. user_subscriptions 表: (user_id, group_id) 组合字段
+-- ============================================================================
+
+-- 删除旧的唯一约束/索引
+ALTER TABLE user_subscriptions DROP CONSTRAINT IF EXISTS user_subscriptions_user_id_group_id_key;
+DROP INDEX IF EXISTS user_subscriptions_user_id_group_id_key;
+DROP INDEX IF EXISTS usersubscription_user_id_group_id;
+
+-- 创建部分唯一索引
+CREATE UNIQUE INDEX IF NOT EXISTS user_subscriptions_user_group_unique_active
+    ON user_subscriptions(user_id, group_id)
+    WHERE deleted_at IS NULL;
+
+-- ============================================================================
+-- 注意: api_keys 表的 key 字段保留普通唯一约束
+-- API Key 即使软删除后也不应该重复使用（安全考虑）
+-- ============================================================================

backend/migrations/017_add_gemini_tier_id.sql

+-- +goose Up
+-- +goose StatementBegin
+-- 为 Gemini Code Assist OAuth 账号添加默认 tier_id
+-- 包括显式标记为 code_assist 的账号，以及 legacy 账号（oauth_type 为空但 project_id 存在）
+UPDATE accounts
+SET credentials = jsonb_set(
+    credentials,
+    '{tier_id}',
+    '"LEGACY"',
+    true
+)
+WHERE platform = 'gemini'
+  AND type = 'oauth'
+  AND jsonb_typeof(credentials) = 'object'
+  AND credentials->>'tier_id' IS NULL
+  AND (
+    credentials->>'oauth_type' = 'code_assist'
+    OR (credentials->>'oauth_type' IS NULL AND credentials->>'project_id' IS NOT NULL)
+  );
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+-- 回滚：删除 tier_id 字段
+UPDATE accounts
+SET credentials = credentials - 'tier_id'
+WHERE platform = 'gemini'
+  AND type = 'oauth'
+  AND credentials->>'oauth_type' = 'code_assist';
+-- +goose StatementEnd

backend/migrations/README.md

+# Database Migrations
+
+## Overview
+
+This directory contains SQL migration files for database schema changes. The migration system uses SHA256 checksums to ensure migration immutability and consistency across environments.
+
+## Migration File Naming
+
+Format: `NNN_description.sql`
+- `NNN`: Sequential number (e.g., 001, 002, 003)
+- `description`: Brief description in snake_case
+
+Example: `017_add_gemini_tier_id.sql`
+
+## Migration File Structure
+
+```sql
+-- +goose Up
+-- +goose StatementBegin
+-- Your forward migration SQL here
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+-- Your rollback migration SQL here
+-- +goose StatementEnd
+```
+
+## Important Rules
+
+### ⚠️ Immutability Principle
+
+**Once a migration is applied to ANY environment (dev, staging, production), it MUST NOT be modified.**
+
+Why?
+- Each migration has a SHA256 checksum stored in the `schema_migrations` table
+- Modifying an applied migration causes checksum mismatch errors
+- Different environments would have inconsistent database states
+- Breaks audit trail and reproducibility
+
+### ✅ Correct Workflow
+
+1. **Create new migration**
+   ```bash
+   # Create new file with next sequential number
+   touch migrations/018_your_change.sql
+   ```
+
+2. **Write Up and Down migrations**
+   - Up: Apply the change
+   - Down: Revert the change (should be symmetric with Up)
+
+3. **Test locally**
+   ```bash
+   # Apply migration
+   make migrate-up
+
+   # Test rollback
+   make migrate-down
+   ```
+
+4. **Commit and deploy**
+   ```bash
+   git add migrations/018_your_change.sql
+   git commit -m "feat(db): add your change"
+   ```
+
+### ❌ What NOT to Do
+
+- ❌ Modify an already-applied migration file
+- ❌ Delete migration files
+- ❌ Change migration file names
+- ❌ Reorder migration numbers
+
+### 🔧 If You Accidentally Modified an Applied Migration
+
+**Error message:**
+```
+migration 017_add_gemini_tier_id.sql checksum mismatch (db=abc123... file=def456...)
+```
+
+**Solution:**
+```bash
+# 1. Find the original version
+git log --oneline -- migrations/017_add_gemini_tier_id.sql
+
+# 2. Revert to the commit when it was first applied
+git checkout <commit-hash> -- migrations/017_add_gemini_tier_id.sql
+
+# 3. Create a NEW migration for your changes
+touch migrations/018_your_new_change.sql
+```
+
+## Migration System Details
+
+- **Checksum Algorithm**: SHA256 of trimmed file content
+- **Tracking Table**: `schema_migrations` (filename, checksum, applied_at)
+- **Runner**: `internal/repository/migrations_runner.go`
+- **Auto-run**: Migrations run automatically on service startup
+
+## Best Practices
+
+1. **Keep migrations small and focused**
+   - One logical change per migration
+   - Easier to review and rollback
+
+2. **Write reversible migrations**
+   - Always provide a working Down migration
+   - Test rollback before committing
+
+3. **Use transactions**
+   - Wrap DDL statements in transactions when possible
+   - Ensures atomicity
+
+4. **Add comments**
+   - Explain WHY the change is needed
+   - Document any special considerations
+
+5. **Test in development first**
+   - Apply migration locally
+   - Verify data integrity
+   - Test rollback
+
+## Example Migration
+
+```sql
+-- +goose Up
+-- +goose StatementBegin
+-- Add tier_id field to Gemini OAuth accounts for quota tracking
+UPDATE accounts
+SET credentials = jsonb_set(
+    credentials,
+    '{tier_id}',
+    '"LEGACY"',
+    true
+)
+WHERE platform = 'gemini'
+  AND type = 'oauth'
+  AND credentials->>'tier_id' IS NULL;
+-- +goose StatementEnd
+
+-- +goose Down
+-- +goose StatementBegin
+-- Remove tier_id field
+UPDATE accounts
+SET credentials = credentials - 'tier_id'
+WHERE platform = 'gemini'
+  AND type = 'oauth'
+  AND credentials->>'tier_id' = 'LEGACY';
+-- +goose StatementEnd
+```
+
+## Troubleshooting
+
+### Checksum Mismatch
+See "If You Accidentally Modified an Applied Migration" above.
+
+### Migration Failed
+```bash
+# Check migration status
+psql -d sub2api -c "SELECT * FROM schema_migrations ORDER BY applied_at DESC;"
+
+# Manually rollback if needed (use with caution)
+# Better to fix the migration and create a new one
+```
+
+### Need to Skip a Migration (Emergency Only)
+```sql
+-- DANGEROUS: Only use in development or with extreme caution
+INSERT INTO schema_migrations (filename, checksum, applied_at)
+VALUES ('NNN_migration.sql', 'calculated_checksum', NOW());
+```
+
+## References
+
+- Migration runner: `internal/repository/migrations_runner.go`
+- Goose syntax: https://github.com/pressly/goose
+- PostgreSQL docs: https://www.postgresql.org/docs/

deploy/.env.example

@@ -86,3 +86,11 @@ GEMINI_OAUTH_CLIENT_ID=
 GEMINI_OAUTH_CLIENT_SECRET=
 # Optional; leave empty to auto-select scopes based on oauth_type
 GEMINI_OAUTH_SCOPES=
+
+# -----------------------------------------------------------------------------
+# Gemini Quota Policy (OPTIONAL, local simulation)
+# -----------------------------------------------------------------------------
+# JSON overrides for local quota simulation (Code Assist only).
+# Example:
+# GEMINI_QUOTA_POLICY={"tiers":{"LEGACY":{"pro_rpd":50,"flash_rpd":1500,"cooldown_minutes":30},"PRO":{"pro_rpd":1500,"flash_rpd":4000,"cooldown_minutes":5},"ULTRA":{"pro_rpd":2000,"flash_rpd":0,"cooldown_minutes":5}}}
+GEMINI_QUOTA_POLICY=

deploy/README.md

@@ -123,6 +123,7 @@ docker-compose down -v
 | `GEMINI_OAUTH_CLIENT_ID` | No | *(builtin)* | Google OAuth client ID (Gemini OAuth). Leave empty to use the built-in Gemini CLI client. |
 | `GEMINI_OAUTH_CLIENT_SECRET` | No | *(builtin)* | Google OAuth client secret (Gemini OAuth). Leave empty to use the built-in Gemini CLI client. |
 | `GEMINI_OAUTH_SCOPES` | No | *(default)* | OAuth scopes (Gemini OAuth) |
+| `GEMINI_QUOTA_POLICY` | No | *(empty)* | JSON overrides for Gemini local quota simulation (Code Assist only). |
 
 See `.env.example` for all available options.
 

deploy/config.example.yaml

@@ -21,6 +21,32 @@ server:
 # - simple: Hides SaaS features and skips billing/balance checks
 run_mode: "standard"
 
+# =============================================================================
+# 网关配置
+# =============================================================================
+gateway:
+  # 等待上游响应头超时时间（秒）
+  response_header_timeout: 300
+  # 请求体最大字节数（默认 100MB）
+  max_body_size: 104857600
+  # 连接池隔离策略：
+  # - proxy: 按代理隔离，同一代理共享连接池（适合代理少、账户多）
+  # - account: 按账户隔离，同一账户共享连接池（适合账户少、需严格隔离）
+  # - account_proxy: 按账户+代理组合隔离（默认，最细粒度）
+  connection_pool_isolation: "account_proxy"
+  # HTTP 上游连接池配置（HTTP/2 + 多代理场景默认）
+  max_idle_conns: 240
+  max_idle_conns_per_host: 120
+  max_conns_per_host: 240
+  idle_conn_timeout_seconds: 300
+  # 上游连接池客户端缓存配置
+  # max_upstream_clients: 最大缓存客户端数量，超出后淘汰最久未使用的
+  # client_idle_ttl_seconds: 客户端空闲回收阈值（秒），超时且无活跃请求时回收
+  max_upstream_clients: 5000
+  client_idle_ttl_seconds: 900
+  # 并发槽位过期时间（分钟）
+  concurrency_slot_ttl_minutes: 15
+
 # =============================================================================
 # Database Configuration (PostgreSQL)
 # =============================================================================
@@ -96,6 +122,21 @@ pricing:
   # Hash check interval in minutes
   hash_check_interval_minutes: 10
 
+# =============================================================================
+# Gateway (Optional)
+# =============================================================================
+gateway:
+  # Wait time (in seconds) for upstream response headers (streaming body not affected)
+  response_header_timeout: 300
+  # Log upstream error response body summary (safe/truncated; does not log request content)
+  log_upstream_error_body: false
+  # Max bytes to log from upstream error body
+  log_upstream_error_body_max_bytes: 2048
+  # Auto inject anthropic-beta for API-key accounts when needed (default off)
+  inject_beta_for_apikey: false
+  # Allow failover on selected 400 errors (default off)
+  failover_on_400: false
+
 # =============================================================================
 # Gemini OAuth (Required for Gemini accounts)
 # =============================================================================
@@ -115,3 +156,19 @@ gemini:
     client_secret: "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"
     # Optional scopes (space-separated). Leave empty to auto-select based on oauth_type.
     scopes: ""
+  quota:
+    # Optional: local quota simulation for Gemini Code Assist (local billing).
+    # These values are used for UI progress + precheck scheduling, not official Google quotas.
+    tiers:
+      LEGACY:
+        pro_rpd: 50
+        flash_rpd: 1500
+        cooldown_minutes: 30
+      PRO:
+        pro_rpd: 1500
+        flash_rpd: 4000
+        cooldown_minutes: 5
+      ULTRA:
+        pro_rpd: 2000
+        flash_rpd: 0
+        cooldown_minutes: 5

deploy/docker-compose-test.yml

@@ -19,6 +19,10 @@ services:
     image: sub2api:latest
     container_name: sub2api
     restart: unless-stopped
+    ulimits:
+      nofile:
+        soft: 100000
+        hard: 100000
     ports:
       - "${BIND_HOST:-0.0.0.0}:${SERVER_PORT:-8080}:8080"
     volumes:
@@ -86,6 +90,7 @@ services:
       - GEMINI_OAUTH_CLIENT_ID=${GEMINI_OAUTH_CLIENT_ID:-}
       - GEMINI_OAUTH_CLIENT_SECRET=${GEMINI_OAUTH_CLIENT_SECRET:-}
       - GEMINI_OAUTH_SCOPES=${GEMINI_OAUTH_SCOPES:-}
+      - GEMINI_QUOTA_POLICY=${GEMINI_QUOTA_POLICY:-}
     depends_on:
       postgres:
         condition: service_healthy
@@ -107,6 +112,10 @@ services:
     image: postgres:18-alpine
     container_name: sub2api-postgres
     restart: unless-stopped
+    ulimits:
+      nofile:
+        soft: 100000
+        hard: 100000
     volumes:
       - postgres_data:/var/lib/postgresql/data
     environment:
@@ -132,6 +141,10 @@ services:
     image: redis:7-alpine
     container_name: sub2api-redis
     restart: unless-stopped
+    ulimits:
+      nofile:
+        soft: 100000
+        hard: 100000
     volumes:
       - redis_data:/data
     command: >