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/curl测试手册.md
+++ b/docs/curl测试手册.md
@@ -22,6 +22,7 @@
 - [12. 图片服务](#12-图片服务)
 - [13. 报告服务](#13-报告服务)
 - [14. 知识库路由](#14-知识库路由)
+- [15. 异步任务查询](#15-异步任务查询)
 - [附录. 已知问题](#附录-已知问题)

 ---
@@ -587,15 +588,18 @@ curl -s -X POST http://localhost:5001/documents/upload \
      "size": 18,
      "replaced": false
    },
-    "sync_status": "已保存并添加到向量库"
+    "sync_status": "已保存，向量化任务已启动",
+    "task_id": "a1b2c3d4e5f6"
  },
-  "message": "文件上传成功，已保存并添加到向量库",
+  "message": "文件上传成功，已保存，向量化任务已启动",
  "status": "success",
  "status_code": 2002,
  "success": true
 }
 ```

+> **异步说明**：文件保存为同步操作，向量化在后台线程异步执行。响应中的 `task_id` 可用于轮询向量化进度（`GET /tasks/<task_id>`）。
+>
 > **同名文件处理**：上传同名文件时，旧版本的切片会被自动清理后覆盖（`replaced: true`），不会生成时间戳后缀文件。

 **验证结果**：✅ 通过
@@ -624,7 +628,8 @@ curl -s -X POST http://localhost:5001/documents/batch-upload \
      {"filename": "file2.txt", "path": "public_kb/file2.txt", "status": "success", "replaced": false}
    ],
    "success_count": 2,
-    "total": 2
+    "total": 2,
+    "task_id": "b2c3d4e5f6a1"
  },
  "message": "批量上传完成，成功 2/2 个文件",
  "status": "success",
@@ -633,6 +638,8 @@ curl -s -X POST http://localhost:5001/documents/batch-upload \
 }
 ```

+> **异步说明**：批量上传成功后自动触发后台向量化任务。`task_id` 可用于轮询向量化进度（`GET /tasks/<task_id>`）。若无成功上传的文件则不返回 `task_id`。
+>
 > **同名文件处理**：与单文件上传相同，批量上传中遇到同名文件也会自动覆盖旧版本（`replaced: true`）。

 **验证结果**：✅ 通过
@@ -882,7 +889,7 @@ curl -s -X DELETE "http://localhost:5001/chunks/人员名册.txt_text_0?collecti

 ### POST /sync

-触发文档同步。
+触发文档同步（异步任务）。

 ```bash
 curl -s -X POST http://localhost:5001/sync \
@@ -893,24 +900,23 @@ curl -s -X POST http://localhost:5001/sync \
 ```json
 {
  "data": {
-    "result": {
-      "documents_added": 1,
-      "documents_deleted": 1,
-      "documents_modified": 0,
-      "documents_processed": 2,
-      "end_time": "2026-05-04T01:45:42",
-      "errors": [],
-      "start_time": "2026-05-04T01:45:41",
-      "status": "completed"
-    }
+    "task_id": "c3d4e5f6a1b2",
+    "message": "同步任务已启动，通过 GET /tasks/c3d4e5f6a1b2 查询进度"
  },
-  "message": "同步完成",
+  "message": "同步任务已启动",
  "status": "success",
  "status_code": 2010,
  "success": true
 }
 ```

+> **⚠️ 异步变更**：此接口已从同步改为异步。不再直接返回同步结果，而是返回 `task_id`。后端需通过 `GET /tasks/<task_id>` 轮询任务状态，直到 `status` 为 `completed` 或 `failed`。
+>
+> **冲突检测**：如果已有同步任务正在运行，返回 HTTP 409：
+> ```json
+> {"error": "TASK_RUNNING", "message": "同步任务正在执行中 (task_id: xxx)，请等待完成"}
+> ```
+
 **验证结果**：✅ 通过

 ---
@@ -1456,44 +1462,54 @@ curl -s -X POST http://localhost:5001/exam/generate \
 ```json
 {
  "data": {
-    "questions": [
-      {
-        "content": {
-          "stem": "重购率的定义是下列哪一项？",
-          "answer": "B",
-          "data": {
-            "options": [
-              {"content": "选项A内容", "key": "A"},
-              {"content": "品规连续两周订货客户数/上周订货客户数*100%", "key": "B"}
-            ]
-          },
-          "explanation": "重购率的定义是..."
-        },
-        "difficulty": 3,
-        "question_type": "single_choice",
-        "source_trace": {
-          "chunk_ids": ["1.docx_76"],
-          "document_name": "public_kb/1.docx",
-          "page_numbers": [1],
-          "sources": [...]
-        }
-      }
-    ],
-    "request_id": null,
-    "source_chunks_used": 15,
-    "success": true,
-    "total": 10,
-    "requested_types": {"single_choice": 5, "true_false": 3, "fill_blank": 2},
-    "actual_types": {"single_choice": 5, "true_false": 3, "fill_blank": 2},
-    "warnings": []
+    "task_id": "d4e5f6a1b2c3",
+    "message": "出题任务已启动 (10题)，通过 GET /tasks/d4e5f6a1b2c3 查询结果"
  },
-  "message": "出题成功",
+  "message": "出题任务已启动",
  "status": "success",
  "status_code": 2020,
  "success": true
 }
 ```

+> **⚠️ 异步变更**：此接口已从同步改为异步。响应仅返回 `task_id`，后端需通过 `GET /tasks/<task_id>` 轮询任务状态。任务完成后，`result` 字段包含完整出题结果（格式见下方说明）。
+
+**轮询结果（GET /tasks/\<task_id\> 完成后的 result 字段）**：
+```json
+{
+  "questions": [
+    {
+      "content": {
+        "stem": "重购率的定义是下列哪一项？",
+        "answer": "B",
+        "data": {
+          "options": [
+            {"content": "选项A内容", "key": "A"},
+            {"content": "品规连续两周订货客户数/上周订货客户数*100%", "key": "B"}
+          ]
+        },
+        "explanation": "重购率的定义是..."
+      },
+      "difficulty": 3,
+      "question_type": "single_choice",
+      "source_trace": {
+        "chunk_ids": ["1.docx_76"],
+        "document_name": "public_kb/1.docx",
+        "page_numbers": [1],
+        "sources": [...]
+      }
+    }
+  ],
+  "request_id": null,
+  "source_chunks_used": 15,
+  "success": true,
+  "total": 10,
+  "requested_types": {"single_choice": 5, "true_false": 3, "fill_blank": 2},
+  "actual_types": {"single_choice": 5, "true_false": 3, "fill_blank": 2},
+  "warnings": []
+}
+```
+
 > **说明**：`warnings` 字段在某题型实际生成数量少于请求数量时返回提示信息。

 **验证结果**：✅ 通过（2026-06-05）
@@ -1527,31 +1543,41 @@ curl -s -X POST http://localhost:5001/exam/generate-smart \
 ```json
 {
  "data": {
-    "ai_analysis": {
-      "total_knowledge_points": 21,
-      "suitable_types": ["single_choice", "multiple_choice", "true_false", "subjective"],
-      "question_types": {
-        "single_choice": 8,
-        "multiple_choice": 6,
-        "true_false": 4,
-        "fill_blank": 0,
-        "subjective": 3
-      },
-      "reason": "文档包含21个知识点，涵盖术语定义、流程步骤、数值标准..."
-    },
-    "questions": [...],
-    "request_id": null,
-    "source_chunks_used": 15,
-    "success": true,
-    "total": 16
+    "task_id": "e5f6a1b2c3d4",
+    "message": "AI 智能出题任务已启动，通过 GET /tasks/e5f6a1b2c3d4 查询结果"
  },
-  "message": "AI 智能出题成功",
+  "message": "AI 智能出题任务已启动",
  "status": "success",
  "status_code": 2020,
  "success": true
 }
 ```

+> **⚠️ 异步变更**：此接口已从同步改为异步。响应仅返回 `task_id`，后端需通过 `GET /tasks/<task_id>` 轮询任务状态。任务完成后，`result` 字段包含完整出题结果（含 `ai_analysis` 字段）。
+
+**轮询结果（GET /tasks/\<task_id\> 完成后的 result 字段）**：
+```json
+{
+  "ai_analysis": {
+    "total_knowledge_points": 21,
+    "suitable_types": ["single_choice", "multiple_choice", "true_false", "subjective"],
+    "question_types": {
+      "single_choice": 8,
+      "multiple_choice": 6,
+      "true_false": 4,
+      "fill_blank": 0,
+      "subjective": 3
+    },
+    "reason": "文档包含21个知识点，涵盖术语定义、流程步骤、数值标准..."
+  },
+  "questions": [...],
+  "request_id": null,
+  "source_chunks_used": 15,
+  "success": true,
+  "total": 16
+}
+```
+
 **注意事项**：
 - 实际出题数量 ≤ min(文档知识点数, AI 推荐数量)
 - 如果文档知识点较少，生成的题目数量会相应减少
@@ -1601,33 +1627,43 @@ curl -s -X POST http://localhost:5001/exam/grade \
 ```json
 {
  "data": {
-    "request_id": null,
-    "results": [
-      {
-        "question_id": "q1",
-        "score": 2,
-        "max_score": 2,
-        "grading_status": "success",
-        "details": {
-          "correct": true,
-          "student_answer": "B",
-          "correct_answer": "B",
-          "feedback": "正确！"
-        }
-      }
-    ],
-    "score_rate": 100.0,
-    "success": true,
-    "total_max_score": 2,
-    "total_score": 2
+    "task_id": "f6a1b2c3d4e5",
+    "message": "批阅任务已启动 (1题)，通过 GET /tasks/f6a1b2c3d4e5 查询结果"
  },
-  "message": "批阅完成",
+  "message": "批阅任务已启动",
  "status": "success",
  "status_code": 2021,
  "success": true
 }
 ```

+> **⚠️ 异步变更**：此接口已从同步改为异步。响应仅返回 `task_id`，后端需通过 `GET /tasks/<task_id>` 轮询任务状态。任务完成后，`result` 字段包含完整批阅结果（格式见下方说明）。
+
+**轮询结果（GET /tasks/\<task_id\> 完成后的 result 字段）**：
+```json
+{
+  "request_id": null,
+  "results": [
+    {
+      "question_id": "q1",
+      "score": 2,
+      "max_score": 2,
+      "grading_status": "success",
+      "details": {
+        "correct": true,
+        "student_answer": "B",
+        "correct_answer": "B",
+        "feedback": "正确！"
+      }
+    }
+  ],
+  "score_rate": 100.0,
+  "success": true,
+  "total_max_score": 2,
+  "total_score": 2
+}
+```
+
 **`grading_status` 取值说明**：
 - `success`：评分成功
 - `failed`：评分失败（主观题 LLM 解析失败或超时），此时 `details` 包含 `error` 字段
@@ -1823,6 +1859,190 @@ curl -s -X POST http://localhost:5001/kb/route \

 ---

+## 15. 异步任务查询
+
+> 所有异步操作（同步、重建索引、上传向量化、出题、批阅）返回的 `task_id` 均可通过以下接口查询进度。
+
+### GET /tasks
+
+获取任务列表。
+
+```bash
+curl -s http://localhost:5001/tasks
+```
+
+**查询参数**：
+| 参数 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `status` | string | ❌ | 过滤状态：`pending` / `running` / `completed` / `failed` |
+| `type` | string | ❌ | 过滤类型：`sync` / `reindex` / `upload` / `batch_upload` / `exam_generate` / `exam_grade` |
+| `limit` | int | ❌ | 返回数量限制（默认 50） |
+
+**响应示例**：
+```json
+{
+  "data": {
+    "tasks": [
+      {
+        "task_id": "a1b2c3d4e5f6",
+        "type": "sync",
+        "description": "文档同步",
+        "status": "running",
+        "progress": 45.0,
+        "current": 9,
+        "total": 20,
+        "stage": "处理文件",
+        "message": "已处理: 产品手册.pdf",
+        "created_at": "2026-06-05T10:30:00"
+      }
+    ],
+    "total": 1
+  },
+  "message": "查询成功",
+  "status": "success",
+  "status_code": 2000,
+  "success": true
+}
+```
+
+**验证结果**：✅ 通过
+
+---
+
+### GET /tasks/\<task_id\>
+
+获取单个任务状态（JSON 轮询接口）。
+
+**后端组推荐使用此接口轮询任务进度，建议间隔 1-2 秒。**
+
+```bash
+curl -s http://localhost:5001/tasks/a1b2c3d4e5f6
+```
+
+**响应示例（运行中）**：
+```json
+{
+  "data": {
+    "task_id": "a1b2c3d4e5f6",
+    "type": "sync",
+    "description": "文档同步",
+    "status": "running",
+    "progress": 45.0,
+    "current": 9,
+    "total": 20,
+    "stage": "处理文件",
+    "message": "已处理: 产品手册.pdf",
+    "created_at": "2026-06-05T10:30:00",
+    "started_at": "2026-06-05T10:30:01"
+  },
+  "message": "查询成功",
+  "status": "success",
+  "status_code": 2000,
+  "success": true
+}
+```
+
+**响应示例（已完成）**：
+```json
+{
+  "data": {
+    "task_id": "a1b2c3d4e5f6",
+    "type": "sync",
+    "description": "文档同步",
+    "status": "completed",
+    "progress": 100.0,
+    "current": 20,
+    "total": 20,
+    "stage": "完成",
+    "message": "同步完成",
+    "created_at": "2026-06-05T10:30:00",
+    "started_at": "2026-06-05T10:30:01",
+    "completed_at": "2026-06-05T10:30:15",
+    "duration_ms": 14000,
+    "result": {
+      "documents_processed": 20,
+      "documents_added": 3,
+      "documents_modified": 2,
+      "documents_deleted": 0,
+      "errors": []
+    }
+  },
+  "message": "查询成功",
+  "status": "success",
+  "status_code": 2000,
+  "success": true
+}
+```
+
+> **任务状态**：
+> - `pending`：已创建，等待执行
+> - `running`：正在执行
+> - `completed`：执行完成，`result` 字段包含完整结果
+> - `failed`：执行失败，`error` 字段包含错误信息
+>
+> **轮询建议**：间隔 1-2 秒，当 `status` 为 `completed` 或 `failed` 时停止轮询。
+
+**验证结果**：✅ 通过
+
+---
+
+### GET /tasks/\<task_id\>/progress
+
+SSE 流式任务进度推送（dev-ui 前端推荐使用）。
+
+```bash
+curl -s -N http://localhost:5001/tasks/a1b2c3d4e5f6/progress
+```
+
+**SSE 事件序列**：
+```
+data: {"type": "start", "data": {"stage": "扫描文档"}}
+
+data: {"type": "progress", "data": {"progress": 10.0, "current": 2, "total": 20, "stage": "处理文件", "message": "已处理: file1.pdf"}}
+
+data: {"type": "progress", "data": {"progress": 25.0, "current": 5, "total": 20, "stage": "处理文件", "message": "已处理: file2.docx"}}
+
+data: {"type": "complete", "data": {"task_id": "a1b2c3d4e5f6", "status": "completed", "result": {...}}}
+```
+
+> **SSE 事件类型**：
+> - `start`：任务开始
+> - `progress`：进度更新（包含 progress/current/total/stage/message）
+> - `complete`：任务完成（data 为完整任务详情，含 result）
+> - `error`：任务失败（data 包含 message 错误信息）
+> - 每 1 秒发送一次 `: heartbeat` 保活
+
+**验证结果**：✅ 通过
+
+---
+
+### GET /tasks/stats
+
+获取任务统计信息。
+
+```bash
+curl -s http://localhost:5001/tasks/stats
+```
+
+**响应示例**：
+```json
+{
+  "data": {
+    "total": 5,
+    "by_status": {"running": 1, "completed": 3, "failed": 1},
+    "by_type": {"sync": 2, "exam_generate": 2, "upload": 1}
+  },
+  "message": "查询成功",
+  "status": "success",
+  "status_code": 2000,
+  "success": true
+}
+```
+
+**验证结果**：✅ 通过
+
+---
+
 ## 附录. 已知问题

 ### 1. /rag 接口 collections 参数
@@ -1951,11 +2171,11 @@ curl -s -X POST http://localhost:5001/kb/route \
 当代码升级涉及元数据字段变更时（如新增 `chunk_index`、`doc_type`），需要重构向量库：

 ```bash
-# 重构指定知识库（清除哈希记录 → 触发全量同步）
+# 重构指定知识库（清除哈希记录 → 触发全量同步，异步任务）
 curl -s -X POST http://127.0.0.1:5001/collections/<kb_name>/reindex
 ```

-> **⚠️ 注意**：reindex 会调用 `sync_now()` 全局同步，期间 gunicorn worker 被阻塞，搜索和问答接口将暂时无响应。建议在低峰期执行。
+> **⚠️ 注意**：reindex 已改为异步任务，立即返回 `task_id`。通过 `GET /tasks/<task_id>` 轮询进度。不再阻塞 gunicorn worker，搜索和问答接口不受影响。

 ### Reranker 配置