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:
@@ -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`
|
||||
Reference in New Issue
Block a user