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 迁移计划

exam_pkg/api.py

@@ -2,8 +2,8 @@
 出题与批题系统 API 蓝图
 
 提供 REST API 接口：
-- 出题：生成题目（返回 JSON 给后端）
-- 批题：批阅答案（返回结果给后端）
+- 出题：生成题目（异步任务，返回 task_id）
+- 批题：批阅答案（异步任务，返回 task_id）
 
 职责边界：
 - RAG 服务负责：生成题目 + 批阅答案
@@ -12,6 +12,11 @@
 使用方式：
     from exam_pkg.api import exam_bp
     app.register_blueprint(exam_bp, url_prefix='/exam')
+
+异步任务流程：
+    1. POST /exam/generate → 返回 {"task_id": "xxx", ...}
+    2. GET /tasks/xxx → 轮询状态，直到 completed
+    3. result 字段包含完整出题/批阅结果
 """
 
 from flask import Blueprint, request, jsonify
@@ -29,7 +34,7 @@ from auth.gateway import (
 )
 
 # 导入统一响应格式
-from core.status_codes import EXAM_SUCCESS, GRADE_SUCCESS, EXAM_ERROR, GRADE_ERROR, BAD_REQUEST, NO_CONTENT, LLM_ERROR
+from core.status_codes import EXAM_SUCCESS, GRADE_SUCCESS, EXAM_ERROR, GRADE_ERROR, BAD_REQUEST, UNAUTHORIZED, FORBIDDEN, NO_CONTENT, LLM_ERROR
 from api.response_utils import success_response, error_response
 
 # 合法题型
@@ -169,7 +174,7 @@ def api_generate_questions():
         # 获取当前用户
         user = get_current_user()
         if not user:
-            return error_response("UNAUTHORIZED", BAD_REQUEST, "未认证", http_status=401)
+            return error_response("UNAUTHORIZED", UNAUTHORIZED, "未认证", http_status=401)
 
         # 检查向量库访问权限
         if not check_collection_permission(
@@ -178,20 +183,51 @@ def api_generate_questions():
             collection_name=collection,
             operation="read"
         ):
-            return error_response("FORBIDDEN", BAD_REQUEST, "权限不足", http_status=403)
+            return error_response("FORBIDDEN", FORBIDDEN, "权限不足", http_status=403)
 
-        # 调用新版出题接口
-        result = generate_questions_from_file(
-            file_path=file_path,
-            collection=collection,
-            question_types=question_types,
-            difficulty=data.get('difficulty', 3),
-            options=data.get('options', {}),
-            request_id=data.get('request_id'),
-            exclude_stems=data.get('exclude_stems')
+        # 调用新版出题接口（异步任务）
+        from core.task_registry import get_registry
+        import logging as _logging
+        _logger = _logging.getLogger(__name__)
+
+        registry = get_registry()
+        total_questions = sum(question_types.values())
+        task = registry.create_task(
+            'exam_generate',
+            f"出题: {os.path.basename(file_path)} ({total_questions}题)",
+            total=total_questions
         )
 
-        return success_response(data=result, status_code=EXAM_SUCCESS, message="出题成功")
+        def _do_generate(task, fp, coll, q_types, diff, opts, req_id, excl):
+            """后台执行出题"""
+            registry.update_progress(task.id, stage='检索知识', message='正在检索相关文档切片...')
+            result = generate_questions_from_file(
+                file_path=fp,
+                collection=coll,
+                question_types=q_types,
+                difficulty=diff,
+                options=opts,
+                request_id=req_id,
+                exclude_stems=excl
+            )
+            registry.update_progress(task.id, stage='完成', message=f"生成 {result.get('total', 0)} 道题")
+            return result
+
+        registry.start_task(
+            task.id, _do_generate,
+            file_path, collection, question_types,
+            data.get('difficulty', 3), data.get('options', {}),
+            data.get('request_id'), data.get('exclude_stems')
+        )
+
+        return success_response(
+            data={
+                'task_id': task.id,
+                'message': f'出题任务已启动 ({total_questions}题)，通过 GET /tasks/{task.id} 查询结果'
+            },
+            status_code=EXAM_SUCCESS,
+            message="出题任务已启动"
+        )
 
     except Exception as e:
         return error_response("EXAM_ERROR", EXAM_ERROR, str(e), http_status=500)
@@ -240,7 +276,7 @@ def api_generate_smart():
         # 获取当前用户
         user = get_current_user()
         if not user:
-            return error_response("UNAUTHORIZED", BAD_REQUEST, "未认证", http_status=401)
+            return error_response("UNAUTHORIZED", UNAUTHORIZED, "未认证", http_status=401)
 
         # 检查向量库访问权限
         if not check_collection_permission(
@@ -249,34 +285,57 @@ def api_generate_smart():
             collection_name=collection,
             operation="read"
         ):
-            return error_response("FORBIDDEN", BAD_REQUEST, "权限不足", http_status=403)
+            return error_response("FORBIDDEN", FORBIDDEN, "权限不足", http_status=403)
 
-        # 1. 调用 AI 分析文件，获取推荐的题型和数量
-        from exam_pkg.manager import analyze_file_for_exam
-        ai_analysis = analyze_file_for_exam(
-            file_path=file_path,
-            collection=collection
+        # AI 智能出题（异步任务）
+        from core.task_registry import get_registry
+        import logging as _logging
+        _logger = _logging.getLogger(__name__)
+
+        registry = get_registry()
+        task = registry.create_task(
+            'exam_generate',
+            f"AI智能出题: {os.path.basename(file_path)}"
         )
 
-        question_types = ai_analysis.get('question_types', {})
-        if not question_types or sum(question_types.values()) == 0:
-            return error_response("EXAM_ERROR", EXAM_ERROR, "AI 分析后未生成有效题型配置", http_status=500)
+        def _do_smart_generate(task, fp, coll, diff, opts, req_id, excl):
+            """后台执行 AI 智能出题"""
+            registry.update_progress(task.id, stage='AI分析', message='正在分析文档内容...')
+            from exam_pkg.manager import analyze_file_for_exam
+            ai_analysis = analyze_file_for_exam(file_path=fp, collection=coll)
 
-        # 2. 使用 AI 推荐的题型调用出题接口
-        result = generate_questions_from_file(
-            file_path=file_path,
-            collection=collection,
-            question_types=question_types,
-            difficulty=data.get('difficulty', 3),
-            options=data.get('options', {}),
-            request_id=data.get('request_id'),
-            exclude_stems=data.get('exclude_stems')
+            q_types = ai_analysis.get('question_types', {})
+            if not q_types or sum(q_types.values()) == 0:
+                raise ValueError("AI 分析后未生成有效题型配置")
+
+            total = sum(q_types.values())
+            registry.update_progress(task.id, total=total, stage='生成题目',
+                                     message=f"AI 推荐 {total} 道题，正在生成...")
+
+            result = generate_questions_from_file(
+                file_path=fp, collection=coll,
+                question_types=q_types, difficulty=diff,
+                options=opts, request_id=req_id, exclude_stems=excl
+            )
+            result['ai_analysis'] = ai_analysis
+            registry.update_progress(task.id, stage='完成', message=f"生成 {result.get('total', 0)} 道题")
+            return result
+
+        registry.start_task(
+            task.id, _do_smart_generate,
+            file_path, collection,
+            data.get('difficulty', 3), data.get('options', {}),
+            data.get('request_id'), data.get('exclude_stems')
         )
 
-        # 3. 在返回结果中添加 AI 分析信息
-        result['ai_analysis'] = ai_analysis
-
-        return success_response(data=result, status_code=EXAM_SUCCESS, message="AI 智能出题成功")
+        return success_response(
+            data={
+                'task_id': task.id,
+                'message': 'AI 智能出题任务已启动，通过 GET /tasks/' + task.id + ' 查询结果'
+            },
+            status_code=EXAM_SUCCESS,
+            message="AI 智能出题任务已启动"
+        )
 
     except Exception as e:
         return error_response("EXAM_ERROR", EXAM_ERROR, str(e), http_status=500)
@@ -367,13 +426,34 @@ def api_grade_answers():
                     f"第 {i+1} 题的 question_type 无效: {q_type}，合法值: {', '.join(sorted(VALID_QUESTION_TYPES))}",
                     http_status=400)
 
-        # 调用新版批题接口
-        result = grade_answers(
-            answers=answers,
-            request_id=data.get('request_id')
+        # 调用批题接口（异步任务）
+        from core.task_registry import get_registry
+        registry = get_registry()
+
+        task = registry.create_task(
+            'exam_grade',
+            f"批阅: {len(answers)} 道题",
+            total=len(answers)
         )
 
-        return success_response(data=result, status_code=GRADE_SUCCESS, message="批阅完成")
+        def _do_grade(task, ans_list, req_id):
+            """后台执行批阅"""
+            registry.update_progress(task.id, stage='批阅中', message='正在逐题评分...')
+            result = grade_answers(answers=ans_list, request_id=req_id)
+            registry.update_progress(task.id, stage='完成',
+                                     message=f"批阅完成，得分率 {result.get('score_rate', 0):.1f}%")
+            return result
+
+        registry.start_task(task.id, _do_grade, answers, data.get('request_id'))
+
+        return success_response(
+            data={
+                'task_id': task.id,
+                'message': f'批阅任务已启动 ({len(answers)}题)，通过 GET /tasks/{task.id} 查询结果'
+            },
+            status_code=GRADE_SUCCESS,
+            message="批阅任务已启动"
+        )
 
     except Exception as e:
         return error_response("GRADE_ERROR", GRADE_ERROR, str(e), http_status=500)