100d1a06eb
- 后端 API（Flask + Gunicorn） - RAG 引擎（混合检索 + 云端 Reranker + 引用溯源） - 文档解析（MinerU + 多格式支持） - Docker 生产部署配置 - 排除前端项目、敏感配置、模型文件
220 lines
5.8 KiB
Markdown
220 lines
5.8 KiB
Markdown
# 状态码功能更新说明
|
||
|
||
> **更新日期**: 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` | 修改 |
|