refactor(api): 统一响应格式迁移 + 异步任务系统 + 状态码体系完善

- 将全部路由文件（12个）的 jsonify 响应迁移至 success_response/error_response 统一格式 - 修复 sync_routes.py error_response 参数错误（P0） - 新增异步任务系统：task_registry + task_routes - 新增状态码：TASK_NOT_FOUND(4014)、TASK_CONFLICT(4015)、REINDEX_ERROR(5040) - 修正 task_routes/exam_pkg 中语义不匹配的状态码 - 更新 curl 测试手册、后端对接规范文档 - 添加缓存性能报告和 Redis 迁移计划
2026-06-05 22:56:00 +08:00
parent 54a6815ad4
commit 183a57e7f1
19 changed files with 2659 additions and 548 deletions
--- a/docs/后端对接规范.md
+++ b/docs/后端对接规范.md
@@ -4,9 +4,33 @@

 ## 📋 变更记录（2026-06-05 更新）

-> **本次更新内容**：新增 AI 智能出题端口、更新生产环境测试结果
+> **本次更新内容**：新增 AI 智能出题端口、更新生产环境测试结果、**长操作改为异步任务**
 >
 > **2026-06-05 更新**：出题批卷接口格式优化与输入校验增强
+>
+> **2026-06-05 异步任务变更**：同步、上传向量化、出题、批阅等长耗时操作改为异步任务模式，立即返回 `task_id`，通过 `GET /tasks/<task_id>` 轮询结果
+
+### 异步任务变更（⚠️ 重要，2026-06-05）
+
+| 端点 | 变更说明 |
+|------|----------|
+| `POST /sync` | 改为异步任务，返回 `{"task_id": "xxx"}` 而非同步结果 |
+| `POST /documents/sync` | 改为异步任务，返回 `{"task_id": "xxx"}` |
+| `POST /collections/<kb>/reindex` | 改为异步任务，返回 `{"task_id": "xxx"}` |
+| `POST /documents/upload` | 新增 `task_id` 字段（向量化后台执行） |
+| `POST /documents/batch-upload` | 新增 `task_id` 字段（批量向量化后台执行） |
+| `POST /exam/generate` | 改为异步任务，返回 `{"task_id": "xxx"}` |
+| `POST /exam/generate-smart` | 改为异步任务，返回 `{"task_id": "xxx"}` |
+| `POST /exam/grade` | 改为异步任务，返回 `{"task_id": "xxx"}` |
+
+**新增任务查询接口**：
+
+| 端点 | 方法 | 功能 | 说明 |
+|------|------|------|------|
+| `/tasks` | GET | 任务列表 | 支持按 status/type 过滤 |
+| `/tasks/<task_id>` | GET | 任务状态（JSON） | 后端组推荐轮询接口，建议 1-2 秒间隔 |
+| `/tasks/<task_id>/progress` | GET | 任务进度（SSE） | dev-ui 前端推荐使用 |
+| `/tasks/stats` | GET | 任务统计 | 按状态和类型分组统计 |

 ### 新增端口

@@ -123,10 +147,22 @@ RAG服务负责：

 ### 2.4 出题系统（可选）

-| 端点 | 方法 | 功能 |
-|-----|------|------|
-| `/exam/generate` | POST | 生成题目 |
-| `/exam/grade` | POST | 批阅答案 |
+| 端点 | 方法 | 功能 | 说明 |
+|-----|------|------|------|
+| `/exam/generate` | POST | 生成题目 | 异步任务，返回 task_id |
+| `/exam/generate-smart` | POST | AI 智能出题 | 异步任务，返回 task_id |
+| `/exam/grade` | POST | 批阅答案 | 异步任务，返回 task_id |
+
+### 2.5 异步任务查询
+
+> 所有异步操作（同步、重建索引、上传向量化、出题、批阅）返回的 `task_id` 均可通过以下接口查询进度。
+
+| 端点 | 方法 | 功能 | 说明 |
+|-----|------|------|------|
+| `/tasks` | GET | 任务列表 | 支持按 status/type 过滤 |
+| `/tasks/<task_id>` | GET | 任务状态（JSON） | **后端组推荐轮询接口**，建议 1-2 秒间隔 |
+| `/tasks/<task_id>/progress` | GET | 任务进度（SSE） | dev-ui 前端推荐使用 |
+| `/tasks/stats` | GET | 任务统计 | 按状态和类型分组统计 |

 ---

