# 使用统计

<cite>
**本文引用的文件**
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [server/prisma/migrations/20260422105352_add_content_status/migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/src/modules/tts/tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [server/src/types/index.ts](file://server/src/types/index.ts)
- [my-uniapp-vue3/src/pages/logs/index.vue](file://my-uniapp-vue3/src/pages/logs/index.vue)
</cite>

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

## 简介
本文件面向“使用统计系统”的数据文档，聚焦以下目标：
- 使用量统计机制：Token消耗记录、音频生成时长统计、功能使用频率分析
- 数据收集与存储策略：实时更新、批量处理、历史归档
- 统计报表能力：日/周/月趋势、用户行为分析、收入统计
- 指标计算方法：平均使用量、峰值分析、预测模型
- 统计查询接口：时间范围筛选、用户维度分析、导出功能
- 统计数据的API与可视化展示方案

在当前代码库中，统计相关的关键实现集中在订阅与用量模块、Token使用记录表、TTS生成流程以及性能监控中间件等位置。

## 项目结构
围绕使用统计的核心文件分布如下：
- 订阅与用量服务：负责音频时长配额、费用计算、用量扣减与记录
- 数据模型：TokenUsage 表用于记录各类使用明细
- 中间件：使用限制中间件与性能监控中间件
- TTS 服务：音频生成流程中的时长与状态记录
- 前端日志页面：展示请求统计与错误分析

```mermaid
graph TB
subgraph "后端"
A["订阅与用量服务<br/>subscription.service.ts"]
B["中间件<br/>usageLimit.ts / performance.ts"]
C["数据模型<br/>schema.prisma / migration.sql"]
D["TTS 服务<br/>tts.service.ts"]
end
subgraph "前端"
E["日志与统计页面<br/>logs/index.vue"]
end
E --> |"API 调用"| A
A --> |"读写"| C
D --> |"生成完成更新状态/时长"| C
B --> |"限流/配额校验"| A
```

**图表来源**
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [server/prisma/migrations/20260422105352_add_content_status/migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)
- [server/src/modules/tts/tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [my-uniapp-vue3/src/pages/logs/index.vue](file://my-uniapp-vue3/src/pages/logs/index.vue)

**章节来源**
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [server/prisma/migrations/20260422105352_add_content_status/migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/src/modules/tts/tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [my-uniapp-vue3/src/pages/logs/index.vue](file://my-uniapp-vue3/src/pages/logs/index.vue)

## 核心组件
- Token 使用记录与余额管理
  - TokenUsage 表记录每次使用类型、数量、内容长度、关联订单与创建时间
  - 提供消费与查询接口，支持分页与排序
- 音频生成时长统计与配额
  - 基于文本长度估算音频时长，结合会员等级与月度配额进行扣减与记录
  - 支持预估生成费用、检查配额、动态重置配额
- 使用限制中间件
  - 按用户每日使用次数与字数限制进行校验，支持免费/付费会员差异化配额
- 性能监控中间件
  - 统计总请求、平均响应时间、慢请求、错误数及端点级指标
- TTS 生成流程
  - 生成完成后回写音频时长、状态，并触发后续业务动作
- 前端日志与统计页面
  - 展示请求总量、错误数、警告数、平均响应时间等基础统计

**章节来源**
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [server/prisma/migrations/20260422105352_add_content_status/migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/src/modules/tts/tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [my-uniapp-vue3/src/pages/logs/index.vue](file://my-uniapp-vue3/src/pages/logs/index.vue)

## 架构总览
使用统计系统的整体交互流程如下：

```mermaid
sequenceDiagram
participant Client as "客户端"
participant Logs as "日志统计页面<br/>logs/index.vue"
participant API as "订阅服务<br/>subscription.service.ts"
participant DB as "数据库<br/>TokenUsage/用户表"
participant Perf as "性能中间件<br/>performance.ts"
Client->>Logs : 打开日志统计页
Logs->>API : GET /api/logs/stats
API->>DB : 查询统计聚合
DB-->>API : 返回统计结果
API-->>Logs : 返回统计数据
Logs-->>Client : 展示统计卡片
Client->>API : POST /api/tts/generate
API->>Perf : 记录请求开始
API->>DB : 写入TokenUsage/更新用户用量
API-->>Client : 返回生成任务信息
API->>DB : 生成完成后更新音频时长/状态
```

**图表来源**
- [my-uniapp-vue3/src/pages/logs/index.vue](file://my-uniapp-vue3/src/pages/logs/index.vue)
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)

## 详细组件分析

### 组件A：Token 使用记录与余额管理
- 数据模型
  - TokenUsage 表包含用户ID、类型、数量、内容长度、订单关联、创建时间等字段，并建立索引以支持按用户与时间检索
- 主要功能
  - 消耗Token：校验余额、更新余额、记录使用明细
  - 查询Token使用列表：分页、排序、总数统计
- 关键实现位置
  - Token 使用记录与查询接口
  - Token 余额与消费逻辑

```mermaid
erDiagram
TOKEN_USAGE {
int id PK
int userId
string type
int amount
int contentLength
int orderId
datetime createdAt
}
USER {
int id PK
int usedAudioMinutes
datetime subscriptionResetDate
}
ORDER {
int id PK
}
USER ||--o{ TOKEN_USAGE : "拥有"
ORDER ||--o{ TOKEN_USAGE : "关联"
```

**图表来源**
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [server/prisma/migrations/20260422105352_add_content_status/migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)

**章节来源**
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [server/prisma/migrations/20260422105352_add_content_status/migration.sql](file://server/prisma/migrations/20260422105352_add_content_status/migration.sql)
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)

### 组件B：音频生成时长统计与配额
- 时长估算与费用计算
  - 基于文本长度估算音频时长，结合会员等级与月度配额计算配额内/超额分钟数与价格
  - 支持预估生成费用、检查配额、动态重置配额（每月1日）
- 用量扣减与记录
  - 生成完成后更新用户已用时长，并记录一条类型为“audio_generation”的Token使用记录
- 关键实现位置
  - 音频时长估算与费用计算
  - 配额检查与用量扣减
  - Token 使用记录创建

```mermaid
flowchart TD
Start(["开始：收到生成请求"]) --> Estimate["估算音频时长"]
Estimate --> CheckQuota["检查月度配额与超额策略"]
CheckQuota --> |不足且不允许超额| Deny["拒绝生成并返回原因"]
CheckQuota --> |允许或在配额内| Consume["扣除音频时长并记录Token使用"]
Consume --> UpdateUser["更新用户usedAudioMinutes"]
UpdateUser --> Log["写入TokenUsage记录"]
Log --> End(["结束"])
```

**图表来源**
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)

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

### 组件C：使用限制中间件
- 功能概述
  - 根据用户会员等级设置每日使用次数与字数限制
  - 自动重置每日使用次数，防止超限
- 关键实现位置
  - 使用次数与字数限制检查
  - 每日重置逻辑

```mermaid
flowchart TD
Enter(["进入请求"]) --> GetUserId["获取用户ID"]
GetUserId --> |未登录| Allow["允许访问无限制"]
GetUserId --> |已登录| LoadUser["加载用户信息"]
LoadUser --> Reset["若日期变更则重置dailyUsage"]
Reset --> CheckDaily["检查每日使用次数"]
CheckDaily --> |超限| Reject["抛出配额超限错误"]
CheckDaily --> |未超限| Allow
```

**图表来源**
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/src/types/index.ts](file://server/src/types/index.ts)

**章节来源**
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/src/types/index.ts](file://server/src/types/index.ts)

### 组件D：性能监控中间件
- 功能概述
  - 统计总请求、平均响应时间、慢请求、错误数
  - 聚合端点级指标（请求次数、平均/最大响应时间、错误数）
- 关键实现位置
  - 性能指标结构与更新逻辑

```mermaid
flowchart TD
ReqStart(["请求开始"]) --> Exec["执行业务逻辑"]
Exec --> Resp["计算响应时长"]
Resp --> Update["更新全局与端点级指标"]
Update --> Done(["请求结束"])
```

**图表来源**
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)

**章节来源**
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)

### 组件E：TTS 生成流程与时长回写
- 功能概述
  - 生成音频时创建处理中记录，完成后回写音频URL、时长、状态等
  - 生成过程中可能因额度限制切换不同供应商
- 关键实现位置
  - 生成主流程与状态回写
  - 额度限制判断与供应商切换

```mermaid
sequenceDiagram
participant Caller as "调用方"
participant TTS as "TTS服务"
participant DB as "数据库"
participant WS as "WebSocket"
Caller->>TTS : 调用生成接口
TTS->>DB : 创建处理中记录
TTS->>TTS : 分段/并行合成
TTS->>DB : 完成后更新音频URL/时长/状态
TTS-->>Caller : 返回结果
TTS->>WS : 推送生成完成事件
```

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

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

### 组件F：前端日志与统计页面
- 功能概述
  - 展示总请求、错误、警告、平均响应时间等统计卡片
  - 支持切换“请求日志”“错误分析”“自动修复”等标签页
- 关键实现位置
  - 统计卡片渲染与数据拉取
  - 错误分析与自动修复入口

```mermaid
sequenceDiagram
participant Page as "日志页面"
participant API as "后端API"
participant Store as "页面状态"
Page->>API : GET /api/logs?limit=50
API-->>Page : 返回日志列表
Page->>API : GET /api/logs/stats
API-->>Page : 返回统计聚合
Page->>Store : 更新统计卡片与日志列表
```

**图表来源**
- [my-uniapp-vue3/src/pages/logs/index.vue](file://my-uniapp-vue3/src/pages/logs/index.vue)

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

## 依赖关系分析
- 订阅与用量服务依赖数据库模型与中间件
- TTS 服务依赖存储服务与WebSocket推送
- 前端日志页面依赖后端统计接口

```mermaid
graph LR
Logs["日志页面<br/>logs/index.vue"] --> SubSvc["订阅服务<br/>subscription.service.ts"]
SubSvc --> Prisma["Prisma 模型<br/>schema.prisma"]
TTS["TTS 服务<br/>tts.service.ts"] --> Prisma
Perf["性能中间件<br/>performance.ts"] --> SubSvc
Usage["使用限制中间件<br/>usageLimit.ts"] --> SubSvc
```

**图表来源**
- [my-uniapp-vue3/src/pages/logs/index.vue](file://my-uniapp-vue3/src/pages/logs/index.vue)
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)

**章节来源**
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [server/src/middleware/usageLimit.ts](file://server/src/middleware/usageLimit.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/src/modules/tts/tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [server/prisma/schema.prisma](file://server/prisma/schema.prisma)
- [my-uniapp-vue3/src/pages/logs/index.vue](file://my-uniapp-vue3/src/pages/logs/index.vue)

## 性能考量
- 实时更新
  - Token 使用记录与用户用量在关键操作（如音频生成完成）时实时写入
- 批量处理
  - 建议对高频统计场景采用定时任务批量汇总（例如每小时/每天），降低在线写入压力
- 历史归档
  - 对历史TokenUsage可按月/季度归档至冷存储，保留最近N个月热数据
- 查询优化
  - 为TokenUsage建立复合索引（用户+时间、用户+类型），提升统计查询效率

## 故障排查指南
- 配额不足
  - 现象：生成被拒绝，提示“本月配额已用完”
  - 处理：检查用户会员等级与usedAudioMinutes，确认是否需要升级或等待重置
- 额度受限切换
  - 现象：生成过程中因额度限制切换供应商
  - 处理：查看日志中“RATE_LIMIT”提示，调整供应商优先级或等待额度恢复
- 统计异常
  - 现象：前端统计卡片数值异常
  - 处理：检查后端性能中间件指标与数据库查询，确认统计接口返回正确

**章节来源**
- [server/src/modules/subscription/subscription.service.ts](file://server/src/modules/subscription/subscription.service.ts)
- [server/src/middleware/performance.ts](file://server/src/middleware/performance.ts)
- [server/src/modules/tts/tts.service.ts](file://server/src/modules/tts/tts.service.ts)
- [my-uniapp-vue3/src/pages/logs/index.vue](file://my-uniapp-vue3/src/pages/logs/index.vue)

## 结论
本使用统计系统以TokenUsage为核心载体，结合订阅与用量服务、中间件与TTS流程，实现了音频生成时长统计、配额控制与基础性能监控。建议在此基础上扩展：
- 增设统计报表API（日/周/月趋势、用户维度、导出）
- 引入批量统计与历史归档策略
- 完善预测模型与峰值分析能力

## 附录

### 统计查询接口设计建议
- 时间范围筛选
  - 参数：startTime、endTime
  - 实现：按TokenUsage.createdAt范围过滤
- 用户维度分析
  - 参数：userId、memberLevel
  - 实现：按用户ID或会员等级聚合
- 导出功能
  - 参数：format（csv/json）、filters
  - 实现：后端生成文件并提供下载链接

### 统计指标计算方法
- 平均使用量
  - 计算公式：总用量 / 统计周期天数
- 峰值分析
  - 方法：按小时/日聚合，取最大值
- 预测模型
  - 方法：基于历史趋势（线性回归/指数平滑）预测未来用量