osiman/SuperBizAgent-java
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
31 Commits 15 Branches 0 Tags
125e8281e70db50fbe36d367b4d529bebf12c1dd
Commit Graph
12 Commits
Author SHA1 Message Date
zhuyongxin d6229f3385 feat(knowledge): 完成 L0+L1 混合检索集成 
核心功能：
- 新增 FrontmatterParser 解析 YAML frontmatter
- 新增 KnowledgeIndexService L0 内存索引
- 新增 LookupKnowledgeTool 混合检索工具
- 增强 DocumentManagementService 文件保存和索引同步

技术实现：
- 数据库迁移 V004: api_document.metadata (TEXT)
- 依赖新增: snakeyaml 2.0
- 配置新增: knowledge.base-path
- 可观测性: requestId 追踪 + 性能日志

质量保证：
- 单元测试: 31/31 通过
- 测试覆盖: FrontmatterParser(11), KnowledgeIndexService(13), LookupKnowledgeTool(7)
- 启动验证: L0 索引正常加载

归档文档：
- OpenSpec: openspec/changes/lookup-knowledge-integration/
- devflow 档案: devflow/projects/2026-06-24-lookup-knowledge-integration/
- handoff: handoff/2026-06-24-lookup-knowledge-integration.md
 2026-06-24 16:07:10 +08:00
zhuyongxin c86045b33f archive: Phase 1 基础设施搭建归档 
归档信息：
- 变更名称：phase-1-infrastructure
- 工作流：spec-driven
- 归档位置：openspec/changes/archive/2026-06-23-phase-1-infrastructure/

完成情况：
- ✅ 所有产物完成（proposal, design, specs, tasks）
- ✅ 任务完成：33/35 (94%)
- ⚠️ 2 个任务跳过（混合检索、集成测试，有充分理由）

验收结果：
- ✅ 静态验证：编译通过
- ✅ 脚本验证：16/16 单元测试通过
- ✅ 端到端验证：上传→索引→检索→删除完整流程

Delta Specs：
- 跳过同步（用户选择）
- functional-specs.md 保留在归档目录中

devflow 档案：
- ✅ 已完整回填（brief, evidence, decisions, acceptance）
- ✅ devflow/index.md 状态更新为 archived
 2026-06-23 19:20:05 +08:00
zhuyongxin 24101a8d66 feat(phase1): 支持上传时指定文档类别 
功能增强：
- DocumentController 新增 category 参数
  POST /api/documents/upload?category=api

- DocumentUploadRequest 新增 category 字段
  - 支持用户指定：api、domain、troubleshoot 等
  - 默认值：upload（未指定时）

- VectorIndexService.indexDocumentChunks 接收 category
  - 将用户指定的类别存入 Milvus metadata
  - metadata.category = 用户指定值 或 "upload"

使用示例：
```bash
# 上传 API 文档
curl -X POST /api/documents/upload \
  -F "file=@redis-api.md" \
  -F "category=api"

# 上传领域知识文档
curl -X POST /api/documents/upload \
  -F "file=@cache-theory.md" \
  -F "category=domain"

# 检索时按类别过滤
searchSimilarDocuments("Redis接口", 5, "api")
```

完整流程：
1. 文件索引：自动从路径提取（aiops-docs/api/ → "api"）
2. 用户上传：从接口参数获取（category=api）
3. 检索时：可按类别过滤（category 参数）

编译验证：BUILD SUCCESS
 2026-06-23 16:43:47 +08:00
zhuyongxin 075cc36270 feat(phase1): 支持按类别过滤的文档检索 
功能增强：
- VectorIndexService 自动提取文档类别
  - 文件索引：从路径提取（如 aiops-docs/api/ → "api"）
  - 上传文档：默认类别 "upload"
  - metadata.category 字段存储类别信息

- VectorSearchService 支持类别过滤
  - searchSimilarDocuments(query, topK): 原方法，不过滤
  - searchSimilarDocuments(query, topK, category): 新方法，按类别过滤
  - 使用 Milvus expr 过滤：metadata["category"] == "xxx"

使用场景：
- 目录结构：
  aiops-docs/
  ├── api/          → category="api"
  ├── domain/       → category="domain"
  └── troubleshoot/ → category="troubleshoot"

- 检索示例：
  // 只检索 API 文档
  searchSimilarDocuments("Redis接口", 5, "api")

  // 只检索领域知识
  searchSimilarDocuments("缓存原理", 5, "domain")

  // 全量检索
  searchSimilarDocuments("问题诊断", 5, null)

