audio_codebuddy/.qoder/repowiki/zh/content/项目概述/核心功能特性/会员订阅系统/使用统计.md

使用统计

本文引用的文件

• server/src/modules/subscription/subscription.service.ts
• server/prisma/schema.prisma
• server/prisma/migrations/20260422105352_add_content_status/migration.sql
• server/src/middleware/usageLimit.ts
• server/src/middleware/performance.ts
• server/src/modules/tts/tts.service.ts
• server/src/types/index.ts
• my-uniapp-vue3/src/pages/logs/index.vue

目录

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

简介

本文件面向“使用统计系统”的数据文档，聚焦以下目标：

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

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

项目结构

围绕使用统计的核心文件分布如下：

• 订阅与用量服务：负责音频时长配额、费用计算、用量扣减与记录
• 数据模型：TokenUsage 表用于记录各类使用明细
• 中间件：使用限制中间件与性能监控中间件
• TTS 服务：音频生成流程中的时长与状态记录

• 前端日志页面：展示请求统计与错误分析

  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
• server/src/middleware/usageLimit.ts
• server/src/middleware/performance.ts
• server/prisma/schema.prisma
• server/prisma/migrations/20260422105352_add_content_status/migration.sql
• server/src/modules/tts/tts.service.ts
• my-uniapp-vue3/src/pages/logs/index.vue

章节来源

• server/src/modules/subscription/subscription.service.ts
• server/prisma/schema.prisma
• server/prisma/migrations/20260422105352_add_content_status/migration.sql
• server/src/middleware/usageLimit.ts
• server/src/middleware/performance.ts
• server/src/modules/tts/tts.service.ts
• my-uniapp-vue3/src/pages/logs/index.vue

核心组件

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

章节来源

• server/prisma/schema.prisma
• server/prisma/migrations/20260422105352_add_content_status/migration.sql
• server/src/modules/subscription/subscription.service.ts
• server/src/middleware/usageLimit.ts
• server/src/middleware/performance.ts
• server/src/modules/tts/tts.service.ts
• my-uniapp-vue3/src/pages/logs/index.vue

架构总览

使用统计系统的整体交互流程如下：

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
• server/src/modules/subscription/subscription.service.ts
• server/src/middleware/performance.ts
• server/prisma/schema.prisma

详细组件分析

组件A：Token 使用记录与余额管理

• 数据模型
  • TokenUsage 表包含用户ID、类型、数量、内容长度、订单关联、创建时间等字段，并建立索引以支持按用户与时间检索
• 主要功能
  • 消耗Token：校验余额、更新余额、记录使用明细
  • 查询Token使用列表：分页、排序、总数统计

• 关键实现位置

  • Token 使用记录与查询接口

  • Token 余额与消费逻辑

    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
• server/prisma/migrations/20260422105352_add_content_status/migration.sql

章节来源

• server/prisma/schema.prisma
• server/prisma/migrations/20260422105352_add_content_status/migration.sql
• server/src/modules/subscription/subscription.service.ts

组件B：音频生成时长统计与配额

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

• 关键实现位置

  • 音频时长估算与费用计算
  • 配额检查与用量扣减

  • Token 使用记录创建

    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

章节来源

• server/src/modules/subscription/subscription.service.ts

组件C：使用限制中间件

• 功能概述
  • 根据用户会员等级设置每日使用次数与字数限制
  • 自动重置每日使用次数，防止超限

• 关键实现位置

  • 使用次数与字数限制检查

  • 每日重置逻辑

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

图表来源

• server/src/middleware/usageLimit.ts
• server/src/types/index.ts

章节来源

• server/src/middleware/usageLimit.ts
• server/src/types/index.ts

组件D：性能监控中间件

• 功能概述
  • 统计总请求、平均响应时间、慢请求、错误数
  • 聚合端点级指标（请求次数、平均/最大响应时间、错误数）

• 关键实现位置

  • 性能指标结构与更新逻辑

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

图表来源

• server/src/middleware/performance.ts

章节来源

• server/src/middleware/performance.ts

组件E：TTS 生成流程与时长回写

• 功能概述
  • 生成音频时创建处理中记录，完成后回写音频URL、时长、状态等
  • 生成过程中可能因额度限制切换不同供应商

• 关键实现位置

  • 生成主流程与状态回写

  • 额度限制判断与供应商切换

    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

章节来源

• server/src/modules/tts/tts.service.ts

组件F：前端日志与统计页面

• 功能概述
  • 展示总请求、错误、警告、平均响应时间等统计卡片
  • 支持切换“请求日志”“错误分析”“自动修复”等标签页

• 关键实现位置

  • 统计卡片渲染与数据拉取

  • 错误分析与自动修复入口

    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

章节来源

• my-uniapp-vue3/src/pages/logs/index.vue

依赖关系分析

• 订阅与用量服务依赖数据库模型与中间件
• TTS 服务依赖存储服务与WebSocket推送

• 前端日志页面依赖后端统计接口

  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
• server/src/modules/subscription/subscription.service.ts
• server/src/middleware/performance.ts
• server/src/middleware/usageLimit.ts
• server/prisma/schema.prisma

章节来源

• server/src/modules/subscription/subscription.service.ts
• server/src/middleware/usageLimit.ts
• server/src/middleware/performance.ts
• server/src/modules/tts/tts.service.ts
• server/prisma/schema.prisma
• my-uniapp-vue3/src/pages/logs/index.vue

性能考量

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

故障排查指南

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

章节来源

• server/src/modules/subscription/subscription.service.ts
• server/src/middleware/performance.ts
• server/src/modules/tts/tts.service.ts
• my-uniapp-vue3/src/pages/logs/index.vue

结论

本使用统计系统以TokenUsage为核心载体，结合订阅与用量服务、中间件与TTS流程，实现了音频生成时长统计、配额控制与基础性能监控。建议在此基础上扩展：

• 增设统计报表API（日/周/月趋势、用户维度、导出）
• 引入批量统计与历史归档策略
• 完善预测模型与峰值分析能力

附录

统计查询接口设计建议

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

统计指标计算方法

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