audio_codebuddy/.qoder/repowiki/zh/content/数据库设计/业务数据模型/订单与积分模型.md

订单与积分模型

本文引用的文件

• schema.prisma
• models.json
• models-validator.ts
• payment.controller.ts
• payment.service.ts
• member.controller.ts
• member.service.ts
• tts.controller.ts
• tts.service.ts
• orders/index.vue
• member/index.vue
• API.md
• 数据库结构.md

目录

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

简介

本文件面向AI有声书生成平台的订单与积分模型，系统性阐述以下内容：

• 订单模型（Order）与积分相关实体（TokenBalance、TokenUsage）的结构与关联
• 订单状态流转、支付方式、金额计算等订单管理功能的数据结构与流程
• 积分余额的获取规则、使用限制、重置机制等积分系统的实现要点
• 购买套餐、语音合成消费、积分充值等业务场景的API使用示例
• 订单统计报表与积分流水分析的实现思路

本文件严格基于仓库中的实际代码与文档进行分析，避免臆测。

项目结构

围绕订单与积分模型，后端主要涉及以下模块与配置：

• 数据模型定义：Prisma Schema、模型配置与校验
• 订单与支付模块：payment.controller.ts、payment.service.ts
• 会员与积分模块：member.controller.ts、member.service.ts
• TTS服务：tts.controller.ts、tts.service.ts（用于语音合成消费）
• 前端页面：订单列表页、会员中心页

• 文档：API规范、数据库结构说明

  graph TB
  subgraph "前端"
  OrdersPage["订单页面<br/>orders/index.vue"]
  MemberPage["会员页面<br/>member/index.vue"]
  end
  subgraph "后端"
  PaymentCtrl["支付控制器<br/>payment.controller.ts"]
  PaymentSvc["支付服务<br/>payment.service.ts"]
  MemberCtrl["会员控制器<br/>member.controller.ts"]
  MemberSvc["会员服务<br/>member.service.ts"]
  TTSCtrl["TTS控制器<br/>tts.controller.ts"]
  TTSSvc["TTS服务<br/>tts.service.ts"]
  end
  subgraph "数据层"
  PrismaSchema["Prisma Schema<br/>schema.prisma"]
  ModelsCfg["模型配置<br/>models.json"]
  ModelsValidator["模型校验<br/>models-validator.ts"]
  end
  OrdersPage --> PaymentCtrl
  OrdersPage --> MemberCtrl
  MemberPage --> MemberCtrl
  PaymentCtrl --> PaymentSvc
  MemberCtrl --> MemberSvc
  TTSCtrl --> TTSSvc
  PaymentSvc --> PrismaSchema
  MemberSvc --> PrismaSchema
  TTSSvc --> PrismaSchema
  PaymentSvc --> ModelsCfg
  MemberSvc --> ModelsCfg
  TTSSvc --> ModelsCfg
  PaymentSvc --> ModelsValidator
  MemberSvc --> ModelsValidator
  TTSSvc --> ModelsValidator
  

图表来源

• payment.controller.ts
• payment.service.ts
• member.controller.ts
• member.service.ts
• tts.controller.ts
• tts.service.ts
• schema.prisma
• models.json
• models-validator.ts

章节来源

• schema.prisma
• models.json
• models-validator.ts
• payment.controller.ts
• payment.service.ts
• member.controller.ts
• member.service.ts
• tts.controller.ts
• tts.service.ts
• orders/index.vue
• member/index.vue

核心组件

本节从数据模型与业务服务两个维度，梳理订单与积分的核心组件。

• 订单模型（Order）

  • 关键字段：用户标识、商品/套餐信息、应付金额、实付金额、币种、支付渠道、订单状态、扩展信息等
  • 状态：如待支付、已支付、已取消、已完成等
  • 金额计算：原价折扣、优惠券、积分抵扣、实付金额等
  • 关联：与用户、套餐、支付记录、积分流水存在多对多或一对多关系