编译验证：BUILD SUCCESS
 2026-06-23 16:33:52 +08:00
zhuyongxin 4ef8d87961 feat(phase1): 实现文档分块向量化索引 
Task 5.6: 向量化索引实现
- VectorIndexService 新增方法：
  - indexDocumentChunks(docId, chunks): 索引文档分块到 Milvus
  - deleteDocumentChunks(docId): 删除文档的所有向量
  - buildDocumentMetadata(): 构建文档元数据（区分文件索引）

核心流程：
1. 上传时：文本提取 → 分块 → 向量化 → 存入 Milvus + MySQL
2. 检索时：问题向量化 → Milvus 语义检索 → 返回相似文档
3. 删除时：删除元数据 + 删除向量索引

实现细节：
- 复用 indexSingleFile 的向量化逻辑
- metadata.docId 标识文档来源（区分 upload: 和 file:）
- 删除表达式：metadata["docId"] == "xxx"
- 自动去重：上传前删除旧向量数据

DocumentManagementService 完整实现：
- uploadDocument: 完整向量化流程（移除 TODO）
- deleteDocument: 同步删除向量索引（移除 TODO）

编译验证：BUILD SUCCESS

Progress: 32/34 tasks completed (94%)
 2026-06-23 16:08:50 +08:00
zhuyongxin 26aaf149d8 feat(phase1): 完成全局完善和基础设施文档 
Task 6.1: 统一异常处理
- 创建 GlobalExceptionHandler：Spring 全局异常拦截器
  - SessionNotFoundException: 404 会话未找到
  - DocumentProcessException: 400 文档处理异常
  - MaxUploadSizeExceededException: 400 文件大小超限
  - IllegalArgumentException: 400 参数错误
  - Exception: 500 系统异常兜底
- 统一响应格式：Result<T> + HTTP 状态码

Task 6.2: Docker Compose 配置
- 创建 docker-compose.yml：本地开发环境一键启动
  - MySQL 8.0: 数据持久化，端口 3306
  - Redis 7: 会话缓存，端口 6379
  - Milvus Standalone: 向量索引，端口 19530
    - etcd: 元数据存储
    - MinIO: 对象存储
- 数据卷持久化：mysql-data, redis-data, milvus-data
- 健康检查：自动重启机制

Task 6.3: 更新 README.md
- 新增 Phase 1 专属章节：
  - 架构概览（已完成功能清单）
  - 本地开发环境（前置要求、快速开始）
  - 数据库迁移（Flyway 脚本说明）
  - API 文档（文档管理接口示例）
  - 项目结构（分层架构说明）
  - 待办事项（向量化索引、混合检索）
  - 技术决策（包名重构、文本格式、分块策略）

编译验证：BUILD SUCCESS

Progress: 31/33 tasks completed (94%)
 2026-06-23 15:50:47 +08:00
zhuyongxin e76d4ce48f feat(phase1): 完成文档查询和删除接口 
Task 5.4: 文档查询接口
- DocumentManagementService 新增查询方法：
  - queryDocumentById: 根据 docId 查询单个文档
  - queryDocumentsByStatus: 根据状态查询（分页）
  - queryDocumentsByFaultSource: 根据故障源查询
  - convertToResponse: 实体转 DTO 工具方法
- DocumentController 新增 RESTful 接口：
  - GET /api/documents/{docId}
  - GET /api/documents/status/{status}?page=0&size=20
  - GET /api/documents/faultSource/{faultSource}

Task 5.5: 文档删除接口
- DocumentManagementService 新增删除方法：
  - deleteDocument: 删除文档元数据
  - TODO: 向量索引删除待实现
- DocumentController 新增删除接口：
  - DELETE /api/documents/{docId}

功能特性：
- 统一异常处理：DocumentProcessException
- 统一响应格式：Result<T>
- 分页支持：Page/PageRequest
- 事务支持：@Transactional

编译验证：BUILD SUCCESS

Progress: 28/33 tasks completed (85%)
 2026-06-23 15:48:04 +08:00
zhuyongxin f446290d0f feat(phase1): 完成文档上传接口 
Task 5.3: 文档上传接口
- 创建 DocumentManagementService：文档上传核心逻辑
  - 文件格式验证（仅 .md/.txt）
  - 文件 hash 计算与去重检查
  - 文本提取与分块处理
  - 文档元数据持久化（ApiDocument）
  - 向量化索引标记为 TODO（待补充）
- 创建 DocumentController：RESTful 上传接口
  - POST /api/documents/upload
  - 支持参数：file, faultCategory, faultSource, apiName, version
  - 返回：文档 docId

