GitLab

Restore account_usage_service.go, antigravity_gateway_service.go,
antigravity_credits_overages.go and its test to upstream/main state.
These credits balance precheck changes were accidentally included
during cherry-pick of channel management commits.

- Parse candidatesTokensDetails from Gemini API to separate image/text output tokens
- Add image_output_tokens and image_output_cost to usage_log (migration 089)
- Support per-image-token pricing via output_cost_per_image_token from model pricing data
- Channel pricing ImageOutputPrice override works in token billing mode
- Auto-fill image_output_price in channel pricing form from model defaults
- Add "channel_mapped" billing model source as new default (migration 088)
- Bills by model name after channel mapping, before account mapping
- Fix channel cache error TTL sign error (115s → 5s)
- Fix Update channel only invalidating new groups, not removed groups
- Fix frontend model_mapping clearing sending undefined instead of {}
- Credits balance precheck via shared AccountUsageService cache before injection
- Skip credits injection for accounts with insufficient balance
- Don't mark credits exhausted for "exhausted your capacity on this model" 429s

- 定价查找支持通配符(suffix *)，最长前缀优先匹配
- 模型限制(restrict_models)同样支持通配符匹配
- OpenAI 网关接入渠道映射/BillingModelSource/模型限制
- 按次/图片计费模式创建时强制要求价格或层级(前后端)
- 用户使用记录列表增加计费模式 badge 列

- GatewayService/OpenAIGatewayService 注入 ModelPricingResolver
- RecordUsage 从旧路径迁移到 CalculateCostUnified（支持 per_request/image 模式）
- 无渠道时自动回退旧路径，保持原有行为
- 长上下文双倍计费仅在无渠道定价时生效
- CostBreakdown 新增 BillingMode 字段，使用日志记录实际计费模式
- 模型限制错误改为与"无可用账号"相同的 503 响应

- 新增 GET /admin/channels/model-pricing?model=xxx API
- 从 BillingService 查询 LiteLLM/Fallback 默认定价
- 前端添加模型时自动查询并填充价格（$/MTok）
- 仅在所有价格字段为空时才自动填充，不覆盖手动配置

Cherry-picked from release/custom-0.1.106: a9117600

shaw authored Mar 27, 2026 and 陈曦 committed Mar 29, 2026

新增功能：
- 新增 TLS 指纹 Profile CRUD 管理（Ent schema + 迁移 + Admin API + 前端管理界面）
- 支持账号绑定数据库中的自定义 TLS Profile，或随机选择（profile_id=-1）
- HTTPUpstream.DoWithTLS 接口从 bool 改为 *tlsfingerprint.Profile，支持按账号指定 Profile
- AccountUsageService 注入 TLSFingerprintProfileService，统一 usage 场景与网关的 Profile 解析逻辑

代码优化：
- 删除已被 TLSFingerprintProfileService 完全取代的 registry.go 死代码（418 行）
- 提取 3 个 dialer 的重复 TLS 握手逻辑为 performTLSHandshake() 共用函数
- 修复 GetTLSFingerprintProfileID 缺少 json.Number 处理的 bug
- gateway_service.Forward 中 ResolveTLSProfile 从重试循环内重复调用改为预解析局部变量
- 删除冗余的 buildClientHelloSpec() 单行 wrapper 和 int64(e.ID) 无效转换
- tls_fingerprint_profile_cache.go 日志从 log.Printf 改为 slog 结构化日志
- dialer_capture_test.go 添加 //go:build integration 标签，防止 CI 失败
- 去重 TestProfileExpectation 类型至共享 test_types_test.go
- 修复 9 个测试文件缺少 tlsfingerprint import 的编译错误
- 修复 error_policy_integration_test.go 中 handleError 回调签名被错误替换的问题

When an antigravity account returns 500 "Internal error encountered."
on all 3 retry attempts, increment a Redis counter and apply escalating
penalties:
- 1st round: temp unschedulable 10 minutes
- 2nd round: temp unschedulable 10 hours
- 3rd round: permanently mark as error

Counter resets on any successful response (< 400).

新增功能：
- 新增 TLS 指纹 Profile CRUD 管理（Ent schema + 迁移 + Admin API + 前端管理界面）
- 支持账号绑定数据库中的自定义 TLS Profile，或随机选择（profile_id=-1）
- HTTPUpstream.DoWithTLS 接口从 bool 改为 *tlsfingerprint.Profile，支持按账号指定 Profile
- AccountUsageService 注入 TLSFingerprintProfileService，统一 usage 场景与网关的 Profile 解析逻辑

