# 计费与配额

<cite>
**本文引用的文件**
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [server/src/modules/subscription/subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [server/src/modules/payment/payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [server/src/modules/payment/payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [server/src/modules/tts/tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/src/middleware/errorHandler.ts](file://server/src/middleware/errorHandler.ts)
- [server/src/types/index.ts](file://server/src/types/index.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [docs/API.md](file://docs/API.md)
- [docs/支付集成指南.md](file://docs/支付集成指南.md)
- [docs/TTS成本分析报告.md](file://docs/TTS成本分析报告.md)
- [server/src/services/log.service.ts](file://server/src/services/log.service.ts)
</cite>

## 目录
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

```mermaid
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](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [server/src/modules/subscription/subscription.service.ts:1-727](file://server/src/modules/subscription/subscription.service.ts#L1-L727)
- [server/src/modules/payment/payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [server/src/modules/payment/payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [server/src/modules/tts/tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [server/prisma/schema.prisma:1-470](file://server/prisma/schema.prisma#L1-L470)
- [server/src/services/log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)

章节来源
- [server/src/modules/subscription/subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [server/src/modules/subscription/subscription.service.ts:1-727](file://server/src/modules/subscription/subscription.service.ts#L1-L727)
- [server/src/modules/payment/payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [server/src/modules/payment/payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [server/src/modules/tts/tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [server/prisma/schema.prisma:1-470](file://server/prisma/schema.prisma#L1-L470)
- [docs/API.md:1-499](file://docs/API.md#L1-L499)
- [docs/支付集成指南.md:277-336](file://docs/支付集成指南.md#L277-L336)
- [docs/TTS成本分析报告.md:62-216](file://docs/TTS成本分析报告.md#L62-L216)
- [server/src/services/log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)

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

章节来源
- [server/src/modules/subscription/subscription.service.ts:1-727](file://server/src/modules/subscription/subscription.service.ts#L1-L727)
- [server/src/modules/payment/payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [server/src/modules/tts/tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/prisma/schema.prisma:1-470](file://server/prisma/schema.prisma#L1-L470)
- [server/src/services/log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)

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

```mermaid
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](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [server/src/modules/payment/payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [server/src/modules/subscription/subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [server/src/modules/subscription/subscription.service.ts:556-727](file://server/src/modules/subscription/subscription.service.ts#L556-L727)
- [server/src/modules/tts/tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [server/prisma/schema.prisma:1-470](file://server/prisma/schema.prisma#L1-L470)

## 详细组件分析

### 订阅与配额服务（subscription.service.ts）
- Token计费配置与成本计算
  - 提供不同AI模型与TTS提供商的成本配置，支持按字数估算Token消耗与总成本。
  - 提供建议售价以保证利润空间。
- 音频时长计费系统
  - 基于语速（字/分钟）将文本长度转换为音频时长。
  - 支持包月配额与按量超额计费，不同会员等级对应不同的配额与超额单价。
- 配额检查与余额管理
  - 检查用户Token余额是否充足；支持无限配额场景。
  - 提供Token使用记录查询与分页。
- 音频时长余额与扣费
  - 每月1日重置音频时长配额；生成完成后按实际时长扣费并记录使用。
  - 提供音频生成预估接口，返回配额内/外分钟数与预估费用。

```mermaid
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](file://server/src/modules/subscription/subscription.service.ts#L556-L727)

章节来源
- [server/src/modules/subscription/subscription.service.ts:95-155](file://server/src/modules/subscription/subscription.service.ts#L95-L155)
- [server/src/modules/subscription/subscription.service.ts:519-600](file://server/src/modules/subscription/subscription.service.ts#L519-L600)
- [server/src/modules/subscription/subscription.service.ts:602-727](file://server/src/modules/subscription/subscription.service.ts#L602-L727)

### 支付服务（payment.service.ts）
- 订单创建与支付通道
  - 支持支付宝与微信支付，生成支付链接或二维码；提供沙箱/模拟支付能力。
- 支付回调与订阅激活
  - 验签并通过回调更新订单状态；成功后激活订阅、更新用户等级与会员到期时间。
  - 根据套餐配置初始化或更新Token余额（含重置日期）。
- 订单查询与列表
  - 提供订单列表与详情查询，便于财务对账与审计。

```mermaid
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](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [server/src/modules/payment/payment.service.ts:121-509](file://server/src/modules/payment/payment.service.ts#L121-L509)

章节来源
- [server/src/modules/payment/payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [server/src/modules/payment/payment.service.ts:121-509](file://server/src/modules/payment/payment.service.ts#L121-L509)

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

章节来源
- [server/src/modules/tts/tts.service.ts:200-542](file://server/src/modules/tts/tts.service.ts#L200-L542)
- [server/src/modules/tts/tts.service.ts:544-715](file://server/src/modules/tts/tts.service.ts#L544-L715)

### 使用限制中间件（usageLimit.ts）
- 每日使用次数与字数限制
  - 基于用户会员等级配置每日次数与单次字数上限；跨日自动重置。
  - 对超限请求抛出配额超限错误。

章节来源
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/src/types/index.ts:120-124](file://server/src/types/index.ts#L120-L124)

### 错误处理中间件（errorHandler.ts）
- 统一错误响应
  - 捕获自定义业务错误（如配额超限、参数错误等），返回标准化错误码与消息。

章节来源
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)

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

章节来源
- [server/prisma/schema.prisma:10-470](file://server/prisma/schema.prisma#L10-L470)
- [docs/支付集成指南.md:277-336](file://docs/支付集成指南.md#L277-L336)

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

章节来源
- [server/src/modules/subscription/subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [server/src/modules/payment/payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [docs/API.md:1-499](file://docs/API.md#L1-L499)

## 依赖关系分析
- 订阅服务依赖Prisma模型进行余额与使用记录的读写。
- 支付服务在回调中激活订阅并初始化Token余额，依赖Prisma模型。
- TTS服务在生成完成后调用订阅服务进行音频时长扣费与记录。
- 中间件在TTS生成前进行字数/次数限制校验。
- 日志服务贯穿各模块，提供请求与错误日志记录与分析。

```mermaid
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](file://server/src/modules/subscription/subscription.service.ts#L1-L727)
- [server/src/modules/payment/payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [server/src/modules/tts/tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [server/prisma/schema.prisma:1-470](file://server/prisma/schema.prisma#L1-L470)
- [server/src/services/log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)

章节来源
- [server/src/modules/subscription/subscription.service.ts:1-727](file://server/src/modules/subscription/subscription.service.ts#L1-L727)
- [server/src/modules/payment/payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [server/src/modules/tts/tts.service.ts:1-715](file://server/src/modules/tts/tts.service.ts#L1-L715)
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/src/middleware/errorHandler.ts:1-67](file://server/src/middleware/errorHandler.ts#L1-L67)
- [server/prisma/schema.prisma:1-470](file://server/prisma/schema.prisma#L1-L470)
- [server/src/services/log.service.ts:1-354](file://server/src/services/log.service.ts#L1-L354)

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

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

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

章节来源
- [server/src/modules/payment/payment.service.ts:358-406](file://server/src/modules/payment/payment.service.ts#L358-L406)
- [server/src/middleware/usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)
- [server/src/modules/subscription/subscription.service.ts:410-437](file://server/src/modules/subscription/subscription.service.ts#L410-L437)
- [server/src/modules/tts/tts.service.ts:518-542](file://server/src/modules/tts/tts.service.ts#L518-L542)
- [server/src/services/log.service.ts:217-297](file://server/src/services/log.service.ts#L217-L297)

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

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

## 附录

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

章节来源
- [server/prisma/schema.prisma:10-470](file://server/prisma/schema.prisma#L10-L470)
- [docs/支付集成指南.md:277-336](file://docs/支付集成指南.md#L277-L336)

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

章节来源
- [docs/TTS成本分析报告.md:62-216](file://docs/TTS成本分析报告.md#L62-L216)
- [server/src/modules/subscription/subscription.service.ts:519-600](file://server/src/modules/subscription/subscription.service.ts#L519-L600)
- [server/src/modules/subscription/subscription.service.ts:685-724](file://server/src/modules/subscription/subscription.service.ts#L685-L724)