@@ -247,7 +283,7 @@ ENABLE_DIFY_WORKFLOW=false

 ---

-**最后更新**: 2026-04-29
+**最后更新**: 2026-06-05

 > 本文档供后端开发人员参考，用于对接 RAG 知识库服务。

@@ -1089,17 +1125,24 @@ Content-Type: multipart/form-data
 ```json
 {
  "success": true,
-  "message": "文件上传成功，已保存并添加到向量库",
-  "file": {
-    "filename": "document.pdf",
-    "collection": "public_kb",
-    "path": "public_kb/document.pdf",
-    "size": 1024000,
-    "replaced": false
+  "status_code": 2002,
+  "message": "文件上传成功，已保存，向量化任务已启动",
+  "data": {
+    "file": {
+      "filename": "document.pdf",
+      "collection": "public_kb",
+      "path": "public_kb/document.pdf",
+      "size": 1024000,
+      "replaced": false
+    },
+    "sync_status": "已保存，向量化任务已启动",
+    "task_id": "a1b2c3d4e5f6"
  }
 }
 ```

+> **异步说明**：文件保存为同步操作，向量化在后台线程异步执行。响应中的 `task_id` 可用于轮询向量化进度（`GET /tasks/<task_id>`）。当同步服务不可用时，`task_id` 为 `null`，`sync_status` 为 `"已保存，等待手动同步"`。
+
 **同名文件处理**：上传同名文件时，旧版本的切片会被自动清理后覆盖（`replaced: true`），不会生成时间戳后缀文件。这确保了向量库中不会出现同一文档的新旧切片共存的情况。

 ### 5.2 批量上传
@@ -1257,26 +1300,51 @@ POST /sync

 **请求体：** 无需传递参数（同步所有知识库）

-**响应：**
+**响应（异步任务）：**
 ```json
 {
  "success": true,
-  "status": "success",
  "status_code": 2010,
-  "message": "同步完成",
+  "message": "同步任务已启动",
  "data": {
-    "result": {
-      "documents_added": 1,
-      "documents_deleted": 1,
-      "documents_modified": 0,
-      "documents_processed": 2,
-      "errors": [],
-      "status": "completed"
-    }
+    "task_id": "c3d4e5f6a1b2",
+    "message": "同步任务已启动，通过 GET /tasks/c3d4e5f6a1b2 查询进度"
  }
 }
 ```

+> **⚠️ 异步变更**：此接口已从同步改为异步。不再直接返回同步结果，而是返回 `task_id`。后端需通过 `GET /tasks/<task_id>` 轮询任务状态，直到 `status` 为 `completed` 或 `failed`。任务完成后，`result` 字段包含完整的同步结果（含 `documents_processed`、`documents_added` 等）。
+>
+> **冲突检测**：如果已有同步任务正在运行，返回 HTTP 409：`{"error": "TASK_RUNNING", "message": "同步任务正在执行中 (task_id: xxx)，请等待完成"}`
+
+**后端轮询示例**：
+
+```python
+import time
+import requests
+
+def trigger_sync_and_wait():
+    """触发同步并等待完成"""
+    # 1. 触发同步任务
+    resp = requests.post('http://rag-service:5001/sync')
+    task_id = resp.json()['data']['task_id']
+
+    # 2. 轮询任务状态（每 2 秒）
+    while True:
+        time.sleep(2)
+        status_resp = requests.get(f'http://rag-service:5001/tasks/{task_id}')
+        task_data = status_resp.json()['data']
+
+        if task_data['status'] == 'completed':
+            print(f"同步完成: {task_data['result']}")
+            return task_data['result']
+        elif task_data['status'] == 'failed':
+            raise Exception(f"同步失败: {task_data['error']}")
+        else:
+            print(f"同步中: {task_data['progress']}% - {task_data['message']}")
+```
+```
+
 ### 6.2 同步状态

 ```
