GitLab

将仓储层/基础设施改为 Ent + 原生 SQL 执行路径，并移除 AutoMigrate 与 GORM 依赖。
重构内容包括：
- 仓储层改用 Ent/SQL（含 usage_log/account 等复杂查询），统一错误映射
- 基础设施与 setup 初始化切换为 Ent + SQL migrations
- 集成测试与 fixtures 迁移到 Ent 事务模型
- 清理遗留 GORM 模型/依赖，补充迁移与文档说明
- 增加根目录 Makefile 便于前后端编译

测试：
- go test -tags unit ./...
- go test -tags integration ./...

  - apiKeyService.GetByKey(...) 返回的“找不到 API key”在这个项目里通常会被翻译成业务错误（比如
    service.ErrApiKeyNotFound 这类 ApplicationError），而不是直接把 gorm.ErrRecordNotFound 透传到中
    间件层。
  - 因此你在中间件里用 errors.Is(err, gorm.ErrRecordNotFound) 去判断“无效 key”，很容易匹配不到（尤其
    是：后面加 Redis 缓存、换存储实现、或测试里用 stub repo 时，根本不会出现 gorm 的错误）。
  - 匹配不到时就会走到 500 Failed to validate API key，导致无效 API key 被错误地当成服务端故障返回
    500（应该是 401）。

  修复思路：中间件不要依赖 gorm 的错误，改成判断业务层错误，例如：

  if errors.Is(err, service.ErrApiKeyNotFound) {
      abortWithGoogleError(c, 401, "Invalid API key")
      return
  }

  如果你把 GetByKey 的“not found”统一封装成业务错误，这样才不会被底层实现（gorm/redis/mock）影响。

使用 `id -u` 替代 `$EUID` 进行 root 权限检查。
`$EUID` 是 bash 内置变量，在通过 pipe 执行脚本时可能不可靠。

问题：当分配订阅天数过大时，expires_at 年份可能超过 9999，
导致 time.Time JSON 序列化失败（RFC 3339 要求年份 <= 9999），
使后台无法显示和删除异常数据。

修复：
- handler 层添加 validity_days 最大值验证（max=36500，即100年）
- service 层添加 MaxValidityDays 和 MaxExpiresAt 双重保护
- 启动时自动修复已存在的异常数据（expires_at > 2099年）

Implement deferred batch update mechanism to reduce database load:

- Add DeferredService for batching account last_used_at updates
- Add TimingWheelService for efficient recurring task scheduling
- Integrate with GatewayService and OpenAIGatewayService
- Implement BatchUpdateLastUsed repository method using CASE...WHEN SQL
- Fix golangci-lint error: Replace interface{} with any

Benefits:
- Reduces database writes by batching updates (10-second intervals)
- Improves request throughput by deferring non-critical updates
- Maintains accurate account usage tracking for scheduling

问题：仪表盘“最近用量”调用 /usage 时传入完整 ISO 时间戳（含时分秒/时区），后端 start_date/end_date 仅接受 YYYY-MM-DD，导致请求参数校验失败，页面无法正常展示最近用量。

解决：
- loadRecentUsage 改为传入 YYYY-MM-DD（从 toISOString() 取日期部分），与后端参数格式约定保持一致
- 补充注释说明：后端会将 end_date 扩展到当日结束时间，以及 toISOString() 为 UTC 可能带来的统计口径差异
- 同步修正 usageAPI.getByDateRange 的参数注释，避免后续误用

验证：npm -C frontend run build

feat 增加 caddy 示例安全反向代理

# Conflicts:

修复 loadRecentUsage 函数中日期格式问题，将 ISO 完整格式改为 YYYY-MM-DD 格式，与后端 API 期望一致。

- 修复DataTable组件watch监听actionsExpanded导致的无限循环卡死问题
- 为AccountsView和UsersView添加actionsCount属性启用操作列展开功能
- 修复i18n翻译中邮箱地址的@符号未转义导致的编译错误

问题：
- 编辑账号弹窗使用size='lg'
- 新增账号弹窗使用size='xl'
- 两者宽度不一致，体验不统一

修复：
- 将EditAccountModal的size从lg改为xl
- 与CreateAccountModal保持一致

问题：
- admin/settings页面无法访问，报错'Invalid linked format'
- vue-i18n解析器将{'@'}误认为链接格式语法

修复：
- 将zh.ts和en.ts中的{'@'}替换为直接的@字符
- 影响范围：代理配置相关的翻译字符串

新增功能：

1. 操作列宽度自适应
   - checkActionsColumnWidth 方法：智能检测操作按钮是否超出列宽
     - 临时展开所有按钮测量实际宽度
     - 计算包含gap的总宽度
     - 与可用宽度对比，自动显示/隐藏"展开"按钮
   - 新增 actionsCount prop：
     - 用于快速判断是否需要展开功能
     - 避免DOM查询带来的性能开销

2. 列数自适应padding
   - getAdaptivePaddingClass 方法：根据列数动态调整内边距
     - ≥10列 → px-2 (8px)
     - ≥7列  → px-3 (12px)
     - ≥5列  → px-4 (16px)
     - <5列  → px-6 (24px，原始值)
   - 让表格在列数较多时更紧凑，提升空间利用率

- 将弹窗尺寸从 lg 改为 xl，增加内容显示空间
- 修复 AI Studio tooltip 被弹窗边界截断的问题
  - 调整定位从 left-0 改为 right-0
  - 减小宽度从 w-[28rem] 改为 w-80
  - 提高 z-index 确保正确显示

- 在stubUsageLogRepo中实现GetUserStatsAggregated方法
- 根据userLogs计算统计数据而不是返回错误
- 修复类型转换问题（int转int64）

- 修复gofmt格式问题
- 为stubUsageLogRepo添加缺失的GetApiKeyStatsAggregated方法

- 改进API密钥管理界面
- 优化用户使用统计视图
- 完善初始化设置向导

- 改进账户管理视图
- 优化分组管理界面
- 完善代理管理功能
- 增强兑换码管理
- 改进订阅管理视图
- 优化使用统计展示
- 完善用户管理界面

- 改进数据格式化逻辑
- 增强工具函数可读性

- 新增英文翻译条目
- 完善中文翻译内容
- 改进多语言支持

- 改进ConfirmDialog对话框组件
- 增强DataTable表格组件功能和响应式布局
- 优化EmptyState空状态组件
- 完善SubscriptionProgressMini订阅进度组件

- 优化使用统计处理逻辑
- 增强API密钥仓储层功能
- 改进账户使用服务
- 完善API契约测试覆盖

- 合并多个独立查询为单个SQL查询
- 减少数据库往返次数
- 提升仪表板统计数据获取效率