feat: PLANNING体系首版（00路线图/02任务总表/03执行协议/I-03/I-04/registry42口径）+M1止血交付

2026-09-12 14:25:25 +08:00
commit 8242e730b4
482 changed files with 37029 additions and 0 deletions
@@ -0,0 +1,17 @@
+- [x] TranslateUsage 模型正确定义，包含所有必需字段（user、translate_type、from_lang、to_lang、text_length、created_at、ip_address）
+- [x] user 字段为可空外键，关联到 FUser 模型
+- [x] translate_type 使用 choices 限制为 text/detect/image/audio
+- [x] 迁移文件成功生成且无错误
+- [x] TranslateUsage 在 Admin 后台正确注册，支持筛选和搜索
+- [x] record_translate_usage Celery 任务正确创建使用量记录
+- [x] 文本翻译成功后调用使用量记录（translate_type=text）
+- [x] 语种识别成功后调用使用量记录（translate_type=detect）
+- [x] 图片翻译任务提交成功后调用使用量记录（translate_type=image）
+- [x] 语音翻译任务提交成功后调用使用量记录（translate_type=audio）
+- [x] 已认证用户的记录正确关联到用户
+- [x] 匿名用户的记录 user 为 NULL 但 IP 正确记录
+- [x] GET /api/baiduFanyi/usage/ 返回今日次数和累计次数
+- [x] 使用量查询 API 支持已登录用户和匿名用户两种场景
+- [x] 前端页面顶部展示"今日翻译 X 次 | 累计 Y 次"
+- [x] 国际化文案已添加到 zh.json、en.json 等文件
+- [x] 所有 API 视图的 permission_classes 保持 AllowAny 不变
@@ -0,0 +1,105 @@
+# 百度翻译后端使用量记录 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
@@ -0,0 +1,33 @@
+# Tasks
+
+- [x] Task 1: 创建 TranslateUsage 数据模型和迁移
+  - [x] SubTask 1.1: 在 `api/models.py` 中创建 `TranslateUsage` 模型（含 user、translate_type、from_lang、to_lang、text_length、created_at、ip_address 字段）
+  - [x] SubTask 1.2: 创建并验证 Django 迁移文件
+
+- [x] Task 2: 注册模型到 Admin 后台
+  - [x] SubTask 2.1: 创建 `api/admin.py`，注册 `TranslateUsage` 模型（含 list_display、list_filter、search_fields）
+
+- [x] Task 3: 添加异步记录使用量的 Celery 任务
+  - [x] SubTask 3.1: 在 `api/tasks.py` 中新增 `record_translate_usage` 异步任务函数
+
+- [x] Task 4: 修改后端视图记录使用量
+  - [x] SubTask 4.1: 修改 `BaiduFanyiView.post()` - 成功后调用 `record_translate_usage`
+  - [x] SubTask 4.2: 修改 `RecognizeLangTypeViews.post()` - 成功后调用 `record_translate_usage`
+  - [x] SubTask 4.3: 修改 `PictureRecognizeViews.post()` - 成功后调用 `record_translate_usage`
+  - [x] SubTask 4.4: 修改 `SpeechRecognitionView.post()` - 成功后调用 `record_translate_usage`
+
+- [x] Task 5: 新增使用量查询 API 端点
+  - [x] SubTask 5.1: 创建 `TranslateUsageView` 视图（GET /baiduFanyi/usage/）
+  - [x] SubTask 5.2: 在 `api/urls.py` 中注册路由
+
+- [x] Task 6: 前端集成使用量展示
+  - [x] SubTask 6.1: 在 `request.ts` 中新增 `usage` API 方法
+  - [x] SubTask 6.2: 在 `BaiduTranslate.tsx` 中展示使用统计卡片
+  - [x] SubTask 6.3: 添加国际化文案
+
+# Task Dependencies
+- Task 2 依赖于 Task 1（需先有模型才能注册）
+- Task 3 独立，可与 Task 2 并行
+- Task 4 依赖于 Task 3（需先有任务函数才能调用）
+- Task 5 独立，可与 Task 4 并行
+- Task 6 依赖于 Task 5（需先有 API 端点才能调用）