audio_codebuddy/.qoder/repowiki/zh/content/核心模块/订阅付费系统/会员管理.md

会员管理

本文档引用的文件

• member.controller.ts
• member.service.ts
• subscription.controller.ts
• subscription.service.ts
• payment.controller.ts
• payment.service.ts
• auth.ts
• usageLimit.ts
• rate-limiter.ts
• sentry.service.ts
• log.service.ts
• schema.prisma
• migration.sql
• API.md
• 订阅系统使用说明.md
• 支付集成指南.md

目录

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

引言

会员管理系统是音频TTS应用的核心业务模块，负责管理用户的会员订阅、套餐定价、权益分配和使用配额控制。该系统采用分层架构设计，通过清晰的模块划分实现了功能解耦和业务逻辑分离。

系统主要包含三个核心模块：

• 会员管理模块：处理用户会员状态、订单管理和支付流程
• 订阅管理模块：管理套餐计划、订阅状态和Token配额系统
• 支付管理模块：集成多种支付方式，处理支付回调和订单状态

项目结构

基于代码库分析，会员管理系统采用模块化架构，每个功能模块都有独立的控制器、服务层和数据模型：

graph TB
subgraph "客户端层"
Frontend[前端应用]
Mobile[移动端应用]
end
subgraph "API网关层"
Auth[认证中间件]
RateLimit[限流中间件]
UsageLimit[使用限制中间件]
end
subgraph "业务逻辑层"
MemberModule[会员模块]
SubscriptionModule[订阅模块]
PaymentModule[支付模块]
end
subgraph "数据持久层"
Prisma[Prisma ORM]
MySQL[(MySQL数据库)]
end
Frontend --> Auth
Mobile --> Auth
Auth --> RateLimit
RateLimit --> UsageLimit
UsageLimit --> MemberModule
UsageLimit --> SubscriptionModule
UsageLimit --> PaymentModule
MemberModule --> Prisma
SubscriptionModule --> Prisma
PaymentModule --> Prisma
Prisma --> MySQL

图表来源

• member.controller.ts:1-90
• subscription.controller.ts:1-191
• payment.controller.ts:1-258

章节来源

• member.controller.ts:1-90
• subscription.controller.ts:1-191
• payment.controller.ts:1-258

核心组件

会员等级体系

系统采用三级会员等级体系，每级会员享有不同的权益和限制：

等级	名称	月度价格	年度价格	日生成次数	单次字数限制	音色数量	音质标准
0	免费版	¥0	¥0	3次	5000字	5种	标准
1	月度会员	¥19.9	¥199	20次	50000字	全部	高清
2	年度会员	¥19.9	¥199	无限制	无限制	全部	高清

套餐定价策略

订阅系统采用"包月批发+按量零售"的混合定价模式：

flowchart TD
Start([用户选择套餐]) --> CheckExisting{是否有现有订阅}
CheckExisting --> |是| ExtendPeriod[延长订阅期限]
CheckExisting --> |否| NewSubscription[创建新订阅]
ExtendPeriod --> CalculateDays[计算延长天数]
NewSubscription --> SetStartDate[设置开始日期]
CalculateDays --> UpdateSubscription[更新订阅信息]
SetStartDate --> CreateSubscription[创建订阅记录]
UpdateSubscription --> UpdateUser[更新用户状态]
CreateSubscription --> UpdateUser
UpdateUser --> UpdateToken[更新Token余额]
UpdateToken --> End([完成])

图表来源

• payment.service.ts:409-509

使用配额控制系统

系统实现了多层次的使用配额控制机制：

classDiagram
class User {
+int id
+int memberLevel
+DateTime memberExpireAt
+int dailyUsage
+string lastUsageDate
+int usedAudioMinutes
+DateTime subscriptionResetDate
}
class SubscriptionPlan {
+int id
+string name
+int level
+decimal priceMonthly
+decimal priceYearly
+int dailyGenerations
+int perGenerationLimit
+int monthlyTokens
+int monthlyMinutes
+bool overageEnabled
+decimal overagePrice
}
class TokenBalance {
+int id
+int userId
+int totalTokens
+int usedTokens
+DateTime resetDate
}
class TokenUsage {
+int id
+int userId
+string type
+int amount
+int contentLength
+DateTime createdAt
}
User --> SubscriptionPlan : "拥有"
User --> TokenBalance : "拥有"
User --> TokenUsage : "产生"
TokenBalance --> TokenUsage : "记录"

