# 会员管理

<cite>
**本文档引用的文件**
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [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)
- [auth.ts](file://server/src/middleware/auth.ts)
- [usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [rate-limiter.ts](file://server/src/middleware/rate-limiter.ts)
- [sentry.service.ts](file://server/src/services/sentry.service.ts)
- [log.service.ts](file://server/src/services/log.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)
- [migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)
- [API.md](file://docs/API.md)
- [订阅系统使用说明.md](file://docs/订阅系统使用说明.md)
- [支付集成指南.md](file://docs/支付集成指南.md)
</cite>

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

## 引言

会员管理系统是音频TTS应用的核心业务模块，负责管理用户的会员订阅、套餐定价、权益分配和使用配额控制。该系统采用分层架构设计，通过清晰的模块划分实现了功能解耦和业务逻辑分离。

系统主要包含三个核心模块：
- **会员管理模块**：处理用户会员状态、订单管理和支付流程
- **订阅管理模块**：管理套餐计划、订阅状态和Token配额系统
- **支付管理模块**：集成多种支付方式，处理支付回调和订单状态

## 项目结构

基于代码库分析，会员管理系统采用模块化架构，每个功能模块都有独立的控制器、服务层和数据模型：

```mermaid
graph TB
subgraph "客户端层"
Frontend[前端应用]
Mobile[移动端应用]
end
subgraph "API网关层"
Auth[认证中间件]
RateLimit[限流中间件]
UsageLimit[使用限制中间件]
end
subgraph "业务逻辑层"
MemberModule[会员模块]
SubscriptionModule[订阅模块]
PaymentModule[支付模块]
end
subgraph "数据持久层"
Prisma[Prisma ORM]
MySQL[(MySQL数据库)]
end
Frontend --> Auth
Mobile --> Auth
Auth --> RateLimit
RateLimit --> UsageLimit
UsageLimit --> MemberModule
UsageLimit --> SubscriptionModule
UsageLimit --> PaymentModule
MemberModule --> Prisma
SubscriptionModule --> Prisma
PaymentModule --> Prisma
Prisma --> MySQL
```

**图表来源**
- [member.controller.ts:1-90](file://server/src/modules/member/member.controller.ts#L1-L90)
- [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)

**章节来源**
- [member.controller.ts:1-90](file://server/src/modules/member/member.controller.ts#L1-L90)
- [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)

## 核心组件

### 会员等级体系

系统采用三级会员等级体系，每级会员享有不同的权益和限制：

| 等级 | 名称 | 月度价格 | 年度价格 | 日生成次数 | 单次字数限制 | 音色数量 | 音质标准 |
|------|------|----------|----------|------------|-------------|----------|----------|
| 0 | 免费版 | ¥0 | ¥0 | 3次 | 5000字 | 5种 | 标准 |
| 1 | 月度会员 | ¥19.9 | ¥199 | 20次 | 50000字 | 全部 | 高清 |
| 2 | 年度会员 | ¥19.9 | ¥199 | 无限制 | 无限制 | 全部 | 高清 |

### 套餐定价策略

订阅系统采用"包月批发+按量零售"的混合定价模式：

```mermaid
flowchart TD
Start([用户选择套餐]) --> CheckExisting{是否有现有订阅}
CheckExisting --> |是| ExtendPeriod[延长订阅期限]
CheckExisting --> |否| NewSubscription[创建新订阅]
ExtendPeriod --> CalculateDays[计算延长天数]
NewSubscription --> SetStartDate[设置开始日期]
CalculateDays --> UpdateSubscription[更新订阅信息]
SetStartDate --> CreateSubscription[创建订阅记录]
UpdateSubscription --> UpdateUser[更新用户状态]
CreateSubscription --> UpdateUser
UpdateUser --> UpdateToken[更新Token余额]
UpdateToken --> End([完成])
```

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

### 使用配额控制系统

系统实现了多层次的使用配额控制机制：

```mermaid
classDiagram
class User {
+int id
+int memberLevel
+DateTime memberExpireAt
+int dailyUsage
+string lastUsageDate
+int usedAudioMinutes
+DateTime subscriptionResetDate
}
class SubscriptionPlan {
+int id
+string name
+int level
+decimal priceMonthly
+decimal priceYearly
+int dailyGenerations
+int perGenerationLimit
+int monthlyTokens
+int monthlyMinutes
+bool overageEnabled
+decimal overagePrice
}
class TokenBalance {
+int id
+int userId
+int totalTokens
+int usedTokens
+DateTime resetDate
}
class TokenUsage {
+int id
+int userId
+string type
+int amount
+int contentLength
+DateTime createdAt
}
User --> SubscriptionPlan : "拥有"
User --> TokenBalance : "拥有"
User --> TokenUsage : "产生"
TokenBalance --> TokenUsage : "记录"
```

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

**章节来源**
- [member.service.ts:1-183](file://server/src/modules/member/member.service.ts#L1-L183)
- [subscription.service.ts:158-296](file://server/src/modules/subscription/subscription.service.ts#L158-L296)
- [schema.prisma:254-332](file://server/prisma/schema.prisma#L254-L332)

## 架构概览

会员管理系统采用典型的三层架构设计，通过中间件实现横切关注点的分离：

```mermaid
sequenceDiagram
participant Client as 客户端
participant Auth as 认证中间件
participant Controller as 控制器
participant Service as 服务层
participant DB as 数据库
Client->>Auth : 请求API
Auth->>Auth : 验证JWT令牌
Auth->>Controller : 通过认证
Controller->>Service : 调用业务逻辑
Service->>DB : 查询/更新数据
DB-->>Service : 返回结果
Service-->>Controller : 业务结果
Controller-->>Client : 响应数据
```

**图表来源**
- [auth.ts:7-49](file://server/src/middleware/auth.ts#L7-L49)
- [member.controller.ts:21-30](file://server/src/modules/member/member.controller.ts#L21-L30)

系统的关键特性包括：

1. **认证授权**：JWT令牌验证，支持可选认证模式
2. **限流保护**：基于Redis/Memory的分布式限流
3. **使用限制**：每日使用次数和字数限制
4. **错误监控**：Sentry集成和日志分析
5. **支付集成**：支付宝、微信支付和模拟支付

**章节来源**
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [rate-limiter.ts:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)

## 详细组件分析

### 会员管理模块

会员管理模块负责处理用户的基本会员状态和订单管理：

#### 核心功能流程

```mermaid
flowchart TD
CreateOrder[创建订单] --> ValidateInput[验证输入参数]
ValidateInput --> CheckUser[检查用户存在性]
CheckUser --> GenerateOrderNo[生成订单号]
GenerateOrderNo --> SaveOrder[保存订单记录]
SaveOrder --> ReturnOrder[返回订单信息]
GetStatus[获取会员状态] --> GetUser[获取用户信息]
GetUser --> CheckDailyUsage[检查每日使用次数]
CheckDailyUsage --> CalculateQuota[计算配额信息]
CalculateQuota --> ReturnStatus[返回状态信息]
```

**图表来源**
- [member.service.ts:76-100](file://server/src/modules/member/member.service.ts#L76-L100)
- [member.service.ts:39-73](file://server/src/modules/member/member.service.ts#L39-L73)

#### 订单管理流程

```mermaid
sequenceDiagram
participant User as 用户
participant API as 订单API
participant Service as 订单服务
participant DB as 数据库
User->>API : POST /api/member/order
API->>Service : createOrder(userId, productType)
Service->>Service : 验证产品类型
Service->>Service : 生成订单号
Service->>DB : 创建订单记录
DB-->>Service : 订单ID
Service-->>API : 订单信息
API-->>User : {orderNo, amount}
```

**图表来源**
- [member.controller.ts:33-48](file://server/src/modules/member/member.controller.ts#L33-L48)
- [member.service.ts:76-100](file://server/src/modules/member/member.service.ts#L76-L100)

**章节来源**
- [member.controller.ts:1-90](file://server/src/modules/member/member.controller.ts#L1-L90)
- [member.service.ts:1-183](file://server/src/modules/member/member.service.ts#L1-L183)

### 订阅管理模块

订阅管理模块负责套餐计划、Token配额和音频时长管理：

#### 套餐计划管理

系统支持五级套餐体系，每级套餐都有独特的功能组合：

| 套餐级别 | 名称 | 月度Token | 月度音频分钟 | 超额单价 | API访问 | 批量处理 | 团队管理 |
|----------|------|-----------|--------------|----------|---------|----------|----------|
| 0 | 免费版 | 1500 | 10 | 不支持 | 否 | 否 | 否 |
| 1 | 入门版 | 4500 | 30 | ¥8/分钟 | 否 | 否 | 否 |
| 2 | 专业版 | 15000 | 100 | ¥7/分钟 | 否 | 否 | 否 |
| 3 | 旗舰版 | 60000 | 400 | ¥6/分钟 | 是 | 否 | 否 |
| 4 | 企业版 | 225000 | 1500 | ¥5/分钟 | 是 | 是 | 是 |

#### Token配额系统

```mermaid
flowchart TD
CheckQuota[检查配额] --> GetBalance[获取Token余额]
GetBalance --> CheckUnlimited{是否无限额}
CheckUnlimited --> |是| Allow[允许使用]
CheckUnlimited --> |否| Compare[比较剩余Token]
Compare --> Enough{剩余Token充足?}
Enough --> |是| Allow[允许使用]
Enough --> |否| Deny[拒绝使用]
ConsumeToken[消费Token] --> UpdateBalance[更新余额]
UpdateBalance --> LogUsage[记录使用]
LogUsage --> Complete[完成]
```

**图表来源**
- [subscription.service.ts:495-513](file://server/src/modules/subscription/subscription.service.ts#L495-L513)
- [subscription.service.ts:411-450](file://server/src/modules/subscription/subscription.service.ts#L411-L450)

#### 音频时长计费系统

系统采用"包月配额+按量计费"的混合模式：

```mermaid
flowchart TD
Start([音频生成请求]) --> CalcMinutes[计算音频时长]
CalcMinutes --> CheckQuota[检查月度配额]
CheckQuota --> HasOverage{是否支持超额?}
HasOverage --> |否| CheckRemaining{剩余时长充足?}
HasOverage --> |是| CalcCost[计算费用]
CheckRemaining --> |是| CalcCost
CheckRemaining --> |否| Deny[拒绝生成]
CalcCost --> Charge[扣费]
Charge --> Complete[生成音频]
Deny --> Complete
```

**图表来源**
- [subscription.service.ts:653-683](file://server/src/modules/subscription/subscription.service.ts#L653-L683)
- [subscription.service.ts:557-600](file://server/src/modules/subscription/subscription.service.ts#L557-L600)

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

### 支付管理模块

支付管理模块集成了多种支付方式，提供了完整的支付流程：

#### 支付流程

```mermaid
sequenceDiagram
participant User as 用户
participant API as 支付API
participant Service as 支付服务
participant PaymentSDK as 支付SDK
participant DB as 数据库
User->>API : POST /api/payment/create
API->>Service : createPaymentOrder(userId, planId, method)
Service->>Service : 验证套餐和用户
Service->>Service : 生成订单号
Service->>DB : 创建订单记录
Service->>PaymentSDK : 调用支付接口
PaymentSDK-->>Service : 支付链接/二维码
Service-->>API : 支付信息
API-->>User : 支付URL/二维码
Note over PaymentSDK,DB : 异步回调处理
PaymentSDK->>Service : 支付回调通知
Service->>DB : 更新订单状态
Service->>DB : 激活订阅
```

**图表来源**
- [payment.controller.ts:9-33](file://server/src/modules/payment/payment.controller.ts#L9-L33)
- [payment.service.ts:122-191](file://server/src/modules/payment/payment.service.ts#L122-L191)

#### 支付方式支持

系统支持三种支付方式：

1. **支付宝支付**：支持网页支付和扫码支付
2. **微信支付**：支持H5支付和Native支付
3. **模拟支付**：开发环境下的测试支付

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

## 依赖关系分析

### 数据模型关系

```mermaid
erDiagram
User {
int id PK
int memberLevel
datetime memberExpireAt
int dailyUsage
string lastUsageDate
int usedAudioMinutes
datetime subscriptionResetDate
}
SubscriptionPlan {
int id PK
int level
decimal priceMonthly
decimal priceYearly
int dailyGenerations
int monthlyTokens
int monthlyMinutes
bool overageEnabled
decimal overagePrice
}
Subscription {
int id PK
int userId FK
int planId FK
datetime startDate
datetime endDate
string status
bool autoRenew
}
Order {
int id PK
int userId FK
string orderNo UK
int planId FK
string productType
decimal amount
string status
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
datetime createdAt
}
User ||--o{ Subscription : "拥有"
User ||--o{ Order : "创建"
User ||--o{ TokenBalance : "拥有"
User ||--o{ TokenUsage : "产生"
SubscriptionPlan ||--o{ Subscription : "定义"
SubscriptionPlan ||--o{ Order : "关联"
```

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

### 模块间依赖

```mermaid
graph LR
subgraph "认证层"
AuthMiddleware[认证中间件]
RateLimiter[限流中间件]
UsageLimit[使用限制中间件]
end
subgraph "业务模块"
MemberModule[会员模块]
SubscriptionModule[订阅模块]
PaymentModule[支付模块]
end
subgraph "数据访问"
Prisma[Prisma ORM]
Database[(MySQL)]
end
AuthMiddleware --> MemberModule
AuthMiddleware --> SubscriptionModule
AuthMiddleware --> PaymentModule
RateLimiter --> AuthMiddleware
UsageLimit --> AuthMiddleware
MemberModule --> Prisma
SubscriptionModule --> Prisma
PaymentModule --> Prisma
Prisma --> Database
```

**图表来源**
- [auth.ts:1-81](file://server/src/middleware/auth.ts#L1-L81)
- [rate-limiter.ts:1-120](file://server/src/middleware/rate-limiter.ts#L1-L120)
- [usageLimit.ts:1-66](file://server/src/middleware/usageLimit.ts#L1-L66)

**章节来源**
- [schema.prisma:1-472](file://server/prisma/schema.prisma#L1-L472)

## 性能考虑

### 缓存策略

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

1. **Redis缓存**：用于限流器状态存储
2. **内存缓存**：作为Redis不可用时的降级方案
3. **数据库索引**：为常用查询字段建立索引

### 性能优化措施

1. **异步处理**：支付回调和日志记录采用异步处理
2. **连接池**：数据库连接使用连接池管理
3. **分页查询**：大量数据查询使用分页机制
4. **批量操作**：Token使用记录采用批量插入

### 监控指标

系统集成了全面的监控指标：

- **Sentry错误监控**：捕获和分析运行时错误
- **日志分析服务**：自动分析错误模式和提供修复建议
- **性能追踪**：使用Sentry Profiling进行性能分析

## 故障排除指南

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

#### 认证相关问题

| 问题描述 | 可能原因 | 解决方案 |
|----------|----------|----------|
| Token已过期 | JWT令牌过期 | 重新登录获取新Token |
| Token无效 | 签名验证失败 | 检查服务器密钥配置 |
| 缺少Authorization头 | 请求未携带认证信息 | 添加Bearer Token到请求头 |

#### 支付相关问题

| 问题描述 | 可能原因 | 解决方案 |
|----------|----------|----------|
| 支付回调失败 | 签名验证失败 | 检查支付配置和证书 |
| 订单状态不更新 | 异步回调未处理 | 检查回调URL配置 |
| 支付SDK加载失败 | 环境依赖缺失 | 安装相应的支付SDK |

#### 配额相关问题

| 问题描述 | 可能原因 | 解决方案 |
|----------|----------|----------|
| Token余额不足 | 配额用尽 | 升级套餐或等待重置 |
| 使用次数超限 | 日使用次数限制 | 等待次日重置或升级会员 |
| 音频时长不足 | 月度配额用尽 | 购买额外时长或升级套餐 |

**章节来源**
- [sentry.service.ts:1-52](file://server/src/services/sentry.service.ts#L1-L52)
- [log.service.ts:233-315](file://server/src/services/log.service.ts#L233-L315)

## 结论

会员管理系统通过清晰的模块划分和完善的业务逻辑实现了完整的会员订阅管理功能。系统采用了现代化的架构设计，具备良好的扩展性和维护性。

### 主要优势

1. **模块化设计**：三个核心模块职责明确，便于维护和扩展
2. **多层次保护**：认证、限流、使用限制形成完整的安全防护体系
3. **灵活的定价策略**：支持多种套餐和计费模式
4. **完善的监控**：集成Sentry和日志分析，提供全面的运维支持
5. **支付集成**：支持多种支付方式，满足不同用户需求

### 改进建议

1. **自动续费功能**：目前系统支持手动续费，可考虑添加自动续费功能
2. **退款管理**：当前缺少专门的退款处理流程，可增加退款管理功能
3. **数据分析**：可增加会员使用行为的数据分析功能
4. **多语言支持**：可考虑添加国际化支持

## 附录

### API接口说明

#### 会员管理API

| 接口 | 方法 | 描述 | 认证要求 |
|------|------|------|----------|
| `/api/member/benefits` | GET | 获取会员权益信息 | 否 |
| `/api/member/status` | GET | 获取用户会员状态 | 是 |
| `/api/member/order` | POST | 创建订单 | 是 |
| `/api/member/pay/mock` | POST | 模拟支付 | 是 |
| `/api/member/orders` | GET | 获取订单列表 | 是 |

#### 订阅管理API

| 接口 | 方法 | 描述 | 认证要求 |
|------|------|------|----------|
| `/api/subscription/plans` | GET | 获取套餐列表 | 否 |
| `/api/subscription/subscription` | GET | 获取用户订阅信息 | 是 |
| `/api/subscription/balance` | GET | 获取用户Token余额 | 是 |
| `/api/subscription/usage` | GET | 获取Token使用记录 | 是 |
| `/api/subscription/quota` | GET | 获取用户配额 | 是 |

#### 支付管理API

| 接口 | 方法 | 描述 | 认证要求 |
|------|------|------|----------|
| `/api/payment/create` | POST | 创建支付订单 | 是 |
| `/api/payment/mock` | POST | 模拟支付 | 是 |
| `/api/payment/orders` | GET | 获取订单列表 | 是 |
| `/api/payment/alipay/notify` | POST | 支付宝异步通知 | 否 |
| `/api/payment/wechat/notify` | POST | 微信支付回调 | 否 |

### 数据库表结构

系统使用Prisma ORM管理数据模型，主要表结构包括：

1. **User表**：用户基本信息和会员状态
2. **SubscriptionPlan表**：套餐计划定义
3. **Subscription表**：用户订阅记录
4. **Order表**：支付订单记录
5. **TokenBalance表**：Token余额管理
6. **TokenUsage表**：Token使用记录

### 配置说明

系统支持多种环境配置：

1. **认证配置**：JWT密钥和认证开关
2. **支付配置**：支付宝和微信支付的密钥配置
3. **监控配置**：Sentry DSN和日志级别
4. **数据库配置**：MySQL连接参数