SuperBizAgent-java/openspec/changes/phase-1-infrastructure/tasks.md

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%+）