From cf88421a70ae71edeb13b5eb4e2cbcd8e4f35a1f Mon Sep 17 00:00:00 2001
From: KirisameVanilla <118162831+kirisamevanilla@users.noreply.github.com>
Date: Mon, 22 Sep 2025 22:10:46 +0800
Subject: [PATCH] docs: api

---
 README.md | 203 +++++++++++++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 187 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 2ee1d6b..9a2051b 100644
--- a/README.md
+++ b/README.md
@@ -193,11 +193,81 @@ Authorization: Bearer <your_jwt_token>
 
 ---
 
-### 3. 管理员模块 (`/admin`)
+### 3. 翻译模块 (`/translate`)
+
+#### 3.1 文本翻译
+
+- **接口**: `POST /translate`
+- **描述**: 使用百度翻译API进行文本翻译
+- **需要认证**: 是
+- **请求体**:
+
+```json
+{
+  "query": "Hello World",
+  "from_lang": "auto",
+  "to_lang": "zh"
+}
+```
+
+- **请求参数说明**:
+  - `query`: 待翻译的文本
+  - `from_lang`: 源语言，支持值: `auto`(自动检测), `fr`(法语), `jp`(日语), `zh`(中文)，默认为 `auto`
+  - `to_lang`: 目标语言，支持值: `fr`(法语), `jp`(日语), `zh`(中文)，默认为 `zh`，不能为 `auto`
+
+- **响应**:
+
+```json
+{
+  "translated_text": "你好世界"
+}
+```
+
+- **状态码**:
+  - `200`: 翻译成功
+  - `401`: 未授权
+  - `500`: 翻译服务错误
+
+#### 3.2 调试翻译接口
+
+- **接口**: `POST /translate/debug`
+- **描述**: 管理员专用的翻译调试接口，带有限流保护
+- **需要认证**: 管理员权限
+- **查询参数**:
+  - `query`: 待翻译文本
+  - `from_lang`: 源语言，默认为 `auto`
+  - `to_lang`: 目标语言，默认为 `zh`
+
+- **限制**: 每秒最多2次请求
+- **状态码**:
+  - `200`: 翻译成功
+  - `429`: 请求频率过高
+  - `403`: 权限不足
+
+---
+
+### 4. Redis测试模块 (`/ping-redis`)
+
+#### 4.1 Redis连接测试
+
+- **接口**: `GET /ping-redis`
+- **描述**: 测试Redis连接状态
+- **需要认证**: 否
+- **响应**:
+
+```json
+{
+  "pong": true
+}
+```
+
+---
+
+### 5. 管理员模块 (`/admin`)
 
 > **注意**: 所有管理员接口都需要管理员权限
 
-#### 3.1 获取词典列表
+#### 5.1 获取词典列表
 
 - **接口**: `GET /admin/dict`
 - **描述**: 分页获取词典数据，用于后台管理
@@ -224,7 +294,7 @@ Authorization: Bearer <your_jwt_token>
 }
 ```
 
-#### 3.2 搜索词条
+#### 5.2 搜索词条
 
 - **接口**: `POST /admin/dict/search_word`
 - **描述**: 在后台管理中搜索特定词条
@@ -254,11 +324,92 @@ Authorization: Bearer <your_jwt_token>
 ]
 ```
 
