Files

T

zhuyongxin 8bd758dbaf 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%)

2026-06-23 14:44:43 +08:00

3.8 KiB

Raw Permalink Blame History

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)	文档向量检索

关键决策

枚举类型存储为 VARCHAR
- 数据库列类型：VARCHAR(16/32)
- JPA 映射：@Enumerated(EnumType.STRING) + columnDefinition = "VARCHAR"
- 原因：Hibernate schema 验证要求类型严格匹配
Redis 序列化采用 JSON
- 配置：GenericJackson2JsonRedisSerializer + JavaTimeModule
- 原因：支持 Java 8 时间类型、复杂对象序列化
会话过期时间可配置
- 默认 TTL 通过参数传入（灵活控制不同场景的会话时长）
- 支持动态刷新会话过期时间
Repository 查询方法遵循 Spring Data JPA 命名约定
- 方法名即查询语义（findByXxxAndYyy）
- 无需手写 SQL，提高可维护性

验证标准

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

遗留问题

包名混合
- 实体类在 org.example.domain.entity
- 枚举类在 com.superbiz.agent.domain.enums
- 需要 Task 4 统一重构
Milvus 未启动
- 当前阻塞完整应用启动
- 文档管理服务（Task 5）依赖 Milvus
- 需要启动 Zilliz Cloud 集群
测试覆盖不完整
- 缺少配置类测试（MySQLConnectionTest 独立运行成功）
- 缺少集成测试

3.8 KiB Raw Permalink Blame History Unescape Escape