功能特性：
- MD5 hash 去重：防止重复上传
- 事务支持：元数据与索引状态一致性
- 异常处理：DocumentProcessException 统一封装
- 分块配置：使用 DocumentChunkConfig 默认配置

待补充：
- TODO: VectorIndexService.indexDocumentChunks() 实现
- 当前文档状态直接标记为 INDEXED

编译验证：BUILD SUCCESS

Progress: 26/33 tasks completed (79%)
 2026-06-23 15:28:02 +08:00
zhuyongxin ea77518880 feat(phase1): 完成文本提取和文档分块服务 
Task 5.1: TextExtractor 服务
- 创建 TextExtractorService（仅支持 .md 和 .txt）
- 其他格式（.docx、.pdf）需通过外部转换服务先转为 Markdown
- 支持 UTF-8 编码的纯文本提取
- 提供文件格式验证方法

Task 5.2: 文档分块服务适配
- 修改 DocumentChunk DTO：添加 @Builder 支持
- 字段重命名：startIndex/endIndex → startOffset/endOffset
- 修复 DocumentChunkService 中的三处构造调用
- 使用 builder 模式替代构造函数

技术决策：
- 简化文本提取，只支持 Markdown 和纯文本
- 复杂格式转换由外部服务处理（分离关注点）
- 统一使用 Lombok @Builder 简化对象构建

编译验证：BUILD SUCCESS

Progress: 25/33 tasks completed (76%)
 2026-06-23 15:15:10 +08:00
zhuyongxin 360e4febae feat(phase1): 完成分层结构优化和 DTO 创建 
Task 4.2: 分层结构优化
- 创建 exception 包
  - SessionNotFoundException: 会话未找到异常
  - DocumentProcessException: 文档处理异常
- 已有分层结构验证
  - controller: 控制器层 ✅
  - service: 业务逻辑层 ✅
  - repository: 数据访问层 ✅
  - domain: 领域模型层 (entity/model/enums) ✅
  - config: 配置层 ✅
  - tool: 工具类 ✅

Task 4.3: 创建 DTO 类
- DiagnosisRequest: 诊断请求 DTO (10 个字段)
- DiagnosisResponse: 诊断响应 DTO (12 个字段 + 内部类)
- DocumentUploadRequest: 文档上传请求 DTO (7 个字段)
- DocumentQueryResponse: 文档查询响应 DTO (11 个字段 + 内部类)
- Result<T>: 统一响应结果 DTO (泛型包装)

功能特性：
- 异常类支持自定义错误信息和原因链
- DTO 使用 Lombok 简化代码
- Result 提供静态工厂方法（success/error）
- DocumentUploadRequest 支持 MultipartFile
- Response DTO 支持嵌套数据结构

编译验证：BUILD SUCCESS

Progress: 23/33 tasks completed (70%)
 2026-06-23 15:02:38 +08:00
zhuyongxin c3a232540a refactor(phase1): 完成包名重构 (org.example → com.superbiz.agent) 
Task 4.1: 包名统一重构
- 重命名 41 个 Java 文件的包名
- 更新所有 import 语句
- 恢复枚举类（FaultCategory、DiagnosisStatus、SourceType）
- 更新测试类的 import

重构范围：
- domain/entity: 3 个实体类
- domain/model: 2 个数据类
- domain/enums: 3 个枚举类
- repository: 3 个接口
- service/session: 2 个类（接口 + 实现）
- config: 9 个配置类
- controller: 2 个控制器
- agent/tool: 4 个工具类
- client: 1 个客户端
- Main.java: 主类

验证结果：
- 编译成功，无错误
- 所有测试通过 (27/27)
  - ApiDocumentRepositoryTest: 7/7 ✅
  - CaseLibraryRepositoryTest: 6/6 ✅
  - DiagnosisRecordRepositoryTest: 6/6 ✅
  - RedisSessionManagerTest: 8/8 ✅

Progress: 21/33 tasks completed (64%)
 2026-06-23 14:56:04 +08:00
zhuyongxin 5ddb7a6d93 feat(phase1): 完成基础设施搭建初步工作 
- 添加 JPA/Flyway/Redis 依赖到 pom.xml
- 创建 3 个 Flyway 迁移脚本（diagnosis_record/case_library/api_document）
- 创建枚举类（FaultCategory/DiagnosisStatus/SourceType）
- 配置 MySQL + Redis 连接（application.yml）

状态：数据库表脚本就绪，等待数据库创建后验证
 2026-06-23 10:53:24 +08:00