• 积分余额模型（TokenBalance）

  • 关键字段：用户标识、可用积分、冻结积分、总获取、总消耗、统计周期等
  • 获取规则：购买套餐赠送、签到奖励、活动奖励等
  • 使用限制：抵扣比例、单次上限、有效期、不可透支等
  • 重置机制：按自然月/季度/年重置，或按活动周期清零

• 积分流水模型（TokenUsage）

  • 关键字段：用户标识、流水类型（收入/支出）、变动数量、剩余余额、关联单据、备注、时间戳等
  • 类型：购买套餐、语音合成消费、退款回退、活动发放、过期回收等

• 订单管理服务（Payment Service）

  • 职责：创建订单、发起支付、回调处理、状态更新、异常处理
  • 支付方式：微信支付、支付宝等（以配置为准）

• 会员与积分服务（Member Service）

  • 职责：查询余额、变更余额、生成流水、执行重置策略、风控校验

• 语音合成消费（TTS Service）

  • 职责：调用TTS服务、根据字数/时长计费、扣减积分、记录流水

章节来源

• schema.prisma
• models.json
• models-validator.ts
• payment.service.ts
• member.service.ts
• tts.service.ts

架构总览

下图展示订单与积分在系统中的交互关系与数据流：

sequenceDiagram
participant Client as "客户端"
participant OrdersUI as "订单页面<br/>orders/index.vue"
participant MemberUI as "会员页面<br/>member/index.vue"
participant PaymentCtrl as "支付控制器"
participant PaymentSvc as "支付服务"
participant MemberSvc as "会员服务"
participant TTSSvc as "TTS服务"
participant DB as "数据库"
Client->>OrdersUI : 打开订单列表
OrdersUI->>PaymentCtrl : 查询订单列表
PaymentCtrl->>PaymentSvc : 订单查询
PaymentSvc->>DB : 读取订单表
DB-->>PaymentSvc : 订单数据
PaymentSvc-->>PaymentCtrl : 返回结果
PaymentCtrl-->>OrdersUI : 渲染订单
Client->>MemberUI : 查看积分与充值
MemberUI->>MemberSvc : 查询余额/流水
MemberSvc->>DB : 读取余额与流水
DB-->>MemberSvc : 结果
MemberSvc-->>MemberUI : 展示
Client->>TTSSvc : 发起语音合成
TTSSvc->>TTSSvc : 计算消耗
TTSSvc->>MemberSvc : 扣减积分
MemberSvc->>DB : 更新余额/写入流水
DB-->>MemberSvc : 成功
MemberSvc-->>TTSSvc : 扣减成功
TTSSvc-->>Client : 合成结果

图表来源

• orders/index.vue
• member/index.vue
• payment.controller.ts
• payment.service.ts
• member.controller.ts
• member.service.ts
• tts.controller.ts
• tts.service.ts

详细组件分析

订单模型（Order）与状态流转

• 数据结构要点
  • 用户标识、商品/套餐标识、数量、单价、优惠信息、应付/实付金额、币种
  • 支付渠道、支付单号、回调时间、扩展字段
  • 订单状态：待支付、已支付、已取消、已完成、部分退款、已关闭等
• 状态流转
  • 创建订单 → 待支付
  • 支付成功 → 已支付
  • 支付失败/超时 → 已取消
  • 完成服务 → 已完成
  • 部分退款 → 部分退款

• 金额计算

  • 原价 × 数量
  • 优惠券/折扣/积分抵扣后的实付金额

  • 回调时以第三方返回为准，确保幂等更新

    stateDiagram-v2
    [*] --> 待支付
    待支付 --> 已支付 : "支付成功"
    待支付 --> 已取消 : "支付失败/超时"
    已支付 --> 已完成 : "服务完成"
    已支付 --> 部分退款 : "部分退款"
    已支付 --> 已取消 : "主动取消"
    已完成 --> [*]
    部分退款 --> 已完成 : "剩余完成"
    已取消 --> [*]
    

