feat: 添加 CORS 支持和列表 API（修复前端跨域和数据加载问题）

chengjie · claude · chengjie · commit 21c26c36455b · 2025-11-12T23:33:04.000+08:00
## 修改内容 ### 1. 添加 CORS Middleware（main.py） - 配置允许的前端域名（生产 + 本地开发） - 支持 OPTIONS 预检请求 - 允许的方法：GET, POST, PUT, DELETE, OPTIONS - 允许的 Headers：Content-Type, Authorization, X-Request-ID ### 2. 新增任务列表 API（api/task.py） - 端点：GET /tasks - 功能：分页、按状态过滤、排序 - 参数验证：Literal 类型 + Query 约束 - 分页元数据：total_pages, has_next, has_prev ### 3. 新增文档列表 API（api/documents.py） - 端点：GET /documents - 功能：使用 LightRAG 原生 get_docs_paginated() - 支持：分页、状态过滤、排序 - 端点：GET /documents/status_counts - 功能：返回各状态的文档数量统计 ## 技术细节 - ✅ 验证了 LightRAG doc_status API 的实际行为（返回 tuple[list, int]） - ✅ 使用 Literal 类型限制枚举值（status, sort_field, sort_direction） - ✅ 添加参数验证（page_size ≤ 100, page ≤ 10000） - ✅ 完善错误处理（501 Not Implemented, 500 Internal Server Error） - ✅ 本地测试通过（CORS 预检返回 200，列表 API 正常工作） ## 解决的问题 - 🐛 修复前端 CORS 预检失败（OPTIONS 返回 405） - 🐛 修复前端刷新后列表为空（缺少列表 API） - 🐛 修复前端无法获取文档状态统计 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
diff --git a/api/documents.py b/api/documents.py
@@ -3,6 +3,7 @@
 """
 
 from fastapi import APIRouter, HTTPException, Depends, Query, BackgroundTasks
+from typing import Optional, Literal
 from src.multi_tenant import get_tenant_lightrag
 from src.tenant_deps import get_tenant_id
 from src.logger import logger
@@ -185,3 +186,156 @@ async def delete_document(
         "doc_id": doc_id,
         "tenant_id": tenant_id
     }
+
+
+# ============ GET 文档列表 ============
+
+@router.get("/documents")
+async def list_documents(
+    tenant_id: str = Depends(get_tenant_id),
+    page: int = Query(1, ge=1, le=10000, description="页码（从 1 开始）"),
+    page_size: int = Query(50, ge=1, le=100, description="每页数量（最多 100）"),
+    status_filter: Optional[Literal["pending", "processing", "preprocessed", "processed", "failed"]] = None,
+    sort_field: Literal["created_at", "updated_at"] = Query("created_at"),
+    sort_direction: Literal["asc", "desc"] = Query("desc")
+):
+    """
+    获取租户的文档列表（支持分页、过滤、排序）
+
+    **功能**：
+    - ✅ 分页：page, page_size
+    - ✅ 过滤：status_filter (pending/processing/preprocessed/processed/failed)
+    - ✅ 排序：sort_field (created_at/updated_at), sort_direction (asc/desc)
+    - ✅ 使用 LightRAG 原生分页 API
+
+    **示例请求**：
+    - GET /documents?tenant_id=tenant_a&page=1&page_size=20
+    - GET /documents?tenant_id=tenant_a&status_filter=processed&sort_field=updated_at&sort_direction=desc
+
+    **示例响应**：
+    ```json
+    {
+        "documents": [
+            {
+                "doc_id": "doc-abc123",
+                "status": "processed",
+                "file_path": "research_paper.pdf",
+                "created_at": "2025-11-06T10:00:00",
+                "updated_at": "2025-11-06T10:05:00"
+            }
+        ],
+        "pagination": {
+            "total": 100,
+            "page": 1,
+            "page_size": 20,
+            "total_pages": 5,
+            "has_next": true,
+            "has_prev": false
+        }
+    }
+    ```
+    """
+    try:
+        # 获取 LightRAG 实例
+        lightrag = await get_tenant_lightrag(tenant_id)
+
+        # 验证 doc_status 是否可用
+        if not hasattr(lightrag, 'doc_status'):
+            raise HTTPException(
+                status_code=501,
+                detail="Document status storage not available"
+            )
+
+        # 调用 LightRAG 的分页方法
+        docs_list, total = await lightrag.doc_status.get_docs_paginated(
+            status_filter=status_filter,
+            page=page,
+            page_size=page_size,
+            sort_field=sort_field,
+            sort_direction=sort_direction
+        )
+
+        # 格式化文档数据
+        documents = []
+        for doc in docs_list:
+            # docs_list 是列表，每个元素是文档对象
+            if hasattr(doc, '__dict__'):
+                doc_dict = doc.__dict__.copy()
+            elif isinstance(doc, dict):
+                doc_dict = doc.copy()
+            else:
+                # 尝试转换为字典
+                doc_dict = {"raw_data": str(doc)}
+
+            documents.append(doc_dict)
+
+        return {
+            "documents": documents,
+            "pagination": {
+                "total": total,
+                "page": page,
+                "page_size": page_size,
+                "total_pages": (total + page_size - 1) // page_size if total > 0 else 0,
+                "has_next": page * page_size < total,
+                "has_prev": page > 1
+            }
+        }
+
+    except NotImplementedError as e:
+        logger.error(f"get_docs_paginated not implemented: {e}")
+        raise HTTPException(
+            status_code=501,
+            detail="Document pagination not implemented in current LightRAG version"
+        )
+    except Exception as e:
+        logger.error(f"Failed to list documents for tenant {tenant_id}: {e}", exc_info=True)
+        raise HTTPException(
+            status_code=500,
+            detail=f"Failed to retrieve documents: {str(e)}"
+        )
+
+
+@router.get("/documents/status_counts")
+async def get_document_status_counts(tenant_id: str = Depends(get_tenant_id)):
+    """
+    获取文档状态统计
+
+    **功能**：
+    - 返回各状态的文档数量（pending/processing/preprocessed/processed/failed）
+
+    **示例响应**：
+    ```json
+    {
+        "status_counts": {
+            "pending": 5,
+            "processing": 2,
+            "preprocessed": 3,
+            "processed": 100,
+            "failed": 1,
+            "all": 111
+        }
+    }
+    ```
+    """
+    try:
+        # 获取 LightRAG 实例
+        lightrag = await get_tenant_lightrag(tenant_id)
+
+        # 验证 doc_status 是否可用
+        if not hasattr(lightrag, 'doc_status'):
+            raise HTTPException(
+                status_code=501,
+                detail="Document status storage not available"
+            )
+
+        # 调用 LightRAG 的统计方法
+        counts = await lightrag.doc_status.get_all_status_counts()
+
+        return {"status_counts": counts}
+
+    except Exception as e:
+        logger.error(f"Failed to get status counts for tenant {tenant_id}: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail="Failed to get status counts"
+        )
diff --git a/api/task.py b/api/task.py
@@ -3,11 +3,12 @@
 """
 
 from datetime import datetime
