[Feature] 支持团队分发制度：子账号、额度限流、卡密充值与倍率活动

[KilimiaoSix]

背景

当前 CodexManager 更偏个人使用场景：管理员本地维护账号池、平台 Key 和网关转发能力。对于团队或小型平台化使用场景，希望能进一步演进为“管理员维护资源池，成员/客户通过子账号和分发 Key 使用”的模式。

这个方向可以让 CodexManager 从个人账号池工具扩展为复合型分发平台。

目标

希望支持一套团队/平台分发制度：

• 管理员账号负责维护 Codex 账号池、聚合 API、模型、路由策略和全局配置。
• 子账号负责使用平台能力，只能看到自己的 Key、余额、用量和请求记录。
• 管理员可以给子账号或项目下发额度、设置限流、禁用 Key。
• 支持卡密充值，用于内部额度发放、活动兑换或商业化分发。
• 支持可配置的用量倍率，例如 0.7x 活动折扣、1x 默认计费、2x 高级模型或高优先级计费。

建议功能

1. 用户与权限体系

• 增加管理员 / 子账号角色。
• 管理员可创建、禁用、编辑子账号。
• 子账号只能管理自己的平台 Key 和查看自己的用量。
• 管理端继续保留账号池、平台 Key、请求日志、聚合 API 等完整能力。

2. 平台 Key 归属

• 平台 Key 增加归属关系，例如 owner_user_id 或 project_id。
• 支持一人一 Key、一项目一 Key、CI 专用 Key。
• Key 可设置：
  • 启用 / 禁用
  • 模型限制
  • 推理等级限制
  • 服务等级限制
  • 账号计划筛选
  • 并发限制
  • 日 / 月 / 总额度限制

3. 额度与账本

建议把“真实消耗”和“平台扣费”分开：

• 真实消耗：上游账号池实际使用的 token、模型、账号、请求日志。
• 平台扣费：对子账号余额扣除的 billable usage。

建议增加不可变流水表，记录：

• 充值
• 管理员赠送 / 调整
• 请求扣费
• 请求失败退款
• 过期清零
• 活动赠送

每条扣费流水建议记录：

• 原始 token 用量
• 计费倍率
• 实际扣除额度
• 命中的计费规则
• 关联请求日志

4. 请求前限额与请求后结算

为了避免超用，建议网关请求链路增加额度校验：

1. 请求进入时根据 Key 找到用户 / 项目钱包。
2. 检查 Key 状态、用户状态、余额、并发和限流规则。
3. 对流式请求可先冻结预估额度。
4. 请求完成后按真实 usage 结算。
5. 请求失败或中断时释放冻结额度或按实际用量结算。

5. 卡密充值

支持管理员批量生成卡密：

• 面额
• 有效期
• 可兑换次数，默认一次
• 绑定活动或套餐
• 启用 / 禁用
• 批次管理
• 兑换记录

安全上建议数据库只保存卡密 hash，明文只在生成时展示一次。

6. 倍率活动 / 计费规则

希望支持可配置倍率，例如：

• 全局默认 1x
• 活动折扣 0.7x
• 高级模型 2x
• Fast 服务等级 1.5x
• 指定用户 / 指定 Key / 指定模型 / 指定时间段的特殊倍率

建议抽象为 pricing_rules：

• 名称
• 倍率
• 适用范围：全局、用户、Key、模型、服务等级、时间段
• 优先级
• 开始时间 / 结束时间
• 启用状态

建议第一版采用“最高优先级规则覆盖”，避免多规则叠乘导致账单解释复杂。

阶段建议

Phase 1：团队分发 MVP

• 子账号
• Key 归属
• 管理员手动分配额度
• 请求前余额检查
• 请求后扣费
• 子账号用量页
• 管理员查看全局用量和成员用量

Phase 2：计费倍率与活动

• pricing_rules
• 0.7x / 1x / 2x 倍率
• 按模型、Key、用户、时间段匹配规则
• 账本记录倍率和规则来源

Phase 3：卡密充值

• 卡密批量生成
• 卡密兑换
• 充值流水
• 批次管理
• 兑换审计

Phase 4：更强的平台化能力

• 项目 / 团队空间
• 套餐
• 月度额度
• 余额过期
• 报表导出
• 风控和异常消耗提醒

