# 会员订阅系统
**本文引用的文件**
- [订阅系统使用说明.md](file://docs/订阅系统使用说明.md)
- [支付集成指南.md](file://docs/支付集成指南.md)
- [subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [index.ts](file://server/src/types/index.ts)
- [schema.prisma](file://server/prisma/schema.prisma)
- [index.vue](file://my-uniapp-vue3/src/pages/member/index.vue)
## 目录
1. [简介](#简介)
2. [项目结构](#项目结构)
3. [核心组件](#核心组件)
4. [架构总览](#架构总览)
5. [详细组件分析](#详细组件分析)
6. [依赖关系分析](#依赖关系分析)
7. [性能考量](#性能考量)
8. [故障排查指南](#故障排查指南)
9. [结论](#结论)
10. [附录](#附录)
## 简介
本文件面向会员订阅系统，系统化阐述会员体系设计理念、分级策略、订阅管理机制、使用配额系统、支付集成架构、会员权益管理以及API接口与集成指南。系统采用“包月配额+按量超支”的双轨计费策略，结合Token与音频时长两种配额维度，覆盖从免费体验到企业级的多层级套餐，并提供支付宝、微信支付的集成与回调处理能力。
## 项目结构
订阅系统由后端服务与前端页面协同构成：
- 后端模块
- 订阅模块：提供套餐查询、余额查询、Token使用记录、音频时长配额检查与消费等接口
- 支付模块：负责订单创建、支付渠道对接、回调处理与订阅激活
- 类型定义：统一用户、订单、状态等类型
- 数据模型：Prisma Schema 定义用户、订单、订阅、Token余额与使用记录等
- 前端页面
- 订阅套餐页面：展示套餐列表、选择套餐、支付方式与应付金额
- 支付确认与结果页面：跳转支付、轮询订单状态、展示支付结果
```mermaid
graph TB
subgraph "前端"
FE_Member["订阅页面
pages/member/index.vue"]
end
subgraph "后端"
C_Sub["订阅控制器
subscription.controller.ts"]
S_Sub["订阅服务
subscription.service.ts"]
C_Pay["支付控制器
payment.controller.ts"]
S_Pay["支付服务
payment.service.ts"]
Types["类型定义
types/index.ts"]
Prisma["数据模型
prisma/schema.prisma"]
end
FE_Member --> C_Sub
FE_Member --> C_Pay
C_Sub --> S_Sub
C_Pay --> S_Pay
S_Sub --> Prisma
S_Pay --> Prisma
S_Sub --> Types
S_Pay --> Types
```
图表来源
- [subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [subscription.service.ts:1-938](file://server/src/modules/subscription/subscription.service.ts#L1-L938)
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [index.ts:1-124](file://server/src/types/index.ts#L1-L124)
- [schema.prisma:1-200](file://server/prisma/schema.prisma#L1-L200)
章节来源
- [subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [index.ts:1-124](file://server/src/types/index.ts#L1-L124)
- [schema.prisma:1-200](file://server/prisma/schema.prisma#L1-L200)
## 核心组件
- 套餐与定价
- 默认包含免费版、入门版、专业版、旗舰版、企业版五档，支持月付与年付
- 配额维度：Token配额、音频时长配额、每日生成次数、单次生成上限、音色数量、音质等级、API访问、批量处理、团队管理等
- 订阅管理
- 订单创建、状态流转、订阅激活与续期、自动续费开关
- 支付集成
- 支付宝、微信支付（含沙箱/模拟）、回调签名验证、订单状态查询
- 使用配额系统
- Token余额与使用记录；音频时长配额（包月+按量超支）
- 会员权益
- 功能解锁、优先级提升、专属音色、批量处理、团队管理等
章节来源
- [subscription.service.ts:158-296](file://server/src/modules/subscription/subscription.service.ts#L158-L296)
- [payment.service.ts:122-191](file://server/src/modules/payment/payment.service.ts#L122-L191)
- [subscription.service.ts:519-649](file://server/src/modules/subscription/subscription.service.ts#L519-L649)
- [index.vue:1-253](file://my-uniapp-vue3/src/pages/member/index.vue#L1-L253)
## 架构总览
订阅系统采用前后端分离架构，前端通过HTTP接口与后端交互，后端通过Prisma访问MySQL数据库。支付模块支持支付宝与微信支付，回调处理确保订单状态一致性。
```mermaid
sequenceDiagram
participant U as "用户"
participant FE as "前端页面"
participant PC as "支付控制器"
participant PS as "支付服务"
participant SC as "订阅控制器"
participant SS as "订阅服务"
participant DB as "数据库"
U->>FE : 选择套餐与支付方式
FE->>PC : POST /api/payment/create
PC->>PS : 创建支付订单
PS->>DB : 写入订单记录
PS-->>FE : 返回支付链接/二维码
FE->>U : 跳转支付
U-->>PS : 支付完成异步回调
PS->>PS : 验证签名
PS->>DB : 更新订单状态
PS->>SS : 激活订阅
SS->>DB : 创建/续期订阅、更新用户等级
SS->>DB : 初始化/更新Token余额
PS-->>FE : 订单状态轮询
FE-->>U : 展示支付结果
```
图表来源
- [payment.controller.ts:10-33](file://server/src/modules/payment/payment.controller.ts#L10-L33)
- [payment.service.ts:122-191](file://server/src/modules/payment/payment.service.ts#L122-L191)
- [subscription.service.ts:409-509](file://server/src/modules/subscription/subscription.service.ts#L409-L509)
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)
## 详细组件分析
### 套餐与定价策略
- 套餐等级与功能
- 免费版：基础音色、标准音质、有限时长配额
- 入门版：高清音质、全部音色、超出按量计费
- 专业版：无损音质、API访问、批量处理（部分场景）
- 旗舰版：VIP优先队列、专属技术支持、批量处理、团队管理
- 企业版：最高配额与权限，支持大量并发与团队协作
- 定价与配额
- 月付/年付价格与Token配额对应，超出部分按零售价计费
- 音频时长配额采用“包月批发价+按量零售价”策略，降低大用户成本
章节来源
- [subscription.service.ts:158-296](file://server/src/modules/subscription/subscription.service.ts#L158-L296)
- [订阅系统使用说明.md:16-63](file://docs/订阅系统使用说明.md#L16-L63)
### 订阅管理机制
- 订单生命周期
- 创建：生成唯一订单号、记录套餐与金额、状态为“待支付”
- 支付：支付宝/微信回调验证签名后更新状态为“已支付”
- 激活：创建或续期订阅，更新用户会员等级与到期时间
- 续费：现有有效期内的订阅到期后自动延长30天
- 订阅状态与有效期
- 状态：active/expired/cancelled
- 有效期：按30天周期递增或首次创建
章节来源
- [payment.service.ts:359-406](file://server/src/modules/payment/payment.service.ts#L359-L406)
- [payment.service.ts:409-509](file://server/src/modules/payment/payment.service.ts#L409-L509)
- [subscription.controller.ts:32-42](file://server/src/modules/subscription/subscription.controller.ts#L32-L42)
### 使用配额系统
- Token配额
- 用户Token余额与使用记录，支持无限额度（-1）与按月重置
- 消耗逻辑：生成请求时检查余额，余额不足则拒绝
- 音频时长配额（新增）
- 按“包月批发价”与“按量零售价”计算，支持月度重置
- 免费版不支持超出，其他等级支持超出并按分钟计费
- 提供预估接口，前端展示生成费用与可用时长
```mermaid
flowchart TD
Start(["开始"]) --> CheckQuota["检查用户音频时长配额"]
CheckQuota --> Enough{"剩余时长足够？"}
Enough --> |否| Overage{"是否支持超出？"}
Overage --> |否| Deny["拒绝生成"]
Overage --> |是| Charge["按量计费零售价"]
Enough --> |是| Allow["允许生成"]
Charge --> Consume["生成完成后扣除时长并记录使用"]
Allow --> Consume
Consume --> End(["结束"])
Deny --> End
```
图表来源
- [subscription.service.ts:651-724](file://server/src/modules/subscription/subscription.service.ts#L651-L724)
章节来源
- [subscription.service.ts:519-724](file://server/src/modules/subscription/subscription.service.ts#L519-L724)
- [subscription.controller.ts:160-188](file://server/src/modules/subscription/subscription.controller.ts#L160-L188)
### 支付集成架构
- 支付宝
- 电脑网站支付/当面付（预下单）两种方式
- 异步回调与同步返回均进行签名验证
- 沙箱环境支持，开发阶段可使用模拟支付
- 微信支付
- Native支付（扫码）生成二维码
- 异步回调与订单查询接口
- 证书与密钥配置要求严格
- 回调处理
- 验证签名后更新订单状态
- 成功后激活订阅并初始化/更新Token余额
```mermaid
sequenceDiagram
participant FE as "前端"
participant PC as "支付控制器"
participant PS as "支付服务"
participant ALI as "支付宝网关"
participant WX as "微信支付网关"
participant DB as "数据库"
FE->>PC : POST /api/payment/create
alt 支付宝
PC->>PS : 生成支付宝支付链接
PS->>ALI : 发起支付
ALI-->>PS : 返回支付链接/二维码
else 微信支付
PC->>PS : 生成微信支付二维码
PS->>WX : 发起支付
WX-->>PS : 返回二维码
end
PS-->>PC : 返回支付信息
PC-->>FE : 返回支付链接/二维码
ALI-->>PS : 异步回调
WX-->>PS : 异步回调
PS->>PS : 验证签名
PS->>DB : 更新订单状态
PS->>DB : 激活订阅/更新Token余额
```
图表来源
- [payment.controller.ts:58-149](file://server/src/modules/payment/payment.controller.ts#L58-L149)
- [payment.service.ts:194-295](file://server/src/modules/payment/payment.service.ts#L194-L295)
- [payment.service.ts:359-406](file://server/src/modules/payment/payment.service.ts#L359-L406)
章节来源
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [支付集成指南.md:28-208](file://docs/支付集成指南.md#L28-L208)
### 会员权益管理
- 权益映射
- 音色数量、音质等级、API访问、批量处理、团队管理等
- 免费版限制较多，其他等级逐步解锁
- 优先级与专属服务
- VIP优先队列、专属技术支持等权益随等级提升
- 等级与到期
- 用户memberLevel与memberExpireAt字段决定当前权益与有效期
章节来源
- [subscription.service.ts:158-296](file://server/src/modules/subscription/subscription.service.ts#L158-L296)
- [index.ts:18-124](file://server/src/types/index.ts#L18-L124)
### 前端集成与页面
- 订阅页面
- 展示套餐列表、特性对比、推荐标识与价格
- 选择支付方式（支付宝/微信），点击“立即订阅”跳转支付确认页
- 支付流程
- 前端创建订单后跳转支付，轮询订单状态，支付成功后刷新用户状态与余额
章节来源
- [index.vue:1-253](file://my-uniapp-vue3/src/pages/member/index.vue#L1-L253)
## 依赖关系分析
```mermaid
classDiagram
class SubscriptionController {
+GET /subscription/plans
+GET /subscription/balance
+GET /subscription/usage
+POST /subscription/check-quota
+GET /subscription/audio-balance
+GET /subscription/audio-estimate
}
class SubscriptionService {
+getPlans()
+getUserTokenBalance()
+getTokenUsageList()
+checkQuota()
+getUserAudioBalance()
+getAudioEstimate()
}
class PaymentController {
+POST /payment/create
+POST /payment/mock
+POST /payment/alipay/notify
+POST /payment/wechat/notify
+GET /payment/orders
}
class PaymentService {
+createPaymentOrder()
+generateAlipayPayment()
+generateWechatPayment()
+handlePaymentCallback()
+activateSubscription()
}
class PrismaSchema {
+User
+Order
+Subscription
+TokenBalance
+TokenUsage
+SubscriptionPlan
}
class Types {
+MemberLevel
+OrderStatus
+ProductType
}
SubscriptionController --> SubscriptionService
PaymentController --> PaymentService
SubscriptionService --> PrismaSchema
PaymentService --> PrismaSchema
SubscriptionService --> Types
PaymentService --> Types
```
图表来源
- [subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [subscription.service.ts:1-938](file://server/src/modules/subscription/subscription.service.ts#L1-L938)
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [schema.prisma:1-200](file://server/prisma/schema.prisma#L1-L200)
- [index.ts:1-124](file://server/src/types/index.ts#L1-L124)
章节来源
- [subscription.controller.ts:1-191](file://server/src/modules/subscription/subscription.controller.ts#L1-L191)
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)
- [schema.prisma:1-200](file://server/prisma/schema.prisma#L1-L200)
## 性能考量
- 订单与订阅状态查询
- 使用索引优化：用户ID、订单号、状态、套餐ID等
- 配额检查
- 音频时长配额计算为O(1)，Token余额检查为O(1)
- 支付回调
- 异步回调避免阻塞主流程，回调中仅做状态更新与订阅激活
- 重置策略
- Token与音频时长按月重置，避免长期累积导致查询压力
[本节为通用指导，不涉及具体文件分析]
## 故障排查指南
- 支付宝/微信支付未配置
- 现象：返回模拟支付链接或提示支付不可用
- 处理：检查环境变量与证书文件，确保SDK初始化成功
- 回调签名验证失败
- 现象：回调被拒绝或订单状态未更新
- 处理：核对回调URL、签名算法与密钥配置
- 订单重复处理
- 现象：同一订单多次回调导致重复激活
- 处理：回调中先检查订单状态，若已支付则直接返回成功
- 配额不足
- 现象：生成请求被拒绝
- 处理：引导用户升级套餐或减少生成规模
章节来源
- [payment.service.ts:340-356](file://server/src/modules/payment/payment.service.ts#L340-L356)
- [payment.service.ts:359-406](file://server/src/modules/payment/payment.service.ts#L359-L406)
- [subscription.service.ts:651-683](file://server/src/modules/subscription/subscription.service.ts#L651-L683)
## 结论
会员订阅系统通过清晰的分级策略与灵活的计费模型，满足从个人用户到企业用户的多样化需求。系统在支付集成、配额管理与权益解锁方面具备良好的扩展性与稳定性，建议后续完善自动续费、退款与数据分析等功能，持续优化用户体验与运营效率。
[本节为总结性内容，不涉及具体文件分析]
## 附录
### API 接口清单与说明
- 订阅相关
- GET /api/subscription/plans：获取套餐列表
- GET /api/subscription/balance：获取Token余额
- GET /api/subscription/usage：获取Token使用记录
- POST /api/subscription/check-quota：检查Token配额
- GET /api/subscription/audio-balance：获取音频时长余额
- GET /api/subscription/audio-estimate：获取音频生成预估
- 支付相关
- POST /api/payment/create：创建支付订单
- POST /api/payment/mock：模拟支付（开发环境）
- POST /api/payment/alipay/notify：支付宝异步回调
- POST /api/payment/wechat/notify：微信支付异步回调
- GET /api/payment/orders：获取订单列表
- GET /api/payment/orders/:orderNo：获取订单详情
章节来源
- [订阅系统使用说明.md:183-351](file://docs/订阅系统使用说明.md#L183-L351)
- [subscription.controller.ts:9-188](file://server/src/modules/subscription/subscription.controller.ts#L9-L188)
- [payment.controller.ts:9-203](file://server/src/modules/payment/payment.controller.ts#L9-L203)
### 数据库模型概览
- User：用户基本信息、会员等级、到期时间、音频时长与重置时间等
- Order：订单信息、支付方式、状态、金额与关联套餐
- SubscriptionPlan：套餐配置、价格、配额与功能特性
- TokenBalance：Token总配额、已用、重置时间
- TokenUsage：Token使用记录、类型、内容长度与描述
章节来源
- [schema.prisma:10-61](file://server/prisma/schema.prisma#L10-L61)