fix(exam): 正确返回文件未索引错误

docs/出题批题后端对接指南.md

@@ -4,10 +4,15 @@
 
 | 接口 | 方法 | 功能 | 超时建议 |
 |------|------|------|----------|
-| `/exam/generate` | POST | 生成题目（手动指定题型数量） | 120秒 |
-| `/exam/generate-smart` | POST | 生成题目（AI 自动分析文档结构出题） | 120秒 |
+| `/exam/generate` | POST | 生成题目（手动指定题型数量） | 读取超时至少 650 秒 |
+| `/exam/generate-smart` | POST | 生成题目（AI 自动分析文档结构出题） | 读取超时至少 650 秒 |
 | `/exam/grade` | POST | 批阅答案 | 60秒 |
 
+> **2026-07-19 变更**：
+> 1. 文件未完成向量化时不再返回“成功但 0 道题”，统一返回 HTTP 409、`FILE_NOT_INDEXED`、业务状态码 `4016`
+> 2. `/exam/generate-smart` 会在 AI 分析前检查文件状态，未索引时不会调用模型
+> 3. 正常成功响应保持不变；Gunicorn 出题超时调整为 600 秒
+>
 > **2026-07-03 变更**：
 > 1. 移除出题总题数 20 道上限，超过 50 道时返回警告（不影响出题）
 > 2. 填空题批阅增加 `student_answer` 格式校验（必须为字符串列表）
@@ -34,7 +39,7 @@ Content-Type: application/json
 | `collection` | string 或 string[] | ✅ | 向量库名称，支持数组（按优先级顺序检索，找到文件即停止） |
 | `question_types` | object | ✅ | 题型及数量，**无上限**（超过 50 道时服务端返回警告但仍正常出题） |
 | `difficulty` | int | ❌ | 难度等级 1-5，默认 3 |
-| `request_id` | string | ❌ | 请求ID，相同ID返回缓存结果（幂等性） |
+| `request_id` | string | ❌ | 请求追踪 ID，服务端原样返回；当前不提供幂等缓存 |
 | `exclude_stems` | string[] | ❌ | 排除已有题目的题干列表，避免重复出题（最多 100 条） |
 
 **请求示例：**
@@ -51,7 +56,7 @@ Content-Type: application/json
     "subjective": 1
   },
   "difficulty": 3,
-  "request_id": "uuid-for-idempotency"
+  "request_id": "uuid-for-tracing"
 }
 ```
 
@@ -107,29 +112,28 @@ Content-Type: application/json
 }
 ```
 
-**⚠️ 文件/向量库不存在时的响应：**
+**⚠️ 文件未完成向量化时的响应：**
 
-当 `file_path` 在指定 `collection` 中找不到，或 `collection` 不存在时，接口**不会返回错误**，而是返回空结果：
+当 `file_path` 在指定 `collection` 中找不到时，两个出题接口都返回 HTTP 409：
 
 ```json
 {
-  "success": true,
-  "status": "success",
-  "status_code": 2020,
-  "message": "出题成功",
+  "success": false,
+  "status": "failed",
+  "error_code": "FILE_NOT_INDEXED",
+  "status_code": 4016,
+  "message": "文件未向量化: 文件 1.docx 未在向量库中找到，可能正在向量化或未上传",
   "data": {
-    "request_id": null,
-    "total": 0,
-    "questions": [],
-    "requested_types": {"single_choice": 1},
-    "actual_types": {},
-    "warnings": ["single_choice: 请求 1 道，实际生成 0 道"]
+    "request_id": "uuid-for-tracing",
+    "file_status": "not_found",
+    "chunk_count": 0
   }
 }
 ```
 
-> **后端注意**：必须检查 `data.total` 是否 > 0 来判断出题是否成功，不能仅依赖 `success` 字段。
-```
+> **后端处理**：收到 HTTP 409 且 `error_code=FILE_NOT_INDEXED` 时，提示用户文件尚未完成向量化；不要把该响应当作成功题目入库，也不要立即高频重试。
+>
+> 当前版本要求后端传入有效的 `collection`。不存在的向量库暂时也可能表现为 `FILE_NOT_INDEXED`。
 
 ### 2.3 返回字段说明
 
@@ -173,9 +177,10 @@ Content-Type: application/json
 |--------|------|------|
 | `MISSING_PARAMS` | 400 | 缺少必填参数（file_path / collection / question_types） |
 | `INVALID_PARAMS` | 400 | 参数校验失败（题型无效、难度越界、总题数≤0 等） |
+| `FILE_NOT_INDEXED` | 409 | 文件未完成向量化，业务状态码为 `4016` |
 | `EXAM_ERROR` | 500 | 出题过程异常（LLM 调用失败、解析错误等） |
 
-> **注意**：文件不存在或向量库不存在时，不会返回错误码，而是返回 `success=true` + `total=0` + `warnings`（见上方说明）。后端应检查 `total > 0`。
+> **注意**：即使文件已索引，模型也可能少生成题目。成功响应仍应检查 `data.total` 和 `data.warnings`；部分生成属于成功响应，不应与 `FILE_NOT_INDEXED` 混淆。
 
 ### 2.6 智能出题接口（/exam/generate-smart）
 
@@ -209,7 +214,7 @@ Content-Type: application/json
 }
 ```
 
-**响应：** 与 `/exam/generate` 格式相同，额外包含 `ai_analysis` 字段（AI 分析结果）。
+**响应：** 成功时与 `/exam/generate` 格式相同，并额外包含 `ai_analysis`；文件未索引时同样返回 HTTP 409，且不会执行 AI 分析。
 
 ---
 
@@ -553,7 +558,7 @@ Content-Type: application/json
 2026-07-03 起，出题接口**不再限制总题数**。服务端会在请求数超过 50 道时记录警告日志，但不影响出题。建议：
 - 单次出题不超过 30 道（LLM 生成耗时与题数成正比，30 道约需 5-8 分钟）
 - 超过 30 道建议分批调用
-- 设置 120 秒以上超时
+- 后端 HTTP 客户端读取超时设置为至少 650 秒
 
 ### Q6: 填空题学生答案传错了会怎样？
 
@@ -565,6 +570,6 @@ Content-Type: application/json
 
 ---
 
-**文档版本**: v1.2
-**更新时间**: 2026-07-03  
+**文档版本**: v1.3
+**更新时间**: 2026-07-19
 **相关文档**: [后端对接规范.md](./后端对接规范.md)