106 lines
5.7 KiB
Markdown
106 lines
5.7 KiB
Markdown
# 百度翻译后端使用量记录 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](file:///c:/Users/12914/Desktop/vscode/chunyu_project/api/models.py) - 新增模型（当前为空，需创建）
|
||
- [chunyu_project/api/views/BaiduFanyiView.py](file:///c:/Users/12914/Desktop/vscode/chunyu_project/api/views/BaiduFanyiView.py) - 修改视图记录使用量
|
||
- [chunyu_project/api/urls.py](file:///c:/Users/12914/Desktop/vscode/chunyu_project/api/urls.py) - 新增使用量查询端点
|
||
- [chunyu_project/api/admin.py](file:///c:/Users/12914/Desktop/vscode/chunyu_project/api/admin.py) - 注册模型（需创建）
|
||
- [chunyu_project/api/tasks.py](file:///c:/Users/12914/Desktop/vscode/chunyu_project/api/tasks.py) - 新增异步记录使用量任务
|
||
- [chunyu_project_react/src/pages/BaiduTranslate/BaiduTranslate.tsx](file:///c:/Users/12914/Desktop/vscode/chunyu_project_react/src/pages/BaiduTranslate/BaiduTranslate.tsx) - 展示使用统计
|
||
- [chunyu_project_react/src/utils/request.ts](file:///c:/Users/12914/Desktop/vscode/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
|