audio_codebuddy/.qoder/repowiki/zh/content/数据库设计/业务数据模型/业务数据模型.md

业务数据模型

本文引用的文件

• schema.prisma
• payment.controller.ts
• payment.service.ts
• subscription.controller.ts
• subscription.service.ts
• member.controller.ts
• member.service.ts
• auth.controller.ts
• auth.service.ts
• orders 页面
• 支付确认页面
• 支付结果页面
• 会员中心页面
• 数据库结构文档
• 支付集成指南
• 订阅系统使用说明

目录

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层对外提供接口。

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
• subscription.controller.ts
• member.controller.ts
• auth.controller.ts
• orders 页面
• 支付确认页面
• 支付结果页面
• 会员中心页面

章节来源

• schema.prisma
• payment.controller.ts
• subscription.controller.ts
• member.controller.ts
• auth.controller.ts

核心组件

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

• 用户（User）

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

• 订单（Order）

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

• 订阅（Subscription）

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

• 订阅套餐（SubscriptionPlan）

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

• 积分余额（TokenBalance）

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

• 积分使用（TokenUsage）

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

章节来源

• schema.prisma

架构总览

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

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

详细组件分析

订单模型（Order）

• 数据结构要点

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

• 业务规则

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

• 状态流转

  stateDiagram-v2
  [*] --> 待支付
  待支付 --> 已支付 : "支付成功"
  待支付 --> 已取消 : "用户取消/超时"
  已支付 --> [*]
  已取消 --> [*]
  

图表来源

• schema.prisma

章节来源

• schema.prisma

订阅模型（Subscription）

• 数据结构要点

  • 起止日期与状态共同决定订阅有效性。
  • 自动续费标志决定到期后的处理策略。
  • 与SubscriptionPlan的外键关系承载套餐能力与配额。

• 业务规则

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

• 周期管理

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

图表来源

• schema.prisma

章节来源

• schema.prisma

积分余额模型（TokenBalance）

• 数据结构要点

  • 用户唯一索引确保一对一关系。
  • 总令牌与已用令牌构成可用余额计算基础。
  • 重置日期用于月度配额周期化管理。

• 业务规则

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

• 配额控制

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

图表来源

• schema.prisma

章节来源

• schema.prisma

依赖关系分析

• 订单与订阅

  • 订单可选择订阅套餐，支付完成后创建或续期订阅。
  • 订阅状态变化影响用户可用配额与功能权限。

• 订单与积分

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

• 用户与配额

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

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

图表来源

• schema.prisma

章节来源

• schema.prisma

性能考虑

• 索引策略

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

• 查询优化

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

• 写入优化

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

故障排除指南

• 订单状态异常

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

• 订阅未生效

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

• 积分不足

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

章节来源

• 支付集成指南
• 订阅系统使用说明

结论

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

附录

API使用示例（路径指引）

• 订单管理

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

• 订阅服务

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

• 积分消费

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

• 前端页面参考

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

章节来源

• payment.controller.ts
• subscription.controller.ts
• member.controller.ts
• orders 页面
• 支付确认页面
• 支付结果页面
• 会员中心页面