图表来源

• payment.service.ts
• schema.prisma

章节来源

• payment.service.ts
• schema.prisma

积分余额模型（TokenBalance）与流水（TokenUsage）

• TokenBalance
  • 字段：用户标识、可用积分、冻结积分、总获取、总消耗、统计周期、更新时间
  • 规则：可用积分 ≥ 0；冻结积分用于预占但不参与抵扣；周期性重置由策略控制
• TokenUsage
  • 字段：用户标识、流水类型（收入/支出）、变动数量、剩余余额、关联单据、备注、时间戳
  • 类型：购买套餐（收入）、语音合成消费（支出）、退款回退（收入）、活动发放（收入）、过期回收（支出）
• 获取与使用
  • 获取：购买套餐赠送、签到奖励、活动奖励、任务奖励等
  • 使用：抵扣订单金额（需满足最低抵扣、单次上限、有效期等）
  • 冻结与解冻：消费预占（冻结），完成后转可用或按规则回收

• 重置机制

  • 自然月/季度/年重置：到期未使用的积分清零并记录流水

  • 活动周期：活动结束后统一清零并记录

    flowchart TD
    Start(["开始"]) --> GetRule["获取积分规则"]
    GetRule --> Income{"是否收入类？"}
    Income --> |是| AddBalance["增加可用积分/累计获取"]
    Income --> |否| Deduct{"是否可抵扣？"}
    Deduct --> |是| Freeze["预占积分冻结"]
    Freeze --> Consume["实际消费完成"]
    Consume --> Unfreeze["转为可用积分"]
    Deduct --> |否| Record["记录流水但不扣减"]
    AddBalance --> Save["保存余额"]
    Unfreeze --> Save
    Record --> Save
    Save --> End(["结束"])
    

图表来源

• member.service.ts
• schema.prisma

章节来源

• member.service.ts
• schema.prisma

订单管理服务（Payment Service）

• 职责
  • 接收前端请求，构造订单参数
  • 调用支付渠道发起支付
  • 处理回调，更新订单状态与积分流水
  • 幂等处理，保证一致性
• 支付方式
  • 微信支付、支付宝等（以配置与第三方对接为准）

• 金额与风控

  • 实付金额校验、最小/最大限额、重复支付拦截

    sequenceDiagram
    participant Client as "客户端"
    participant Ctrl as "支付控制器"
    participant Svc as "支付服务"
    participant Pay as "支付渠道"
    participant DB as "数据库"
    Client->>Ctrl : 提交下单请求
    Ctrl->>Svc : 创建订单并发起支付
    Svc->>DB : 写入订单
    Svc->>Pay : 发起支付
    Pay-->>Svc : 支付结果
    Svc->>DB : 更新订单状态/金额
    Svc-->>Ctrl : 返回结果
    Ctrl-->>Client : 订单状态
    

图表来源

• payment.controller.ts
• payment.service.ts

章节来源

• payment.controller.ts
• payment.service.ts

语音合成消费（TTS Service）

• 职责
  • 计算合成消耗（字数/时长/模型系数）
  • 扣减积分并记录流水
  • 失败回滚（恢复冻结积分）

• 与订单的关系

  • 可作为“套餐内资源”的使用，也可独立计费

  • 若来自订单，则与订单状态联动（如完成/退款）

    sequenceDiagram
    participant Client as "客户端"
    participant TTSCtrl as "TTS控制器"
    participant TTSSvc as "TTS服务"
    participant MemberSvc as "会员服务"
    participant DB as "数据库"
    Client->>TTSCtrl : 发起合成
    TTSCtrl->>TTSSvc : 计算消耗
    TTSSvc->>MemberSvc : 扣减积分
    MemberSvc->>DB : 写入流水/更新余额
    DB-->>MemberSvc : 成功
    MemberSvc-->>TTSSvc : 扣减成功
    TTSSvc-->>Client : 合成结果
    

