# 状态码功能更新说明

> **更新日期**: 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, ...}` |

---

## 四、响应格式示例

### 成功响应

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

### 错误响应

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

---

## 五、后端对接代码示例

### Python 示例

```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 示例

```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` | 修改 |