# 订单与积分模型

<cite>
**本文引用的文件**
- [schema.prisma](file://server/prisma/schema.prisma)
- [models.json](file://server/src/config/models.json)
- [models-validator.ts](file://server/src/config/models-validator.ts)
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [orders/index.vue](file://my-uniapp-vue3/src/pages/orders/index.vue)
- [member/index.vue](file://my-uniapp-vue3/src/pages/member/index.vue)
- [API.md](file://docs/API.md)
- [数据库结构.md](file://docs/数据库结构.md)
</cite>

## 目录
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规范、数据库结构说明

```mermaid
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](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)
- [models.json](file://server/src/config/models.json)
- [models-validator.ts](file://server/src/config/models-validator.ts)

章节来源
- [schema.prisma](file://server/prisma/schema.prisma)
- [models.json](file://server/src/config/models.json)
- [models-validator.ts](file://server/src/config/models-validator.ts)
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [orders/index.vue](file://my-uniapp-vue3/src/pages/orders/index.vue)
- [member/index.vue](file://my-uniapp-vue3/src/pages/member/index.vue)

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

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

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

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

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

- 会员与积分服务（Member Service）
  - 职责：查询余额、变更余额、生成流水、执行重置策略、风控校验

- 语音合成消费（TTS Service）
  - 职责：调用TTS服务、根据字数/时长计费、扣减积分、记录流水

章节来源
- [schema.prisma](file://server/prisma/schema.prisma)
- [models.json](file://server/src/config/models.json)
- [models-validator.ts](file://server/src/config/models-validator.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)

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

```mermaid
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](file://my-uniapp-vue3/src/pages/orders/index.vue)
- [member/index.vue](file://my-uniapp-vue3/src/pages/member/index.vue)
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [member.controller.ts](file://server/src/modules/member/member.controller.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)

## 详细组件分析

### 订单模型（Order）与状态流转
- 数据结构要点
  - 用户标识、商品/套餐标识、数量、单价、优惠信息、应付/实付金额、币种
  - 支付渠道、支付单号、回调时间、扩展字段
  - 订单状态：待支付、已支付、已取消、已完成、部分退款、已关闭等
- 状态流转
  - 创建订单 → 待支付
  - 支付成功 → 已支付
  - 支付失败/超时 → 已取消
  - 完成服务 → 已完成
  - 部分退款 → 部分退款
- 金额计算
  - 原价 × 数量
  - 优惠券/折扣/积分抵扣后的实付金额
  - 回调时以第三方返回为准，确保幂等更新

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

图表来源
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)

章节来源
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)

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

```mermaid
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](file://server/src/modules/member/member.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)

章节来源
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [schema.prisma](file://server/prisma/schema.prisma)

### 订单管理服务（Payment Service）
- 职责
  - 接收前端请求，构造订单参数
  - 调用支付渠道发起支付
  - 处理回调，更新订单状态与积分流水
  - 幂等处理，保证一致性
- 支付方式
  - 微信支付、支付宝等（以配置与第三方对接为准）
- 金额与风控
  - 实付金额校验、最小/最大限额、重复支付拦截

```mermaid
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](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)

章节来源
- [payment.controller.ts](file://server/src/modules/payment/payment.controller.ts)
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)

### 语音合成消费（TTS Service）
- 职责
  - 计算合成消耗（字数/时长/模型系数）
  - 扣减积分并记录流水
  - 失败回滚（恢复冻结积分）
- 与订单的关系
  - 可作为“套餐内资源”的使用，也可独立计费
  - 若来自订单，则与订单状态联动（如完成/退款）

```mermaid
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](file://server/src/modules/tts/tts.controller.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)

章节来源
- [tts.controller.ts](file://server/src/modules/tts/tts.controller.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)

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

章节来源
- [orders/index.vue](file://my-uniapp-vue3/src/pages/orders/index.vue)
- [member/index.vue](file://my-uniapp-vue3/src/pages/member/index.vue)

## 依赖分析
- 组件耦合
  - Payment Service 依赖 Member Service（积分抵扣/流水）、数据库（订单与流水）
  - Member Service 依赖数据库（余额与流水）、配置（规则与重置策略）
  - TTS Service 依赖 Member Service（扣减积分）、数据库（流水）
- 外部依赖
  - 支付渠道SDK（微信/支付宝）
  - 第三方回调签名验证
- 潜在风险
  - 幂等性：支付回调与主动查询需保证重复处理不重复计费
  - 一致性：积分扣减与订单状态需事务性保障
  - 性能：高并发下积分与订单的读写锁竞争

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

图表来源
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)

章节来源
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)

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

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

章节来源
- [payment.service.ts](file://server/src/modules/payment/payment.service.ts)
- [member.service.ts](file://server/src/modules/member/member.service.ts)
- [tts.service.ts](file://server/src/modules/tts/tts.service.ts)

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

## 附录

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

章节来源
- [API.md](file://docs/API.md)

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

章节来源
- [schema.prisma](file://server/prisma/schema.prisma)
- [数据库结构.md](file://docs/数据库结构.md)