图表来源

• schema.prisma:10-332

章节来源

• member.service.ts:1-183
• subscription.service.ts:158-296
• schema.prisma:254-332

架构概览

会员管理系统采用典型的三层架构设计，通过中间件实现横切关注点的分离：

sequenceDiagram
participant Client as 客户端
participant Auth as 认证中间件
participant Controller as 控制器
participant Service as 服务层
participant DB as 数据库
Client->>Auth : 请求API
Auth->>Auth : 验证JWT令牌
Auth->>Controller : 通过认证
Controller->>Service : 调用业务逻辑
Service->>DB : 查询/更新数据
DB-->>Service : 返回结果
Service-->>Controller : 业务结果
Controller-->>Client : 响应数据

图表来源

• auth.ts:7-49
• member.controller.ts:21-30

系统的关键特性包括：

1. 认证授权：JWT令牌验证，支持可选认证模式
2. 限流保护：基于Redis/Memory的分布式限流
3. 使用限制：每日使用次数和字数限制
4. 错误监控：Sentry集成和日志分析
5. 支付集成：支付宝、微信支付和模拟支付

章节来源

• auth.ts:1-81
• rate-limiter.ts:1-120
• usageLimit.ts:1-66

详细组件分析

会员管理模块

会员管理模块负责处理用户的基本会员状态和订单管理：

核心功能流程

flowchart TD
CreateOrder[创建订单] --> ValidateInput[验证输入参数]
ValidateInput --> CheckUser[检查用户存在性]
CheckUser --> GenerateOrderNo[生成订单号]
GenerateOrderNo --> SaveOrder[保存订单记录]
SaveOrder --> ReturnOrder[返回订单信息]
GetStatus[获取会员状态] --> GetUser[获取用户信息]
GetUser --> CheckDailyUsage[检查每日使用次数]
CheckDailyUsage --> CalculateQuota[计算配额信息]
CalculateQuota --> ReturnStatus[返回状态信息]

图表来源

• member.service.ts:76-100
• member.service.ts:39-73

订单管理流程

sequenceDiagram
participant User as 用户
participant API as 订单API
participant Service as 订单服务
participant DB as 数据库
User->>API : POST /api/member/order
API->>Service : createOrder(userId, productType)
Service->>Service : 验证产品类型
Service->>Service : 生成订单号
Service->>DB : 创建订单记录
DB-->>Service : 订单ID
Service-->>API : 订单信息
API-->>User : {orderNo, amount}

图表来源

• member.controller.ts:33-48
• member.service.ts:76-100

章节来源

• member.controller.ts:1-90
• member.service.ts:1-183

订阅管理模块

订阅管理模块负责套餐计划、Token配额和音频时长管理：

套餐计划管理

系统支持五级套餐体系，每级套餐都有独特的功能组合：

套餐级别	名称	月度Token	月度音频分钟	超额单价	API访问	批量处理	团队管理
0	免费版	1500	10	不支持	否	否	否
1	入门版	4500	30	¥8/分钟	否	否	否
2	专业版	15000	100	¥7/分钟	否	否	否
3	旗舰版	60000	400	¥6/分钟	是	否	否
4	企业版	225000	1500	¥5/分钟	是	是	是

Token配额系统

flowchart TD
CheckQuota[检查配额] --> GetBalance[获取Token余额]
GetBalance --> CheckUnlimited{是否无限额}
CheckUnlimited --> |是| Allow[允许使用]
CheckUnlimited --> |否| Compare[比较剩余Token]
Compare --> Enough{剩余Token充足?}
Enough --> |是| Allow[允许使用]
Enough --> |否| Deny[拒绝使用]
ConsumeToken[消费Token] --> UpdateBalance[更新余额]
UpdateBalance --> LogUsage[记录使用]
LogUsage --> Complete[完成]

图表来源

