# 会员服务API

<cite>
**本文档引用的文件**
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [types/index.ts](file://server/src/types/index.ts)
- [models/index.ts](file://server/src/models/index.ts)
- [app.ts](file://server/src/app.ts)
- [schema.prisma](file://server/prisma/schema.prisma)
- [支付集成指南.md](file://docs/支付集成指南.md)
- [订阅系统使用说明.md](file://docs/订阅系统使用说明.md)
- [API.md](file://docs/API.md)
</cite>

## 目录
1. [项目概述](#项目概述)
2. [核心组件架构](#核心组件架构)
3. [会员权益接口](#会员权益接口)
4. [会员状态接口](#会员状态接口)
5. [订单创建接口](#订单创建接口)
6. [支付订单接口](#支付订单接口)
7. [会员等级与权益体系](#会员等级与权益体系)
8. [订单管理流程](#订单管理流程)
9. [支付集成与安全](#支付集成与安全)
10. [数据库模型](#数据库模型)
11. [性能与扩展性](#性能与扩展性)
12. [故障排除指南](#故障排除指南)
13. [总结](#总结)

## 项目概述

会员服务模块是AI语音应用的核心付费功能模块，提供完整的会员订阅管理、订单处理和支付集成能力。该模块采用微服务架构设计，通过清晰的职责分离实现了会员权益管理、状态查询、订单创建和支付处理等功能。

模块基于Koa.js框架构建，使用TypeScript进行类型安全编程，配合Prisma ORM实现数据库操作。整个系统支持多种支付方式，包括支付宝、微信支付和模拟支付，为企业级部署提供了灵活的支付解决方案。

## 核心组件架构

```mermaid
graph TB
subgraph "客户端层"
Web[Web前端]
Mobile[移动端应用]
MiniProgram[小程序]
end
subgraph "API网关层"
Router[Koa Router]
Auth[认证中间件]
ErrorHandler[错误处理]
end
subgraph "业务服务层"
MemberService[会员服务]
PaymentService[支付服务]
SubscriptionService[订阅服务]
end
subgraph "数据持久层"
Prisma[Prisma ORM]
MySQL[(MySQL数据库)]
Redis[(Redis缓存)]
end
subgraph "第三方集成"
Alipay[支付宝SDK]
WeChatPay[微信支付SDK]
OSS[对象存储]
end
Web --> Router
Mobile --> Router
MiniProgram --> Router
Router --> Auth
Auth --> MemberService
Auth --> PaymentService
Auth --> SubscriptionService
MemberService --> Prisma
PaymentService --> Prisma
SubscriptionService --> Prisma
Prisma --> MySQL
Prisma --> Redis
PaymentService --> Alipay
PaymentService --> WeChatPay
MemberService --> OSS
```

**图表来源**
- [app.ts:100-128](file://server/src/app.ts#L100-L128)
- [member.controller.ts:1-90](file://server/src/modules/member/member.controller.ts#L1-L90)
- [payment.controller.ts:1-258](file://server/src/modules/payment/payment.controller.ts#L1-L258)

## 会员权益接口

### 接口定义

**GET /api/member/benefits**

该接口用于获取完整的会员权益信息，包括各等级的详细功能对比和价格信息。

### 请求参数

无需请求参数

### 响应数据结构

| 字段 | 类型 | 描述 |
|------|------|------|
| code | number | 响应码，0表示成功 |
| message | string | 响应消息 |
| data | object | 权益数据对象 |

### 权益数据详情

```mermaid
erDiagram
BENEFITS {
array levels
}
LEVEL {
number level
string name
number price
object quota
array features
}
QUOTA {
number dailyLimit
number wordLimit
}
BENEFITS ||--o{ LEVEL : contains
LEVEL ||--|| QUOTA : defines
```

**图表来源**
- [member.service.ts:10-37](file://server/src/modules/member/member.service.ts#L10-L37)
- [types/index.ts:114-124](file://server/src/types/index.ts#L114-L124)

### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "levels": [
      {
        "level": 0,
        "name": "免费版",
        "price": 0,
        "quota": {
          "dailyLimit": 3,
          "wordLimit": 5000
        },
        "features": ["每天3次生成", "每次最多5000字", "基础音色"]
      },
      {
        "level": 1,
        "name": "月度会员",
        "price": 19.9,
        "quota": {
          "dailyLimit": 20,
          "wordLimit": 50000
        },
        "features": ["每天20次生成", "每次最多50000字", "全部音色", "优先处理"]
      },
      {
        "level": 2,
        "name": "年度会员",
        "price": 199,
        "quota": {
          "dailyLimit": -1,
          "wordLimit": -1
        },
        "features": ["无限次生成", "无字数限制", "全部音色", "优先处理", "专属客服"]
      }
    ]
  }
}
```

**章节来源**
- [member.controller.ts:9-18](file://server/src/modules/member/member.controller.ts#L9-L18)
- [member.service.ts:10-37](file://server/src/modules/member/member.service.ts#L10-L37)

## 会员状态接口

### 接口定义

**GET /api/member/status**

该接口用于获取当前用户的会员状态信息，包括会员等级、有效期和使用配额等。

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| Authorization | string | 是 | JWT认证令牌 |

### 响应数据结构

| 字段 | 类型 | 描述 |
|------|------|------|
| code | number | 响应码，0表示成功 |
| message | string | 响应消息 |
| data | object | 会员状态数据 |

### 状态数据详情

```mermaid
flowchart TD
Start([获取会员状态]) --> GetUser["查询用户信息"]
GetUser --> CheckUser{"用户是否存在"}
CheckUser --> |否| Error["抛出错误"]
CheckUser --> |是| GetQuota["获取配额信息"]
GetQuota --> CheckDate{"检查日期重置"}
CheckDate --> ResetDaily["重置每日使用次数"]
CheckDate --> CheckValidity["检查会员有效性"]
ResetDaily --> CalcRemainder["计算剩余配额"]
CheckValidity --> CalcRemainder
CalcRemainder --> ReturnData["返回状态数据"]
Error --> End([结束])
ReturnData --> End
```

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

### 响应示例

```json
{
  "code": 0,
  "message": "success",
  "data": {
    "level": 1,
    "levelName": "月度会员",
    "expireAt": "2026-12-31T23:59:59Z",
    "isValid": true,
    "quota": {
      "dailyLimit": 20,
      "dailyUsed": 3,
      "dailyRemaining": 17,
      "wordLimit": 50000
    }
  }
}
```

**章节来源**
- [member.controller.ts:20-30](file://server/src/modules/member/member.controller.ts#L20-L30)
- [member.service.ts:39-73](file://server/src/modules/member/member.service.ts#L39-L73)

## 订单创建接口

### 接口定义

**POST /api/member/order**

该接口用于创建会员订单，支持月度和年度两种产品类型。

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| Authorization | string | 是 | JWT认证令牌 |
| productType | string | 是 | 产品类型，可选值：'monthly' | 'yearly' |

### 响应数据结构

| 字段 | 类型 | 描述 |
|------|------|------|
| code | number | 响应码，0表示成功 |
| message | string | 响应消息 |
| data | object | 订单信息 |

### 订单创建流程

```mermaid
sequenceDiagram
participant Client as 客户端
participant Controller as 订单控制器
participant Service as 订单服务
participant Prisma as 数据库层
participant User as 用户表
participant Order as 订单表
Client->>Controller : POST /api/member/order
Controller->>Controller : 验证产品类型
Controller->>Service : createOrder(userId, productType)
Service->>Service : 获取价格信息
Service->>Prisma : 查询用户信息
Prisma-->>Service : 返回用户数据
Service->>Prisma : 创建订单记录
Prisma-->>Service : 返回订单信息
Service-->>Controller : 返回订单数据
Controller-->>Client : 订单创建成功
```

**图表来源**
- [member.controller.ts:32-48](file://server/src/modules/member/member.controller.ts#L32-L48)
- [member.service.ts:75-100](file://server/src/modules/member/member.service.ts#L75-L100)

### 响应示例

```json
{
  "code": 0,
  "message": "订单创建成功",
  "data": {
    "orderNo": "ORDER_20260412A1B2C3",
    "amount": 19.9
  }
}
```

**章节来源**
- [member.controller.ts:32-48](file://server/src/modules/member/member.controller.ts#L32-L48)
- [member.service.ts:75-100](file://server/src/modules/member/member.service.ts#L75-L100)

## 支付订单接口

### 接口定义

**POST /api/member/pay/mock**

该接口为开发环境提供模拟支付功能，用于测试支付流程。

### 请求参数

| 参数名 | 类型 | 必填 | 描述 |
|--------|------|------|------|
| Authorization | string | 是 | JWT认证令牌 |
| orderNo | string | 是 | 订单编号 |

### 响应数据结构

| 字段 | 类型 | 描述 |
|------|------|------|
| code | number | 响应码，0表示成功 |
| message | string | 响应消息 |
| data | object | 支付结果 |

### 支付处理流程

```mermaid
flowchart TD
Start([模拟支付请求]) --> CheckEnv{"检查环境"}
CheckEnv --> |生产环境| EnvError["抛出错误"]
CheckEnv --> |开发环境| ValidateOrder["验证订单"]
ValidateOrder --> OrderExists{"订单存在"}
OrderExists --> |否| OrderError["抛出错误"]
OrderExists --> |是| CheckStatus{"检查订单状态"}
CheckStatus --> StatusValid{"状态有效"}
StatusValid --> |否| StatusError["抛出错误"]
StatusValid --> UpdateOrder["更新订单状态为已支付"]
UpdateOrder --> UpdateUser["更新用户会员状态"]
UpdateUser --> CalcExpire["计算会员有效期"]
CalcExpire --> UpdateMember["更新会员等级和到期时间"]
UpdateMember --> Success["返回成功结果"]
EnvError --> End([结束])
OrderError --> End
StatusError --> End
Success --> End
```

**图表来源**
- [member.controller.ts:50-70](file://server/src/modules/member/member.controller.ts#L50-L70)
- [member.service.ts:102-155](file://server/src/modules/member/member.service.ts#L102-L155)

### 响应示例

```json
{
  "code": 0,
  "message": "支付成功",
  "data": {
    "success": true,
    "memberLevel": 1,
    "memberExpireAt": "2026-12-31T23:59:59Z"
  }
}
```

**章节来源**
- [member.controller.ts:50-70](file://server/src/modules/member/member.controller.ts#L50-L70)
- [member.service.ts:102-155](file://server/src/modules/member/member.service.ts#L102-L155)

## 会员等级与权益体系

### 等级定义

系统定义了三个会员等级，每个等级都有明确的功能权限和使用限制：

```mermaid
classDiagram
class MemberLevel {
<<enumeration>>
+FREE : 0
+MONTHLY : 1
+YEARLY : 2
}
class MemberQuota {
+number dailyLimit
+number wordLimit
}
class Level0 {
+name : "免费版"
+dailyLimit : 3
+wordLimit : 5000
+features : ["每天3次生成", "每次最多5000字", "基础音色"]
}
class Level1 {
+name : "月度会员"
+dailyLimit : 20
+wordLimit : 50000
+features : ["每天20次生成", "每次最多50000字", "全部音色", "优先处理"]
}
class Level2 {
+name : "年度会员"
+dailyLimit : -1
+wordLimit : -1
+features : ["无限次生成", "无字数限制", "全部音色", "优先处理", "专属客服"]
}
MemberLevel --> MemberQuota : defines
MemberQuota --> Level0 : configures
MemberQuota --> Level1 : configures
MemberQuota --> Level2 : configures
```

**图表来源**
- [types/index.ts:18](file://server/src/types/index.ts#L18)
- [types/index.ts:120-124](file://server/src/types/index.ts#L120-L124)

### 权益差异

| 特性 | 免费版 | 月度会员 | 年度会员 |
|------|--------|----------|----------|
| 每日生成次数 | 3次 | 20次 | 无限次 |
| 每次生成字数限制 | 5000字 | 50000字 | 无限制 |
| 音色选择 | 基础音色 | 全部音色 | 全部音色 |
| 优先级处理 | ❌ | ✅ | ✅ |
| 专属客服 | ❌ | ❌ | ✅ |
| 价格 | ¥0/月 | ¥19.9/月 | ¥199/年 |

### 升级条件

会员升级遵循以下规则：
1. **同级续费**：现有会员可在到期前进行续费
2. **跨级升级**：可选择升级到更高等级，按差价收费
3. **自动续费**：支持设置自动续费功能
4. **有效期计算**：续费时按剩余有效期顺延计算

**章节来源**
- [member.service.ts:10-37](file://server/src/modules/member/member.service.ts#L10-L37)
- [types/index.ts:120-124](file://server/src/types/index.ts#L120-L124)

## 订单管理流程

### 订单生命周期

```mermaid
stateDiagram-v2
[*] --> Pending : 创建订单
Pending --> Paid : 支付成功
Pending --> Failed : 支付失败
Pending --> Refunded : 退款处理
Paid --> Active : 会员激活
Active --> Expired : 到期
Active --> Cancelled : 取消
Expired --> [*]
Cancelled --> [*]
Failed --> [*]
Refunded --> [*]
```

### 订单状态流转

| 状态 | 描述 | 用途 |
|------|------|------|
| pending | 待支付 | 订单刚创建 |
| paid | 已支付 | 支付成功，等待激活 |
| failed | 支付失败 | 支付异常或取消 |
| refunded | 已退款 | 退款处理完成 |

### 订单数据结构

```mermaid
erDiagram
ORDER {
int id PK
int userId
string orderNo UK
string productType
decimal amount
string status
string paymentMethod
datetime paidAt
datetime createdAt
datetime updatedAt
}
USER {
int id PK
int memberLevel
datetime memberExpireAt
int dailyUsage
string lastUsageDate
}
ORDER ||--|| USER : belongs_to
```

**图表来源**
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)
- [schema.prisma:10-38](file://server/prisma/schema.prisma#L10-L38)

**章节来源**
- [member.service.ts:75-100](file://server/src/modules/member/member.service.ts#L75-L100)
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)

## 支付集成与安全

### 支付方式支持

系统支持多种支付方式，每种支付方式都有相应的集成配置：

```mermaid
graph LR
subgraph "支付方式"
Mock[模拟支付]
Alipay[支付宝]
WeChat[微信支付]
end
subgraph "集成特性"
Mock --> Dev[开发环境]
Alipay --> Production[生产环境]
WeChat --> Production
end
subgraph "安全措施"
Signature[签名验证]
HTTPS[HTTPS传输]
RateLimit[限流保护]
Validation[参数校验]
end
Mock --> Signature
Alipay --> Signature
WeChat --> Signature
```

### 支付回调处理

```mermaid
sequenceDiagram
participant Client as 客户端
participant Alipay as 支付宝
participant Server as 支付服务器
participant Callback as 回调处理
participant Database as 数据库
Client->>Server : 创建支付订单
Server-->>Client : 返回支付链接
Client->>Alipay : 完成支付
Alipay->>Callback : 异步通知
Callback->>Callback : 验证签名
Callback->>Database : 更新订单状态
Callback-->>Alipay : 确认接收
Callback->>Database : 激活会员服务
```

**图表来源**
- [payment.controller.ts:57-95](file://server/src/modules/payment/payment.controller.ts#L57-L95)
- [payment.service.ts:358-406](file://server/src/modules/payment/payment.service.ts#L358-L406)

### 安全措施

系统实施了多层次的安全保护措施：

1. **签名验证**：所有支付回调都进行数字签名验证
2. **HTTPS传输**：确保支付数据在传输过程中的安全性
3. **参数校验**：严格的输入参数验证和过滤
4. **限流保护**：防止恶意请求和攻击
5. **错误处理**：完善的异常捕获和错误处理机制

**章节来源**
- [payment.controller.ts:57-95](file://server/src/modules/payment/payment.controller.ts#L57-L95)
- [payment.service.ts:340-356](file://server/src/modules/payment/payment.service.ts#L340-L356)

## 数据库模型

### 核心数据表结构

```mermaid
erDiagram
User {
int id PK
string phone
string openid
string nickname
string avatar
int memberLevel
datetime memberExpireAt
int dailyUsage
string lastUsageDate
datetime createdAt
datetime updatedAt
}
Order {
int id PK
int userId FK
string orderNo UK
string productType
decimal amount
string status
string paymentMethod
datetime paidAt
datetime createdAt
datetime updatedAt
}
User ||--o{ Order : places
User {
int id PK
int memberLevel
datetime memberExpireAt
int dailyUsage
string lastUsageDate
}
Order {
int id PK
int userId FK
string orderNo UK
string productType
decimal amount
string status
datetime paidAt
}
```

**图表来源**
- [schema.prisma:10-38](file://server/prisma/schema.prisma#L10-L38)
- [schema.prisma:40-61](file://server/prisma/schema.prisma#L40-L61)

### 数据库连接配置

系统使用Prisma ORM进行数据库操作，支持MySQL数据库连接：

```mermaid
flowchart TD
Init[应用启动] --> Connect[建立数据库连接]
Connect --> Test[测试连接可用性]
Test --> Success[连接成功]
Test --> Fail[连接失败]
Success --> Ready[准备就绪]
Fail --> Error[抛出错误]
Ready --> Operations[执行数据库操作]
Operations --> Close[优雅关闭连接]
```

**图表来源**
- [models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)

**章节来源**
- [schema.prisma:10-61](file://server/prisma/schema.prisma#L10-L61)
- [models/index.ts:1-15](file://server/src/models/index.ts#L1-L15)

## 性能与扩展性

### 性能优化策略

系统采用了多项性能优化措施：

1. **连接池管理**：数据库连接池配置，减少连接开销
2. **缓存策略**：Redis缓存常用数据，提高响应速度
3. **异步处理**：支付回调异步处理，避免阻塞主线程
4. **资源复用**：SDK实例复用，减少初始化开销

### 扩展性设计

```mermaid
graph TB
subgraph "水平扩展"
LoadBalancer[负载均衡器]
WebServer1[Web服务器1]
WebServer2[Web服务器2]
WebServerN[Web服务器N]
end
subgraph "垂直扩展"
Database[数据库集群]
Cache[Redis集群]
Storage[对象存储]
end
LoadBalancer --> WebServer1
LoadBalancer --> WebServer2
LoadBalancer --> WebServerN
WebServer1 --> Database
WebServer2 --> Database
WebServerN --> Database
WebServer1 --> Cache
WebServer2 --> Cache
WebServerN --> Cache
```

## 故障排除指南

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

| 问题类型 | 症状 | 可能原因 | 解决方案 |
|----------|------|----------|----------|
| 支付失败 | 订单状态未更新 | 支付回调未到达 | 检查回调URL配置 |
| 会员未激活 | 状态仍为免费版 | 支付状态异常 | 手动同步支付状态 |
| 订单重复 | 同一订单多次创建 | 并发请求导致 | 实现幂等性处理 |
| 支付签名验证失败 | 回调被拒绝 | 密钥配置错误 | 检查支付密钥 |

### 调试工具

系统提供了完善的调试和监控工具：

1. **日志系统**：详细的请求和响应日志
2. **性能监控**：实时监控系统性能指标
3. **错误追踪**：Sentry集成，实时错误监控
4. **数据库监控**：Prisma查询日志

**章节来源**
- [app.ts:64-68](file://server/src/app.ts#L64-L68)
- [payment.controller.ts:57-95](file://server/src/modules/payment/payment.controller.ts#L57-L95)

## 总结

会员服务模块是一个功能完整、架构清晰的付费系统解决方案。通过模块化的设计，系统实现了会员权益管理、订单处理和支付集成的有机结合。

### 核心优势

1. **完整的功能覆盖**：从权益查询到订单创建，再到支付处理形成完整闭环
2. **灵活的支付支持**：支持多种支付方式，满足不同用户需求
3. **完善的安全保障**：多层次的安全措施确保交易安全
4. **良好的扩展性**：模块化设计便于功能扩展和维护

### 技术特点

- 基于Koa.js和TypeScript的企业级开发
- 使用Prisma ORM简化数据库操作
- 支持多种支付方式和第三方集成
- 完善的日志和监控体系

该模块为AI语音应用提供了坚实的付费功能基础，为后续的功能扩展和业务发展奠定了良好基础。