feat: add account enable scheduling toggle

Author: Cshvee

.trellis/spec/backend/database-guidelines.md

@@ -0,0 +1,100 @@
+# Database Guidelines
+
+> Database patterns and conventions for this project.
+
+---
+
+## Overview
+
+<!--
+Document your project's database conventions here.
+
+Questions to answer:
+- What ORM/query library do you use?
+- How are migrations managed?
+- What are the naming conventions for tables/columns?
+- How do you handle transactions?
+-->
+
+(To be filled by the team)
+
+---
+
+## Query Patterns
+
+<!-- How should queries be written? Batch operations? -->
+
+(To be filled by the team)
+
+---
+
+## Migrations
+
+<!-- How to create and run migrations -->
+
+### Scenario: Backward-Compatible Account Flags
+
+#### 1. Scope / Trigger
+
+- Trigger: adding a persisted account-level boolean flag used by runtime/admin behavior.
+- This project supports both PostgreSQL and SQLite, so every new account column needs both migration paths.
+
+#### 2. Signatures
+
+- PostgreSQL migration: `ALTER TABLE accounts ADD COLUMN IF NOT EXISTS <flag> BOOLEAN DEFAULT <value>;`
+- SQLite migration registry: add `{"accounts", "<flag>", "INTEGER DEFAULT <0|1>"}` to `migrateSQLite`.
+- Row model: add the field to `AccountRow` and to all account row `SELECT`/`Scan` lists that return full account state.
+
+#### 3. Contracts
+
+- Account flags that should preserve old data must use a default matching existing behavior.
+- Reads should use `COALESCE(<flag>, <default>)` so older rows and partially migrated databases retain expected semantics.
+- Account list queries should continue loading all non-deleted accounts unless the feature explicitly changes account visibility.
+
+#### 4. Validation & Error Matrix
+
+- Missing column before migration -> migration must create it without data loss.
+- Existing row with `NULL` flag -> `COALESCE` must return the default behavior.
+- Setter update failure -> return the database error to the admin handler; do not silently ignore it.
+
+#### 5. Good/Base/Bad Cases
+
+- Good: `enabled` defaults to true and `COALESCE(enabled, true)` is selected into `AccountRow.Enabled`.
+- Base: inserting an account without specifying the flag keeps old behavior.
+- Bad: filtering rows by the flag in `ListActive` when the flag only controls scheduling.
+
+#### 6. Tests Required
+
+- Fresh SQLite database initializes with the new column.
+- Inserted account has the expected default flag value.
+- Setter toggles the flag and `ListActive` reflects the value.
+
+#### 7. Wrong vs Correct
+
+Wrong:
+```sql
+SELECT ... FROM accounts WHERE status <> 'deleted' AND enabled = true;
+```
+
+Correct:
+```sql
+SELECT ..., COALESCE(enabled, true)
+FROM accounts
+WHERE status <> 'deleted' AND COALESCE(error_message, '') <> 'deleted';
+```
+
+---
+
+## Naming Conventions
+
+<!-- Table names, column names, index names -->
+
+(To be filled by the team)
+
+---
+
+## Common Mistakes
+
+<!-- Database-related mistakes your team has made -->
+
+(To be filled by the team)

.trellis/spec/backend/quality-guidelines.md

@@ -0,0 +1,102 @@
+# Quality Guidelines
+
+> Code quality standards for backend development.
+
+---
+
+## Overview
+
+<!--
+Document your project's quality standards here.
+
+Questions to answer:
+- What patterns are forbidden?
+- What linting rules do you enforce?
+- What are your testing requirements?
+- What code review standards apply?
+-->
+
+(To be filled by the team)
+
+---
+
+## Forbidden Patterns
+
+<!-- Patterns that should never be used and why -->
+
+(To be filled by the team)
+
+---
+
+## Required Patterns
+
+<!-- Patterns that must always be used -->
+
+### Scenario: Dispatch-Only Account Gates
+
+#### 1. Scope / Trigger
+
+- Trigger: adding or changing account flags that control whether an account may receive new proxied requests.
+- This is a cross-layer contract because the flag is stored in DB, exposed by admin API, synced into runtime state, and shown in the UI.
+
+#### 2. Signatures
+
+- Runtime flag: `auth.Account.DispatchPaused int32`.
+- Admin API: `POST /api/admin/accounts/:id/enable` with `{"enabled": boolean}`.
+- Database setter: `SetAccountEnabled(ctx context.Context, id int64, enabled bool) error`.
+
+#### 3. Contracts
+
+- `enabled=true`: account is eligible for normal scheduler/dispatch selection if all existing health, cooldown, usage, API-key, and concurrency gates also pass.
+- `enabled=false`: account is excluded from scheduler/dispatch selection only.
+- `enabled=false` must not block RT refresh, AT refresh, manual refresh, token cache writes, testing, usage probes, recovery probes, import/export, auto-clean, account list visibility, credential updates, or existing `locked` semantics.
+- `locked` is separate and means auto-clean protection; do not reuse it as a dispatch gate.
+
+#### 4. Validation & Error Matrix
+
+- Invalid `:id` -> `400` with the existing admin error response helper.
+- Malformed JSON body -> `400`.
+- Database update failure -> `500`.
+- Nonexistent IDs follow the existing account flag setter behavior unless the setter is explicitly changed across all account flag endpoints.
+
+#### 5. Good/Base/Bad Cases
+
+- Good: `IsAvailable()` and `fastSchedulerSnapshot()` both reject `DispatchPaused`.
+- Base: disabled accounts still appear in `ListAccounts` and can be manually refreshed.
+- Bad: filtering `enabled=false` inside `ListActive`, `parallelRefreshAll`, usage probes, recovery probes, or clean-up paths.
+
+#### 6. Tests Required
+
+- Scheduler tests proving disabled accounts are skipped by both normal and fast scheduler paths.
+- Regression tests proving disabled accounts still participate in usage probes, recovery probes, and auto-clean.
+- Database tests proving new accounts default to enabled and can be toggled.
+
+#### 7. Wrong vs Correct
+
+Wrong:
+```go
+// This hides disabled accounts from refresh, probes, UI, and clean-up.
+SELECT ... FROM accounts WHERE enabled = true
+```
+
+Correct:
+```go
+// Load all non-deleted accounts and apply the enabled gate only in dispatch selection.
+SELECT ..., COALESCE(enabled, true) FROM accounts WHERE status <> 'deleted'
+```
+
+---
+
+## Testing Requirements
+
+<!-- What level of testing is expected -->
+
+(To be filled by the team)
+
+---
+
+## Code Review Checklist
+
+<!-- What reviewers should check -->
+
+(To be filled by the team)