+#### 5.3 批量更新词条
+
+- **接口**: `PUT /admin/dict/adjust`
+- **描述**: 批量更新词典定义内容
+- **需要认证**: 管理员权限
+- **请求体**:
+
+```json
+{
+  "updates": [
+    {
+      "id": "integer",
+      "language": "fr" | "jp",
+      "pos": "string",
+      "meaning": "string",
+      "example": "string",
+      "eng_explanation": "string"
+    }
+  ]
+}
+```
+
+- **响应**:
+
+```json
+{
+  "success_count": "integer",
+  "errors": ["string"]
+}
+```
+
+- **状态码**:
+  - `200`: 更新成功
+  - `400`: 词条不存在
+  - `422`: 无改动信息
+
+#### 5.4 添加新词条
+
+- **接口**: `POST /admin/dict/add`
+- **描述**: 添加新的词典条目
+- **需要认证**: 管理员权限
+- **请求体**:
+
+```json
+{
+  "word": "string",
+  "language": "fr" | "jp",
+  "pos": "string",
+  "meaning": "string",
+  "example": "string",
+  "eng_explanation": "string"
+}
+```
+
+- **状态码**:
+  - `200`: 添加成功
+  - `409`: 释义已存在
+  - `400`: 不支持的语言类型
+
+#### 5.5 Excel批量导入
+
+- **接口**: `POST /admin/dict/update_by_xlsx`
+- **描述**: 通过Excel文件批量导入词典数据
+- **需要认证**: 管理员权限
+- **请求类型**: `multipart/form-data`
+- **请求参数**:
+  - `file`: Excel文件 (.xlsx 或 .xls 格式)
+
+- **响应**:
+
+```json
+{
+  "message": "导入成功"
+}
+```
+
+- **状态码**:
+  - `200`: 导入成功
+  - `400`: 文件格式错误
+  - `500`: 导入失败
+
 ---
 
-### 4. 数据模型
+### 6. 数据模型
 
-#### 4.1 法语词性枚举
+#### 6.1 法语词性枚举
 
 ```text
 n. - 名词
@@ -276,7 +427,7 @@ interj. - 感叹词
 art. - 冠词
 ```
 
-#### 4.2 日语词性枚举
+#### 6.2 日语词性枚举
 
 ```text
 名词, 形容词, 形容动词, 连用, 一段动词, 五段动词, 
@@ -286,7 +437,7 @@ art. - 冠词
 
 ---
 
-### 5. 错误码说明
+### 7. 错误码说明
 
 | 状态码 | 说明 |
 |--------|------|
@@ -295,11 +446,14 @@ art. - 冠词
 | 401 | 未授权/令牌无效 |
 | 403 | 权限不足 |
 | 404 | 资源未找到 |
+| 409 | 资源冲突（如重复数据） |
+| 422 | 请求实体错误 |
+| 429 | 请求频率过高 |
 | 500 | 服务器内部错误 |
 
 ---
 
-### 6. 使用示例
+### 8. 使用示例
 
 #### 完整的API调用流程示例
 
@@ -329,29 +483,46 @@ curl -X POST "http://127.0.0.1:8000/search" \
     "query": "bonjour",
     "language": "fr"
   }'
+
+# 4. 使用翻译API
+curl -X POST "http://127.0.0.1:8000/translate" \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer <your_token_here>" \
+  -d '{
+    "query": "Hello World",
+    "from_lang": "auto",
+    "to_lang": "zh"
+  }'
+
+# 5. 测试Redis连接
+curl -X GET "http://127.0.0.1:8000/ping-redis"
 ```
 
 ---
 
-### 7. 开发者说明
+### 9. 开发者说明
 
 - **数据库**: 使用MySQL存储词典数据和用户信息
-- **缓存**: 使用Redis进行token黑名单管理
+- **缓存**: 使用Redis进行token黑名单管理和API限流
 - **认证**: JWT令牌有效期为2小时
+- **翻译服务**: 集成百度翻译API，支持多语言互译
+- **限流保护**: 翻译调试接口有每秒2次请求限制
+- **文件上传**: 支持Excel格式的批量词典导入
 - **CORS**: 支持本地开发环境跨域访问
 - **API文档**: 启动服务后访问 `http://127.0.0.1:8000/docs` 查看Swagger文档
 
 ---
 
-### 8. 部署说明
+### 10. 部署说明
 
 1. 安装依赖: `pip install -r requirements.txt`
 2. 配置数据库连接 (settings.py)
-3. 启动Redis服务
-4. 运行数据库迁移
-5. 启动服务: `python main.py`
+3. 配置百度翻译API密钥 (BAIDU_APPID, BAIDU_APPKEY)
+4. 启动Redis服务
+5. 运行数据库迁移
+6. 启动服务: `python main.py`
 
 ---
 
-*文档版本: 1.0*  
-*最后更新: 2025年9月4日*
+*文档版本: 2.0*  
+*最后更新: 2025年9月22日*