代码优化：
- 删除已被 TLSFingerprintProfileService 完全取代的 registry.go 死代码（418 行）
- 提取 3 个 dialer 的重复 TLS 握手逻辑为 performTLSHandshake() 共用函数
- 修复 GetTLSFingerprintProfileID 缺少 json.Number 处理的 bug
- gateway_service.Forward 中 ResolveTLSProfile 从重试循环内重复调用改为预解析局部变量
- 删除冗余的 buildClientHelloSpec() 单行 wrapper 和 int64(e.ID) 无效转换
- tls_fingerprint_profile_cache.go 日志从 log.Printf 改为 slog 结构化日志
- dialer_capture_test.go 添加 //go:build integration 标签，防止 CI 失败
- 去重 TestProfileExpectation 类型至共享 test_types_test.go
- 修复 9 个测试文件缺少 tlsfingerprint import 的编译错误
- 修复 error_policy_integration_test.go 中 handleError 回调签名被错误替换的问题

1. accounts/check 补全 plan_type：当 id_token 缺少 plan_type（如 Mobile RT），
   自动调用 accounts/check 端点获取订阅类型
2. orgID 精确匹配账号：从 JWT 提取 poid 匹配正确账号，避免 Go map
   遍历顺序随机导致 plan_type 不稳定
3. RT 刷新时设置隐私：调用 disableOpenAITraining 关闭训练数据共享，
   结果存入 extra.privacy_mode，后续跳过重复设置
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

## Problem

When a proxy is unreachable, token refresh retries up to 4 times with
30s timeout each, causing requests to hang for ~2 minutes before
failing with a generic 502 error. The failed account is not marked,
so subsequent requests keep hitting it.

## Changes

### Proxy connection fast-fail
- Set TCP dial timeout to 5s and TLS handshake timeout to 5s on
  antigravity client, so proxy connectivity issues fail within 5s
  instead of 30s
- Reduce overall HTTP client timeout from 30s to 10s
- Export `IsConnectionError` for service-layer use
- Detect proxy connection errors in `RefreshToken` and return
  immediately with "proxy unavailable" error (no retries)

### Token refresh temp-unschedulable
- Add 8s context timeout for token refresh on request path
- Mark account as temp-unschedulable for 10min when refresh fails
  (both background `TokenRefreshService` and request-path
  `GetAccessToken`)
- Sync temp-unschedulable state to Redis cache for immediate
  scheduler effect
- Inject `TempUnschedCache` into `AntigravityTokenProvider`

### Account failover
- Return `UpstreamFailoverError` on `GetAccessToken` failure in
  `Forward`/`ForwardGemini` to trigger handler-level account switch
  instead of returning 502 directly

### Proxy probe alignment
- Apply same 5s dial/TLS timeout to shared `httpclient` pool
- Reduce proxy probe timeout from 30s to 10s

复用 GroupCapacityService，在 admin 分组列表中添加容量列，
显示每个分组的实时并发/会话/RPM 使用量和上限。
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

分组管理列表增强：

1. 今日/累计用量列：
   - 新增独立端点 GET /admin/groups/usage-summary
   - 一次查询返回所有分组的今日费用和累计费用（actual_cost）
   - 前端异步加载后合并显示在分组列表中