admin/handler.go

@@ -109,6 +109,7 @@ func (h *Handler) RegisterRoutes(r *gin.Engine) {
 	api.PATCH("/accounts/:id/scheduler", h.UpdateAccountScheduler)
 	api.DELETE("/accounts/:id", h.DeleteAccount)
 	api.POST("/accounts/:id/refresh", h.RefreshAccount)
+	api.POST("/accounts/:id/enable", h.ToggleAccountEnabled)
 	api.POST("/accounts/:id/lock", h.ToggleAccountLock)
 	api.POST("/accounts/:id/reset-status", h.ResetAccountStatus)
 	api.GET("/accounts/:id/test", h.TestConnection)
@@ -294,6 +295,7 @@ type accountResponse struct {
 	LastRateLimitedAt        string                     `json:"last_rate_limited_at,omitempty"`
 	LastTimeoutAt            string                     `json:"last_timeout_at,omitempty"`
 	LastServerErrorAt        string                     `json:"last_server_error_at,omitempty"`
+	Enabled                  bool                       `json:"enabled"`
 	Locked                   bool                       `json:"locked"`
 	AllowedAPIKeyIDs         []int64                    `json:"allowed_api_key_ids"`
 }
@@ -349,6 +351,7 @@ func (h *Handler) ListAccounts(c *gin.Context) {
 			Status:                   row.Status,
 			ATOnly:                   row.GetCredential("refresh_token") == "" && row.GetCredential("access_token") != "",
 			ProxyURL:                 row.ProxyURL,
+			Enabled:                  row.Enabled,
 			Locked:                   row.Locked,
 			AllowedAPIKeyIDs:         row.GetCredentialInt64Slice("allowed_api_key_ids"),
 			ScoreBiasOverride:        nullableInt64Pointer(row.ScoreBiasOverride),
@@ -1651,6 +1654,40 @@ func (h *Handler) RefreshAccount(c *gin.Context) {
 	writeMessage(c, http.StatusOK, "账号刷新成功")
 }
 
+// ToggleAccountEnabled 切换账号是否参与调度选择
+func (h *Handler) ToggleAccountEnabled(c *gin.Context) {
+	idStr := c.Param("id")
+	id, err := strconv.ParseInt(idStr, 10, 64)
+	if err != nil {
+		writeError(c, http.StatusBadRequest, "无效的账号 ID")
+		return
+	}
+
+	var req struct {
+		Enabled bool `json:"enabled"`
+	}
+	if err := c.ShouldBindJSON(&req); err != nil {
+		writeError(c, http.StatusBadRequest, "请求格式错误")
+		return
+	}
+
+	ctx, cancel := context.WithTimeout(c.Request.Context(), 3*time.Second)
+	defer cancel()
+
+	if err := h.db.SetAccountEnabled(ctx, id, req.Enabled); err != nil {
+		writeError(c, http.StatusInternalServerError, "更新启用状态失败: "+err.Error())
+		return
+	}
+
+	h.store.ApplyAccountEnabled(id, req.Enabled)
+
+	if req.Enabled {
+		writeMessage(c, http.StatusOK, "账号已启用")
+	} else {
+		writeMessage(c, http.StatusOK, "账号已禁用")
+	}
+}
+
 // ToggleAccountLock 切换账号的锁定状态
 func (h *Handler) ToggleAccountLock(c *gin.Context) {
 	idStr := c.Param("id")

auth/fast_scheduler.go

@@ -402,6 +402,9 @@ func (a *Account) fastSchedulerSnapshot(baseLimit int64, now time.Time) (Account
 	}
 
 	available := a.Status != StatusError && tier != HealthTierBanned && a.AccessToken != ""
+	if atomic.LoadInt32(&a.DispatchPaused) != 0 {
+		available = false
+	}
 	if a.Status == StatusCooldown && now.Before(a.CooldownUtil) && !a.premium5hCooldownSuppressedLocked(now) {
 		available = false
 	}