init: RAG 知识库服务初始提交
- 后端 API（Flask + Gunicorn） - RAG 引擎（混合检索 + 云端 Reranker + 引用溯源） - 文档解析（MinerU + 多格式支持） - Docker 生产部署配置 - 排除前端项目、敏感配置、模型文件
This commit is contained in:
lacerate551
219
docs/状态码功能更新说明.md
Normal file
219
docs/状态码功能更新说明.md
Normal file
@@ -0,0 +1,219 @@
|
||||
# 状态码功能更新说明
|
||||
|
||||
> **更新日期**: 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` | 修改 |
|
||||
Reference in New Issue
Block a user