wangdl/api-server
2
0
Fork 0
Code Issues 45 Pull Requests Actions Packages Projects Releases Wiki Activity

M0-11 Quota, Billing & Cost 基础版 #11

New Issue
Open
opened 2026-05-22 21:00:16 +08:00 by wangdl · 0 comments
wangdl commented 2026-05-22 21:00:16 +08:00
Owner
Copy Link

目标

设计知习后端额度、计费与成本模块，为全系统提供用户会员额度管理、AI 调用成本记录和服务商账单追踪能力。

本 Issue 只做架构设计，不直接实现代码。

背景说明

知习的 AI 调用（DeepSeek、硅基流动、百度 OCR）、文件存储（COS）、Embedding 生成都是有成本的。需要精确记录每次消耗、按用户/模块/服务商维度汇总成本，为定价决策和成本优化提供数据支撑。

Quota 管"用户有没有额度可用"，Cost 管"每次调用花了多少钱"。两者必须联动但不能混成一个模块。

模块职责

  1. 本模块负责：

    • 会员计划定义（免费/付费，各档位额度配置）
    • 用户额度管理（总额度、已用额度、重置周期）
    • 额度扣减（实时扣减，保证不超用）
    • 功能用量统计（按功能类型：AI 对话/OCR/Vision/Embedding/存储）
    • AI 调用成本记录（每次 AI 调用的 token 消耗和费用）
    • 服务商账单台账（各供应商的费用汇总）
    • 成本预警（日/周/月成本超过阈值时通知 Admin）

  2. 本模块不负责：

    • 支付接入（Apple IAP 等）
    • 发票和财务系统对接
    • 流量限流（走 Traffic Protection）

候选数据对象

  • MembershipPlan（会员计划）
  • UserMembership（用户会员绑定）
  • QuotaConfig（额度配置）
  • QuotaUsage（额度使用记录）
  • ExternalApiUsageLog（外部 API 调用消耗日志）
  • CostDailySummary（每日成本汇总）
  • CostAlertRule（成本预警规则）
  • CostAlertEvent（成本预警事件）
  • ModelPriceConfig（模型价格配置）
  • VendorAccount（服务商账户）

基础设施依赖判断

  • MySQL：是（额度、会员、成本数据持久化）
  • Redis：是（额度实时扣减需要高性能计数器）
  • BullMQ：是（成本汇总异步计算、预警检查）
  • Qdrant：否
  • AI Gateway：否（但需订阅 AIUsageLog 事件来计算成本）
  • COS：否

API 设计

  1. Internal Provider（供其他模块调用）：

    • QuotaService.checkAndDeduct(userId, quotaType, amount)：检查并扣减额度
    • QuotaService.getRemaining(userId)：查询剩余额度
    • CostService.recordUsage(usageLog)：记录 API 调用消耗

  2. CAPI：

    • 查询当前会员状态
    • 查询剩余额度

  3. AAPI：

    • 会员计划管理
    • 用户额度管理（手动调整）
    • 成本报表（按时间/模块/服务商）
    • 成本预警规则配置
    • 模型价格配置

Domain Event 设计

  • QuotaConsumed：额度扣减
  • QuotaExhausted：额度耗尽
  • CostRecorded：成本记录
  • CostAlertTriggered：成本预警触发

Admin 视图设计

  1. 会员管理页：会员计划列表（名称、价格、额度配置）、用户会员列表
  2. 额度管理页：用户额度概览、额度使用趋势、手动调整额度
  3. 成本报表页：按服务商/模块/时间的成本汇总、成本趋势图、Top 消耗用户
  4. 成本预警页：预警规则配置、预警历史

交付检查

  • 路由归属：Internal Provider + CAPI + AAPI
  • 是否需要 Prisma migration：是
  • 是否需要 MySQL：是
  • 是否需要 Redis：是
  • 是否需要 BullMQ：是
  • 是否需要 Qdrant：否
  • 是否需要 AI Gateway：否（但需要消费 AIUsageLog 事件）
  • 是否需要 Content Safety：否
  • 是否需要 Cost 记录：本模块是 Cost 记录模块自身
  • 是否需要 AuditLog：是（手动调整额度、价格变更）
  • 是否需要 Domain Event：是
  • 是否需要 Admin 视图：是
  • 是否需要 E2E/集成测试：是

验收标准

  1. MembershipPlan / QuotaConfig / QuotaUsage Prisma schema
  2. 额度扣减方案（Redis 实时扣减 + MySQL 异步同步）
  3. Cost 记录方案（消费 AIUsageLog 事件）
  4. 成本汇总方案（按日/周/月）
  5. 成本预警机制设计
  6. Admin 管理视图设计
  7. 集成测试覆盖额度扣减和成本记录

禁止事项

  • 禁止额度扣减不使用 Redis 而直接操作 MySQL（高并发下会超卖）
  • 禁止 AI 调用不记录成本（所有 AI 调用必须记账）
  • 禁止手动调整额度不记录审计
  • 禁止模型价格变更不记录版本
  • 禁止跨模块直接操作 Quota 表（必须通过 QuotaService）

不建议当前阶段实现

  • 支付系统对接
  • 发票管理
  • 多币种支持
  • 成本分摊到单个知识库维度
