# 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 天（按实施计划）