feat: 新增限额管理功能

[ding113]

No description provided.

[ding113]

此 PR 是从 dev 分支合并到 main 分支，因此请无视目标分支规则正常审核

[claude]

代码审查报告 🔍

感谢提交这个全面的限额管理功能！这是一个设计良好、实现细致的大型 PR。以下是我的审查意见：

---

✅ 亮点与优秀设计

1. 时间算法修正 (src/lib/rate-limit/time-utils.ts)

• ✅ 自然时间窗口：周/月限额改为自然周一和月初重置，更符合业务直觉
• ✅ 动态 TTL 计算：Redis key 的过期时间精确到下一个重置点，避免数据泄漏
• ✅ 时区处理规范：统一使用 Asia/Shanghai 时区，使用 date-fns-tz 处理
• ✅ 类型安全：完整的 TypeScript 类型定义

2. 降级策略完善 (src/lib/rate-limit/service.ts)

• ✅ Fail Open 原则：Redis 不可用时自动降级到数据库，不影响服务可用性
• ✅ Cache Warming：数据库查询后自动回写 Redis，优化后续请求性能
• ✅ 原子性保证：使用 Lua 脚本解决并发检查的竞态条件
• ✅ 详细日志记录：每个关键路径都有 info/warn 级别日志

3. 前端架构清晰 (src/app/dashboard/quotas/)

• ✅ Server/Client 分离：Server Component 负责数据获取，Client Component 处理交互
• ✅ 组件复用性高：QuotaToolbar 和 QuotaProgress 可在多个页面复用
• ✅ 进度条颜色警告：4 级颜色（正常/警告/危险/超限）清晰直观
• ✅ 自动刷新机制：使用 useTransition + router.refresh 优雅处理

4. 文档完善 (FRONTEND_DESIGN.md)

• ✅ 详尽的设计文档：818 行完整记录设计思路、实施细节、测试结果
• ✅ 架构图和目录结构：清晰展示代码组织
• ✅ 未来优化建议：列出了短期/中期/长期的改进方向

---

⚠️ 需要注意的问题

1. 环境变量新增但未在文档中突出强调

ENABLE_CODEX_INSTRUCTIONS_INJECTION=false

• 📝 建议：在 README.md 主文档的"环境变量"章节也添加说明，避免用户遗漏
• 📝 建议：在 Docker Compose 示例配置中也添加此变量

2. LiteLLM 价格数据更新

• public/seed/litellm-prices.json 有 22532 行新增和 24047 行删除
• ✅ 这是正常的价格数据同步，但建议：
  • 📝 在 PR 描述中说明价格数据的更新来源和日期
  • 📝 考虑添加自动化脚本定期同步价格数据

3. CI 工作流修改

• .github/workflows/claude-ci-autofix.yml 中移除了 [skip ci] 标记
• ⚠️ 这意味着自动修复会再次触发 CI，可能导致循环
• 📝 建议：确认这是有意为之还是应该保留 [skip ci] 避免无限循环

---

🔒 安全性检查

✅ 通过的检查

1. 所有 API 都经过 Session 认证（Server Actions）
2. 用户只能查看自己的限额（非管理员）
3. 敏感数据不暴露到客户端
4. Redis 操作有完整的错误处理
5. 没有 SQL 注入风险（使用 Drizzle ORM）

⚠️ 建议加固

1. 并发限制的边界测试：

   • 建议添加压力测试，验证 Lua 脚本在高并发下的正确性
   • 测试 Redis 不可用时的降级路径是否真的 Fail Open

2. 时区边界情况：

   • 测试服务器时区与配置时区不一致时的行为
   • 测试夏令时切换时的边界情况

---

📊 性能评估

✅ 优化点

• Server Components 减少客户端包大小
• Redis Pipeline 批量操作
• useMemo 避免重复计算
• 并发查询（Promise.all）

📝 建议进一步优化

