rag/docs/状态码功能更新说明.md

状态码功能更新说明

更新日期: 2026-04-30 改动范围: 长时间运行端口的响应格式增强

---

一、更新概述

为方便后端判断 RAG 服务处理状态，以下端口增加了统一的 status_code 字段：

端口	改动文件
/documents/upload	api/document_routes.py
/documents/batch-upload	api/document_routes.py
/sync	api/sync_routes.py
/exam/generate	exam_pkg/api.py
/exam/grade	exam_pkg/api.py

---

二、状态码速查表

处理中 (10xx)

状态码	常量名	说明
1000	PROCESSING	通用处理中
1010	SYNC_RUNNING	同步进行中
1020	EXAM_GENERATING	出题生成中
1021	EXAM_GRADING	批阅进行中

成功 (20xx)

状态码	常量名	说明
2000	SUCCESS	通用成功
2002	UPLOAD_SUCCESS	文件上传成功
2003	BATCH_UPLOAD_SUCCESS	批量上传成功
2010	SYNC_SUCCESS	同步完成
2020	EXAM_SUCCESS	出题成功
2021	GRADE_SUCCESS	批阅完成

客户端错误 (40xx)

状态码	常量名	说明
4000	BAD_REQUEST	请求参数错误
4004	NO_FILE	没有上传文件
4005	NO_FILE_SELECTED	没有选择文件
4006	NO_COLLECTION	未指定向量库
4007	UNSUPPORTED_FORMAT	不支持的文件格式
4008	FILE_TOO_LARGE	文件过大

服务端错误 (50xx)

状态码	常量名	说明
5000	INTERNAL_ERROR	内部错误
5010	SYNC_ERROR	同步失败
5020	EXAM_ERROR	出题失败
5021	GRADE_ERROR	批阅失败

---

三、各端口改动对照

3.1 文档上传 /documents/upload

场景	旧响应	新响应
成功	{"success": true, ...}	{"status": "success", "status_code": 2002, ...}
无文件	{"error": "没有上传文件"}	{"status": "failed", "status_code": 4004, ...}
格式错误	{"error": "不支持的文件类型"}	{"status": "failed", "status_code": 4007, ...}
文件过大	{"error": "文件大小超过限制"}	{"status": "failed", "status_code": 4008, ...}

3.2 批量上传 /documents/batch-upload

场景	旧响应	新响应
成功	{"success": true, ...}	{"status": "success", "status_code": 2003, ...}

3.3 同步服务 /sync

场景	旧响应	新响应
成功	{"success": true, ...}	{"status": "success", "status_code": 2010, ...}
服务不可用	{"error": "同步服务未启用"}	{"status": "failed", "status_code": 5000, ...}
同步失败	{"error": "xxx"}	{"status": "failed", "status_code": 5010, ...}

3.4 出题 /exam/generate

场景	旧响应	新响应
成功	{"success": true, ...}	{"status": "success", "status_code": 2020, ...}
参数缺失	{"error": "缺少参数"}	{"status": "failed", "status_code": 4000, ...}
出题失败	{"error": "xxx"}	{"status": "failed", "status_code": 5020, ...}

3.5 批阅 /exam/grade

场景	旧响应	新响应
成功	{"success": true, ...}	{"status": "success", "status_code": 2021, ...}
批阅失败	{"error": "xxx"}	{"status": "failed", "status_code": 5021, ...}

---

四、响应格式示例

成功响应

{
  "status": "success",
  "status_code": 2002,
  "message": "文件上传成功",
  "success": true,
  "data": {
    "file": {
      "filename": "document.pdf",
      "collection": "public_kb",
      "path": "public_kb/document.pdf",
      "size": 102400
    }
  }
}

错误响应

{
  "status": "failed",
  "status_code": 4007,
  "message": "不支持的文件格式: .exe，支持: pdf, docx, doc, xlsx, txt",
  "success": false,
  "error": {
    "error": "UNSUPPORTED_FORMAT",
    "error_code": 4007,
    "details": {}
  }
}

---

五、后端对接代码示例

Python 示例

def handle_rag_response(response):
    """处理 RAG 服务响应"""
    data = response.json()
    status_code = data.get("status_code", 0)

    # 判断处理状态
    if 2000 <= status_code < 3000:
        # 成功
        return data.get("data", data)

    elif 4000 <= status_code < 5000:
        # 客户端错误
        raise ClientError(data.get("message"), status_code)

    elif 5000 <= status_code < 6000:
        # 服务端错误
        raise ServerError(data.get("message"), status_code)

    # 兼容旧格式
    if data.get("success"):
        return data
    raise Exception(data.get("error", "未知错误"))

JavaScript 示例

function handleRagResponse(data) {
  const statusCode = data.status_code || 0;

  if (statusCode >= 2000 && statusCode < 3000) {
    // 成功
    return data.data || data;
  } else if (statusCode >= 4000 && statusCode < 5000) {
    // 客户端错误
    throw new ClientError(data.message, statusCode);
  } else if (statusCode >= 5000 && statusCode < 6000) {
    // 服务端错误
    throw new ServerError(data.message, statusCode);
  }

  // 兼容旧格式
  if (data.success) return data;
  throw new Error(data.error || "未知错误");
}

---

六、向后兼容说明

所有响应保留了 success 字段：

• 成功时 success: true
• 失败时 success: false

旧代码仍可通过 success 字段判断，无需立即修改。

---

七、文件变更清单

文件	变更类型
core/status_codes.py	新增
api/response_utils.py	新增
api/document_routes.py	修改
api/sync_routes.py	修改
exam_pkg/api.py	修改