-from fastapi import APIRouter, HTTPException, Depends
+from typing import Optional, Literal
+from fastapi import APIRouter, HTTPException, Depends, Query
 
 from src.logger import logger
 from src.tenant_deps import get_tenant_id
-from .task_store import get_task, update_task
+from .task_store import get_task, update_task, get_tenant_tasks
 from .models import TaskStatus, TaskInfo
 
 router = APIRouter()
@@ -184,3 +185,132 @@ async def sync_task_with_lightrag(task: TaskInfo, tenant_id: str) -> TaskInfo:
         )
 
     return task
+
+
+@router.get("/tasks")
+async def list_tasks(
+    tenant_id: str = Depends(get_tenant_id),
+    status: Optional[Literal["pending", "processing", "completed", "failed"]] = None,
+    page: int = Query(1, ge=1, le=10000, description="页码（从 1 开始）"),
+    page_size: int = Query(50, ge=1, le=100, description="每页数量（最多 100）"),
+    sort_by: Literal["created_at", "updated_at", "status"] = Query("created_at"),
+    sort_order: Literal["asc", "desc"] = Query("desc")
+):
+    """
+    获取租户的任务列表（支持分页、过滤、排序）
+
+    **功能**：
+    - ✅ 分页：page, page_size
+    - ✅ 过滤：status (pending/processing/completed/failed)
+    - ✅ 排序：sort_by (created_at/updated_at/status), sort_order (asc/desc)
+
+    **注意**：
+    - 当前在内存中分页，如果任务量 >10000，性能会下降
+    - 建议未来在存储层实现分页
+
+    **示例请求**：
+    - GET /tasks?tenant_id=tenant_a&page=1&page_size=20
+    - GET /tasks?tenant_id=tenant_a&status=completed&sort_by=updated_at&sort_order=desc
+
+    **示例响应**：
+    ```json
+    {
+        "tasks": [
+            {
+                "task_id": "xxx",
+                "tenant_id": "tenant_a",
+                "status": "completed",
+                "doc_id": "doc_001",
+                "filename": "test.pdf",
+                "created_at": "2025-10-14T20:00:00",
+                "updated_at": "2025-10-14T20:02:30"
+            }
+        ],
+        "pagination": {
+            "total": 100,
+            "page": 1,
+            "page_size": 20,
+            "total_pages": 5,
+            "has_next": true,
+            "has_prev": false
+        }
+    }
+    ```
+    """
+    try:
+        # 获取所有任务
+        tasks_dict = get_tenant_tasks(tenant_id)
+
+        # 如果没有任务，返回空列表
+        if not tasks_dict:
+            return {
+                "tasks": [],
+                "pagination": {
+                    "total": 0,
+                    "page": page,
+                    "page_size": page_size,
+                    "total_pages": 0,
+                    "has_next": False,
+                    "has_prev": False
+                }
+            }
+
+        tasks_list = list(tasks_dict.values())
+
+        # 过滤状态
+        if status:
+            tasks_list = [t for t in tasks_list if t.status.value == status]
+
+        # 排序
+        reverse = (sort_order == "desc")
+        tasks_list.sort(
+            key=lambda t: getattr(t, sort_by, 0) or 0,
+            reverse=reverse
+        )
+
+        # 分页
+        total = len(tasks_list)
+        start = (page - 1) * page_size
+        end = start + page_size
+        tasks_page = tasks_list[start:end]
+
+        # 转换为 dict（确保可序列化）
+        tasks_data = []
+        for t in tasks_page:
+            if hasattr(t, 'dict'):
+                tasks_data.append(t.dict())
+            else:
+                # 手动转换为字典
+                task_dict = {
+                    "task_id": t.task_id,
+                    "tenant_id": t.tenant_id,
+                    "status": t.status.value,
+                    "doc_id": t.doc_id,
+                    "filename": t.filename,
+                    "created_at": t.created_at,
+                    "updated_at": t.updated_at
+                }
+                if hasattr(t, 'result') and t.result:
+                    task_dict["result"] = t.result
+                if hasattr(t, 'error') and t.error:
+                    task_dict["error"] = t.error
+                tasks_data.append(task_dict)
+
+        return {
+            "tasks": tasks_data,
+            "pagination": {
+                "total": total,
+                "page": page,
+                "page_size": page_size,
+                "total_pages": (total + page_size - 1) // page_size,
+                "has_next": end < total,
+                "has_prev": page > 1
+            }
+        }
+
+    except Exception as e:
+        logger.error(f"Failed to list tasks for tenant {tenant_id}: {e}")
+        raise HTTPException(
+            status_code=500,
+            detail="Failed to retrieve tasks"
+        )
diff --git a/main.py b/main.py
@@ -6,6 +6,7 @@
 """
 
 from fastapi import FastAPI
+from fastapi.middleware.cors import CORSMiddleware
 
 # 导入 RAG 相关模块
 from src.rag import lifespan
@@ -94,6 +95,20 @@
     ]
 )
 
+# 添加 CORS middleware（修复前端跨域问题）
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=[
+        "https://main.d2bxt3tjxqfsjq.amplifyapp.com",  # 前端生产域名
+        "http://localhost:3000",  # 本地开发（React）
+        "http://localhost:5173",  # 本地开发（Vite）
+    ],
+    allow_credentials=False,  # 不发送 cookies，降低安全风险
+    allow_methods=["GET", "POST", "PUT", "DELETE", "OPTIONS"],
+    allow_headers=["Content-Type", "Authorization", "X-Request-ID"],
+    max_age=3600,  # 预检请求缓存 1 小时
+)
+
 # 注册 API 路由
 app.include_router(api_router)
 
