jhzhang/rag
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

refactor(api): 统一响应格式迁移 + 异步任务系统 + 状态码体系完善

Browse Source 
- 将全部路由文件（12个）的 jsonify 响应迁移至 success_response/error_response 统一格式
- 修复 sync_routes.py error_response 参数错误（P0）
- 新增异步任务系统：task_registry + task_routes
- 新增状态码：TASK_NOT_FOUND(4014)、TASK_CONFLICT(4015)、REINDEX_ERROR(5040)
- 修正 task_routes/exam_pkg 中语义不匹配的状态码
- 更新 curl 测试手册、后端对接规范文档
- 添加缓存性能报告和 Redis 迁移计划
This commit is contained in:
lacerate551
2026-06-05 22:56:00 +08:00
parent 54a6815ad4
commit 183a57e7f1
19 changed files with 2659 additions and 548 deletions
Download Patch File Download Diff File Expand all files Collapse all files

134
api/sync_routes.py
View File

@@ -31,12 +31,12 @@ Example:
"""
from typing import Optional, Tuple, Any
from flask import Blueprint, request, jsonify, current_app
from flask import Blueprint, request, current_app
import logging
logger = logging.getLogger(__name__)
from auth.gateway import require_gateway_auth
from core.status_codes import SYNC_SUCCESS, SYNC_ERROR, INTERNAL_ERROR
from core.status_codes import SUCCESS, SYNC_SUCCESS, SYNC_ERROR, INTERNAL_ERROR, SERVICE_UNAVAILABLE
from api.response_utils import success_response, error_response
sync_bp = Blueprint('sync', __name__)
@@ -68,9 +68,7 @@ def _require_sync_service() -> Tuple[Optional[Any], Optional[Tuple]]:
service = _get_sync_service()
if not service:
return None, error_response(
error="SERVICE_UNAVAILABLE",
error_code=INTERNAL_ERROR,
message="同步服务未启用",
"SERVICE_UNAVAILABLE", INTERNAL_ERROR, "同步服务未启用",
http_status=503
)
return service, None
@@ -82,9 +80,10 @@ def _require_sync_service() -> Tuple[Optional[Any], Optional[Tuple]]:
@require_gateway_auth
def trigger_sync() -> Tuple[Any, int]:
"""
手动触发知识库同步
手动触发知识库同步（异步任务）
扫描文档目录，检测变更并执行向量化处理。
立即返回 task_id，后台线程执行同步。
客户端通过 GET /tasks/<task_id> 轮询进度。
请求体 (可选):
{
@@ -93,7 +92,7 @@ def trigger_sync() -> Tuple[Any, int]:
}
Returns:
成功: {"success": true, "data": {"result": {...}}}
成功: {"success": true, "data": {"task_id": "xxx", "message": "同步任务已启动"}}
失败: {"error": "...", "error_code": "..."}
Example:
@@ -104,22 +103,65 @@ def trigger_sync() -> Tuple[Any, int]:
if err:
return err
try:
result = service.sync_now()
return success_response(
data={"result": result.to_dict() if hasattr(result, 'to_dict') else result},
status_code=SYNC_SUCCESS,
message="同步完成"
)
except Exception as e:
logger.error(f"同步操作异常: {e}")
from core.task_registry import get_registry
registry = get_registry()
# 检查是否有正在运行的同步任务
running = registry.list_tasks(status='running', task_type='sync', limit=1)
if running:
return error_response(
error="SYNC_ERROR",
error_code=SYNC_ERROR,
message="操作失败",
http_status=500
"TASK_RUNNING", SYNC_ERROR,
f"同步任务正在执行中 (task_id: {running[0].id})，请等待完成",
http_status=409
)
# 创建异步任务
task = registry.create_task('sync', '文档同步')
def _do_sync(task, sync_service):
"""后台执行同步"""
# 注册进度回调
processed = [0]
def on_change(change):
processed[0] += 1
registry.update_progress(
task.id,
current=processed[0],
stage='处理文件',
message=f"已处理: {change.document_name if hasattr(change, 'document_name') else change.document_id}"
)
old_callback = sync_service.on_change_callback
sync_service.on_change_callback = on_change
try:
registry.update_progress(task.id, stage='扫描文档', message='正在检测变更...')
result = sync_service.sync_now()
result_dict = result.to_dict() if hasattr(result, 'to_dict') else {
'documents_processed': result.documents_processed,
'documents_added': result.documents_added,
'documents_modified': result.documents_modified,
'documents_deleted': result.documents_deleted,
'errors': result.errors,
}
return result_dict
finally:
sync_service.on_change_callback = old_callback
registry.start_task(task.id, _do_sync, service)
return success_response(
data={
'task_id': task.id,
'message': '同步任务已启动，通过 GET /tasks/' + task.id + ' 查询进度'
},
status_code=SYNC_SUCCESS,
message="同步任务已启动"
)
@sync_bp.route('/sync/status', methods=['GET'])
@require_gateway_auth
@@ -143,12 +185,8 @@ def get_sync_status() -> Tuple[Any, int]:
"""
service, err = _require_sync_service()
if err:
return jsonify({
"status": "failed",
"status_code": INTERNAL_ERROR,
"enabled": False,
"message": "同步服务未启用"
})
return error_response("SERVICE_UNAVAILABLE", SERVICE_UNAVAILABLE, "同步服务未启用", http_status=503,
enabled=False)
try:
# 获取状态信息
@@ -163,15 +201,11 @@ def get_sync_status() -> Tuple[Any, int]:
if hasattr(service, 'get_status'):
status.update(service.get_status())
return jsonify(status)
return success_response(data=status)
except Exception as e:
logger.error(f"状态查询异常: {e}")
return jsonify({
"status": "failed",
"status_code": INTERNAL_ERROR,
"enabled": True,
"error": "操作失败"
})
return error_response("INTERNAL_ERROR", INTERNAL_ERROR, "操作失败", http_status=500,
enabled=True)
@sync_bp.route('/sync/history', methods=['GET'])
@@ -196,13 +230,11 @@ def get_sync_history() -> Tuple[Any, int]:
try:
history = service.get_sync_history(limit=limit) if hasattr(service, 'get_sync_history') else []
return jsonify({"history": history})
return success_response(data={"history": history})
except Exception as e:
logger.error(f"同步操作异常: {e}")
return error_response(
error="SYNC_ERROR",
error_code=SYNC_ERROR,
message="操作失败",
"SYNC_ERROR", SYNC_ERROR, "操作失败",
http_status=500
)
@@ -231,13 +263,11 @@ def get_change_logs() -> Tuple[Any, int]:
try:
changes = service.get_change_logs(limit=limit, collection=collection) if hasattr(service, 'get_change_logs') else []
return jsonify({"changes": changes})
return success_response(data={"changes": changes})
except Exception as e:
logger.error(f"同步操作异常: {e}")
return error_response(
error="SYNC_ERROR",
error_code=SYNC_ERROR,
message="操作失败",
"SYNC_ERROR", SYNC_ERROR, "操作失败",
http_status=500
)
@@ -263,27 +293,23 @@ def start_sync_monitor() -> Tuple[Any, int]:
try:
if hasattr(service, 'is_running') and service.is_running():
return jsonify({"status": "success", "status_code": SYNC_SUCCESS, "message": "文件监控已在运行"})
return success_response(status_code=SYNC_SUCCESS, message="文件监控已在运行")
if hasattr(service, 'start'):
success = service.start()
if success:
return jsonify({"status": "success", "status_code": SYNC_SUCCESS, "message": "文件监控已启动"})
return success_response(status_code=SYNC_SUCCESS, message="文件监控已启动")
else:
return error_response(
error="SYNC_ERROR",
error_code=SYNC_ERROR,
message="启动文件监控失败",
"SYNC_ERROR", SYNC_ERROR, "启动文件监控失败",
http_status=500
)
else:
return jsonify({"status": "success", "message": "文件监控功能不可用"})
return success_response(message="文件监控功能不可用")
except Exception as e:
logger.error(f"同步操作异常: {e}")
return error_response(
error="SYNC_ERROR",
error_code=SYNC_ERROR,
message="操作失败",
"SYNC_ERROR", SYNC_ERROR, "操作失败",
http_status=500
)
@@ -306,12 +332,10 @@ def stop_sync_monitor() -> Tuple[Any, int]:
try:
if hasattr(service, 'stop'):
service.stop()
return jsonify({"status": "success", "status_code": SYNC_SUCCESS, "message": "文件监控已停止"})
return success_response(status_code=SYNC_SUCCESS, message="文件监控已停止")
except Exception as e:
logger.error(f"同步操作异常: {e}")
return error_response(
error="SYNC_ERROR",
error_code=SYNC_ERROR,
message="操作失败",
"SYNC_ERROR", SYNC_ERROR, "操作失败",
http_status=500
)