# 会员订阅系统

<cite>
**本文引用的文件**
- [订阅系统使用说明.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)
</cite>

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

## 简介
本文件面向会员订阅系统，系统化阐述会员体系设计理念、分级策略、订阅管理机制、使用配额系统、支付集成架构、会员权益管理以及API接口与集成指南。系统采用“包月配额+按量超支”的双轨计费策略，结合Token与音频时长两种配额维度，覆盖从免费体验到企业级的多层级套餐，并提供支付宝、微信支付的集成与回调处理能力。

## 项目结构
订阅系统由后端服务与前端页面协同构成：
- 后端模块
  - 订阅模块：提供套餐查询、余额查询、Token使用记录、音频时长配额检查与消费等接口
  - 支付模块：负责订单创建、支付渠道对接、回调处理与订阅激活
  - 类型定义：统一用户、订单、状态等类型
  - 数据模型：Prisma Schema 定义用户、订单、订阅、Token余额与使用记录等
- 前端页面
  - 订阅套餐页面：展示套餐列表、选择套餐、支付方式与应付金额
  - 支付确认与结果页面：跳转支付、轮询订单状态、展示支付结果

```mermaid
graph TB
subgraph "前端"
FE_Member["订阅页面<br/>pages/member/index.vue"]
end
subgraph "后端"
C_Sub["订阅控制器<br/>subscription.controller.ts"]
S_Sub["订阅服务<br/>subscription.service.ts"]
C_Pay["支付控制器<br/>payment.controller.ts"]
S_Pay["支付服务<br/>payment.service.ts"]
Types["类型定义<br/>types/index.ts"]
Prisma["数据模型<br/>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)