vscode-workbench/.trae/specs/baidu-translate-usage-tracking/spec.md

百度翻译后端使用量记录 Spec

Why

当前百度翻译功能已聚合文本翻译、语种识别、图片翻译、语音翻译等多个百度 API 接口，但后端未记录用户的使用量。为了统计每个用户对翻译功能的使用情况，需要在后端增加使用量记录能力，为后续的用户行为分析和配额管理提供数据基础。

What Changes

• 新增 TranslateUsage 模型，记录每次翻译 API 调用（用户、翻译类型、源语言、目标语言、文本长度、调用时间）
• 修改 BaiduFanyiView、RecognizeLangTypeViews、PictureRecognizeViews、SpeechRecognitionView 四个视图，在成功调用后异步记录使用量
• 新增 /baiduFanyi/usage/ API 端点，供前端查询当前用户的使用统计
• 在前端页面展示用户的使用统计摘要（今日调用次数、累计调用次数）
• 注册模型到 Django Admin 后台，便于运营查看

Impact

• Affected specs: 无
• Affected code:
  • chunyu_project/api/models.py - 新增模型（当前为空，需创建）
  • chunyu_project/api/views/BaiduFanyiView.py - 修改视图记录使用量
  • chunyu_project/api/urls.py - 新增使用量查询端点
  • chunyu_project/api/admin.py - 注册模型（需创建）
  • chunyu_project/api/tasks.py - 新增异步记录使用量任务
  • chunyu_project_react/src/pages/BaiduTranslate/BaiduTranslate.tsx - 展示使用统计
  • chunyu_project_react/src/utils/request.ts - 新增 usage API

ADDED Requirements

Requirement: 翻译使用量数据模型

系统 SHALL 提供 TranslateUsage 数据模型，用于持久化记录每次翻译 API 调用。

Scenario: 模型创建成功

• WHEN Django 迁移执行
• THEN 数据库中创建 api_translateusage 表，包含字段：id、user（外键）、translate_type（枚举：text/detect/image/audio）、from_lang、to_lang、text_length、created_at、ip_address

Scenario: 匿名用户使用翻译

• WHEN 未登录用户调用翻译 API
• THEN 使用量记录中 user 字段为 NULL，但 ip_address 字段记录请求 IP

Requirement: 文本翻译使用量记录

系统 SHALL 在文本翻译成功后自动记录使用量。

Scenario: 同步翻译成功

• WHEN 用户提交文本翻译请求且同步调用百度 API 成功
• THEN 系统创建一条 TranslateUsage 记录，translate_type 为 "text"，text_length 为输入文本长度

Scenario: 异步翻译任务提交成功

• WHEN 用户提交文本翻译请求转为异步任务（返回 task_id）
• THEN 系统在任务提交时即创建使用量记录（因为配额消耗已发生）

Requirement: 语种识别使用量记录

系统 SHALL 在语种识别成功后自动记录使用量。

Scenario: 语种识别成功

• WHEN 用户提交语种识别请求且成功返回结果
• THEN 系统创建一条 TranslateUsage 记录，translate_type 为 "detect"，to_lang 为空

Requirement: 图片翻译使用量记录

系统 SHALL 在图片翻译任务提交成功后自动记录使用量。

Scenario: 图片翻译任务提交成功

• WHEN 用户上传图片并提交图片翻译任务成功
• THEN 系统创建一条 TranslateUsage 记录，translate_type 为 "image"，text_length 为图片文件大小（字节）

Requirement: 语音翻译使用量记录

系统 SHALL 在语音翻译任务提交成功后自动记录使用量。

Scenario: 语音翻译任务提交成功

• WHEN 用户上传音频并提交语音翻译任务成功
• THEN 系统创建一条 TranslateUsage 记录，translate_type 为 "audio"，text_length 为音频文件大小（字节）

Requirement: 使用量查询 API

系统 SHALL 提供 API 端点供用户查询自己的使用统计。

Scenario: 已登录用户查询使用统计

• WHEN 已登录用户 GET /api/baiduFanyi/usage/
• THEN 返回今日调用次数、累计调用次数、按类型分组的统计

Scenario: 未登录用户使用 IP 查询

• WHEN 未登录用户 GET /api/baiduFanyi/usage/
• THEN 根据 IP 地址返回该 IP 的使用统计

Requirement: 前端使用统计展示

系统 SHALL 在前端页面展示用户的使用统计摘要。

Scenario: 展示使用统计卡片

• WHEN 用户访问百度翻译页面
• THEN 页面顶部显示"今日翻译 X 次 | 累计 Y 次"的统计信息

Requirement: Admin 后台管理

系统 SHALL 在 Django Admin 中展示翻译使用量记录。

Scenario: Admin 查看使用记录

• WHEN 管理员访问 Admin 后台的 TranslateUsage 列表
• THEN 显示用户、翻译类型、源语言、目标语言、文本长度、调用时间、IP 地址，支持按类型和日期筛选

MODIFIED Requirements

Requirement: 现有翻译视图权限

当前翻译 API 的 permission_classes = [AllowAny] SHALL 保持不变，但系统 SHALL 在有用户认证时记录用户信息。

Scenario: 已认证用户调用

• WHEN 已登录用户调用翻译 API
• THEN 使用量记录关联到该用户

Scenario: 匿名用户调用

• WHEN 未登录用户调用翻译 API
• THEN 使用量记录 user 为 NULL，仅记录 IP