1. Keys 和 Providers 页面：

   • 当前未拆分 Client Component，用户多时可能影响交互响应
   • 建议参考 Users 页面的模式进行拆分

2. 数据库查询：

   • getUsersWithQuotas 中使用 Promise.all 查询所有用户限额
   • 当用户数 > 100 时，考虑添加分页或懒加载

---

🧪 测试建议

功能测试清单（建议添加自动化测试）

• 时间窗口切换测试（周一 00:00 重置、月初重置）
• Redis 不可用时的降级测试
• 并发请求的限流测试（Lua 脚本正确性）
• 不同时区下的时间计算测试
• 进度条颜色变化测试（60%, 80%, 100% 边界）

性能测试建议

• 100+ 用户时的页面加载时间
• 高频刷新（10s）时的服务器压力
• Redis Pipeline 批量操作的延迟

---

📋 代码质量

✅ 通过的检查

• TypeScript 类型检查通过
• ESLint 检查通过
• 代码风格一致
• 注释清晰完整
• 错误处理完善

📝 小建议

1. QuotaToolbar 组件：

   • 当前有很多 props（sortOptions, filterOptions 等）
   • 考虑使用配置对象或 Context 简化

2. magic numbers：

   • 60% / 80% / 100% 等阈值建议提取为常量
   • 示例：const QUOTA_WARNING_THRESHOLD = 0.6

---

🎯 总体评价

这是一个高质量的 PR：

• ✅ 功能完整，覆盖用户/密钥/供应商三层限额
• ✅ 架构清晰，Server/Client 分离合理
• ✅ 性能优化到位，有完善的降级策略
• ✅ 文档详尽，FRONTEND_DESIGN.md 可作为最佳实践参考
• ✅ 类型安全，代码质量高

建议操作：

1. 解决上述 ⚠️ 标记的问题（CI 循环风险、环境变量文档）
2. 添加部分自动化测试（时间窗口、并发限流）
3. 合并后监控生产环境的 Redis 性能和降级情况

---

📌 合并前检查清单

• 确认 CI workflow 修改不会导致无限循环
• 更新 README.md 主文档的环境变量说明
• 验证 Docker Compose 配置包含新环境变量
• 在测试环境验证周一/月初的限额重置逻辑
• 确认 LiteLLM 价格数据来源可靠

---

整体推荐：✅ 批准合并（解决检查清单后）

感谢贡献这么优秀的功能！💯

[claude]

✅ 优秀设计：动态 TTL 避免数据泄漏

这个设计很棒！通过动态计算 TTL 到下一个重置点，确保：

1. Redis key 在正确的时间自动过期
2. 不会出现"跨周/跨月"的脏数据
3. 节省 Redis 内存

建议：考虑添加单元测试验证边界情况：

// 测试用例
test("weekly TTL at Sunday 23:59", () => {
  // 周日 23:59 的 TTL 应该约为 60 秒（1分钟后是周一）
});

test("monthly TTL on last day", () => {
  // 月末最后一天的 TTL 应该正确计算到次月 1 号
});

[claude]

📝 UI 小建议：Tabs 选中状态未根据当前路由高亮

当前问题：无论在哪个子页面，defaultValue="users" 都会高亮"用户限额"。

建议修复：根据当前路由动态设置 value：

"use client";
import { usePathname } from "next/navigation";

export default function QuotasLayout({ children }: { children: React.ReactNode }) {
  const pathname = usePathname();
  const currentTab = pathname.split("/").pop() || "users";

  return (
    <div className="space-y-6">
      {/* ...省略... */}
      <Tabs value={currentTab} className="space-y-4">
        {/* ...省略... */}
      </Tabs>
    </div>
  );
}

或者使用 Shadcn 的导航组件（更语义化）：

<nav className="flex space-x-2">
  <Link href="/dashboard/quotas/users">
    <Button variant={isActive ? "default" : "ghost"}>用户限额</Button>
  </Link>
  {/* ... */}
</nav>