docs: 重构文档结构，分离学习笔记和 MVP 架构设计

**变更概述：** - 将 MVP 架构设计文档独立到项目根目录 `mvp/` - 整理 `docs/` 为纯学习和分析文档目录 - 按类型分类：learning（学习）、analysis（分析）、reports（报告）、guides（指南） **目录结构：** ``` mvp/ # MVP 架构设计（独立） ├── README.md # 数据库设计总览 ├── architecture/ # 架构文档 │ ├── agent-architecture-mvp.md │ ├── implementation-plan.md │ └── ... └── tables/ # 数据表设计 docs/ # 学习和分析文档 ├── learning/ # 学习笔记（00-08 编号） ├── analysis/ # 分析笔记 + 重构计划 ├── reports/ # 临时报告 └── guides/ # 指南文档 ``` **详细变更：** - docs/README.md → mvp/README.md（数据库设计入口） - docs/architecture/ → mvp/architecture/（架构设计） - docs/tables/ → mvp/tables/（数据表设计） - docs/学习笔记-*.md → docs/learning/07-*.md, 08-*.md - docs/项目学习路径.md → docs/learning/00-*.md - docs/功能分析报告.md → docs/analysis/ - docs/修复报告-*.md → docs/reports/ - docs/日志配置*.md → docs/guides/ 或 docs/reports/ - docs/design/ → docs/analysis/（问题分析和重构计划）
2026-06-23 14:14:51 +08:00
parent caef477cec
commit 60be51f4a5
25 changed files with 339 additions and 606 deletions
@@ -1,400 +1,52 @@
 # Phase 1 Infrastructure - Tasks

