tasks.md 19 KB
Implementation Plan: RAG System Refactoring
Overview
本实施计划将 RAG 系统重构分为 6 个主要阶段，每个阶段都可以独立部署和验证。重构采用渐进式策略，确保在整个过程中系统保持可用，并且所有 API 接口向后兼容。每个任务都明确引用了相关的需求，确保可追溯性。
Tasks
[x] 1. Phase 1: 基础设施搭建
- 1.1 创建新的目录结构
- 创建 src/ 目录及其子目录（domain/, application/, infrastructure/, presentation/, config/, shared/）
- 创建 tests/ 目录及其子目录（unit/, integration/, e2e/, fixtures/）
- 创建 docs/, scripts/, docker/ 目录
- 在每个目录中创建 init.py 文件
Requirements: 1.1, 8.1, 8.2, 8.3, 8.4
[x] 1.2 设置配置管理系统
创建 config/settings.py，定义 Settings、DatabaseSettings、InfinitySettings、ElasticsearchSettings 类
使用 Pydantic BaseSettings 实现配置加载和验证
实现 get_settings() 函数返回配置单例
创建 .env.example 文件，列出所有配置项
Requirements: 2.1, 2.2, 2.4, 2.5
[ ]* 1.3 编写配置管理单元测试
测试配置从环境变量、配置文件和默认值的加载
测试配置验证（无效值应抛出错误）
测试配置优先级（环境变量 > 配置文件 > 默认值）
Requirements: 2.2, 2.4, 2.5
[x] 1.4 建立测试框架
安装测试依赖（pytest, pytest-asyncio, pytest-cov, hypothesis, httpx）
创建 tests/conftest.py，定义全局测试夹具
创建 pytest.ini，配置测试选项和标记
配置覆盖率报告
Requirements: 7.6
[x] 1.5 配置日志系统
安装 structlog 库
创建 config/logging.py，配置结构化日志
实现日志处理器（控制台、文件、远程）
定义日志格式（JSON 格式，包含请求 ID、时间戳等）
Requirements: 6.3, 6.5, 6.6
[ ]* 1.6 编写日志系统测试
测试日志输出格式
测试日志级别过滤
测试多目标输出
Requirements: 6.3, 6.5, 6.6
[x] 1.7 配置 CI/CD 流水线
创建 .github/workflows/test.yml
配置自动运行单元测试、集成测试、端到端测试
配置覆盖率上传到 Codecov
Requirements: 7.6
[x] 2. Checkpoint - 验证基础设施
- 确保所有测试通过，配置系统正常工作，询问用户是否有问题
[x] 3. Phase 2: 领域层重构
- 3.1 创建共享领域概念
- 创建 domain/shared/value_objects.py，定义 ID、Timestamp 等共享值对象
- 创建 domain/shared/exceptions.py，定义 DomainException、InvalidValueException、BusinessRuleViolationException
Requirements: 1.3, 6.1
[x] 3.2 实现向量搜索领域模型
创建 domain/vector_search/value_objects.py，实现 Vector 和 SearchQuery 值对象
创建 domain/vector_search/entities.py，实现 Document 和 SearchResult 实体
实现实体的业务逻辑方法（如 Document.update_content()）
创建 domain/vector_search/exceptions.py，定义领域异常
Requirements: 1.3, 8.1
[ ]* 3.3 编写向量搜索领域模型单元测试
测试 Vector 值对象的创建和验证
测试 Vector 的不可变性
测试 SearchQuery 的创建和验证
测试 Document 实体的业务逻辑
Requirements: 1.3, 8.1
[ ]* 3.4 编写向量搜索领域模型属性测试
Property: Vector dimension count equals list length
Validates: Requirements 1.3
[x] 3.5 定义向量搜索仓储接口
创建 domain/vector_search/repositories.py，定义 DocumentRepository 抽象类
定义仓储方法（save, find_by_id, delete, search）
Requirements: 3.1, 8.1
[x] 3.6 实现向量搜索领域服务
创建 domain/vector_search/services.py，实现 HybridSearchService
实现混合搜索的分数合并逻辑
Requirements: 1.3, 8.3
[ ]* 3.7 编写混合搜索服务单元测试
测试分数合并算法
测试结果排序
Requirements: 8.3
[x] 3.8 实现文档解析领域模型
创建 domain/document_parsing/value_objects.py，定义 DocumentType 枚举
创建 domain/document_parsing/entities.py，实现 ParsedDocument 和 DocumentChunk 实体
实现实体的业务逻辑方法（如 ParsedDocument.add_chunk(), validate()）
Requirements: 1.3, 8.2
[ ]* 3.9 编写文档解析领域模型单元测试
测试 ParsedDocument 的创建和验证
测试 DocumentChunk 的创建
测试文档块添加逻辑
Requirements: 8.2
[x] 3.10 定义文档解析领域服务接口
创建 domain/document_parsing/services.py，定义 DocumentParser 和 ChunkingStrategy 抽象类
Requirements: 3.1, 8.2
[x] 3.11 实现知识库领域模型
创建 domain/knowledge_base/entities.py，实现 KnowledgeBase 和 PromptDimension 实体
实现实体的业务逻辑方法（如 add_document(), remove_document(), add_tag()）
Requirements: 1.3, 8.4
[ ]* 3.12 编写知识库领域模型单元测试
测试 KnowledgeBase 的文档管理
测试标签管理
测试业务规则（如文档 ID 不重复）
Requirements: 8.4
[x] 4. Checkpoint - 验证领域层
- 确保领域层测试覆盖率 ≥ 90%，无外部依赖，询问用户是否有问题
[x] 5. Phase 3: 应用层重构
- 5.1 创建共享应用层概念
- 创建 application/shared/interfaces.py，定义 CommandHandler、QueryHandler 协议
- 创建 application/shared/exceptions.py，定义 ApplicationException、ResourceNotFoundException、ValidationException
Requirements: 1.4, 6.1
[x] 5.2 实现向量搜索命令和查询
创建 application/vector_search/commands.py，定义 CreateDocumentCommand、UpdateDocumentCommand、DeleteDocumentCommand
创建 application/vector_search/queries.py，定义 SearchDocumentsQuery、GetDocumentQuery
Requirements: 1.4, 8.1
[x] 5.3 实现向量搜索 DTO
创建 application/vector_search/dtos.py，定义 DocumentDTO
实现 DTO 与领域实体的转换方法
Requirements: 1.4, 8.1
[x] 5.4 实现向量搜索命令处理器
创建 application/vector_search/handlers.py，实现 CreateDocumentHandler
实现 UpdateDocumentHandler 和 DeleteDocumentHandler
注入仓储和领域服务依赖
Requirements: 1.4, 3.2, 8.1
[ ]* 5.5 编写向量搜索命令处理器单元测试
使用 Mock 仓储测试命令处理逻辑
测试异常处理
Requirements: 1.4, 8.1
[x] 5.6 实现向量搜索查询处理器
在 application/vector_search/handlers.py 中实现 SearchDocumentsHandler 和 GetDocumentHandler
实现混合搜索逻辑
Requirements: 1.4, 8.1, 8.3
[ ]* 5.7 编写向量搜索查询处理器单元测试
使用 Mock 仓储测试查询处理逻辑
测试混合搜索逻辑
Requirements: 1.4, 8.1, 8.3
[x] 5.8 实现文档解析应用服务
创建 application/document_parsing/commands.py，定义 ParseDocumentCommand
创建 application/document_parsing/handlers.py，实现 ParseDocumentHandler
创建 application/document_parsing/dtos.py，定义 ParsedDocumentDTO
Requirements: 1.4, 8.2
[ ]* 5.9 编写文档解析应用服务单元测试
测试文档解析命令处理
测试 DTO 转换
Requirements: 8.2
[x] 5.10 实现知识库应用服务
创建 application/knowledge_base/commands.py，定义知识库管理命令
创建 application/knowledge_base/handlers.py，实现命令处理器
创建 application/knowledge_base/dtos.py，定义 KnowledgeBaseDTO
Requirements: 1.4, 8.4
[ ]* 5.11 编写知识库应用服务单元测试
测试知识库管理逻辑
测试 DTO 转换
Requirements: 8.4
[x] 6. Checkpoint - 验证应用层
- 确保应用层测试覆盖率 ≥ 85%，询问用户是否有问题
[x] 7. Phase 4: 基础设施层迁移
- 7.1 创建向量数据库抽象基类
- 创建 infrastructure/vector_db/base.py，定义 VectorDatabase 抽象类
- 定义向量数据库接口方法（connect, create_index, insert, search）
Requirements: 1.5, 3.1, 3.4, 8.1
[x] 7.2 实现 Infinity 向量数据库适配器
创建 infrastructure/vector_db/infinity.py，实现 InfinityVectorDB 类
实现所有抽象方法
处理 Infinity 特定的错误和异常
Requirements: 1.5, 3.4, 8.1
[ ]* 7.3 编写 Infinity 适配器集成测试
使用 Docker 容器启动 Infinity 测试实例
测试连接、索引创建、插入和搜索
Requirements: 8.1
[x] 7.4 实现 Elasticsearch 向量数据库适配器
创建 infrastructure/vector_db/elasticsearch.py，实现 ElasticsearchVectorDB 类
实现所有抽象方法
处理 Elasticsearch 特定的错误和异常
Requirements: 1.5, 3.4, 8.1
[ ]* 7.5 编写 Elasticsearch 适配器集成测试
使用 Docker 容器启动 Elasticsearch 测试实例
测试连接、索引创建、插入和搜索
Requirements: 8.1
[x] 7.6 创建数据库模型
创建 infrastructure/database/models.py，定义 SQLAlchemy ORM 模型
定义 DocumentModel、KnowledgeBaseModel 和关联表
Requirements: 1.5, 8.1, 8.4
[x] 7.7 实现数据库会话管理
创建 infrastructure/database/session.py，实现数据库连接和会话管理
实现 get_session_factory() 函数
Requirements: 1.5
[x] 7.8 实现文档仓储
创建 infrastructure/database/repositories.py，实现 SQLDocumentRepository 类
实现 DocumentRepository 接口的所有方法
集成向量数据库和关系数据库
Requirements: 1.5, 3.4, 8.1
[ ]* 7.9 编写文档仓储集成测试
使用测试数据库测试仓储方法
测试保存、查找、删除、搜索功能
Requirements: 8.1
[x] 7.10 实现知识库仓储
在 infrastructure/database/repositories.py 中实现 SQLKnowledgeBaseRepository 类
实现知识库管理方法
Requirements: 1.5, 3.4, 8.4
[ ]* 7.11 编写知识库仓储集成测试
测试知识库的 CRUD 操作
测试文档关联
Requirements: 8.4
[x] 7.12 实现文档解析器
创建 infrastructure/parsers/base.py，定义 BaseParser 抽象类
创建 infrastructure/parsers/pdf_parser.py，实现 PDFParser
创建 infrastructure/parsers/image_parser.py，实现 ImageParser
Requirements: 1.5, 8.2
[ ]* 7.13 编写文档解析器集成测试
使用测试文件测试 PDF 解析
测试图片解析
Requirements: 8.2
[x] 7.14 实现外部服务集成
创建 infrastructure/external_services/base.py，定义 BaseExternalService
创建 infrastructure/external_services/ragflow.py，实现 Ragflow 集成
创建 infrastructure/external_services/dify.py，实现 Dify 集成
Requirements: 1.5, 8.4
[ ]* 7.15 编写外部服务集成测试
使用 Mock 服务器测试外部服务调用
测试错误处理和重试逻辑
Requirements: 8.4
[x] 7.16 实现文件存储
创建 infrastructure/file_storage/base.py，定义 FileStorage 抽象类
创建 infrastructure/file_storage/local.py，实现本地文件存储
创建 infrastructure/file_storage/s3.py，实现 S3 存储
Requirements: 1.5
[ ]* 7.17 编写文件存储集成测试
测试本地文件存储
使用 MinIO 测试 S3 存储
Requirements: 1.5
[x] 8. Checkpoint - 验证基础设施层
- 确保所有基础设施组件有具体实现，集成测试通过，询问用户是否有问题
[x] 9. Phase 5: 表现层迁移
- 9.1 创建请求和响应模型
- 创建 presentation/schemas/requests.py，定义所有 API 请求模型
- 创建 presentation/schemas/responses.py，定义所有 API 响应模型
- 创建 presentation/schemas/common.py，定义共享模式（如 ErrorResponse）
Requirements: 1.6, 4.1, 4.2
[x] 9.2 实现依赖注入函数
创建 presentation/api/dependencies.py，实现所有依赖注入函数
实现 get_vector_db(), get_document_repository(), get_create_document_handler() 等
使用 FastAPI 的 Depends 机制
Requirements: 1.6, 3.2, 3.5
[x] 9.3 实现错误处理器
创建 presentation/api/error_handlers.py，实现异常处理器
实现 domain_exception_handler, application_exception_handler, generic_exception_handler
注册错误处理器到 FastAPI 应用
Requirements: 1.6, 6.2
[ ]* 9.4 编写错误处理器单元测试
测试不同异常类型的转换
测试错误响应格式
Requirements: 6.2
[x] 9.5 实现请求日志中间件
创建 presentation/api/middleware.py，实现 RequestLoggingMiddleware
记录请求开始、完成和失败
添加请求 ID 和 API 版本到响应头
Requirements: 1.6, 4.5, 6.3, 11.4
[ ]* 9.6 编写请求日志中间件测试
测试日志记录
测试响应头添加
Requirements: 4.5, 6.3, 11.4
[x] 9.7 实现向量搜索 API 路由
创建 presentation/api/v1/vector_search.py，实现文档管理端点
实现 POST /api/v1/documents/（创建文档）
实现 GET /api/v1/documents/{id}（获取文档）
实现 PUT /api/v1/documents/{id}（更新文档）
实现 DELETE /api/v1/documents/{id}（删除文档）
实现 POST /api/v1/documents/search（搜索文档）
Requirements: 1.6, 4.1, 4.2, 8.1
[ ]* 9.8 编写向量搜索 API 端到端测试
测试完整的文档生命周期（创建 → 搜索 → 更新 → 删除）
测试 API 响应格式
测试错误处理
Requirements: 4.1, 4.2, 8.1
[x] 9.9 实现文档解析 API 路由
创建 presentation/api/v1/documents.py，实现文档解析端点
实现 POST /api/v1/documents/parse（解析文档）
实现文件上传处理
Requirements: 1.6, 4.1, 4.2, 8.2
[ ]* 9.10 编写文档解析 API 端到端测试
测试 PDF 文档上传和解析
测试图片文档上传和解析
Requirements: 4.1, 4.2, 8.2
[x] 9.11 实现知识库 API 路由
创建 presentation/api/v1/knowledge_base.py，实现知识库管理端点
实现 POST /api/v1/knowledge-bases/（创建知识库）
实现 GET /api/v1/knowledge-bases/{id}（获取知识库）
实现 PUT /api/v1/knowledge-bases/{id}（更新知识库）
实现 DELETE /api/v1/knowledge-bases/{id}（删除知识库）
实现 POST /api/v1/knowledge-bases/{id}/documents（添加文档）
Requirements: 1.6, 4.1, 4.2, 8.4
[ ]* 9.12 编写知识库 API 端到端测试
测试知识库的 CRUD 操作
测试文档添加和移除
Requirements: 4.1, 4.2, 8.4
[x] 9.13 实现健康检查和指标端点
创建 presentation/api/v1/health.py，实现健康检查端点
实现 GET /health（健康检查）
实现 GET /metrics（性能指标）
Requirements: 1.6, 11.2, 11.3
[ ]* 9.14 编写健康检查和指标端点测试
测试健康检查响应
测试指标端点响应
Requirements: 11.2, 11.3
[x] 9.15 创建 FastAPI 应用主文件
创建 src/main.py，初始化 FastAPI 应用
注册所有路由
注册中间件和错误处理器
配置 CORS、OpenAPI 文档等
Requirements: 1.6, 9.6
[x] 9.16 实现向后兼容性适配器
如果旧 API 路径与新路径不同，创建适配器路由
确保所有旧端点仍然可用
在旧端点中添加废弃警告日志
Requirements: 4.1, 4.2, 10.4
[ ]* 9.17 编写 API 向后兼容性测试
加载重构前的 API 规范（OpenAPI）
对比重构后的 API 规范
验证所有旧端点仍然存在且行为一致
Requirements: 4.1, 4.2
[x] 10. Checkpoint - 验证表现层
- 确保所有 API 端点迁移完成，向后兼容性测试通过，询问用户是否有问题
[x] 11. Phase 6: 废弃代码清理和文档
- 11.1 标记旧代码为废弃
- 在旧代码模块中添加 @deprecated 装饰器或注释
- 在旧代码被调用时记录废弃警告日志
Requirements: 10.3, 10.4
[ ]* 11.2 编写废弃警告测试
测试调用废弃代码时是否记录警告
Requirements: 10.4
[x] 11.3 更新所有导入引用
搜索并替换所有指向旧模块的导入语句
更新为指向新模块
Requirements: 10.6
[x] 11.4 删除未使用的旧代码
确认新代码稳定后，删除旧代码文件
删除旧的 api/sdk、api/db、api/dataset 等目录
Requirements: 10.5
[x] 11.5 创建架构文档
创建 docs/architecture.md，描述分层架构和模块职责
包含架构图和设计决策
Requirements: 9.1
[x] 11.6 创建 API 文档
创建 docs/api.md，描述所有 API 端点
使用 FastAPI 自动生成 OpenAPI 文档
Requirements: 9.3, 9.6
[x] 11.7 创建部署文档
创建 docs/deployment.md，说明如何配置和部署系统
包含环境变量配置、Docker 部署等
Requirements: 9.4
[x] 11.8 创建开发指南
创建 docs/development.md，说明如何设置开发环境和运行测试
包含代码规范、提交规范等
Requirements: 9.5
[x] 11.9 更新 README.md
更新项目说明
添加快速开始指南
添加文档链接
Requirements: 9.1
[x] 11.10 添加公共 API 文档字符串
为所有公共类、函数和方法添加 docstring
使用 Google 风格或 NumPy 风格
Requirements: 9.2
[ ]* 11.11 验证文档完整性
使用工具检查所有公共 API 是否有 docstring
Requirements: 9.2
[x] 11.12 运行性能基准测试
对关键 API 端点运行性能测试
比较重构前后的响应时间
确保性能没有显著退化
Requirements: 11.1, 11.6
[ ]* 11.13 验证测试覆盖率
运行覆盖率报告
确保总体覆盖率 ≥ 80%
确保领域层覆盖率 ≥ 90%
Requirements: 7.4
[x] 11.14 创建数据库迁移脚本
使用 Alembic 创建数据库迁移脚本
测试迁移脚本在测试环境
Requirements: 1.5
[x] 11.15 创建 Docker 配置
创建 docker/Dockerfile
创建 docker/docker-compose.yml
包含应用、数据库、向量数据库等服务
Requirements: 9.4
[x] 12. Final Checkpoint - 完整系统验证
- 运行完整的测试套件（单元、集成、端到端）
- 验证所有功能正常工作
- 验证 API 向后兼容性
- 验证性能指标
- 询问用户是否准备好部署
Notes
- 任务标记
*的为可选任务（主要是测试任务），可以跳过以加快 MVP 交付 - 每个任务都引用了具体的需求，确保可追溯性
- Checkpoint 任务用于在关键阶段验证系统状态
- 重构采用渐进式策略，每个阶段都可以独立部署
- 在整个重构过程中，保持 API 向后兼容性是最高优先级
- 建议按顺序执行任务，因为后续任务依赖于前面任务的完成