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）
172 lines
4.8 KiB
Markdown
172 lines
4.8 KiB
Markdown
# 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 天（按实施计划）
|