audio_codebuddy/.qoder/repowiki/zh/content/项目概述/核心功能特性/会员订阅系统/套餐管理.md

套餐管理

本文引用的文件

• subscription.controller.ts
• subscription.service.ts
• payment.controller.ts
• payment.service.ts
• schema.prisma
• index.ts
• auth.ts
• usageLimit.ts
• 支付集成指南.md
• 订阅系统使用说明.md
• index.vue
• orders/index.vue

目录

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

简介

套餐管理系统是AI语音应用的核心商业模块，负责管理用户订阅、付费授权和资源配额。该系统实现了完整的订阅生命周期管理，包括套餐配置、价格策略、功能权限映射和有效期管理。

系统采用多层次套餐体系，涵盖免费版、基础版、专业版和旗舰版四个等级，每个套餐都有独特的功能权限和定价策略。通过Token配额系统实现精细化的资源控制，结合音频时长计费机制，为用户提供灵活的付费体验。

项目结构

套餐管理系统由前后端分离的架构组成，采用模块化设计：

graph TB
subgraph "前端层"
FE_MEMBER[会员中心页面]
FE_ORDERS[订单历史页面]
FE_UTILS[请求工具]
end
subgraph "后端层"
subgraph "路由层"
CTRL_SUB[订阅控制器]
CTRL_PAY[支付控制器]
end
subgraph "服务层"
SVC_SUB[订阅服务]
SVC_PAY[支付服务]
end
subgraph "数据层"
PRISMA[Prisma ORM]
MYSQL[(MySQL数据库)]
end
end
FE_MEMBER --> CTRL_SUB
FE_ORDERS --> CTRL_PAY
CTRL_SUB --> SVC_SUB
CTRL_PAY --> SVC_PAY
SVC_SUB --> PRISMA
SVC_PAY --> PRISMA
PRISMA --> MYSQL

图表来源

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

章节来源

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

核心组件

套餐配置管理

系统实现了标准化的套餐配置管理，支持动态调整套餐属性和价格策略：

套餐等级	月付价格	年付价格	Token配额	主要功能
免费版	¥0	¥0	5,000/月	基础音色、标准音质
基础版	¥9.9	¥99	10,000/月	全部音色、高清音质
专业版	¥29.9	¥299	20,000/月	无损音质、API访问
旗舰版	¥99	¥999	50,000/月	批量处理、团队管理

订阅状态管理

订阅系统支持完整的生命周期管理，包括创建、激活、续期和取消：

stateDiagram-v2
[*] --> 待支付
待支付 --> 已支付 : 支付成功
待支付 --> 已取消 : 支付失败
已支付 --> 已激活 : 订阅创建
已激活 --> 已过期 : 到期时间
已激活 --> 已续期 : 续费操作
已激活 --> 已取消 : 用户取消
已续期 --> 已激活 : 继续使用
已过期 --> [*]
已取消 --> [*]

图表来源

• payment.service.ts:408-509

章节来源

• subscription.service.ts:158-296
• payment.service.ts:408-509

架构概览

系统采用分层架构设计，确保各层职责清晰、耦合度低：

graph TD
subgraph "表现层"
A[前端Vue页面]
B[移动端小程序]
end
subgraph "API网关层"
C[Koa路由]
D[认证中间件]
E[限流中间件]
end
subgraph "业务逻辑层"
F[订阅服务]
G[支付服务]
H[配额服务]
end
subgraph "数据持久层"
I[Prisma ORM]
J[MySQL数据库]
end
A --> C
B --> C
C --> D
C --> F
C --> G
C --> H
F --> I
G --> I
H --> I
I --> J

图表来源

• auth.ts:1-81
• subscription.service.ts:1-938

详细组件分析

订阅服务组件

订阅服务是系统的核心业务逻辑，负责处理用户订阅的所有操作：

核心功能模块

1. 套餐管理

   • 套餐配置初始化
   • 套餐查询和详情获取
   • 套餐状态管理

2. Token配额管理

   • 余额查询和更新
   • 使用记录追踪
   • 配额检查和扣费

3. 音频时长管理

   • 时长计算和计费
   • 超出配额处理
   • 月度重置机制

类关系图

