audio_codebuddy/.qoder/repowiki/zh/content/核心模块/订阅付费系统/计费与配额.md

计费与配额

本文引用的文件

• server/src/modules/subscription/subscription.service.ts
• server/src/modules/subscription/subscription.controller.ts
• server/src/modules/payment/payment.service.ts
• server/src/modules/payment/payment.controller.ts
• server/src/modules/tts/tts.service.ts
• server/src/middleware/usageLimit.ts
• server/src/middleware/errorHandler.ts
• server/src/types/index.ts
• server/prisma/schema.prisma
• docs/API.md
• docs/支付集成指南.md
• docs/TTS成本分析报告.md
• server/src/services/log.service.ts

目录

1. 引言
2. 项目结构
3. 核心组件
4. 架构总览
5. 详细组件分析
6. 依赖关系分析
7. 性能考量
8. 故障排查指南
9. 结论
10. 附录

引言

本文件面向计费与配额系统，系统采用“Token计费 + 音频时长计费”的双轨计费模型，结合套餐体系与实时扣费机制，确保在保障用户体验的同时实现成本可控与商业可持续。文档涵盖以下主题：

• Token计费模型设计与配额计算算法
• 音频生成计费规则与字数转时长算法
• 配额检查机制、实时扣费逻辑、余额不足处理与预估费用计算
• 完整计费API接口文档（配额查询、使用记录、余额变更等）
• 计费数据模型、统计报表、审计日志与财务对账
• 异常处理、数据一致性保证与性能优化策略

项目结构

计费与配额相关能力分布在以下模块与文件中：

• 订阅与配额服务：subscription.service.ts、subscription.controller.ts
• 支付与订单：payment.service.ts、payment.controller.ts
• TTS生成流程：tts.service.ts
• 中间件：usageLimit.ts（字数/次数限制）、errorHandler.ts（统一错误处理）
• 类型定义：types/index.ts
• 数据模型：prisma/schema.prisma
• 文档：API.md、支付集成指南.md、TTS成本分析报告.md

• 日志服务：services/log.service.ts

  graph TB
  subgraph "前端"
  FE["前端页面<br/>订单/余额/使用记录"]
  end
  subgraph "后端"
  CTRL_SUB["订阅控制器<br/>subscription.controller.ts"]
  SVC_SUB["订阅服务<br/>subscription.service.ts"]
  CTRL_PAY["支付控制器<br/>payment.controller.ts"]
  SVC_PAY["支付服务<br/>payment.service.ts"]
  M_WL["使用限制中间件<br/>usageLimit.ts"]
  M_ERR["错误处理中间件<br/>errorHandler.ts"]
  SVC_TTS["TTS服务<br/>tts.service.ts"]
  PRISMA["Prisma模型<br/>schema.prisma"]
  LOG["日志服务<br/>log.service.ts"]
  end
  FE --> CTRL_SUB
  FE --> CTRL_PAY
  CTRL_SUB --> SVC_SUB
  CTRL_PAY --> SVC_PAY
  SVC_SUB --> PRISMA
  SVC_PAY --> PRISMA
  SVC_TTS --> PRISMA
  M_WL --> SVC_TTS
  M_ERR --> CTRL_SUB
  M_ERR --> CTRL_PAY
  LOG --> SVC_SUB
  LOG --> SVC_PAY
  

图表来源

• server/src/modules/subscription/subscription.controller.ts:1-191
• server/src/modules/subscription/subscription.service.ts:1-727
• server/src/modules/payment/payment.controller.ts:1-258
• server/src/modules/payment/payment.service.ts:1-578
• server/src/modules/tts/tts.service.ts:1-715
• server/src/middleware/usageLimit.ts:1-66
• server/src/middleware/errorHandler.ts:1-67
• server/prisma/schema.prisma:1-470
• server/src/services/log.service.ts:1-354

章节来源

• server/src/modules/subscription/subscription.controller.ts:1-191
• server/src/modules/subscription/subscription.service.ts:1-727
• server/src/modules/payment/payment.controller.ts:1-258
• server/src/modules/payment/payment.service.ts:1-578
• server/src/modules/tts/tts.service.ts:1-715
• server/src/middleware/usageLimit.ts:1-66
• server/src/middleware/errorHandler.ts:1-67
• server/prisma/schema.prisma:1-470
• docs/API.md:1-499
• docs/支付集成指南.md:277-336
• docs/TTS成本分析报告.md:62-216
• server/src/services/log.service.ts:1-354