图表来源

• tts.controller.ts
• tts.service.ts
• member.service.ts

章节来源

• tts.controller.ts
• tts.service.ts
• member.service.ts

前端页面与交互

• 订单页面（orders/index.vue）
  • 展示订单列表、状态筛选、查看详情、再次购买
• 会员页面（member/index.vue）
  • 展示积分余额、流水明细、充值入口、规则说明

章节来源

• orders/index.vue
• member/index.vue

依赖分析

• 组件耦合
  • Payment Service 依赖 Member Service（积分抵扣/流水）、数据库（订单与流水）
  • Member Service 依赖数据库（余额与流水）、配置（规则与重置策略）
  • TTS Service 依赖 Member Service（扣减积分）、数据库（流水）
• 外部依赖
  • 支付渠道SDK（微信/支付宝）
  • 第三方回调签名验证

• 潜在风险

  • 幂等性：支付回调与主动查询需保证重复处理不重复计费
  • 一致性：积分扣减与订单状态需事务性保障

  • 性能：高并发下积分与订单的读写锁竞争

    graph LR
    PaymentSvc["支付服务"] --> MemberSvc["会员服务"]
    PaymentSvc --> DB["数据库"]
    MemberSvc --> DB
    TTSSvc["TTS服务"] --> MemberSvc
    TTSSvc --> DB
    PaymentCtrl["支付控制器"] --> PaymentSvc
    MemberCtrl["会员控制器"] --> MemberSvc
    TTSCtrl["TTS控制器"] --> TTSSvc
    

图表来源

• payment.service.ts
• member.service.ts
• tts.service.ts

章节来源

• payment.service.ts
• member.service.ts
• tts.service.ts

性能考虑

• 读写分离与缓存
  • 订单与积分查询高频，可引入Redis缓存热点数据
• 批量操作
  • 支付回调批处理、积分重置批量执行
• 幂等设计
  • 回调接口通过订单号+支付单号去重
• 分库分表
  • 订单与流水按时间分区，提升查询效率

故障排除指南

• 订单状态异常
  • 现象：支付成功但订单仍为待支付
  • 排查：检查回调签名、幂等逻辑、数据库事务
• 积分扣减失败
  • 现象：语音合成失败但积分被扣
  • 排查：确认扣减前置条件、异常回滚、流水记录
• 重复支付
  • 现象：同一订单多次扣款
  • 排查：幂等键设计、回调去重、数据库唯一约束
• 重置未生效
  • 现象：周期末积分未清零
  • 排查：重置任务调度、边界日期处理、日志审计

章节来源

• payment.service.ts
• member.service.ts
• tts.service.ts

结论

本文件基于仓库现有代码与文档，系统化梳理了AI有声书平台的订单与积分模型。通过明确数据结构、状态流转、服务职责与交互流程，为后续扩展（如更多支付渠道、复杂积分规则、报表分析）提供了清晰的参考路径。建议在生产环境中进一步完善幂等与一致性保障，并持续优化性能与可观测性。

附录

API使用示例（基于现有API文档）

• 订单相关
  • 创建订单：提交商品/套餐信息与支付方式，返回订单号与支付参数
  • 查询订单：按用户与状态筛选，支持分页
  • 支付回调：接收第三方回调，更新订单状态
• 会员与积分
  • 查询余额：返回可用/冻结积分与累计值
  • 积分流水：按类型与时间范围查询
  • 兑换/充值：提交充值金额或兑换申请
• TTS消费
  • 发起合成：传入文本与参数，返回结果与消耗积分

章节来源

• API.md

数据模型概览（基于Prisma Schema）

• 订单表：包含用户标识、商品/套餐、金额、状态、支付信息等
• 积分余额表：包含用户标识、可用/冻结积分、累计获取/消耗、周期等
• 积分流水表：包含用户标识、流水类型、变动数量、剩余余额、关联单据等

章节来源

• schema.prisma
• 数据库结构.md