## 目标 设计知习后端额度、计费与成本模块，为全系统提供用户会员额度管理、AI 调用成本记录和服务商账单追踪能力。 本 Issue 只做架构设计，不直接实现代码。 ## 背景说明 知习的 AI 调用（DeepSeek、硅基流动、百度 OCR）、文件存储（COS）、Embedding 生成都是有成本的。需要精确记录每次消耗、按用户/模块/服务商维度汇总成本，为定价决策和成本优化提供数据支撑。 Quota 管"用户有没有额度可用"，Cost 管"每次调用花了多少钱"。两者必须联动但不能混成一个模块。 ## 模块职责 1. 本模块负责： - 会员计划定义（免费/付费，各档位额度配置） - 用户额度管理（总额度、已用额度、重置周期） - 额度扣减（实时扣减，保证不超用） - 功能用量统计（按功能类型：AI 对话/OCR/Vision/Embedding/存储） - AI 调用成本记录（每次 AI 调用的 token 消耗和费用） - 服务商账单台账（各供应商的费用汇总） - 成本预警（日/周/月成本超过阈值时通知 Admin） 2. 本模块不负责： - 支付接入（Apple IAP 等） - 发票和财务系统对接 - 流量限流（走 Traffic Protection） ## 候选数据对象 - MembershipPlan（会员计划） - UserMembership（用户会员绑定） - QuotaConfig（额度配置） - QuotaUsage（额度使用记录） - ExternalApiUsageLog（外部 API 调用消耗日志） - CostDailySummary（每日成本汇总） - CostAlertRule（成本预警规则） - CostAlertEvent（成本预警事件） - ModelPriceConfig（模型价格配置） - VendorAccount（服务商账户） ## 基础设施依赖判断 - MySQL：是（额度、会员、成本数据持久化） - Redis：是（额度实时扣减需要高性能计数器） - BullMQ：是（成本汇总异步计算、预警检查） - Qdrant：否 - AI Gateway：否（但需订阅 AIUsageLog 事件来计算成本） - COS：否 ## API 设计 1. Internal Provider（供其他模块调用）： - QuotaService.checkAndDeduct(userId, quotaType, amount)：检查并扣减额度 - QuotaService.getRemaining(userId)：查询剩余额度 - CostService.recordUsage(usageLog)：记录 API 调用消耗 2. CAPI： - 查询当前会员状态 - 查询剩余额度 3. AAPI： - 会员计划管理 - 用户额度管理（手动调整） - 成本报表（按时间/模块/服务商） - 成本预警规则配置 - 模型价格配置 ## Domain Event 设计 - QuotaConsumed：额度扣减 - QuotaExhausted：额度耗尽 - CostRecorded：成本记录 - CostAlertTriggered：成本预警触发 ## Admin 视图设计 1. 会员管理页：会员计划列表（名称、价格、额度配置）、用户会员列表 2. 额度管理页：用户额度概览、额度使用趋势、手动调整额度 3. 成本报表页：按服务商/模块/时间的成本汇总、成本趋势图、Top 消耗用户 4. 成本预警页：预警规则配置、预警历史 ## 交付检查 - [ ] 路由归属：Internal Provider + CAPI + AAPI - [ ] 是否需要 Prisma migration：是 - [ ] 是否需要 MySQL：是 - [ ] 是否需要 Redis：是 - [ ] 是否需要 BullMQ：是 - [ ] 是否需要 Qdrant：否 - [ ] 是否需要 AI Gateway：否（但需要消费 AIUsageLog 事件） - [ ] 是否需要 Content Safety：否 - [ ] 是否需要 Cost 记录：本模块是 Cost 记录模块自身 - [ ] 是否需要 AuditLog：是（手动调整额度、价格变更） - [ ] 是否需要 Domain Event：是 - [ ] 是否需要 Admin 视图：是 - [ ] 是否需要 E2E/集成测试：是 ## 验收标准 1. MembershipPlan / QuotaConfig / QuotaUsage Prisma schema 2. 额度扣减方案（Redis 实时扣减 + MySQL 异步同步） 3. Cost 记录方案（消费 AIUsageLog 事件） 4. 成本汇总方案（按日/周/月） 5. 成本预警机制设计 6. Admin 管理视图设计 7. 集成测试覆盖额度扣减和成本记录 ## 禁止事项 - 禁止额度扣减不使用 Redis 而直接操作 MySQL（高并发下会超卖） - 禁止 AI 调用不记录成本（所有 AI 调用必须记账） - 禁止手动调整额度不记录审计 - 禁止模型价格变更不记录版本 - 禁止跨模块直接操作 Quota 表（必须通过 QuotaService） ## 不建议当前阶段实现 - 支付系统对接 - 发票管理 - 多币种支持 - 成本分摊到单个知识库维度
wangdl added this to the M0：后端基础能力与架构规范闭环（P0） milestone 2026-05-22 21:00:16 +08:00
wangdl self-assigned this 2026-05-22 21:00:16 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No Label
Milestone
No items
No Milestone M0：后端基础能力与架构规范闭环（P0）
Projects
Clear projects
No project
Assignees
Clear assignees
suyun-Claude wangdl
No Assignees wangdl
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: wangdl/api-server#11
No description provided.
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?