# 业务数据模型

<cite>
**本文引用的文件**
- [schema.prisma](file://server/prisma/schema.prisma)
- [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)
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [auth.service.ts](file://server/src/modules/auth/auth.service.ts)
- [orders 页面](file://my-uniapp-vue3/src/pages/orders/index.vue)
- [支付确认页面](file://my-uniapp-vue3/src/pages/payment-confirm/index.vue)
- [支付结果页面](file://my-uniapp-vue3/src/pages/payment-result/index.vue)
- [会员中心页面](file://my-uniapp-vue3/src/pages/member/index.vue)
- [数据库结构文档](file://docs/database-structure.md)
- [支付集成指南](file://docs/支付集成指南.md)
- [订阅系统使用说明](file://docs/订阅系统使用说明.md)
</cite>

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

## 简介
本文件面向AI有声书生成平台的业务数据模型，聚焦于订单（Order）、订阅（Subscription）、积分余额（TokenBalance）等关键商业实体的数据设计与业务规则。文档从数据模型定义出发，结合订单状态流转、订阅周期管理、使用配额控制等核心业务逻辑，给出支付流程、会员升级、积分消费等典型业务场景的API使用路径与数据流说明，并提供统计分析与报表生成的思路。

## 项目结构
后端采用Prisma进行数据库建模与ORM访问，业务模块分布在server/src/modules下，前端页面位于my-uniapp-vue3/src/pages中。数据库结构与业务模型在schema.prisma中集中定义，支付、订阅、会员等业务通过对应的controller/service层对外提供接口。

```mermaid
graph TB
subgraph "前端"
OrdersPage["订单页面<br/>orders/index.vue"]
PaymentConfirm["支付确认页面<br/>payment-confirm/index.vue"]
PaymentResult["支付结果页面<br/>payment-result/index.vue"]
MemberCenter["会员中心页面<br/>member/index.vue"]
end
subgraph "后端"
AuthCtrl["认证控制器<br/>auth.controller.ts"]
PaymentCtrl["支付控制器<br/>payment.controller.ts"]
SubCtrl["订阅控制器<br/>subscription.controller.ts"]
MemberCtrl["会员控制器<br/>member.controller.ts"]
AuthSvc["认证服务<br/>auth.service.ts"]
PaymentSvc["支付服务<br/>payment.service.ts"]
SubSvc["订阅服务<br/>subscription.service.ts"]
MemberSvc["会员服务<br/>member.service.ts"]
end
OrdersPage --> PaymentCtrl
PaymentConfirm --> PaymentCtrl
PaymentResult --> PaymentCtrl
MemberCenter --> SubCtrl
OrdersPage --> AuthCtrl
PaymentCtrl --> AuthCtrl
SubCtrl --> AuthCtrl
MemberCtrl --> AuthCtrl
PaymentCtrl --> PaymentSvc
SubCtrl --> SubSvc
MemberCtrl --> MemberSvc
AuthCtrl --> AuthSvc
```

**图表来源**
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)
- [orders 页面](file://my-uniapp-vue3/src/pages/orders/index.vue)
- [支付确认页面](file://my-uniapp-vue3/src/pages/payment-confirm/index.vue)
- [支付结果页面](file://my-uniapp-vue3/src/pages/payment-result/index.vue)
- [会员中心页面](file://my-uniapp-vue3/src/pages/member/index.vue)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [auth.controller.ts](file://server/src/modules/auth/auth.controller.ts)

## 核心组件
本节对Order、Subscription、TokenBalance三个核心业务模型进行深入解析，包括字段含义、约束关系、索引策略与业务规则。

- 用户（User）
  - 关键字段：手机号、微信OpenID、会员等级、到期时间、每日用量、上次用量日期、累计音频时长、订阅重置日期等。
  - 与订单、订阅、积分余额、播放记录等存在一对多或一对一关系。
  - 业务规则：会员等级与到期时间决定可用额度；每日用量与上次用量日期用于日配额清零；订阅重置日期用于月度配额重置。

- 订单（Order）
  - 关键字段：订单号唯一、关联用户与可选订阅套餐、金额、状态、支付方式、支付流水号、支付时间等。
  - 业务状态：待支付、已支付、已取消等（默认待支付）。
  - 与订阅套餐（SubscriptionPlan）和用户双向关联；与积分使用（TokenUsage）关联。
  - 索引：按用户+创建时间、订单号、状态、套餐ID建立索引以支持查询与分页。

- 订阅（Subscription）
  - 关键字段：起止日期、状态、自动续费、关联用户与套餐。
  - 状态：激活、暂停、过期、取消等（默认激活）。
  - 与用户、套餐建立外键关系；用于控制用户权限与配额。

- 订阅套餐（SubscriptionPlan）
  - 关键字段：名称、等级、月/年价格、描述、特性、是否推荐、是否启用、排序、日生成次数、单次上限、月度令牌数、月度分钟数、年套餐令牌、超量计费等。
  - 业务规则：等级决定会员等级；月度令牌与分钟数构成月度配额；超量计费用于超出配额的收费。

- 积分余额（TokenBalance）
  - 关键字段：用户唯一、总令牌、已用令牌、重置日期。
  - 业务规则：总令牌=已用令牌+可用令牌；重置日期用于月度配额重置；与TokenUsage记录关联。

- 积分使用（TokenUsage）
  - 关键字段：类型、数量、内容长度、关联订单、描述。
  - 业务规则：记录每次消费的令牌类型与数量，支持按用户与时间维度统计。

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

## 架构总览
下图展示业务数据模型在系统中的位置与交互关系，突出订单、订阅、积分余额三者如何共同支撑支付、会员升级与消费配额控制。

```mermaid
erDiagram
USER ||--o{ ORDER : "拥有"
USER ||--o{ SUBSCRIPTION : "持有"
USER ||--o{ TOKEN_BALANCE : "拥有"
USER ||--o{ TOKEN_USAGE : "产生"
ORDER }o--|| SUBSCRIPTION_PLAN : "对应"
SUBSCRIPTION }o--|| SUBSCRIPTION_PLAN : "基于"
TOKEN_USAGE }o--|| ORDER : "关联"
SUBSCRIPTION_PLAN ||--o{ ORDER : "被购买"
SUBSCRIPTION ||--|| USER : "归属"
TOKEN_BALANCE ||--|| USER : "归属"
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

## 详细组件分析

### 订单模型（Order）
- 数据结构要点
  - 订单号唯一性保证交易幂等与对账。
  - 金额使用Decimal类型确保支付精度。
  - 状态字段默认“待支付”，后续由支付服务更新。
  - 可选planId关联订阅套餐，用于区分一次性购买与订阅购买。

- 业务规则
  - 待支付状态下允许取消并释放配额。
  - 已支付状态下根据planId决定是否创建/续期订阅。
  - 订单与TokenUsage关联，用于记录支付所消耗的令牌。

- 状态流转
```mermaid
stateDiagram-v2
[*] --> 待支付
待支付 --> 已支付 : "支付成功"
待支付 --> 已取消 : "用户取消/超时"
已支付 --> [*]
已取消 --> [*]
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

### 订阅模型（Subscription）
- 数据结构要点
  - 起止日期与状态共同决定订阅有效性。
  - 自动续费标志决定到期后的处理策略。
  - 与SubscriptionPlan的外键关系承载套餐能力与配额。

- 业务规则
  - 订阅到期后状态转为过期或取消，需重新购买或续费。
  - 自动续费开启时，到期前尝试扣费续期。
  - 订阅状态影响用户可用的生成次数、单次上限、月度令牌与分钟数。

- 周期管理
```mermaid
flowchart TD
Start(["开始订阅"]) --> Active["状态=激活"]
Active --> RenewCheck{"到期前检查"}
RenewCheck --> |需要续费| AutoRenew["自动续费尝试"]
RenewCheck --> |无需续费| Active
AutoRenew --> RenewSuccess{"续费成功?"}
RenewSuccess --> |是| Active
RenewSuccess --> |否| Expired["状态=过期"]
Expired --> ManualRenew["手动续费"]
ManualRenew --> Active
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

### 积分余额模型（TokenBalance）
- 数据结构要点
  - 用户唯一索引确保一对一关系。
  - 总令牌与已用令牌构成可用余额计算基础。
  - 重置日期用于月度配额周期化管理。

- 业务规则
  - 消费时从可用余额扣减，记录TokenUsage。
  - 到达重置日期后，根据套餐规则恢复配额。
  - 与订单关联，用于追踪消费来源。

- 配额控制
```mermaid
flowchart TD
Init(["初始化/重置"]) --> Balance["读取用户余额与套餐配额"]
Balance --> Consume{"消费请求?"}
Consume --> |是| Check["校验可用余额>=消费数量"]
Check --> |是| Deduct["扣减已用令牌并写入TokenUsage"]
Check --> |否| Reject["拒绝请求并提示不足"]
Consume --> |否| Wait["等待消费请求"]
Deduct --> Wait
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

## 依赖关系分析
- 订单与订阅
  - 订单可选择订阅套餐，支付完成后创建或续期订阅。
  - 订阅状态变化影响用户可用配额与功能权限。

- 订单与积分
  - 订单支付可能消耗TokenBalance中的令牌，生成TokenUsage记录。
  - TokenUsage与订单建立关联，便于对账与审计。

- 用户与配额
  - 用户的会员等级、到期时间、订阅状态共同决定其可用的生成次数、单次上限、月度令牌与分钟数。

```mermaid
graph LR
Order["订单(Order)"] -- "关联" --> Plan["订阅套餐(SubscriptionPlan)"]
Order -- "关联" --> Usage["积分使用(TokenUsage)"]
Subscription["订阅(Subscription)"] -- "关联" --> Plan
TokenBalance["积分余额(TokenBalance)"] -- "关联" --> User["用户(User)"]
Order -- "关联" --> User
Subscription -- "关联" --> User
```

**图表来源**
- [schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [schema.prisma](file://server/prisma/schema.prisma)

## 性能考虑
- 索引策略
  - 订单：按用户+创建时间、订单号、状态、套餐ID建立索引，支持高效分页与筛选。
  - 订阅：按用户+状态、用户+到期时间建立索引，支持到期扫描与状态变更。
  - 积分：按用户+创建时间、用户+类型建立索引，支持消费统计与报表。

- 查询优化
  - 使用分页查询避免一次性加载大量订单与订阅记录。
  - 对高频统计字段（如月度令牌、分钟数）建立物化视图或缓存，减少重复计算。

- 写入优化
  - 批量插入TokenUsage与批量更新用户配额，降低事务开销。
  - 异步处理订阅到期与自动续费，避免阻塞主流程。

## 故障排除指南
- 订单状态异常
  - 现象：订单显示“待支付”但用户无法发起支付。
  - 排查：检查支付回调是否正确更新状态；核对支付渠道返回信息与订单金额一致性。

- 订阅未生效
  - 现象：支付成功但用户仍无高级权限。
  - 排查：确认订单状态已更新为“已支付”；检查订阅创建逻辑是否执行；验证套餐等级与用户等级匹配。

- 积分不足
  - 现象：生成失败提示余额不足。
  - 排查：核对TokenBalance可用余额与TokenUsage消费明细；检查重置日期是否导致配额回退。

**章节来源**
- [支付集成指南](file://docs/支付集成指南.md)
- [订阅系统使用说明](file://docs/订阅系统使用说明.md)

## 结论
本文档基于Prisma schema定义，系统梳理了订单、订阅、积分余额三大业务模型的数据结构与业务规则，明确了状态流转、周期管理与配额控制的关键实现点，并给出了支付流程、会员升级、积分消费等场景的API使用路径与数据流图。建议在生产环境中配合完善的索引策略、异步任务与监控告警，确保订单支付、订阅续费与积分消费的稳定性与可扩展性。

## 附录

### API使用示例（路径指引）
- 订单管理
  - 创建订单：前端调用后端支付控制器创建订单接口，传入用户标识、套餐ID与金额。
  - 查询订单列表：按用户ID与状态分页查询，支持筛选时间范围。
  - 取消订单：仅限“待支付”状态，调用取消接口并释放相关配额。

- 订阅服务
  - 会员升级：用户选择订阅套餐后创建订单，支付成功后创建/续期订阅。
  - 自动续费：到期前触发续费任务，成功则延长有效期，失败则标记为过期。

- 积分消费
  - 生成音频：根据内容长度计算所需令牌，检查TokenBalance后扣减并记录TokenUsage。
  - 报表统计：按用户、时间、类型聚合TokenUsage，生成消费报表。

- 前端页面参考
  - 订单页面：展示用户历史订单与状态，支持查看详情与再次购买。
  - 支付确认/结果页面：展示支付金额、优惠信息与支付状态反馈。
  - 会员中心页面：展示当前订阅状态、到期时间与升级入口。

**章节来源**
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [subscription.controller.ts](file://server/src/modules/subscription/subscription.controller.ts)
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [orders 页面](file://my-uniapp-vue3/src/pages/orders/index.vue)
- [支付确认页面](file://my-uniapp-vue3/src/pages/payment-confirm/index.vue)
- [支付结果页面](file://my-uniapp-vue3/src/pages/payment-result/index.vue)
- [会员中心页面](file://my-uniapp-vue3/src/pages/member/index.vue)