classDiagram
class SubscriptionService {
+initializePlans()
+getPlans()
+getPlanById(id)
+getUserSubscription(userId)
+getUserTokenBalance(userId)
+consumeToken(userId, amount, type, contentLength)
+calculateAudioCost(textLength, memberLevel, usedMinutes)
+checkAudioQuota(userId, textLength)
}
class PaymentService {
+createPaymentOrder(userId, planId, paymentMethod)
+activateSubscription(userId, planId)
+handlePaymentCallback(orderNo, paymentId, status)
+generateAlipayPayment(orderNo, amount, subject)
+generateWechatPayment(orderNo, amount, subject)
}
class PrismaClient {
+subscriptionPlan
+subscription
+tokenBalance
+tokenUsage
+order
}
SubscriptionService --> PrismaClient : "使用"
PaymentService --> PrismaClient : "使用"

图表来源

• subscription.service.ts:298-324
• payment.service.ts:121-191

章节来源

• subscription.service.ts:298-324
• payment.service.ts:121-191

支付服务组件

支付服务实现了完整的支付流程，支持多种支付方式：

支付流程序列图

sequenceDiagram
participant U as 用户
participant P as 支付页面
participant API as 支付API
participant ALI as 支付宝
participant WX as 微信支付
participant DB as 数据库
U->>P : 选择套餐和支付方式
P->>API : 创建支付订单
API->>DB : 保存订单记录
API->>ALI : 生成支付链接
API->>WX : 生成支付二维码
U->>ALI : 完成支付
ALI->>API : 支付回调通知
API->>DB : 更新订单状态
API->>DB : 激活订阅服务
API->>U : 支付成功通知

图表来源

• payment.controller.ts:9-33
• payment.service.ts:358-406

支付方式支持

支付方式	支持状态	特殊说明
支付宝	✅ 已实现	支持电脑网站支付和扫码支付
微信支付	✅ 已实现	支持NATIVE支付和H5支付
模拟支付	✅ 开发环境可用	仅用于测试和演示
银行卡支付	❌ 待实现	计划中的支付方式

章节来源

• payment.controller.ts:9-33
• payment.service.ts:193-295

前端交互组件

前端页面提供了直观的用户界面，支持套餐选择和支付操作：

会员中心页面

会员中心页面展示了用户当前的订阅状态和可用功能：

flowchart TD
A[用户进入会员中心] --> B{用户已登录?}
B --> |否| C[跳转登录页面]
B --> |是| D[显示Token余额]
D --> E[加载套餐列表]
E --> F{显示推荐套餐}
F --> G[高亮推荐套餐]
G --> H[用户选择套餐]
H --> I[选择支付方式]
I --> J[跳转支付确认]
J --> K[完成支付]
K --> L[更新订阅状态]

图表来源

• index.vue:112-165

章节来源

• index.vue:112-165
• orders/index.vue:138-176

依赖分析

数据模型依赖

系统基于Prisma ORM实现数据持久化，核心数据模型如下：

