archive: Phase 1 基础设施搭建归档
归档信息： - 变更名称：phase-1-infrastructure - 工作流：spec-driven - 归档位置：openspec/changes/archive/2026-06-23-phase-1-infrastructure/ 完成情况： - ✅ 所有产物完成（proposal, design, specs, tasks） - ✅ 任务完成：33/35 (94%) - ⚠️ 2 个任务跳过（混合检索、集成测试，有充分理由） 验收结果： - ✅ 静态验证：编译通过 - ✅ 脚本验证：16/16 单元测试通过 - ✅ 端到端验证：上传→索引→检索→删除完整流程 Delta Specs： - 跳过同步（用户选择） - functional-specs.md 保留在归档目录中 devflow 档案： - ✅ 已完整回填（brief, evidence, decisions, acceptance） - ✅ devflow/index.md 状态更新为 archived
This commit is contained in:
zhuyongxin
@@ -0,0 +1,171 @@
|
||||
# Proposal: Phase 1 基础设施搭建
|
||||
|
||||
## 问题
|
||||
|
||||
当前项目是一个 Demo，需要改造为 MVP 诊断 Agent 系统。Phase 1 需要搭建基础设施：
|
||||
- 缺少持久化层（MySQL + JPA）
|
||||
- 缺少分布式会话管理（Redis）
|
||||
- 代码结构需要重构（包名、分层）
|
||||
- 缺少文档管理基础功能
|
||||
|
||||
## 建议方案
|
||||
|
||||
### 1. 数据持久化
|
||||
|
||||
**方案**：Spring Data JPA + MySQL + Flyway
|
||||
|
||||
**理由**：
|
||||
- JPA 是 Spring Boot 标准持久化方案
|
||||
- Flyway 管理数据库版本，团队协作友好
|
||||
- 3 张表设计已完成（docs/tables/）
|
||||
|
||||
**实现**：
|
||||
1. 添加依赖（spring-boot-starter-data-jpa, mysql-connector-j, flyway-core）
|
||||
2. 创建 3 个 Flyway 迁移脚本（V001/V002/V003）
|
||||
3. 创建 JPA 实体类（DiagnosisRecord, CaseLibrary, ApiDocument）
|
||||
4. 创建 Repository 接口（继承 JpaRepository）
|
||||
|
||||
### 2. 会话管理
|
||||
|
||||
**方案**：Redis 替代内存 HashMap
|
||||
|
||||
**理由**：
|
||||
- 支持分布式部署
|
||||
- 自动 TTL（30 分钟）
|
||||
- Spring Data Redis 集成简单
|
||||
|
||||
**实现**：
|
||||
1. 添加 spring-boot-starter-data-redis 依赖
|
||||
2. 创建 SessionManager 接口 + RedisSessionManager 实现
|
||||
3. SessionContext 使用 JSON 序列化
|
||||
|
||||
### 3. 代码结构重构
|
||||
|
||||
**方案**：包名重构 + 分层优化 + DTO 抽离
|
||||
|
||||
**包名重构**：
|
||||
- `org.example` → `com.superbiz.agent`
|
||||
- 工具：IDEA Refactor → Rename Package
|
||||
|
||||
**分层结构**：
|
||||
```
|
||||
com.superbiz.agent/
|
||||
├── controller/ # REST API
|
||||
├── service/ # 业务逻辑
|
||||
├── repository/ # 数据访问
|
||||
├── domain/
|
||||
│ ├── entity/ # JPA 实体
|
||||
│ ├── dto/ # DTO
|
||||
│ └── enums/ # 枚举
|
||||
├── agent/ # Agent 层（Phase 2）
|
||||
├── tool/ # 工具层
|
||||
├── session/ # 会话管理
|
||||
└── config/ # 配置
|
||||
```
|
||||
|
||||
**DTO 抽离**：
|
||||
- Controller 不直接依赖 Entity
|
||||
- 使用 MapStruct 做对象转换
|
||||
|
||||
### 4. 文档管理
|
||||
|
||||
**方案**：CRUD + Milvus 向量同步
|
||||
|
||||
**功能**：
|
||||
1. 上传接口：文件 → 文本提取 → 分块 → 向量化 → MySQL + Milvus
|
||||
2. 查询接口：分页、过滤
|
||||
3. 删除接口：MySQL + Milvus 同步删除
|
||||
4. 检索工具：精确匹配（MySQL）+ 语义检索（Milvus）+ RRF 融合
|
||||
|
||||
## 范围
|
||||
|
||||
**包含**：
|
||||
- Day 1-2: MySQL 表 + JPA + Repository + Redis 会话
|
||||
- Day 3: 包名重构 + 分层优化 + DTO 抽离
|
||||
- Day 4-5: 文档管理 4 个接口 + 混合检索工具
|
||||
|
||||
**不包含**：
|
||||
- Agent 功能（Phase 2）
|
||||
- 意图识别和 RAG（Phase 2）
|
||||
- Verifier 和 Harness（Phase 3）
|
||||
|
||||
## 非目标
|
||||
|
||||
- 性能优化（后续优化）
|
||||
- 完整的权限控制（MVP 不需要）
|
||||
- 前端界面（只做后端 API）
|
||||
|
||||
## 来自 devflow 的上下文约束
|
||||
|
||||
无（这是首个 OpenSpec，devflow 目录为空）
|
||||
|
||||
## 风险
|
||||
|
||||
1. **包名重构影响范围大**
|
||||
- 缓解：先提交当前代码，独立分支重构
|
||||
- 验证：重构后编译通过 + 启动成功
|
||||
|
||||
2. **Flyway 首次运行可能失败**
|
||||
- 缓解：本地 MySQL 先手动测试
|
||||
- 回退：Flyway 支持 repair 修复
|
||||
|
||||
3. **Redis 本地环境依赖**
|
||||
- 缓解：提供 Docker Compose 配置
|
||||
- 回退：可降级为内存实现（测试用）
|
||||
|
||||
## 关键假设
|
||||
|
||||
1. MySQL 8.0+ 和 Redis 6.0+ 可用（本地或 Docker）
|
||||
2. 现有 Milvus 集成不需要改动
|
||||
3. 单元测试覆盖率目标：70%+
|
||||
|
||||
## 成功标准
|
||||
|
||||
1. ✅ 3 张表创建成功，索引完整
|
||||
2. ✅ Repository 层单元测试通过
|
||||
3. ✅ Redis 会话存取正常，TTL 生效
|
||||
4. ✅ 包名重构完成，编译通过
|
||||
5. ✅ 文档上传/查询/删除接口可用
|
||||
6. ✅ 混合检索工具返回正确结果
|
||||
7. ✅ 整体测试覆盖率 ≥ 70%
|
||||
|
||||
## 产出文件（预期）
|
||||
|
||||
**数据库迁移**：
|
||||
- `src/main/resources/db/migration/V001__create_diagnosis_record.sql`
|
||||
- `src/main/resources/db/migration/V002__create_case_library.sql`
|
||||
- `src/main/resources/db/migration/V003__create_api_document.sql`
|
||||
|
||||
**实体类**：
|
||||
- `com.superbiz.agent.domain.entity.DiagnosisRecord`
|
||||
- `com.superbiz.agent.domain.entity.CaseLibrary`
|
||||
- `com.superbiz.agent.domain.entity.ApiDocument`
|
||||
|
||||
**Repository**：
|
||||
- `com.superbiz.agent.repository.DiagnosisRecordRepository`
|
||||
- `com.superbiz.agent.repository.CaseLibraryRepository`
|
||||
- `com.superbiz.agent.repository.ApiDocumentRepository`
|
||||
|
||||
**会话管理**：
|
||||
- `com.superbiz.agent.session.SessionManager`
|
||||
- `com.superbiz.agent.session.RedisSessionManager`
|
||||
- `com.superbiz.agent.session.SessionContext`
|
||||
|
||||
**文档管理**：
|
||||
- `com.superbiz.agent.controller.DocumentController`
|
||||
- `com.superbiz.agent.service.DocumentService`
|
||||
- `com.superbiz.agent.service.TextExtractor`
|
||||
- `com.superbiz.agent.tool.DocumentSearchTool`
|
||||
|
||||
**配置**：
|
||||
- `pom.xml`（增加依赖）
|
||||
- `application.yml`（增加 MySQL + Redis 配置）
|
||||
|
||||
**测试**：
|
||||
- `*RepositoryTest.java`
|
||||
- `*ServiceTest.java`
|
||||
- `*ControllerTest.java`
|
||||
|
||||
## 工期估算
|
||||
|
||||
5 天（按实施计划）
|
||||
Reference in New Issue
Block a user