会员服务API

本文档引用的文件

member.controller.ts
member.service.ts
payment.controller.ts
payment.service.ts
subscription.controller.ts
subscription.service.ts
types/index.ts
models/index.ts
app.ts
schema.prisma
支付集成指南.md
订阅系统使用说明.md
API.md

项目概述

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

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

核心组件架构

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
member.controller.ts:1-90
payment.controller.ts:1-258

会员权益接口

接口定义

GET /api/member/benefits

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

请求参数

无需请求参数

响应数据结构

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

权益数据详情

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
types/index.ts:114-124

响应示例

{
  "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
member.service.ts:10-37

会员状态接口

接口定义

GET /api/member/status

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

请求参数

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

响应数据结构

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

状态数据详情

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

响应示例

{
  "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
member.service.ts:39-73

订单创建接口

接口定义

POST /api/member/order

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

请求参数

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

响应数据结构

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

订单创建流程

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
member.service.ts:75-100

响应示例

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

章节来源

member.controller.ts:32-48
member.service.ts:75-100

支付订单接口

接口定义

POST /api/member/pay/mock

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

请求参数

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

响应数据结构

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

支付处理流程

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
member.service.ts:102-155

响应示例

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

章节来源

member.controller.ts:50-70
member.service.ts:102-155

会员等级与权益体系

等级定义

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

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
types/index.ts:120-124

权益差异

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

升级条件

会员升级遵循以下规则：

同级续费：现有会员可在到期前进行续费
跨级升级：可选择升级到更高等级，按差价收费
自动续费：支持设置自动续费功能
有效期计算：续费时按剩余有效期顺延计算

章节来源

member.service.ts:10-37
types/index.ts:120-124

订单管理流程

订单生命周期

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

订单状态流转

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

订单数据结构

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
schema.prisma:10-38

章节来源

member.service.ts:75-100
schema.prisma:40-61

支付集成与安全

支付方式支持

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

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

支付回调处理

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
payment.service.ts:358-406

安全措施

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

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

章节来源

payment.controller.ts:57-95
payment.service.ts:340-356

数据库模型

核心数据表结构

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
schema.prisma:40-61

数据库连接配置

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

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

图表来源

models/index.ts:1-15

章节来源

schema.prisma:10-61
models/index.ts:1-15

性能与扩展性

性能优化策略

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

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

扩展性设计

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配置
会员未激活	状态仍为免费版	支付状态异常	手动同步支付状态
订单重复	同一订单多次创建	并发请求导致	实现幂等性处理
支付签名验证失败	回调被拒绝	密钥配置错误	检查支付密钥

调试工具

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

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

章节来源

app.ts:64-68
payment.controller.ts:57-95

总结

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

核心优势

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

技术特点

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

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

会员服务API.md 20 KB Link permanente Histórico Raw

会员服务API

目录

项目概述

核心组件架构

会员权益接口

接口定义

请求参数

响应数据结构

权益数据详情

响应示例

会员状态接口

接口定义

请求参数

响应数据结构

状态数据详情

响应示例

订单创建接口

接口定义

请求参数

响应数据结构

订单创建流程

响应示例

支付订单接口

接口定义

请求参数

响应数据结构

支付处理流程

响应示例

会员等级与权益体系

等级定义

权益差异

升级条件

订单管理流程

订单生命周期

订单状态流转

订单数据结构

支付集成与安全

支付方式支持

支付回调处理

安全措施

数据库模型

核心数据表结构

数据库连接配置

性能与扩展性

性能优化策略

扩展性设计

故障排除指南

常见问题及解决方案

调试工具

总结

核心优势

技术特点

会员服务API.md 20 KB

Link permanente Histórico Raw