# 套餐管理

<cite>
**本文引用的文件**
- [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)
- [schema.prisma](file://server/prisma/schema.prisma)
- [index.ts](file://server/src/types/index.ts)
- [auth.ts](file://server/src/middleware/auth.ts)
- [usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [支付集成指南.md](file://docs/支付集成指南.md)
- [订阅系统使用说明.md](file://docs/订阅系统使用说明.md)
- [index.vue](file://my-uniapp-vue3/src/pages/member/index.vue)
- [orders/index.vue](file://my-uniapp-vue3/src/pages/orders/index.vue)
</cite>

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

## 简介

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

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

## 项目结构

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

```mermaid
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](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)

**章节来源**
- [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)

## 核心组件

### 套餐配置管理

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

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

### 订阅状态管理

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

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

**图表来源**
- [payment.service.ts:408-509](file://server/src/modules/payment/payment.service.ts#L408-L509)

**章节来源**
- [subscription.service.ts:158-296](file://server/src/modules/subscription/subscription.service.ts#L158-L296)
- [payment.service.ts:408-509](file://server/src/modules/payment/payment.service.ts#L408-L509)

## 架构概览

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

```mermaid
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](file://server/src/middleware/auth.ts#L1-L81)
- [subscription.service.ts:1-938](file://server/src/modules/subscription/subscription.service.ts#L1-L938)

## 详细组件分析

### 订阅服务组件

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

#### 核心功能模块

1. **套餐管理**
   - 套餐配置初始化
   - 套餐查询和详情获取
   - 套餐状态管理

2. **Token配额管理**
   - 余额查询和更新
   - 使用记录追踪
   - 配额检查和扣费

3. **音频时长管理**
   - 时长计算和计费
   - 超出配额处理
   - 月度重置机制

#### 类关系图

```mermaid
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](file://server/src/modules/subscription/subscription.service.ts#L298-L324)
- [payment.service.ts:121-191](file://server/src/modules/payment/payment.service.ts#L121-L191)

**章节来源**
- [subscription.service.ts:298-324](file://server/src/modules/subscription/subscription.service.ts#L298-L324)
- [payment.service.ts:121-191](file://server/src/modules/payment/payment.service.ts#L121-L191)

### 支付服务组件

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

#### 支付流程序列图

```mermaid
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](file://server/src/modules/payment/payment.controller.ts#L9-L33)
- [payment.service.ts:358-406](file://server/src/modules/payment/payment.service.ts#L358-L406)

#### 支付方式支持

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

**章节来源**
- [payment.controller.ts:9-33](file://server/src/modules/payment/payment.controller.ts#L9-L33)
- [payment.service.ts:193-295](file://server/src/modules/payment/payment.service.ts#L193-L295)

### 前端交互组件

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

#### 会员中心页面

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

```mermaid
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](file://my-uniapp-vue3/src/pages/member/index.vue#L112-L165)

**章节来源**
- [index.vue:112-165](file://my-uniapp-vue3/src/pages/member/index.vue#L112-L165)
- [orders/index.vue:138-176](file://my-uniapp-vue3/src/pages/orders/index.vue#L138-L176)

## 依赖分析

### 数据模型依赖

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

```mermaid
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](file://server/prisma/schema.prisma#L10-L330)

### 服务间依赖关系

```mermaid
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](file://server/src/middleware/auth.ts#L1-L81)
- [payment.service.ts:1-29](file://server/src/modules/payment/payment.service.ts#L1-L29)

**章节来源**
- [schema.prisma:10-330](file://server/prisma/schema.prisma#L10-L330)
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)

## 性能考虑

### 数据库性能优化

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

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

### 缓存策略

系统采用多层缓存机制：
- Redis缓存用户会话信息
- 内存缓存套餐配置
- 数据库连接池优化

### 异步处理

支付回调和订单处理采用异步队列：
- 支付成功回调异步处理
- 订阅激活延迟执行
- 日志记录异步写入

## 故障排除指南

### 常见问题及解决方案

#### 支付相关问题

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

#### 认证相关问题

```mermaid
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](file://server/src/middleware/auth.ts#L34-L48)

**章节来源**
- [auth.ts:34-48](file://server/src/middleware/auth.ts#L34-L48)
- [payment.service.ts:358-406](file://server/src/modules/payment/payment.service.ts#L358-L406)

### 调试工具

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 | 获取订单详情 |

### 配置说明

#### 环境变量配置

```env
# 支付宝配置
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`数组来调整套餐属性、价格和功能权限。