核心组件

• 订阅与配额服务：负责套餐等级、Token配额、音频时长配额、余额查询、使用记录、配额检查、实时扣费与预估费用计算。
• 支付服务：负责订单创建、支付回调处理、订阅激活、Token余额初始化与重置。
• TTS服务：负责音频生成流程，集成配额检查与扣费逻辑。
• 中间件：使用限制中间件（次数/字数）与统一错误处理。
• 数据模型：Prisma定义的用户、订单、订阅、Token余额与使用记录等模型。
• 日志服务：请求日志、错误分析与统计。

章节来源

• server/src/modules/subscription/subscription.service.ts:1-727
• server/src/modules/payment/payment.service.ts:1-578
• server/src/modules/tts/tts.service.ts:1-715
• server/src/middleware/usageLimit.ts:1-66
• server/prisma/schema.prisma:1-470
• server/src/services/log.service.ts:1-354

架构总览

计费与配额系统围绕“套餐—订阅—配额—扣费—统计”闭环构建，支付成功后激活订阅并初始化Token余额；生成音频前进行配额检查与预估；生成完成后按实际时长扣费并记录使用。

sequenceDiagram
participant U as "用户"
participant FE as "前端"
participant PC as "支付控制器"
participant PS as "支付服务"
participant SC as "订阅控制器"
participant SS as "订阅服务"
participant PR as "Prisma"
participant TS as "TTS服务"
U->>FE : "选择套餐并发起支付"
FE->>PC : "POST /api/payment/create"
PC->>PS : "创建订单"
PS->>PR : "写入订单"
PS-->>PC : "返回支付链接/二维码"
PC-->>FE : "返回支付信息"
FE->>PC : "支付回调/同步返回"
PC->>PS : "处理回调"
PS->>PR : "更新订单状态"
PS->>PR : "激活订阅/更新用户等级"
PS->>PR : "初始化/更新Token余额"
U->>FE : "发起音频生成"
FE->>SC : "GET /api/subscription/audio-estimate"
SC->>SS : "预估费用"
SS-->>SC : "返回预估结果"
SC-->>FE : "显示预估费用"
FE->>TS : "POST /api/tts/generate"
TS->>SS : "检查配额/预估"
TS->>PR : "生成音频并更新状态"
TS->>SS : "扣除音频时长"
SS->>PR : "更新用户usedAudioMinutes/记录TokenUsage"
TS-->>FE : "返回音频URL/时长"

图表来源

• server/src/modules/payment/payment.controller.ts:1-258
• server/src/modules/payment/payment.service.ts:1-578
• server/src/modules/subscription/subscription.controller.ts:1-191
• server/src/modules/subscription/subscription.service.ts:556-727
• server/src/modules/tts/tts.service.ts:1-715
• server/prisma/schema.prisma:1-470

详细组件分析

订阅与配额服务（subscription.service.ts）

• Token计费配置与成本计算
  • 提供不同AI模型与TTS提供商的成本配置，支持按字数估算Token消耗与总成本。
  • 提供建议售价以保证利润空间。
• 音频时长计费系统
  • 基于语速（字/分钟）将文本长度转换为音频时长。
  • 支持包月配额与按量超额计费，不同会员等级对应不同的配额与超额单价。
• 配额检查与余额管理
  • 检查用户Token余额是否充足；支持无限配额场景。
  • 提供Token使用记录查询与分页。

• 音频时长余额与扣费

  • 每月1日重置音频时长配额；生成完成后按实际时长扣费并记录使用。

  • 提供音频生成预估接口，返回配额内/外分钟数与预估费用。

    flowchart TD
    Start(["开始：生成音频"]) --> CalcDur["计算音频时长<br/>textLength -> minutes"]
    CalcDur --> GetQuota["获取用户配额与余额"]
    GetQuota --> CheckUnlimited{"是否无限配额？"}
    CheckUnlimited --> |是| Deduct["直接扣费按量"]
    CheckUnlimited --> |否| Compare{"剩余分钟是否足够？"}
    Compare --> |否| Reject["拒绝生成：余额不足"]
    Compare --> |是| Deduct["扣费：按配额内/外分别计费"]
    Deduct --> Log["记录TokenUsage"]
    Log --> End(["结束"])
    Reject --> End
    