2. 账号数区分可用/限流/总量：
   - 将账号数列从单一总量改为 badge 内多行展示
   - 可用: active + schedulable 的账号数（绿色）
   - 限流: rate_limit/overload/temp_unschedulable 的账号数（橙色，无限流时隐藏）
   - 总量: 全部关联账号数
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Introduce OAuthRefreshAPI as the single entry point for all OAuth token
refresh operations, eliminating the race condition where background
refresh and inline refresh could simultaneously use the same
refresh_token (fixes #1035).

Key changes:
- Add OAuthRefreshExecutor interface extending TokenRefresher with CacheKey
- Add OAuthRefreshAPI.RefreshIfNeeded with lock → DB re-read → double-check flow
- Add ProviderRefreshPolicy / BackgroundRefreshPolicy strategy types
- Simplify all 4 TokenProviders to delegate to OAuthRefreshAPI
- Rewrite TokenRefreshService.refreshWithRetry to use unified API path
- Add MergeCredentials and BuildClaudeAccountCredentials helpers
- Add 40 unit tests covering all new and modified code paths

1. S3 凭证加密存储：使用 SecretEncryptor (AES-256-GCM) 加密 SecretAccessKey，
   防止备份文件中泄露 S3 凭证，兼容旧的未加密数据
2. 修复 saveRecord 竞态条件：添加 recordsMu 互斥锁保护 records 的 load/save
3. 恢复操作增加服务端验证：handler 层要求重新输入管理员密码，通过 bcrypt
   校验，前端弹出密码输入框
4. pg_dump/psql/S3 操作抽象为接口：定义 DBDumper 和 BackupObjectStore 接口，
   实现放入 repository 层，遵循项目依赖注入架构规范
5. 改为流式处理避免大数据库 OOM：备份时 pg_dump stdout -> gzip -> io.Pipe ->
   S3 upload；恢复时 S3 download -> gzip reader -> psql stdin，不再全量加载
6. loadRecords 区分"无数据"和"数据损坏"场景：JSON 解析失败返回明确错误
7. 添加 18 个核心逻辑单元测试：覆盖加密、并发、流式备份/恢复、错误处理等
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

新增管理员专属的数据库备份与恢复功能：
- 全量 PostgreSQL 备份（pg_dump），gzip 压缩后上传到 S3 兼容存储
- 支持手动备份和 cron 定时备份
- 支持从备份恢复（psql --single-transaction）
- 备份文件自动过期清理（默认 14 天）
- 前端完整管理页面（S3 配置、定时配置、备份列表、恢复/下载/删除）
- 内置 Cloudflare R2 配置教程弹窗
- Dockerfile 从 postgres 镜像多阶段复制 pg_dump/psql，确保版本一致
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

之前管理员无法通过 API 密钥管理将用户绑定到订阅类型分组（直接返回错误）。
现在改为检查用户是否持有该分组的有效订阅，有则允许绑定，无则拒绝。

- admin_service: 新增 userSubRepo 依赖，替换硬拒绝为订阅校验
- admin_service: 区分 ErrSubscriptionNotFound 和内部错误，避免 DB 故障被误报
- wire_gen/api_contract_test: 同步新增参数
- UserApiKeysModal: 管理员分组下拉不再过滤订阅类型分组
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

- 为定时测试计划增加 auto_recover 配置，补齐前后端类型、接口、仓储与数据库迁移
- 在定时测试成功后自动恢复账号 error、rate-limit 等可恢复运行时状态
- 新增 /admin/accounts/:id/recover-state 接口，合并原有重置状态与清限流操作
- 更新账号管理菜单与定时测试面板，补充自动恢复开关、说明提示和状态展示
- 补充账号恢复、限流清理与仓储同步相关测试

抽取共享的用户分组专属倍率解析器，统一缓存、singleflight 与回退逻辑。\n\n让 OpenAI 独立计费链路复用专属倍率解析，修复 usage 记录与实际扣费未命中用户专属倍率的问题。\n\n补齐 OpenAI 计费与解析器单元测试，并修复全量回归中暴露的 lint 阻塞项。\n\nCo-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

将 redis leader lock 逻辑从 service 层抽取为 LeaderLocker 接口，
实现移至 repository 层，消除 service 层对 redis 的直接依赖。
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

每个测试计划绑定一个账号和一个模型，按 cron 表达式定期执行测试，
保存历史结果并在前端账号管理页面中提供完整的增删改查和结果查看功能。

主要变更：
- 新增 scheduled_test_plans / scheduled_test_results 两张表及迁移
- 后端 service 层：CRUD 服务 + 后台 cron runner（每分钟扫描到期计划并发执行）
- RunTestBackground 方法通过 httptest 在内存中执行账号测试并解析 SSE 输出
- Redis leader lock + pg_try_advisory_lock 双重保障多实例部署只执行一次
- REST API：5 个管理端点（计划 CRUD + 结果查询）
- 前端 ScheduledTestsPanel 组件：计划管理、启用开关、内联编辑、结果展开查看
- 中英文 i18n 支持
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

新增 UMQ (User Message Queue) 双模式支持:
- serialize: 账号级分布式串行锁 + RPM 自适应延迟（严格限流）
- throttle: 仅 RPM 自适应前置延迟，不阻塞并发（软性限速）

后端:
- config: 新增 Mode 字段，保留 Enabled 向后兼容
- service: 新增 UserMessageQueueService（Lua 锁/延迟算法/清理 worker）
- repository: 新增 UserMsgQueueCache（Redis Lua acquire/release/force-release）
- handler: 新增 UserMsgQueueHelper（SSE ping + 等待循环 + throttle）
- gateway: 按 mode 分支集成 serialize/throttle 逻辑
- lint: 修复 gofmt rewrite rules、errcheck 类型断言、staticcheck QF1012

前端:
- 三态选择器 UI（关闭/软性限速/串行队列）替代 toggle 开关
- BulkEdit 支持 null 语义（不修改）
- i18n 中英文文案

通过 6 轮专家评审（42 次 review）、golangci-lint、单元测试、集成测试。

OAuth 账号收到 401 时，原逻辑同时设置 expires_at=now() 和 SetError()，
但刷新服务只查询 status=active 的账号，导致 error 状态的账号永远无法
被刷新服务拾取，expires_at=now() 实际上是死代码。

修复:
- OAuth 401 使用 SetTempUnschedulable 替代 SetError，保持 status=active
- 新增 oauth_401_cooldown_minutes 配置项（默认 10 分钟）
- 刷新成功后同步清除 DB 和 Redis 中的临时不可调度状态
- 不可重试错误检查(invalid_grant 等)从 Antigravity 推广到所有平台
- 可重试错误耗尽后不再标记 error，下个刷新周期继续重试

恢复流程:
OAuth 401 → temp_unschedulable + expires_at=now → 刷新服务拾取
  → 成功: 清除 temp_unschedulable → 自动恢复
  → invalid_grant: SetError → 永久禁用
  → 网络错误: 仅记日志 → 下周期重试

- add default subscriptions to admin settings

- auto-assign subscriptions on register and admin user creation

- add validation/tests and align settings UI with subscription selector patterns

- 通过 User-Agent 识别 Claude Code 客户端并提取版本号
- 在网关层验证客户端版本是否满足管理员配置的最低要求
- 在管理后台提供版本要求配置选项（英文/中文双语）
- 实现原子缓存 + singleflight 防止并发问题和 thundering herd
- 使用 context.WithoutCancel 隔离 DB 查询，避免客户端断连影响缓存
- 双 TTL 策略：60s 正常、5s 错误恢复，保证性能与可用性
- 仅检查 Claude Code 客户端，其他客户端不受影响
- 添加完整单元测试覆盖版本提取、比对、上下文操作

## 核心功能
- 添加 AdminUpdateAPIKeyGroupID 服务方法，支持绑定/解绑/保持不变三态语义
- 实现 UserRepository.AddGroupToAllowedGroups 接口，自动同步专属分组权限
- 添加 HTTP PUT /api-keys/:id handler 端点，支持管理员直接修改 API Key 分组

## 事务一致性
- 使用 ent Tx 保证专属分组绑定时「添加权限」和「更新 Key」的原子性
- Repository 方法支持 clientFromContext，兼容事务内调用
- 事务失败时自动回滚，避免权限孤立

## 业务逻辑
- 订阅类型分组阻断，需通过订阅管理流程
- 非活跃分组拒绝绑定
- 负 ID 和非法 ID 验证
- 自动授权响应，告知管理员成功授权的分组

## 代码质量
- 16 个单元测试覆盖所有业务路径和边界用例
- 7 个 handler 集成测试覆盖 HTTP 层
- GroupRepo stub 返回克隆副本，防止测试间数据泄漏
- API 类型安全修复（PaginatedResponse<ApiKey>）
- 前端 ref 回调类型对齐 Vue 规范

## 国际化支持
- 中英文提示信息完整
- 自动授权成功/失败提示

- 新增 PUT /api/v1/admin/api-keys/:id 端点，允许管理员修改任意用户 API Key 的分组绑定
- 跳过用户级权限校验但保留分组有效性验证，修改后触发认证缓存失效
- Service 层支持三态语义：nil=不修改，0=解绑，>0=绑定，<0=拒绝
- 指针值拷贝保证安全隔离，负数 groupID 返回 400 INVALID_GROUP_ID
- 前端 UserApiKeysModal 新增可点击的分组选择下拉框，支持多 Key 并发更新
- 下拉支持视口翻转和滚动关闭，按钮有 disabled 和加载状态
- 覆盖：后端 20 个单元测试 (Service 11 + Handler 9) + 前端 16 个 E2E 测试
- golangci-lint 0 issues, make test-unit 全部通过

FetchGoogleOneTier 原先在方法内部直接创建 DriveClient 实例，
导致单元测试中对 googleapis.com 发起真实 HTTP 请求，在 CI 环境
产生 401 错误。

将 DriveClient 作为依赖注入到 GeminiOAuthService，遵循项目
端口与适配器架构规范：
- 新增 repository/gemini_drive_client.go 作为 Provider
- 注册到 repository Wire ProviderSet
- 测试中使用 mockDriveClient 替代真实调用

使用 go-sora2api v1.1.0 SDK 替代原有 ~2000 行自建 HTTP/PoW/TLS 指纹代码，
SDK 提供高并发性能优化（实例级 rand、PoW 缓冲区复用、context.Context 支持）。

- 新增 SoraSDKClient 适配器实现 SoraClient 接口
- 精简 sora_client.go 为仅保留接口和类型定义
- 更新 Wire 绑定使用 SoraSDKClient
- 删除 SoraDirectClient、sora_curl_cffi_sidecar、sora_request_guard 等旧代码
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>