-## 任务清单
-
-### Day 1-2: 数据库 + 实体 + 会话（8 个任务）
-
-#### Task 1.1: 添加依赖到 pom.xml
-**优先级**: P0（阻塞后续任务）
-**预估时间**: 15 分钟
-**产出**:
- 修改 `pom.xml`
- 添加：spring-boot-starter-data-jpa, mysql-connector-j, flyway-core, flyway-mysql, spring-boot-starter-data-redis, spring-boot-starter-test, h2
-**验收**: `mvn clean compile` 成功
-
---
-
-#### Task 1.2: 创建 Flyway 迁移脚本 - diagnosis_record
-**优先级**: P0
-**预估时间**: 30 分钟
-**产出**:
- `src/main/resources/db/migration/V001__create_diagnosis_record.sql`
-**依据**: `docs/tables/diagnosis_record.md`
-**验收**:
- 表结构与文档一致
- 索引完整
- 注释完整
- 本地 MySQL 执行成功
-
---
-
-#### Task 1.3: 创建 Flyway 迁移脚本 - case_library
-**优先级**: P0
-**预估时间**: 20 分钟
-**产出**:
- `src/main/resources/db/migration/V002__create_case_library.sql`
-**依据**: `docs/tables/case_library.md`
-**验收**: 同 Task 1.2
-
---
-
-#### Task 1.4: 创建 Flyway 迁移脚本 - api_document
-**优先级**: P0
-**预估时间**: 20 分钟
-**产出**:
- `src/main/resources/db/migration/V003__create_api_document.sql`
-**依据**: `docs/tables/api_document.md`
-**验收**: 同 Task 1.2
-
---
-
-#### Task 1.5: 配置 MySQL + Redis + Flyway
-**优先级**: P0
-**预估时间**: 20 分钟
-**产出**:
- 修改 `src/main/resources/application.yml`
- 添加 spring.datasource, spring.jpa, spring.flyway, spring.data.redis 配置
-**验收**:
- 应用启动成功
- Flyway 自动执行迁移
- 3 张表创建成功
-
---
-
-#### Task 1.6: 创建 JPA 实体类
-**优先级**: P0
-**预估时间**: 45 分钟
-**产出**:
- `com.superbiz.agent.domain.entity.DiagnosisRecord`
- `com.superbiz.agent.domain.entity.CaseLibrary`
- `com.superbiz.agent.domain.entity.ApiDocument`
-**依赖**: Task 1.2, 1.3, 1.4
-**验收**:
- 字段与数据库一致
- Lombok 注解完整
- JSON 字段序列化正确
- 编译通过
-
---
-
-#### Task 1.7: 创建 Repository 接口
-**优先级**: P0
-**预估时间**: 30 分钟
-**产出**:
- `com.superbiz.agent.repository.DiagnosisRecordRepository`
- `com.superbiz.agent.repository.CaseLibraryRepository`
- `com.superbiz.agent.repository.ApiDocumentRepository`
-**依赖**: Task 1.6
-**验收**:
- 继承 JpaRepository
- 常用查询方法定义
- 编译通过
-
---
-
-#### Task 1.8: Repository 单元测试
-**优先级**: P1
-**预估时间**: 60 分钟
-**产出**:
- `DiagnosisRecordRepositoryTest`
- `CaseLibraryRepositoryTest`
- `ApiDocumentRepositoryTest`
-**依赖**: Task 1.7
-**测试框架**: @DataJpaTest + H2
-**验收**:
- 测试覆盖率 100%
- CRUD 测试通过
- 自定义查询测试通过
-
---
-
-#### Task 1.9: 创建会话管理接口
-**优先级**: P0
-**预估时间**: 30 分钟
-**产出**:
- `com.superbiz.agent.session.SessionManager` (接口)
- `com.superbiz.agent.session.SessionContext` (数据类)
- `com.superbiz.agent.session.ToolCall` (数据类)
-**验收**:
- 接口定义清晰
- SessionContext 字段完整（含 intentType）
- 编译通过
-
---
-
-#### Task 1.10: Redis 会话管理实现
-**优先级**: P0
-**预估时间**: 45 分钟
-**产出**:
- `com.superbiz.agent.session.RedisSessionManager`
- `com.superbiz.agent.session.SessionConfiguration`
-**依赖**: Task 1.9
-**验收**:
- 实现 SessionManager 接口
- TTL 设置为 30 分钟
- JSON 序列化配置正确
- 编译通过
-
---
-
-#### Task 1.11: Redis 会话管理单元测试
-**优先级**: P1
-**预估时间**: 45 分钟
-**产出**:
- `RedisSessionManagerTest`
-**依赖**: Task 1.10
-**测试框架**: @SpringBootTest + Mock RedisTemplate
-**验收**:
- 存取删测试通过
- TTL 测试通过
- 序列化测试通过
-
---
-
-### Day 3: 代码结构重构（3 个任务）
-
-#### Task 3.1: 包名重构
-**优先级**: P0
-**预估时间**: 30 分钟
-**操作**:
-1. IDEA Refactor → Rename Package
-2. `org.example` → `com.superbiz.agent`
-3. 更新 `pom.xml` 中的 mainClass
-4. 全局搜索确认无遗漏
-**验收**:
- 编译通过
- 启动成功
- 无遗漏的 org.example
-
---
-
-#### Task 3.2: 分层结构优化
-**优先级**: P1
-**预估时间**: 45 分钟
-**产出**:
- 创建目录结构（controller/service/repository/domain/tool/config/exception）
- 移动现有类到对应目录
-**验收**:
- 目录结构符合 design.md
- 编译通过
- 启动成功
-
---
-
-#### Task 3.3: DTO 抽离
-**优先级**: P1
-**预估时间**: 60 分钟
-**产出**:
- `com.superbiz.agent.domain.dto.DiagnosisRequest`
- `com.superbiz.agent.domain.dto.DiagnosisResponse`
- `com.superbiz.agent.domain.dto.DocumentUploadRequest`
- `com.superbiz.agent.domain.dto.DocumentQueryResponse`
- `com.superbiz.agent.domain.dto.Result<T>` (统一响应)
-**验收**:
- Controller 不 import Entity
- 编译通过
-
---
-
-### Day 4-5: 文档管理（7 个任务）
-
-#### Task 4.1: 创建 TextExtractor 服务
-**优先级**: P0
-**预估时间**: 60 分钟
-**产出**:
- `com.superbiz.agent.service.TextExtractor`
-**功能**:
- 支持 .txt, .md, .docx, .pdf
- 提取纯文本
-**依赖**: 可能需要添加 Apache POI / PDFBox 依赖
-**验收**:
- 4 种格式提取成功
- 单元测试覆盖
-
---
-
-#### Task 4.2: 文档分块服务
-**优先级**: P0
-**预估时间**: 30 分钟
-**产出**:
- `com.superbiz.agent.service.DocumentChunkService` (可能已存在，重构)
-**功能**:
- chunk_size=500
- overlap=50
-**验收**:
- 分块逻辑正确
- 单元测试通过
-
---
-
-#### Task 4.3: 文档上传接口
-**优先级**: P0
-**预估时间**: 90 分钟
-**产出**:
- `com.superbiz.agent.controller.DocumentController#upload`
- `com.superbiz.agent.service.DocumentService#uploadDocument`
-**依赖**: Task 4.1, 4.2
-**验收**:
- 上传成功返回 documentId
- MySQL + Milvus 数据一致
- 异常处理完整
- 单元测试覆盖
-
---
-
-#### Task 4.4: 文档查询接口
-**优先级**: P1
-**预估时间**: 30 分钟
-**产出**:
- `DocumentController#query`
- `DocumentService#queryDocuments`
-**验收**:
- 分页查询正确
- 过滤条件生效
- 单元测试覆盖
-
---
-
-#### Task 4.5: 文档删除接口
-**优先级**: P1
-**预估时间**: 45 分钟
-**产出**:
- `DocumentController#delete`
- `DocumentService#deleteDocument`
-**验收**:
- MySQL 删除成功
- Milvus 删除成功
- 幂等性保证
- 单元测试覆盖
-
---
-
-#### Task 4.6: 混合检索工具
-**优先级**: P0
-**预估时间**: 90 分钟
-**产出**:
- `com.superbiz.agent.tool.DocumentSearchTool`
-**功能**:
- 精确匹配（MySQL）
- 语义检索（Milvus）
- RRF 融合
-**验收**:
- 精确匹配优先
- 语义检索补漏
- 返回 Top 3
- 单元测试覆盖
-
---
-
-#### Task 4.7: 集成测试
-**优先级**: P1
-**预估时间**: 60 分钟
-**产出**:
- `DocumentIntegrationTest`
-**测试场景**:
- 上传 → 查询 → 检索 → 删除 完整流程
-**验收**:
- 端到端测试通过
-
---
-
-### 全局任务
-
-#### Task G.1: 统一异常处理
-**优先级**: P1
-**预估时间**: 30 分钟
-**产出**:
- `com.superbiz.agent.exception.GlobalExceptionHandler`
- `com.superbiz.agent.exception.SessionNotFoundException`
- `com.superbiz.agent.exception.DocumentProcessException`
-**验收**:
- 异常统一捕获
- 返回格式统一
-
---
-
-#### Task G.2: Docker Compose 配置
-**优先级**: P2
-**预估时间**: 20 分钟
-**产出**:
- `docker-compose.yml` (MySQL + Redis + Milvus)
-**验收**:
- `docker-compose up -d` 启动成功
- 应用连接成功
-
---
-
-#### Task G.3: README 更新
-**优先级**: P2
-**预估时间**: 15 分钟
-**产出**:
- 更新 `README.md`
- 添加 Phase 1 安装说明
- 添加本地开发指南
-
---
-
-## 任务依赖关系图
-
-```
-Day 1-2:
-Task 1.1 → Task 1.5
-         ↓
-Task 1.2, 1.3, 1.4 → Task 1.6 → Task 1.7 → Task 1.8
-         ↓
-Task 1.5 → Task 1.9 → Task 1.10 → Task 1.11
-
-Day 3:
-Task 3.1 (阻塞) → Task 3.2 → Task 3.3
-
-Day 4-5:
-Task 4.1, 4.2 → Task 4.3 → Task 4.7
-              ↓
-              Task 4.4
-              ↓
-              Task 4.5
-              ↓
-              Task 4.6 → Task 4.7
-
-全局:
-Task G.1 (并行)
-Task G.2 (并行)
-Task G.3 (最后)
-```
-
---
-
-## 关键路径
-
-```
-Task 1.1 → 1.5 → 1.6 → 1.7 → 3.1 → 3.2 → 4.1 → 4.3 → 4.6 → 4.7
-```
-
---
-
-## 预估总工时
-
- Day 1-2: 5.5 小时（11 个任务）
- Day 3: 2 小时（3 个任务）
- Day 4-5: 6 小时（7 个任务）
- 全局: 1 小时（3 个任务）
-
-**总计**: 14.5 小时（约 2 个完整工作日）
-
---
-
-## 里程碑
-
-**Milestone 1**: Day 2 结束
- ✅ 数据库表就绪
- ✅ JPA + Repository 可用
- ✅ Redis 会话管理可用
-
-**Milestone 2**: Day 3 结束
- ✅ 包名重构完成
- ✅ 代码结构清晰
-
-**Milestone 3**: Day 5 结束
- ✅ 文档管理 CRUD 完整
- ✅ 混合检索工具可用
- ✅ 单元测试覆盖率达标（70%+）
+## 1. 数据库与依赖
+
+- [x] 1.1 添加依赖到 pom.xml (spring-boot-starter-data-jpa, mysql-connector-j, flyway-core, spring-boot-starter-data-redis)
+- [x] 1.2 创建 Flyway 迁移脚本 V001__create_diagnosis_record.sql
+- [x] 1.3 创建 Flyway 迁移脚本 V002__create_case_library.sql
+- [x] 1.4 创建 Flyway 迁移脚本 V003__create_api_document.sql
+- [x] 1.5 配置 MySQL + Redis + Flyway (application.yml)
+
+## 2. JPA 实体与 Repository
+
+- [ ] 2.1 创建 JPA 实体类 DiagnosisRecord
+- [ ] 2.2 创建 JPA 实体类 CaseLibrary
+- [ ] 2.3 创建 JPA 实体类 ApiDocument
+- [ ] 2.4 创建 DiagnosisRecordRepository 接口
+- [ ] 2.5 创建 CaseLibraryRepository 接口
+- [ ] 2.6 创建 ApiDocumentRepository 接口
+- [ ] 2.7 Repository 单元测试 (DiagnosisRecordRepositoryTest)
+- [ ] 2.8 Repository 单元测试 (CaseLibraryRepositoryTest)
+- [ ] 2.9 Repository 单元测试 (ApiDocumentRepositoryTest)
+
+## 3. 会话管理
+
+- [ ] 3.1 创建 SessionManager 接口
+- [ ] 3.2 创建 SessionContext 数据类
+- [ ] 3.3 创建 ToolCall 数据类
+- [ ] 3.4 创建 RedisSessionManager 实现
+- [ ] 3.5 创建 SessionConfiguration 配置类
+- [ ] 3.6 Redis 会话管理单元测试 (RedisSessionManagerTest)
+
+## 4. 代码结构重构
+
+- [ ] 4.1 包名重构 (org.example → com.superbiz.agent)
+- [ ] 4.2 分层结构优化 (controller/service/repository/domain/tool/config/exception)
+- [ ] 4.3 创建 DTO 类 (DiagnosisRequest, DiagnosisResponse, DocumentUploadRequest, DocumentQueryResponse, Result)
+
+## 5. 文档管理服务
+
+- [ ] 5.1 创建 TextExtractor 服务 (支持 .txt, .md, .docx, .pdf)
+- [ ] 5.2 文档分块服务 (DocumentChunkService, chunk_size=500, overlap=50)
+- [ ] 5.3 文档上传接口 (DocumentController#upload, DocumentService#uploadDocument)
+- [ ] 5.4 文档查询接口 (DocumentController#query, DocumentService#queryDocuments)
+- [ ] 5.5 文档删除接口 (DocumentController#delete, DocumentService#deleteDocument)
+- [ ] 5.6 混合检索工具 (DocumentSearchTool: 精确匹配 + 语义检索 + RRF 融合)
+- [ ] 5.7 文档管理集成测试 (DocumentIntegrationTest)
+
+## 6. 全局完善
+
+- [ ] 6.1 统一异常处理 (GlobalExceptionHandler, SessionNotFoundException, DocumentProcessException)
+- [ ] 6.2 Docker Compose 配置 (MySQL + Redis + Milvus)
+- [ ] 6.3 更新 README.md (Phase 1 安装说明与本地开发指南)