zhuyongxin
8bd758dbaf
创建 Phase 1 基础设施搭建的完整 devflow 文档： - brief.md: 项目背景、目标、范围、技术选型、关键决策 - decisions.md: 6 个架构决策记录 (ADR) - ADR-001: Flyway 数据库版本管理 - ADR-002: 枚举类型存储为 VARCHAR - ADR-003: Redis JSON 序列化 - ADR-004: Spring Data JPA 命名约定 - ADR-005: 会话 TTL 可配置 - ADR-006: 包名暂时混用 - evidence.md: 测试证据、性能指标、编译验证、数据库结构 - 27 个测试全部通过 - 性能指标达标 - 提交记录追踪 - acceptance.md: 验收标准、测试结果、遗留问题 - 20/33 任务完成 - 部分验收通过 更新全局文档： - devflow/index.md: 新增 phase1-infrastructure 项目索引 - devflow/glossary/CONTEXT.md: 新增 8 个术语和 4 条业务规则 Progress: 20/33 tasks completed (61%)
112 lines
3.8 KiB
Markdown
112 lines
3.8 KiB
Markdown
# 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 独立运行成功）
|
||
- 缺少集成测试
|