• subscription.service.ts:495-513
• subscription.service.ts:411-450

音频时长计费系统

系统采用"包月配额+按量计费"的混合模式：

flowchart TD
Start([音频生成请求]) --> CalcMinutes[计算音频时长]
CalcMinutes --> CheckQuota[检查月度配额]
CheckQuota --> HasOverage{是否支持超额?}
HasOverage --> |否| CheckRemaining{剩余时长充足?}
HasOverage --> |是| CalcCost[计算费用]
CheckRemaining --> |是| CalcCost
CheckRemaining --> |否| Deny[拒绝生成]
CalcCost --> Charge[扣费]
Charge --> Complete[生成音频]
Deny --> Complete

图表来源

• subscription.service.ts:653-683
• subscription.service.ts:557-600

章节来源

• subscription.controller.ts:1-191
• subscription.service.ts:1-938

支付管理模块

支付管理模块集成了多种支付方式，提供了完整的支付流程：

支付流程

sequenceDiagram
participant User as 用户
participant API as 支付API
participant Service as 支付服务
participant PaymentSDK as 支付SDK
participant DB as 数据库
User->>API : POST /api/payment/create
API->>Service : createPaymentOrder(userId, planId, method)
Service->>Service : 验证套餐和用户
Service->>Service : 生成订单号
Service->>DB : 创建订单记录
Service->>PaymentSDK : 调用支付接口
PaymentSDK-->>Service : 支付链接/二维码
Service-->>API : 支付信息
API-->>User : 支付URL/二维码
Note over PaymentSDK,DB : 异步回调处理
PaymentSDK->>Service : 支付回调通知
Service->>DB : 更新订单状态
Service->>DB : 激活订阅

图表来源

• payment.controller.ts:9-33
• payment.service.ts:122-191

支付方式支持

系统支持三种支付方式：

1. 支付宝支付：支持网页支付和扫码支付
2. 微信支付：支持H5支付和Native支付
3. 模拟支付：开发环境下的测试支付

章节来源

• payment.controller.ts:1-258
• payment.service.ts:1-578

依赖关系分析

数据模型关系

