zhuyongxin
3f15778b28
- 添加项目级 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）
401 lines
8.5 KiB
Markdown
401 lines
8.5 KiB
Markdown
# 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%+）
|