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
+53 -1
View File
@@ -46,6 +46,54 @@
- 使用场景:通过 SiliconFlow API 调用,替代 DashScope text-embedding-v4
- 维度兼容:1024 = 原 DashScope text-embedding-v4,Milvus 无需重建
### DiagnosisRecord
- 定义:诊断记录实体类,存储每次 Agent 诊断任务的完整记录
- 表名:diagnosis_record
- 主键:id (自增 BIGINT),唯一标识:diagnosis_id (UUID)
- 关联字段:session_id(Redis 会话)、business_id(业务标识)、trace_id(链路追踪)
- 故障分类:fault_category、fault_source、fault_target
- 诊断结果:root_cause(根因)、solution(方案)、report_markdown(完整报告)
- 使用场景:持久化诊断结果,支持历史查询和案例提取
### CaseLibrary
- 定义:案例库实体类,存储高质量诊断案例
- 表名:case_library
- 来源类型:AUTO(自动生成)、MANUAL(人工录入)
- 引用追踪:reference_count(被推荐次数)
- 使用场景:相似案例推荐、知识沉淀
### ApiDocument
- 定义:API 文档元数据实体类,管理接口文档的元信息
- 表名:api_document
- 文件去重:file_hash(MD5 hash)
- 索引状态:PENDING(待处理)、PROCESSING(处理中)、INDEXED(已索引)、FAILED(失败)
- 关联:doc_id 关联 Milvus 中的文档向量
- 使用场景:文档上传、检索、版本管理
### SessionContext
- 定义:会话上下文数据类,存储在 Redis 中的会话数据
- 包含字段:sessionId、userId、businessId、traceId、status、toolCalls、TTL
- 序列化方式:JSON(GenericJackson2JsonRedisSerializer)
- 使用场景:多轮对话上下文管理、工具调用历史追踪
### ToolCall
- 定义:工具调用记录数据类,追踪 Agent 使用的工具及其结果
- 包含字段:toolName、arguments、result、status、duration、calledAt
- 使用场景:诊断过程可观测性、调试、复现
### SessionManager
- 定义:会话管理器接口,定义会话的 CRUD 操作
- 实现:RedisSessionManager(基于 RedisTemplate)
- 核心方法:createSession、getSession、updateSession、deleteSession、refreshSession、addToolCall
- 使用场景:分布式会话管理、Agent 状态维护
### Flyway
- 定义:数据库版本迁移工具,管理 SQL 脚本的版本化执行
- 配置:spring.flyway.enabled=true, baseline-on-migrate=true
- 迁移路径:src/main/resources/db/migration/
- 命名约定:V{version}__{description}.sql(如 V001__create_diagnosis_record.sql)
- 使用场景:数据库表结构版本管理、多环境部署
## 业务规则
- ChatModel 是唯一 LLM 调用抽象:替换模型只需更换 Spring Boot starter 和配置
@@ -53,4 +101,8 @@
- ReactAgent 已兼容 ChatModel 接口,不绑定 DashScope
- base-url 只写 host(如 `https://api.deepseek.com`),不写版本路径(如 `/v1`),Spring AI 会自动追加
- 多 starter 并存时,必须通过 `@Primary` 或 `@Qualifier` 指定默认 Bean
- Milvus collection 启动时必须 `loadCollection()`,否则搜索报 `collection not loaded`
- Milvus collection 启动时必须 `loadCollection()`,否则搜索报 `collection not loaded`
- 枚举类型在数据库中存储为 VARCHAR,JPA 使用 `@Enumerated(EnumType.STRING)` + `columnDefinition = "VARCHAR"`
- JPA ddl-auto 使用 `validate` 模式,表结构修改必须通过 Flyway 迁移脚本
- Redis 会话 TTL 由调用方指定,不同场景使用不同过期时间(短诊断 5 分钟,长会话 1 小时)
- Repository 查询方法遵循 Spring Data JPA 命名约定,复杂查询使用 `@Query`