# Phase 1 基础设施搭建 — Brief

## 背景

MVP 架构已设计完成，但缺少基础设施层：数据持久化、会话管理、实体层。当前代码仍在 `org.example` 包下，需要重构为 `com.superbiz.agent`。

## 目标

搭建 MVP 所需的基础设施层，为 Agent 诊断、案例库、文档管理提供数据支撑。

## 范围

### 已完成 (20/33)

**Task 1: 数据库与依赖**
- MySQL 8.0 连接配置 (119.29.78.52:33306)
- Redis 连接配置 (119.29.78.52:6379)
- Flyway 数据库迁移
- 3 张核心表：diagnosis_record、case_library、api_document

**Task 2: JPA 实体与 Repository**
- 3 个 JPA 实体类：DiagnosisRecord、CaseLibrary、ApiDocument
- 3 个 Repository 接口（基于 Spring Data JPA）
- 19 个单元测试（全部通过）

**Task 3: Redis 会话管理**
- SessionContext 会话上下文数据类
- ToolCall 工具调用记录数据类
- SessionManager 接口
- RedisSessionManager 实现（基于 RedisTemplate）
- SessionConfiguration（JSON 序列化配置）
- 8 个单元测试（全部通过）

### 待完成 (13/33)

**Task 4: 代码结构重构** (0/3)
- 包名重构：org.example → com.superbiz.agent
- 分层结构优化：controller/service/repository/domain/tool/config/exception
- DTO 类创建：DiagnosisRequest、DiagnosisResponse、DocumentUploadRequest、DocumentQueryResponse、Result

**Task 5: 文档管理服务** (0/7)
- TextExtractor 服务（支持 .txt、.md、.docx、.pdf）
- 文档分块服务（chunk_size=500, overlap=50）
- 文档上传、查询、删除接口
- 混合检索工具（精确匹配 + 语义检索 + RRF 融合）
- 文档管理集成测试

**Task 6: 全局完善** (0/3)
- 统一异常处理（GlobalExceptionHandler）
- Docker Compose 配置（MySQL + Redis + Milvus）
- 更新 README.md

## 非目标

- 不修改现有 Agent Framework 逻辑（ChatService、AiOpsService）
- 不改动 Milvus 客户端实现（MilvusClientFactory）
- 不实现 Agent 诊断核心逻辑（Phase 2 内容）

## 技术选型

| 组件 | 技术选型 | 说明 |
|------|---------|------|
| 数据库 | MySQL 8.0 | 持久化存储 |
| 缓存/会话 | Redis | 会话管理、分布式缓存 |
| ORM | Spring Data JPA + Hibernate | 实体映射 |
| 数据库迁移 | Flyway | 版本化表结构管理 |
| 向量存储 | Milvus (Zilliz Cloud) | 文档向量检索 |

## 关键决策

1. **枚举类型存储为 VARCHAR**
   - 数据库列类型：VARCHAR(16/32)
   - JPA 映射：`@Enumerated(EnumType.STRING)` + `columnDefinition = "VARCHAR"`
   - 原因：Hibernate schema 验证要求类型严格匹配

2. **Redis 序列化采用 JSON**
   - 配置：GenericJackson2JsonRedisSerializer + JavaTimeModule
   - 原因：支持 Java 8 时间类型、复杂对象序列化

3. **会话过期时间可配置**
   - 默认 TTL 通过参数传入（灵活控制不同场景的会话时长）
   - 支持动态刷新会话过期时间

4. **Repository 查询方法遵循 Spring Data JPA 命名约定**
   - 方法名即查询语义（findByXxxAndYyy）
   - 无需手写 SQL，提高可维护性

## 验证标准

- ✅ MySQL 连接成功，3 张表已创建
- ✅ Flyway 迁移脚本执行成功（版本 003）
- ✅ Repository 单元测试全部通过（19/19）
- ✅ Redis 会话管理测试全部通过（8/8）
- ✅ 编译无错误
- ⏸️ Milvus 集群状态 STOPPED（不影响当前任务）

## 遗留问题

1. **包名混合**
   - 实体类在 `org.example.domain.entity`
   - 枚举类在 `com.superbiz.agent.domain.enums`
   - 需要 Task 4 统一重构

2. **Milvus 未启动**
   - 当前阻塞完整应用启动
   - 文档管理服务（Task 5）依赖 Milvus
   - 需要启动 Zilliz Cloud 集群

3. **测试覆盖不完整**
   - 缺少配置类测试（MySQLConnectionTest 独立运行成功）
   - 缺少集成测试