图表来源

• server/src/modules/subscription/subscription.service.ts:556-727

章节来源

• server/src/modules/subscription/subscription.service.ts:95-155
• server/src/modules/subscription/subscription.service.ts:519-600
• server/src/modules/subscription/subscription.service.ts:602-727

支付服务（payment.service.ts）

• 订单创建与支付通道
  • 支持支付宝与微信支付，生成支付链接或二维码；提供沙箱/模拟支付能力。
• 支付回调与订阅激活
  • 验签并通过回调更新订单状态；成功后激活订阅、更新用户等级与会员到期时间。
  • 根据套餐配置初始化或更新Token余额（含重置日期）。

• 订单查询与列表

  • 提供订单列表与详情查询，便于财务对账与审计。

    sequenceDiagram
    participant C as "客户端"
    participant PC as "支付控制器"
    participant PS as "支付服务"
    participant SDK as "支付SDK"
    participant DB as "数据库"
    C->>PC : "POST /api/payment/create"
    PC->>PS : "创建订单"
    PS->>SDK : "生成支付链接/二维码"
    SDK-->>PS : "返回支付信息"
    PS->>DB : "写入订单"
    PS-->>PC : "返回支付信息"
    PC-->>C : "返回支付链接/二维码"
    note over SDK,DB : "支付回调"
    SDK-->>PC : "异步通知/同步返回"
    PC->>PS : "处理回调"
    PS->>DB : "更新订单状态/激活订阅"
    PS->>DB : "初始化/更新Token余额"
    

图表来源

• server/src/modules/payment/payment.controller.ts:1-258
• server/src/modules/payment/payment.service.ts:121-509

章节来源

• server/src/modules/payment/payment.controller.ts:1-258
• server/src/modules/payment/payment.service.ts:121-509

TTS服务（tts.service.ts）

• 文本分段与Provider选择
  • 根据Provider类型（阿里云/MiniMax/模拟）选择分段策略与并发参数。
• 音频生成与状态管理
  • 生成完成后合并音频、上传存储、更新章节状态与AudioRecord记录。
• 与计费系统的集成点
  • 在生成前进行配额检查与预估；生成完成后按实际时长扣费并记录使用。

章节来源

• server/src/modules/tts/tts.service.ts:200-542
• server/src/modules/tts/tts.service.ts:544-715

使用限制中间件（usageLimit.ts）

• 每日使用次数与字数限制
  • 基于用户会员等级配置每日次数与单次字数上限；跨日自动重置。
  • 对超限请求抛出配额超限错误。

章节来源

• server/src/middleware/usageLimit.ts:1-66
• server/src/types/index.ts:120-124

错误处理中间件（errorHandler.ts）

• 统一错误响应
  • 捕获自定义业务错误（如配额超限、参数错误等），返回标准化错误码与消息。

章节来源

• server/src/middleware/errorHandler.ts:1-67

数据模型（Prisma schema.prisma）

• 关键模型
  • User：用户基本信息、会员等级、音频时长使用与重置时间。
  • SubscriptionPlan：套餐计划（月/年价格、Token配额、每日生成次数、音色数、音质等）。
  • Subscription：用户订阅记录（起止时间、状态、自动续费）。
  • TokenBalance：Token余额（总量、已用、重置日期）。
  • TokenUsage：Token使用记录（类型、数量、内容长度、描述）。
  • Order：订单（金额、状态、支付渠道、支付单号、购买套餐）。

章节来源

• server/prisma/schema.prisma:10-470
• docs/支付集成指南.md:277-336

计费API接口文档

• 订阅与配额相关接口
  • 获取套餐列表与详情
  • 获取用户订阅信息
  • 获取用户Token余额与使用记录
  • 获取用户配额与配额检查
  • 书籍规模预估与生成配额检查
  • 获取用户音频时长余额与音频生成预估
• 支付相关接口
  • 创建支付订单
  • 支付宝/微信回调与同步返回
  • 订单列表与详情查询
  • 生成支付宝扫码支付二维码

章节来源

• server/src/modules/subscription/subscription.controller.ts:1-191
• server/src/modules/payment/payment.controller.ts:1-258
• docs/API.md:1-499

依赖关系分析

• 订阅服务依赖Prisma模型进行余额与使用记录的读写。
• 支付服务在回调中激活订阅并初始化Token余额，依赖Prisma模型。
• TTS服务在生成完成后调用订阅服务进行音频时长扣费与记录。
• 中间件在TTS生成前进行字数/次数限制校验。

