docs(devflow): 补充 Phase 1 项目记忆文档

创建 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%)
This commit is contained in:
zhuyongxin
2026-06-23 14:44:43 +08:00
parent 48132d297d
commit 8bd758dbaf
6 changed files with 783 additions and 2 deletions
@@ -0,0 +1,111 @@
# 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 独立运行成功)
- 缺少集成测试