mirror of https://github.com/HKUDS/LightRAG.git synced 2025-11-16 01:55:08 +00:00

yangdx 74eecc46e5 feat(pagination): Implement document list pagination backends and frontend UI

- Add pagination support to BaseDocStatusStorage interface and all implementations (PostgreSQL, MongoDB, Redis, JSON)
- Implement RESTful API endpoints for paginated document queries and status counts
- Create reusable pagination UI components with internationalization support
- Optimize performance with database-level pagination and efficient in-memory processing
- Maintain backward compatibility while adding configurable page sizes (10-200 items)

2025-07-30 17:58:32 +08:00

7.7 KiB

Raw Blame History

文档列表页面分页显示功能改造方案

一、改造目标

问题现状

当前文档页面一次性加载所有文档，导致大量文档时界面加载慢
前端内存占用过大，用户操作体验差
状态过滤和排序都在前端进行，效率低下

改造目标

实现后端分页查询，减少单次数据传输量
添加分页控制组件，支持翻页和跳转功能
允许用户设置每页显示行数（10-200条）
保持现有状态过滤和排序功能不变
提升大数据量场景下的性能表现

二、总体架构设计

设计原则

统一分页接口：后端提供统一的分页API，支持状态过滤和排序
智能刷新策略：根据处理状态选择合适的刷新频率和范围
即时用户反馈：状态切换、分页操作提供立即响应
向后兼容：保持现有功能完整性，不影响现有操作流程
性能优化：减少内存占用，优化网络请求

技术方案

后端：在现有存储层基础上添加分页查询接口
前端：改造DocumentManager组件，添加分页控制
数据流：统一分页查询 + 独立状态计数查询

三、后端改造步骤

步骤1：存储层接口扩展

改动文件：lightrag/kg/base.py

关键思路：

在BaseDocStatusStorage抽象类中添加分页查询方法
设计统一的分页接口，支持状态过滤、排序、分页参数
返回文档列表和总数量的元组

接口设计要点：

get_docs_paginated(status_filter, page, page_size, sort_field, sort_direction) -> (documents, total_count)
count_by_status(status) -> int
get_all_status_counts() -> Dict[str, int]

步骤2：各存储后端实现

改动文件：

lightrag/kg/postgres_impl.py
lightrag/kg/mongo_impl.py
lightrag/kg/redis_impl.py
lightrag/kg/json_doc_status_impl.py

PostgreSQL实现要点：

使用LIMIT和OFFSET实现分页
构建动态WHERE条件支持状态过滤
使用COUNT查询获取总数量
添加合适的数据库索引优化查询性能

MongoDB实现要点：

使用skip()和limit()实现分页
使用聚合管道进行状态统计
优化查询条件和索引

Redis 与 Json实现要点：

考虑先用简单的方式实现，即把所有文件清单读到内存中后进行过滤和排序

关键考虑：

确保各存储后端的分页逻辑一致性
处理边界情况（空结果、超出页码范围等）
优化查询性能，避免全表扫描

步骤3：API路由层改造

改动文件：lightrag/api/routers/document_routes.py

新增接口：

POST /documents/paginated - 分页查询文档
GET /documents/status_counts - 获取状态计数

数据模型设计：

DocumentsRequest：分页请求参数
PaginatedDocsResponse：分页响应数据
PaginationInfo：分页元信息

关键逻辑：

参数验证（页码范围、页面大小限制）
并行查询分页数据和状态计数
错误处理和异常响应

步骤4：数据库优化

索引策略：

为workspace + status + updated_at创建复合索引
为workspace + status + created_at创建复合索引
为workspace + updated_at创建索引
为workspace + created_at创建索引

性能考虑：

避免深度分页的性能问题
考虑添加缓存层优化状态计数查询
监控查询性能，必要时调整索引策略

四、前端改造步骤

步骤1：API客户端扩展

改动文件：lightrag_webui/src/api/lightrag.ts

新增函数：

getDocumentsPaginated() - 分页查询文档
getDocumentStatusCounts() - 获取状态计数

类型定义：

定义分页请求和响应的TypeScript类型
确保类型安全和代码提示

步骤2：分页控制组件开发

新增文件：lightrag_webui/src/components/ui/PaginationControls.tsx

组件功能：

支持紧凑模式和完整模式
页码输入和跳转功能
每页显示数量选择（10-200）
总数信息显示
禁用状态处理

设计要点：

响应式设计，适配不同屏幕尺寸
防抖处理，避免频繁请求
错误处理和状态回滚
组件摆放位置：目前状态按钮上方，与scan按钮同一层，居中摆放

步骤3：状态过滤按钮优化

改动文件：现有状态过滤相关组件

优化要点：

添加加载状态指示
数据不足时的智能提示
定期刷新数据，状态切换时如果最先的状态数据距离上次刷新数据超过5秒应即时刷新数据
防止重复点击和并发请求

步骤4：主组件DocumentManager改造

改动文件：lightrag_webui/src/features/DocumentManager.tsx

核心改动：

状态管理重构：

将docs状态改为currentPageDocs（仅存储当前页数据）
添加pagination状态管理分页信息
添加statusCounts状态独立管理状态计数
添加加载状态管理（isStatusChanging, isRefreshing）

数据获取策略：

实现智能刷新：活跃期完整刷新，稳定期轻量刷新
状态切换时立即刷新数据
分页操作时立即更新数据
定期刷新与手动操作协调

布局调整：

将分页控制组件放置在顶部操作栏中间位置
保持状态过滤按钮在表格上方
确保响应式布局适配

事件处理优化：

状态切换时，如果当前页码数据不足，则重置到第一页
页面大小变更时智能计算新页码
错误时状态回滚机制

五、用户体验优化

即时反馈机制

状态切换时显示加载动画
分页操作时提供视觉反馈
数据不足时智能提示用户

错误处理策略

网络错误时自动重试
操作失败时状态回滚
友好的错误提示信息

性能优化措施

防抖处理频繁操作
智能刷新策略减少不必要请求
组件卸载时清理定时器和请求

六、兼容性保障

向后兼容

保留原有的/documents接口作为备用
现有功能（排序、过滤、选择）保持不变
渐进式升级，支持配置开关

数据一致性

确保分页数据与状态计数同步
处理并发更新的数据一致性问题
定期刷新保持数据最新

七、测试策略

功能测试

各种分页场景测试
状态过滤组合测试
排序功能验证
边界条件测试

性能测试

大数据量场景测试
并发访问压力测试
内存使用情况监控
响应时间测试

兼容性测试

不同存储后端测试
不同浏览器兼容性
移动端响应式测试

八、关键实现细节

后端分页查询设计

统一接口：所有存储后端实现相同的分页接口签名
参数验证：严格验证页码、页面大小、排序参数的合法性
性能优化：使用数据库原生分页功能，避免应用层分页
错误处理：统一的错误响应格式和异常处理机制

前端状态管理策略

数据分离：当前页数据与状态计数分别管理
智能刷新：根据文档处理状态选择刷新策略
状态同步：确保UI状态与后端数据保持一致
错误恢复：操作失败时自动回滚到之前状态

分页控制组件设计

紧凑布局：适配顶部操作栏的空间限制
响应式设计：在不同屏幕尺寸下自适应布局
交互优化：防抖处理、加载状态、禁用状态管理
可访问性：支持键盘导航和屏幕阅读器

数据库索引优化

复合索引：workspace + status + sort_field的组合索引
覆盖索引：尽可能使用覆盖索引减少回表查询
索引监控：定期监控索引使用情况和查询性能
渐进优化：根据实际使用情况调整索引策略

7.7 KiB Raw Blame History Unescape Escape