@@ -1359,7 +1427,7 @@ POST /sync/stop
 ```json
 {
  "status": "success",
-  "status_code": 3001,
+  "status_code": 2010,
  "message": "文件监控已启动"
 }
 ```
@@ -1417,26 +1485,24 @@ POST /exam/generate
 | difficulty | 必须为 1-5 的整数 | HTTP 400 INVALID_PARAMS |
 | **总题数上限** | **所有题型数量之和不能超过 20** | HTTP 400 INVALID_PARAMS |

-**响应：**
+**响应（异步任务）：**

-**完整响应格式**（包含外层包装）：
 ```json
 {
  "success": true,
-  "status": "success",
-  "status_code": 2011,
-  "message": "出题完成",
+  "status_code": 2020,
+  "message": "出题任务已启动",
  "data": {
-    "success": true,
-    "request_id": "xxx",
-    "total": 10,
-    "source_chunks_used": 15,
-    "questions": [...]
+    "task_id": "d4e5f6a1b2c3",
+    "message": "出题任务已启动 (10题)，通过 GET /tasks/d4e5f6a1b2c3 查询结果"
  }
 }
 ```

-**data 内部结构**：
+> **⚠️ 异步变更**：此接口已从同步改为异步。响应仅返回 `task_id`，后端需通过 `GET /tasks/<task_id>` 轮询任务状态。任务完成后，`result` 字段包含完整出题结果（格式见下方说明）。
+
+**轮询结果（GET /tasks/\<task_id\> 完成后的 result 字段）**：
+
 ```json
 {
  "success": true,
@@ -1635,25 +1701,22 @@ POST /exam/grade

 #### 响应

-**完整响应格式**（包含外层包装）：
+**响应（异步任务）：**
 ```json
 {
  "success": true,
-  "status": "success",
  "status_code": 2021,
-  "message": "批阅完成",
+  "message": "批阅任务已启动",
  "data": {
-    "request_id": "可选，原样返回",
-    "success": true,
-    "total_score": 12.5,
-    "total_max_score": 22.0,
-    "score_rate": 56.8,
-    "results": [...]
+    "task_id": "f6a1b2c3d4e5",
+    "message": "批阅任务已启动 (5题)，通过 GET /tasks/f6a1b2c3d4e5 查询结果"
  }
 }
 ```

-**data 内部结构**：
+> **⚠️ 异步变更**：此接口已从同步改为异步。响应仅返回 `task_id`，后端需通过 `GET /tasks/<task_id>` 轮询任务状态。任务完成后，`result` 字段包含完整批阅结果（格式见下方说明）。
+
+**轮询结果（GET /tasks/\<task_id\> 完成后的 result 字段）**：

 ```json
 {
@@ -1817,16 +1880,30 @@ def build_grade_request(answer_list, questions_map):
    return {"answers": grade_answers}
 ```

-**Step 4: 调用 RAG 批卷接口**
+**Step 4: 调用 RAG 批卷接口（异步任务）**

 ```python
+import time
+
 def call_rag_grade(grade_request):
-    """调用 RAG 批卷接口"""
+    """调用 RAG 批卷接口并轮询等待结果"""
+    # 1. 提交批阅任务
    response = requests.post(
        'http://rag-service:5001/exam/grade',
        json=grade_request
    )
-    return response.json()
+    task_id = response.json()['data']['task_id']
+
+    # 2. 轮询任务状态（每 2 秒）
+    while True:
+        time.sleep(2)
+        status_resp = requests.get(f'http://rag-service:5001/tasks/{task_id}')
+        task_data = status_resp.json()['data']
+
+        if task_data['status'] == 'completed':
+            return task_data['result']
+        elif task_data['status'] == 'failed':
+            raise Exception(f"批阅失败: {task_data['error']}")
 ```

 **Step 5: 更新学生成绩**
@@ -2430,19 +2507,22 @@ ChromaDB 集合名称限制：

 | 端点 | 方法 | 说明 |
 |------|------|------|
-| `/sync` | POST | 触发同步 |
+| `/sync` | POST | 触发同步（**异步任务，返回 task_id**） |
 | `/sync/status` | GET | 同步状态 |
 | `/sync/history` | GET | 同步历史 |
 | `/sync/changes` | GET | 变更日志 |
 | `/sync/start` | POST | 启动文件监控 |
 | `/sync/stop` | POST | 停止文件监控 |
+| `/documents/sync` | POST | 触发文档同步（**异步任务，返回 task_id**） |
+| `/collections/<kb_name>/reindex` | POST | 重建索引（**异步任务，返回 task_id**） |

 ### 13.7 出题系统

 | 端点 | 方法 | 说明 |
 |------|------|------|
-| `/exam/generate` | POST | 生成题目 |
-| `/exam/grade` | POST | 批改答案 |
+| `/exam/generate` | POST | 生成题目（**异步任务，返回 task_id**） |
+| `/exam/generate-smart` | POST | AI 智能出题（**异步任务，返回 task_id**） |
+| `/exam/grade` | POST | 批改答案（**异步任务，返回 task_id**） |
 | `/exam/health` | GET | 出题服务健康检查 |

 ### 13.8 反馈与 FAQ 管理
@@ -2497,6 +2577,77 @@ ChromaDB 集合名称限制：
 |------|------|------|
 | `/documents/<path>/preview` | GET | 文档预览，按 `chunk_index` 跳转到具体切片（dev-ui 引用溯源用） |

+### 13.13 异步任务查询
+
+> 所有异步操作（同步、重建索引、上传向量化、出题、批阅）返回的 `task_id` 均可通过以下接口查询进度。
+
+| 端点 | 方法 | 说明 |
+|------|------|------|
+| `/tasks` | GET | 任务列表（支持 status/type 过滤） |
+| `/tasks/<task_id>` | GET | 任务状态（JSON 轮询，**后端组推荐使用**） |
+| `/tasks/<task_id>/progress` | GET | 任务进度（SSE 流式，dev-ui 前端使用） |
+| `/tasks/stats` | GET | 任务统计 |
+
+**任务状态字段说明**：
+
+| 字段 | 类型 | 说明 |
+|------|------|------|
+| `task_id` | string | 任务唯一标识 |
+| `type` | string | 类型：sync / reindex / upload / batch_upload / exam_generate / exam_grade |
+| `status` | string | 状态：pending / running / completed / failed |
+| `progress` | float | 进度百分比（0-100） |
+| `current` | int | 当前处理项数 |
+| `total` | int | 总项数 |
+| `stage` | string | 当前阶段 |
+| `message` | string | 当前步骤描述 |
+| `result` | any | 完成后的结果数据（仅 status=completed 时存在） |
+| `error` | string | 失败错误信息（仅 status=failed 时存在） |
+| `duration_ms` | int | 执行耗时毫秒（仅已完成时存在） |
+
+**后端对接轮询模式**：
+
+```python
+import time
+import requests
+
+def async_task_poll(task_id, base_url='http://rag-service:5001', interval=2, timeout=300):
+    """
+    通用异步任务轮询函数
+
+    Args:
+        task_id: 任务 ID
+        base_url: RAG 服务地址
+        interval: 轮询间隔（秒）
+        timeout: 超时时间（秒）
+
+    Returns:
+        任务结果（result 字段）
+
+    Raises:
+        TimeoutError: 超时
+        Exception: 任务失败
+    """
+    elapsed = 0
+    while elapsed < timeout:
+        time.sleep(interval)
+        elapsed += interval
+
+        resp = requests.get(f'{base_url}/tasks/{task_id}')
+        if resp.status_code == 404:
+            raise Exception(f"任务不存在: {task_id}")
+
+        task = resp.json()['data']
+
+        if task['status'] == 'completed':
+            return task.get('result')
+        elif task['status'] == 'failed':
+            raise Exception(f"任务失败: {task.get('error', '未知错误')}")
+        # 可选：记录进度日志
+        # logger.info(f"任务 {task_id}: {task['progress']}% - {task['message']}")
+
+    raise TimeoutError(f"任务超时: {task_id} (已等待 {timeout}s)")
+```
+
 ---

 ## 十四、文件管理服务（后端负责）