erDiagram
USER {
int id PK
string phone
string openid
int memberLevel
datetime memberExpireAt
int usedAudioMinutes
datetime subscriptionResetDate
}
SUBSCRIPTION_PLAN {
int id PK
string name
int level
decimal priceMonthly
decimal priceYearly
int monthlyTokens
int monthlyMinutes
boolean overageEnabled
decimal overagePrice
}
SUBSCRIPTION {
int id PK
int userId FK
int planId FK
datetime startDate
datetime endDate
string status
boolean autoRenew
}
TOKEN_BALANCE {
int id PK
int userId FK
int totalTokens
int usedTokens
datetime resetDate
}
TOKEN_USAGE {
int id PK
int userId FK
string type
int amount
int contentLength
datetime createdAt
}
ORDER {
int id PK
int userId FK
string orderNo
int planId FK
string productType
decimal amount
string status
string paymentMethod
datetime paidAt
}
USER ||--o{ SUBSCRIPTION : has
USER ||--o{ TOKEN_BALANCE : has
USER ||--o{ TOKEN_USAGE : has
USER ||--o{ ORDER : has
SUBSCRIPTION_PLAN ||--o{ SUBSCRIPTION : defines
SUBSCRIPTION_PLAN ||--o{ ORDER : creates
TOKEN_BALANCE ||--o{ TOKEN_USAGE : tracks

图表来源

• schema.prisma:10-330

服务间依赖关系

graph LR
subgraph "外部依赖"
JWT[jwt]
ALIPAY[alipay-sdk]
WECHAT[wechatpay-node-v3]
PRISMA[prisma]
end
subgraph "内部模块"
AUTH[认证中间件]
LIMIT[使用限制]
SUB_SERVICE[订阅服务]
PAY_SERVICE[支付服务]
end
AUTH --> JWT
PAY_SERVICE --> ALIPAY
PAY_SERVICE --> WECHAT
SUB_SERVICE --> PRISMA
PAY_SERVICE --> PRISMA
LIMIT --> PRISMA

图表来源

• auth.ts:1-81
• payment.service.ts:1-29

章节来源

• schema.prisma:10-330
• auth.ts:1-81

性能考虑

数据库性能优化

1. 索引策略

   • 用户ID和状态组合索引用于快速查询活跃订阅
   • 订单号唯一索引确保订单查询效率
   • Token使用记录按时间倒序索引支持高效分页

2. 查询优化

   • 使用惰性加载避免不必要的关联查询
   • 分页查询限制单次查询的数据量
   • 缓存常用配置减少数据库访问

缓存策略

系统采用多层缓存机制：

• Redis缓存用户会话信息
• 内存缓存套餐配置
• 数据库连接池优化

异步处理

支付回调和订单处理采用异步队列：

• 支付成功回调异步处理
• 订阅激活延迟执行
• 日志记录异步写入

故障排除指南

常见问题及解决方案

支付相关问题

问题类型	症状	可能原因	解决方案
支付失败	支付状态未更新	支付回调未收到	检查回调URL配置
订单重复	同一订单多次处理	网络重试导致	实现幂等性处理
余额不足	Token扣费失败	配额检查逻辑错误	检查配额计算逻辑
订阅未激活	用户状态未更新	订阅创建异常	检查订阅服务日志

认证相关问题

flowchart TD
A[认证失败] --> B{Token格式正确?}
B --> |否| C[检查Authorization头格式]
B --> |是| D{Token是否过期?}
D --> |是| E[重新登录获取新Token]
D --> |否| F{Token签名验证失败?}
F --> |是| G[检查密钥配置]
F --> |否| H[检查用户状态]

图表来源

• auth.ts:34-48

章节来源

• auth.ts:34-48
• payment.service.ts:358-406

调试工具

1. 日志监控

   • 支付回调日志
   • 订阅状态变更日志
   • Token使用记录

2. 性能监控

   • API响应时间统计
   • 数据库查询性能
   • 缓存命中率

结论

套餐管理系统实现了完整的订阅商业模式，具有以下特点：

1. 模块化设计：清晰的分层架构便于维护和扩展
2. 灵活的定价策略：支持多种套餐等级和计费方式
3. 完善的权限控制：基于Token的精细化资源管理
4. 可靠的支付集成：支持主流支付方式和安全回调
5. 良好的用户体验：直观的前端界面和流畅的操作流程

系统目前完成了核心功能的实现，包括套餐配置、支付集成和配额管理。后续可以进一步完善自动续费、退款管理和数据分析等功能。

附录

API接口文档

订阅相关接口

接口	方法	路径	功能描述
获取套餐列表	GET	/api/subscription/plans	获取所有可用套餐
获取套餐详情	GET	/api/subscription/plans/:id	获取指定套餐详情
获取订阅信息	GET	/api/subscription/subscription	获取用户当前订阅
获取Token余额	GET	/api/subscription/balance	获取用户Token余额
获取使用记录	GET	/api/subscription/usage	获取Token使用记录
检查配额	POST	/api/subscription/check-quota	检查Token配额
音频时长估算	GET	/api/subscription/audio-estimate	估算音频生成费用

支付相关接口

接口	方法	路径	功能描述
创建订单	POST	/api/payment/create	创建支付订单
支付宝回调	POST	/api/payment/alipay/notify	支付宝异步回调
微信支付回调	POST	/api/payment/wechat/notify	微信支付回调
订单列表	GET	/api/payment/orders	获取订单列表
订单详情	GET	/api/payment/orders/:orderNo	获取订单详情

配置说明

环境变量配置

# 支付宝配置
ALIPAY_APP_ID=your_app_id
ALIPAY_PRIVATE_KEY=your_private_key
ALIPAY_PUBLIC_KEY=alipay_public_key
ALIPAY_NOTIFY_URL=https://your-domain.com/api/payment/alipay/notify

# 微信支付配置
WECHAT_APP_ID=your_app_id
WECHAT_MCH_ID=your_mch_id
WECHAT_SERIAL_NO=your_serial_no
WECHAT_APIV3_KEY=your_apiv3_key
WECHAT_NOTIFY_URL=https://your-domain.com/api/payment/wechat/notify

# 数据库配置
DATABASE_URL=mysql://user:password@localhost:3306/audio_book

套餐配置

套餐配置位于subscription.service.ts文件中，可以通过修改DEFAULT_PLANS数组来调整套餐属性、价格和功能权限。