erDiagram
User {
int id PK
int memberLevel
datetime memberExpireAt
int dailyUsage
string lastUsageDate
int usedAudioMinutes
datetime subscriptionResetDate
}
SubscriptionPlan {
int id PK
int level
decimal priceMonthly
decimal priceYearly
int dailyGenerations
int monthlyTokens
int monthlyMinutes
bool overageEnabled
decimal overagePrice
}
Subscription {
int id PK
int userId FK
int planId FK
datetime startDate
datetime endDate
string status
bool autoRenew
}
Order {
int id PK
int userId FK
string orderNo UK
int planId FK
string productType
decimal amount
string status
datetime paidAt
}
TokenBalance {
int id PK
int userId UK
int totalTokens
int usedTokens
datetime resetDate
}
TokenUsage {
int id PK
int userId FK
string type
int amount
int contentLength
datetime createdAt
}
User ||--o{ Subscription : "拥有"
User ||--o{ Order : "创建"
User ||--o{ TokenBalance : "拥有"
User ||--o{ TokenUsage : "产生"
SubscriptionPlan ||--o{ Subscription : "定义"
SubscriptionPlan ||--o{ Order : "关联"

图表来源

• schema.prisma:10-332

模块间依赖

graph LR
subgraph "认证层"
AuthMiddleware[认证中间件]
RateLimiter[限流中间件]
UsageLimit[使用限制中间件]
end
subgraph "业务模块"
MemberModule[会员模块]
SubscriptionModule[订阅模块]
PaymentModule[支付模块]
end
subgraph "数据访问"
Prisma[Prisma ORM]
Database[(MySQL)]
end
AuthMiddleware --> MemberModule
AuthMiddleware --> SubscriptionModule
AuthMiddleware --> PaymentModule
RateLimiter --> AuthMiddleware
UsageLimit --> AuthMiddleware
MemberModule --> Prisma
SubscriptionModule --> Prisma
PaymentModule --> Prisma
Prisma --> Database

图表来源

• auth.ts:1-81
• rate-limiter.ts:1-120
• usageLimit.ts:1-66

章节来源

• schema.prisma:1-472

性能考虑

缓存策略

系统采用多层缓存策略来提升性能：

1. Redis缓存：用于限流器状态存储
2. 内存缓存：作为Redis不可用时的降级方案
3. 数据库索引：为常用查询字段建立索引

性能优化措施

1. 异步处理：支付回调和日志记录采用异步处理
2. 连接池：数据库连接使用连接池管理
3. 分页查询：大量数据查询使用分页机制
4. 批量操作：Token使用记录采用批量插入

监控指标

系统集成了全面的监控指标：

• Sentry错误监控：捕获和分析运行时错误
• 日志分析服务：自动分析错误模式和提供修复建议
• 性能追踪：使用Sentry Profiling进行性能分析

故障排除指南

常见问题及解决方案

认证相关问题

问题描述	可能原因	解决方案
Token已过期	JWT令牌过期	重新登录获取新Token
Token无效	签名验证失败	检查服务器密钥配置
缺少Authorization头	请求未携带认证信息	添加Bearer Token到请求头

支付相关问题

问题描述	可能原因	解决方案
支付回调失败	签名验证失败	检查支付配置和证书
订单状态不更新	异步回调未处理	检查回调URL配置
支付SDK加载失败	环境依赖缺失	安装相应的支付SDK

配额相关问题

问题描述	可能原因	解决方案
Token余额不足	配额用尽	升级套餐或等待重置
使用次数超限	日使用次数限制	等待次日重置或升级会员
音频时长不足	月度配额用尽	购买额外时长或升级套餐

章节来源

• sentry.service.ts:1-52
• log.service.ts:233-315

结论

会员管理系统通过清晰的模块划分和完善的业务逻辑实现了完整的会员订阅管理功能。系统采用了现代化的架构设计，具备良好的扩展性和维护性。

主要优势

1. 模块化设计：三个核心模块职责明确，便于维护和扩展
2. 多层次保护：认证、限流、使用限制形成完整的安全防护体系
3. 灵活的定价策略：支持多种套餐和计费模式
4. 完善的监控：集成Sentry和日志分析，提供全面的运维支持
5. 支付集成：支持多种支付方式，满足不同用户需求

改进建议

1. 自动续费功能：目前系统支持手动续费，可考虑添加自动续费功能
2. 退款管理：当前缺少专门的退款处理流程，可增加退款管理功能
3. 数据分析：可增加会员使用行为的数据分析功能
4. 多语言支持：可考虑添加国际化支持

附录

API接口说明

会员管理API

接口	方法	描述	认证要求
/api/member/benefits	GET	获取会员权益信息	否
/api/member/status	GET	获取用户会员状态	是
/api/member/order	POST	创建订单	是
/api/member/pay/mock	POST	模拟支付	是
/api/member/orders	GET	获取订单列表	是

订阅管理API

接口	方法	描述	认证要求
/api/subscription/plans	GET	获取套餐列表	否
/api/subscription/subscription	GET	获取用户订阅信息	是
/api/subscription/balance	GET	获取用户Token余额	是
/api/subscription/usage	GET	获取Token使用记录	是
/api/subscription/quota	GET	获取用户配额	是

支付管理API

接口	方法	描述	认证要求
/api/payment/create	POST	创建支付订单	是
/api/payment/mock	POST	模拟支付	是
/api/payment/orders	GET	获取订单列表	是
/api/payment/alipay/notify	POST	支付宝异步通知	否
/api/payment/wechat/notify	POST	微信支付回调	否

数据库表结构

系统使用Prisma ORM管理数据模型，主要表结构包括：

1. User表：用户基本信息和会员状态
2. SubscriptionPlan表：套餐计划定义
3. Subscription表：用户订阅记录
4. Order表：支付订单记录
5. TokenBalance表：Token余额管理
6. TokenUsage表：Token使用记录

配置说明

系统支持多种环境配置：

1. 认证配置：JWT密钥和认证开关
2. 支付配置：支付宝和微信支付的密钥配置
3. 监控配置：Sentry DSN和日志级别
4. 数据库配置：MySQL连接参数