docs: 添加 Phase 1 完整实施计划和 OpenSpec

- 添加项目级 CLAUDE.md 和 AGENTS.md 配置 - 添加完整实施计划（docs/architecture/implementation-detail.md） - 创建 OpenSpec phase-1-infrastructure： - proposal.md: 需求和方案 - design.md: 架构设计 - specs/functional-specs.md: 功能规格 - tasks.md: 21 个任务清单 - decisions.md: grill 阶段决策记录 - .commit: 标记为 Committed OpenSpec OpenSpec 已通过 sm-flow 完整流程（clarify → context → propose → grill → specify → audit → commit）
2026-06-23 10:58:11 +08:00
parent 5ddb7a6d93
commit 3f15778b28
9 changed files with 2178 additions and 0 deletions
@@ -0,0 +1,400 @@
+# 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%+）