• 日志服务贯穿各模块，提供请求与错误日志记录与分析。

  graph LR
  SVC_SUB["订阅服务"] --> PRISMA["Prisma模型"]
  SVC_PAY["支付服务"] --> PRISMA
  SVC_TTS["TTS服务"] --> SVC_SUB
  M_WL["使用限制中间件"] --> SVC_TTS
  M_ERR["错误处理中间件"] --> SVC_SUB
  M_ERR --> SVC_PAY
  LOG["日志服务"] --> SVC_SUB
  LOG --> SVC_PAY
  

图表来源

• server/src/modules/subscription/subscription.service.ts:1-727
• server/src/modules/payment/payment.service.ts:1-578
• server/src/modules/tts/tts.service.ts:1-715
• server/src/middleware/usageLimit.ts:1-66
• server/src/middleware/errorHandler.ts:1-67
• server/prisma/schema.prisma:1-470
• server/src/services/log.service.ts:1-354

章节来源

• server/src/modules/subscription/subscription.service.ts:1-727
• server/src/modules/payment/payment.service.ts:1-578
• server/src/modules/tts/tts.service.ts:1-715
• server/src/middleware/usageLimit.ts:1-66
• server/src/middleware/errorHandler.ts:1-67
• server/prisma/schema.prisma:1-470
• server/src/services/log.service.ts:1-354

性能考量

• 并发与分段
  • TTS分段与并发策略依据Provider类型调整，减少长文本等待时间。
• 缓存与索引
  • Prisma模型已建立常用索引（用户、时间、状态等），提升查询效率。
• 日志与监控
  • 日志服务提供请求统计与错误分析，辅助定位性能瓶颈。
• 重置策略
  • Token与音频时长配额按月重置，避免长期累积导致查询压力。

[本节为通用指导，无需特定文件引用]

故障排查指南

• 支付回调未生效
  • 检查回调签名验证与订单状态更新逻辑；确认支付SDK初始化与证书配置。
• 配额检查失败
  • 确认用户会员等级与套餐配置；检查每日使用次数与字数限制中间件是否生效。
• 余额不足
  • 检查Token余额与使用记录；确认支付成功后是否正确初始化/更新余额。
• 音频生成失败
  • 查看TTS服务生成日志与错误回退逻辑；确认Provider可用性与分段策略。
• 日志与审计
  • 使用日志服务分析错误模式与趋势，定位高频错误与热点路径。

章节来源

• server/src/modules/payment/payment.service.ts:358-406
• server/src/middleware/usageLimit.ts:1-66
• server/src/modules/subscription/subscription.service.ts:410-437
• server/src/modules/tts/tts.service.ts:518-542
• server/src/services/log.service.ts:217-297

结论

本计费与配额系统通过清晰的双轨计费模型（Token与音频时长）、完善的套餐与订阅机制、严格的配额检查与实时扣费流程，实现了成本可控与用户体验的平衡。配合支付回调、日志审计与错误处理机制，系统具备良好的可维护性与扩展性。建议在后续迭代中完善Token扣费与TTS生成流程的深度集成，并持续优化性能与可观测性。

[本节为总结性内容，无需特定文件引用]

附录

计费数据模型（摘录）

• User：会员等级、音频时长使用与重置时间
• SubscriptionPlan：月/年价格、Token配额、每日生成次数、音色数、音质
• Subscription：订阅起止时间、状态、自动续费
• TokenBalance：总量、已用、重置日期
• TokenUsage：类型、数量、内容长度、描述
• Order：金额、状态、支付渠道、支付单号、购买套餐

章节来源

• server/prisma/schema.prisma:10-470
• docs/支付集成指南.md:277-336

Token计费与音频时长计费要点

• Token计费
  • 基于AI模型与TTS提供商的成本配置，按字数估算Token消耗与总成本。
• 音频时长计费
  • 语速固定，文本长度转换为分钟数；包月配额内按批发价计费，超出部分按零售价计费。
• 预估与扣费
  • 生成前提供预估费用；生成完成后按实际时长扣费并记录使用。

章节来源

• docs/TTS成本分析报告.md:62-216
• server/src/modules/subscription/subscription.service.ts:519-600
• server/src/modules/subscription/subscription.service.ts:685-724