兼容性建议

当前已有平台 Key、请求日志、token 统计和账号计划筛选能力，建议尽量复用：

• 平台 Key 继续作为网关访问凭据。
• 新增用户 / 项目 / 钱包层，不直接把 Key 当余额账户。
• 请求日志继续记录真实请求信息。
• 新增账本记录平台侧扣费结果。
• 个人模式可以保持默认行为，未启用团队分发时继续按现有逻辑运行。

价值

这个改造可以让 CodexManager 从个人账号池管理工具升级为团队分发和复合型平台：

• 适合项目组内部共享账号池。
• 适合给不同成员分配不同额度。
• 适合做活动折扣和高优先级加价。
• 适合后续扩展到卡密充值和套餐模式。

[KilimiaoSix]

补充关联现有 issue，方便后续合并讨论和拆分实现：

• [Feature] 增加key的额度限制 #119 是最直接的前置需求：希望给平台 Key 增加额度限制，避免分发出去的 Key 把账号池额度用完。本 issue 可以看作对 [Feature] 增加key的额度限制 #119 的扩展版：从“单个 Key 限额”扩展到“用户 / 项目 / Key / 钱包 / 账本”的完整分发体系。
• [Feature] API KEY管理 #66 也提到过 API Key 消耗和到期时间控制。这里建议保留现有个人模式，同时在启用团队分发模式时增加余额、到期、扣费和审计能力，避免影响当前轻量使用方式。
• [Feature] 聚合api这边增加类似cc switch一样的可选余额检测 #163 提到聚合 API 余额检测。这个能力可以作为资源层的一部分，为团队分发模式提供上游余额、可用性和路由决策依据。
• [Feature] 关于一个key自动账号轮询和api轮询 #179 讨论过一个 Key 同时走账号轮询和 API 轮询的问题。它和本 issue 的关系是“资源路由层”：团队分发侧负责用户余额和计费，底层仍可以复用账号池 / 聚合 API / 混合轮转策略。

因此建议后续实现时可以拆成两条线：

1. 先解决 [Feature] 增加key的额度限制 #119 的 Key 级额度限制，作为团队分发 MVP 的最小闭环。
2. 再在这个基础上引入子账号、钱包账本、卡密充值和倍率活动，避免一次性改动过大。

[KilimiaoSix]

@qxcnm 想问下作者是否有这方面开发需求，或者是否想要做类似的功能，因为我这边团队管理比较需要这个

[qxcnm]

@qxcnm 想问下作者是否有这方面开发需求，或者是否想要做类似的功能，因为我这边团队管理比较需要这个

用户是又这个需求的，但是我个人来说是没有这个需求的，因为我是和几个朋友一起用一下而已，我主要是最近几个月太忙了，要不然我可能自己做了😓

在这里非常感谢大佬对项目的贡献，感谢

[KilimiaoSix]

感谢回复，也辛苦作者维护项目。

那我这边近期会针对团队分发这块做一些专项开发，优先围绕 Key 额度限制、子账号管理、用量记录这些比较核心的能力先推进，后续卡密、倍率活动之类的再逐步补。

如果过程中有比较大的设计取舍，我会再开 issue 或 PR 里同步讨论。

[KilimiaoSix]

进度同步：

• 已在 fork 推送 WIP 分支：KilimiaoSix:feature-account-manager，当前提交 779c64ff（feat: add account quota billing management）。
• 已推进账号系统基础能力：账号登录/会话、成员账号、管理员创建成员、成员仪表盘、成员 API Key/日志隔离。
• 已推进额度分发基础链路：API Key 归属、成员钱包、请求前余额检查、请求成功后按用量扣费、钱包流水记录。
• 已推进额度中心：侧边栏入口、模型/来源/API Key 额度视图，并补了计费规则页签。
• 已补计费规则 MVP：支持按模型匹配、服务层、用户、API Key、时间窗和优先级配置扣费倍率，扣费流水会记录命中的 pricing_rule_id 和扣费明细。

暂不展开的范围：项目维度和卡密充值先延后。

仍待完善：扣费预冻结/严格防透支、钱包流水可视化、计费规则编辑体验、更多价格/倍率策略和整体联调。暂不提 PR，等功能继续收口后再开。