# 订阅付费系统

<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)
- [支付集成指南.md](file://docs/支付集成指南.md)
- [订阅系统使用说明.md](file://docs/订阅系统使用说明.md)
- [security.ts](file://server/src/middleware/security.ts)
- [index.vue](file://my-uniapp-vue3/src/pages/orders/index.vue)
- [index.vue](file://my-uniapp-vue3/src/pages/payment-result/index.vue)
</cite>

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

## 简介

订阅付费系统是一个完整的会员制付费解决方案，集成了多种支付方式、套餐管理和计费规则。该系统支持支付宝和微信支付两种主流支付渠道，提供灵活的订阅套餐设计和精细化的计费管理。

系统采用模块化架构设计，包含支付模块、订阅模块、用户管理模块等多个核心组件。通过Prisma ORM实现数据持久化，支持MySQL数据库。系统具备完善的订单管理、回调处理、状态跟踪等功能。

## 项目结构

项目采用前后端分离的架构模式，主要分为以下层次：

```mermaid
graph TB
subgraph "前端层"
UI[用户界面]
Orders[订单页面]
PaymentResult[支付结果页面]
end
subgraph "后端层"
API[API服务器]
Auth[认证中间件]
Security[安全中间件]
end
subgraph "服务层"
PaymentService[支付服务]
SubscriptionService[订阅服务]
TokenService[令牌服务]
end
subgraph "数据层"
Prisma[Prisma ORM]
MySQL[(MySQL数据库)]
end
UI --> API
Orders --> API
PaymentResult --> API
API --> Auth
API --> Security
API --> PaymentService
API --> SubscriptionService
PaymentService --> Prisma
SubscriptionService --> 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)
- [schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

**章节来源**
- [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-472](file://server/prisma/schema.prisma#L1-L472)

## 核心组件

### 套餐管理系统

系统提供4个层级的订阅套餐，从免费版到企业版，满足不同用户需求：

| 套餐级别 | 月付价格 | 年付价格 | 月度Token配额 | 主要功能 |
|---------|---------|---------|-------------|---------|
| 免费版 | ¥0 | ¥0 | 1,500 | 基础音质，10分钟音频 |
| 入门版 | ¥19 | ¥190 | 4,500 | 高清音质，30分钟音频 |
| 专业版 | ¥59 | ¥590 | 15,000 | 高清音质，100分钟音频 |
| 旗舰版 | ¥199 | ¥1,990 | 60,000 | 高清音质，400分钟音频 |
| 企业版 | ¥599 | ¥5,990 | 225,000 | 高清音质，1,500分钟音频 |

### 计费规则系统

系统采用双轨制计费模式：

1. **Token配额计费**：基于文本转语音的Token消耗
2. **音频时长计费**：基于实际生成的音频时长

```mermaid
flowchart TD
Start([开始计费]) --> CheckQuota{检查套餐配额}
CheckQuota --> |在配额内| InQuota[按包月批发价计费]
CheckQuota --> |超出配额| Overage[按零售价计费]
InQuota --> CalcTotal[计算总费用]
Overage --> CalcOverage[计算超量费用]
CalcOverage --> CalcTotal
CalcTotal --> ApplyDiscount{是否有折扣}
ApplyDiscount --> |是| FinalPrice[应用折扣]
ApplyDiscount --> |否| FinalPrice
FinalPrice --> End([结束])
```

**图表来源**
- [subscription.service.ts:556-600](file://server/src/modules/subscription/subscription.service.ts#L556-L600)

**章节来源**
- [subscription.service.ts:157-296](file://server/src/modules/subscription/subscription.service.ts#L157-L296)
- [subscription.service.ts:518-600](file://server/src/modules/subscription/subscription.service.ts#L518-L600)

## 架构概览

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

```mermaid
graph TB
subgraph "表现层"
Frontend[前端应用]
Mobile[移动端应用]
end
subgraph "控制层"
PaymentController[支付控制器]
SubscriptionController[订阅控制器]
AuthController[认证控制器]
end
subgraph "服务层"
PaymentService[支付服务]
SubscriptionService[订阅服务]
TokenService[令牌服务]
OrderService[订单服务]
end
subgraph "数据访问层"
PrismaClient[Prisma客户端]
Database[(MySQL数据库)]
end
Frontend --> PaymentController
Mobile --> PaymentController
PaymentController --> PaymentService
SubscriptionController --> SubscriptionService
AuthController --> PaymentService
PaymentService --> PrismaClient
SubscriptionService --> PrismaClient
PrismaClient --> Database
```

**图表来源**
- [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)
- [schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

## 详细组件分析

### 支付模块

支付模块是系统的核心组件，负责处理各种支付方式和回调处理：

#### 支付流程序列图

```mermaid
sequenceDiagram
participant User as 用户
participant Frontend as 前端应用
participant PaymentController as 支付控制器
participant PaymentService as 支付服务
participant AlipaySDK as 支付宝SDK
participant WechatPay as 微信支付
participant Database as 数据库
User->>Frontend : 选择套餐并发起支付
Frontend->>PaymentController : POST /api/payment/create
PaymentController->>PaymentService : createPaymentOrder()
PaymentService->>Database : 创建订单记录
alt 支付宝支付
PaymentService->>AlipaySDK : 生成支付链接
AlipaySDK-->>PaymentService : 支付链接
else 微信支付
PaymentService->>WechatPay : 创建支付订单
WechatPay-->>PaymentService : 二维码链接
end
PaymentService-->>PaymentController : 返回支付信息
PaymentController-->>Frontend : 支付页面
Note over User,Database : 用户完成支付后
AlipaySDK-->>PaymentController : 支付回调通知
WechatPay-->>PaymentController : 支付回调通知
PaymentController->>PaymentService : handlePaymentCallback()
PaymentService->>Database : 更新订单状态
PaymentService->>Database : 激活订阅服务
PaymentService->>Database : 更新用户状态
```

**图表来源**
- [payment.controller.ts:9-55](file://server/src/modules/payment/payment.controller.ts#L9-L55)
- [payment.service.ts:121-191](file://server/src/modules/payment/payment.service.ts#L121-L191)

#### 支付回调处理

系统实现了完善的支付回调处理机制：

1. **签名验证**：确保回调数据的真实性
2. **状态同步**：更新订单状态和用户订阅状态
3. **幂等处理**：防止重复处理同一笔订单
4. **异常处理**：捕获并处理各种异常情况

**章节来源**
- [payment.controller.ts:57-149](file://server/src/modules/payment/payment.controller.ts#L57-L149)
- [payment.service.ts:358-406](file://server/src/modules/payment/payment.service.ts#L358-L406)

### 订阅模块

订阅模块负责管理用户的订阅状态和配额：

#### 订阅生命周期

```mermaid
stateDiagram-v2
[*] --> 未订阅
未订阅 --> 订阅中 : 支付成功
订阅中 --> 已过期 : 到期日到达
订阅中 --> 续费中 : 自动续费
续费中 --> 订阅中 : 续费成功
续费中 --> 已过期 : 续费失败
已过期 --> 未订阅 : 重新购买
订阅中 --> 取消订阅 : 用户取消
取消订阅 --> [*]
```

**图表来源**
- [subscription.service.ts:344-359](file://server/src/modules/subscription/subscription.service.ts#L344-L359)

#### 配额管理系统

系统采用多层次的配额管理机制：

1. **Token配额**：基于文本转语音的Token消耗
2. **音频时长配额**：基于实际生成的音频时长
3. **生成次数配额**：限制每日内容生成次数

**章节来源**
- [subscription.service.ts:361-450](file://server/src/modules/subscription/subscription.service.ts#L361-L450)
- [subscription.service.ts:602-724](file://server/src/modules/subscription/subscription.service.ts#L602-L724)

### 数据模型设计

系统采用Prisma ORM进行数据建模，主要数据表包括：

#### 核心数据表关系

```mermaid
erDiagram
User {
int id PK
string phone
string openid
int memberLevel
datetime memberExpireAt
int usedAudioMinutes
datetime subscriptionResetDate
}
SubscriptionPlan {
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
}
Order {
int id PK
int userId FK
string orderNo UK
int planId FK
string productType
decimal amount
string status
string paymentMethod
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
int orderId FK
datetime createdAt
}
User ||--o{ Subscription : "拥有"
User ||--o{ Order : "创建"
User ||--o{ TokenBalance : "拥有"
User ||--o{ TokenUsage : "产生"
SubscriptionPlan ||--o{ Subscription : "定义"
SubscriptionPlan ||--o{ Order : "关联"
Order ||--o{ TokenUsage : "产生"
```

**图表来源**
- [schema.prisma:10-332](file://server/prisma/schema.prisma#L10-L332)

**章节来源**
- [schema.prisma:254-332](file://server/prisma/schema.prisma#L254-L332)

## 依赖关系分析

系统各组件之间的依赖关系如下：

```mermaid
graph TD
subgraph "外部依赖"
AlipaySDK[alipay-sdk]
WechatPay[wechatpay-node-v3]
PrismaClient[prisma-client-js]
KoaRouter[@koa/router]
end
subgraph "内部模块"
PaymentController[payment.controller.ts]
PaymentService[payment.service.ts]
SubscriptionController[subscription.controller.ts]
SubscriptionService[subscription.service.ts]
SecurityMiddleware[security.ts]
end
subgraph "数据模型"
UserModel[User模型]
OrderModel[Order模型]
SubscriptionModel[Subscription模型]
TokenBalanceModel[TokenBalance模型]
end
PaymentController --> PaymentService
SubscriptionController --> SubscriptionService
PaymentService --> PrismaClient
SubscriptionService --> PrismaClient
PaymentService --> AlipaySDK
PaymentService --> WechatPay
SecurityMiddleware --> PaymentController
SecurityMiddleware --> SubscriptionController
PaymentService --> UserModel
PaymentService --> OrderModel
SubscriptionService --> SubscriptionModel
SubscriptionService --> TokenBalanceModel
```

**图表来源**
- [payment.service.ts:1-29](file://server/src/modules/payment/payment.service.ts#L1-L29)
- [subscription.service.ts:1-3](file://server/src/modules/subscription/subscription.service.ts#L1-L3)

**章节来源**
- [payment.service.ts:1-578](file://server/src/modules/payment/payment.service.ts#L1-L578)
- [subscription.service.ts:1-938](file://server/src/modules/subscription/subscription.service.ts#L1-L938)

## 性能考虑

### 缓存策略

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

1. **支付SDK缓存**：避免重复初始化支付SDK
2. **套餐数据缓存**：缓存套餐配置减少数据库查询
3. **用户状态缓存**：缓存用户订阅状态

### 数据库优化

1. **索引优化**：为常用查询字段建立索引
2. **连接池管理**：合理配置数据库连接池
3. **查询优化**：使用JOIN减少查询次数

### 异步处理

1. **支付回调异步处理**：避免阻塞主线程
2. **订单状态轮询**：前端异步轮询订单状态
3. **日志异步写入**：异步记录操作日志

## 故障排除指南

### 支付相关问题

#### 支付宝支付问题

1. **支付链接生成失败**
   - 检查支付宝SDK配置
   - 验证密钥文件完整性
   - 确认回调URL配置正确

2. **支付回调失败**
   - 验证签名验证逻辑
   - 检查回调URL可达性
   - 确认服务器时间同步

#### 微信支付问题

1. **二维码生成失败**
   - 检查商户证书配置
   - 验证API密钥设置
   - 确认证书文件格式正确

2. **订单查询失败**
   - 检查网络连接状态
   - 验证商户配置信息
   - 确认API版本兼容性

### 订阅相关问题

#### 订阅激活失败

1. **检查用户状态**
   - 验证用户是否存在
   - 检查用户等级设置
   - 确认订阅状态一致性

2. **Token余额异常**
   - 检查Token配额计算
   - 验证重置日期逻辑
   - 确认余额更新事务

**章节来源**
- [payment.service.ts:358-406](file://server/src/modules/payment/payment.service.ts#L358-L406)
- [subscription.service.ts:408-509](file://server/src/modules/subscription/subscription.service.ts#L408-L509)

## 结论

订阅付费系统是一个功能完整、架构清晰的会员制付费解决方案。系统具备以下优势：

1. **模块化设计**：各组件职责明确，便于维护和扩展
2. **多支付支持**：同时支持支付宝和微信支付
3. **灵活计费**：支持Token配额和音频时长双重计费模式
4. **完善的安全机制**：包含签名验证、SQL注入防护等安全措施
5. **良好的用户体验**：提供直观的支付流程和状态反馈

系统目前支持核心功能的实现，包括套餐管理、支付处理、订阅激活等。后续可以进一步完善自动续费、退款处理、财务对账等高级功能。

## 附录

### API接口文档

#### 支付相关接口

| 接口 | 方法 | 描述 | 请求参数 | 响应示例 |
|------|------|------|----------|----------|
| /api/payment/create | POST | 创建支付订单 | planId, paymentMethod, returnUrl | 订单信息 |
| /api/payment/mock | POST | 模拟支付成功 | orderNo | 支付结果 |
| /api/payment/orders | GET | 获取订单列表 | page, pageSize | 订单列表 |
| /api/payment/orders/:orderNo | GET | 获取订单详情 | - | 订单详情 |

#### 订阅相关接口

| 接口 | 方法 | 描述 | 请求参数 | 响应示例 |
|------|------|------|----------|----------|
| /api/subscription/plans | GET | 获取套餐列表 | - | 套餐列表 |
| /api/subscription/subscription | GET | 获取用户订阅信息 | - | 订阅信息 |
| /api/subscription/balance | GET | 获取用户Token余额 | - | 余额信息 |
| /api/subscription/usage | GET | 获取Token使用记录 | page, pageSize | 使用记录 |

### 部署配置指南

#### 环境变量配置

```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_APIV3_KEY=your_api_key
WECHAT_NOTIFY_URL=https://your-domain.com/api/payment/wechat/notify

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

#### 安全配置

1. **HTTPS强制**：所有回调URL必须使用HTTPS
2. **域名白名单**：配置允许的回调域名
3. **签名验证**：启用支付回调签名验证
4. **IP限制**：限制支付网关IP访问

### 监控告警设置

#### 关键指标监控

1. **支付成功率**：监控支付宝和微信支付成功率
2. **订单处理延迟**：监控订单创建到支付完成的时间
3. **用户活跃度**：监控订阅用户增长趋势
4. **系统健康度**：监控数据库连接和API响应时间

#### 告警阈值设置

- 支付成功率低于95%触发告警
- 订单处理延迟超过30秒触发告警
- 数据库连接失败率超过1%触发告警
- API响应时间超过5秒触发告警