# Implementation Plan: RAG System Refactoring

## Overview

本实施计划将 RAG 系统重构分为 6 个主要阶段，每个阶段都可以独立部署和验证。重构采用渐进式策略，确保在整个过程中系统保持可用，并且所有 API 接口向后兼容。每个任务都明确引用了相关的需求，确保可追溯性。

## Tasks

- [x] 1. Phase 1: 基础设施搭建
  - [x] 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: 领域层重构
  - [x] 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: 应用层重构
  - [x] 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: 基础设施层迁移
  - [x] 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: 表现层迁移
  - [x] 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: 废弃代码清理和文档
  - [x] 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 向后兼容性是最高优先级
- 建议按顺序执行任务，因为后续任务依赖于前面任务的完成