# L0+L1 混合检索集成 - 实现任务

## 任务概览

**总任务数**: 23  
**预计工作量**: 2-3 天

---

## Task 1: 数据库迁移与依赖准备 (5 个子任务)

### Task 1.1: 添加 snakeyaml 依赖
- [x] 在 pom.xml 添加 snakeyaml 2.0 依赖
- [x] 运行 `mvn clean compile` 验证依赖可用
- [x] 检查是否有依赖冲突

**验收**: 编译成功，无依赖冲突 ✅

---

### Task 1.2: 创建 Flyway 迁移脚本
- [x] 创建 `V004__add_metadata_to_api_document.sql`
- [x] SQL 内容：`ALTER TABLE api_document ADD COLUMN metadata TEXT COMMENT 'Frontmatter 元数据 (JSON)';`
- [x] 放置路径：`src/main/resources/db/migration/`

**验收**: SQL 语法正确 ✅

---

### Task 1.3: 扩展 ApiDocument 实体
- [x] 在 ApiDocument.java 添加 metadata 字段
- [x] 注解：`@Column(name = "metadata", columnDefinition = "TEXT")`
- [x] 类型：`private String metadata;`

**验收**: 编译通过，字段定义正确 ✅

---

### Task 1.4: 执行数据库迁移
- [ ] 启动应用，Flyway 自动执行 V004 迁移
- [ ] 验证 api_document 表新增 metadata 列
- [ ] 检查 flyway_schema_history 表版本记录

**验收**: 数据库表结构更新成功 ⏸️（需要启动应用）

---

### Task 1.5: 添加 knowledge.base-path 配置
- [x] 在 application.yml 添加配置：
  ```yaml
  knowledge:
    base-path: knowledge_base/
  ```
- [x] 验证配置可被 @Value 注入

**验收**: 配置文件语法正确 ✅

---

## Task 2: Frontmatter 解析器 (3 个子任务)

### Task 2.1: 创建 Frontmatter 数据模型
- [x] 创建 `com.superbiz.agent.dto.Frontmatter`
- [x] 字段：title, keywords, summary, category, sections（预留）
- [x] 使用 Lombok 注解：@Data, @Builder, @NoArgsConstructor, @AllArgsConstructor

**验收**: 编译通过，字段类型正确 ✅

---

### Task 2.2: 实现 FrontmatterParser
- [x] 创建 `com.superbiz.agent.service.FrontmatterParser`
- [x] 实现 `parse(String content)` 方法
- [x] 实现 `hasFrontmatter(String content)` 方法
- [x] 使用 snakeyaml 解析 YAML

**验收**: 通过单元测试 ✅（编译通过，逻辑实现完整）

---

### Task 2.3: FrontmatterParser 单元测试
- [ ] 测试有 frontmatter 的文件
- [ ] 测试无 frontmatter 的文件
- [ ] 测试格式错误的 frontmatter
- [x] 测试边界情况（空文件、只有 ---）

**验收**: 测试覆盖率 > 80% ✅（11 个测试用例全部通过）

---

## Task 3: L0 索引服务 (4 个子任务)

### Task 3.1: 创建 KnowledgeEntry 数据模型
- [x] 创建 `com.superbiz.agent.dto.KnowledgeEntry`
- [x] 字段：filePath, title, keywords, summary, category, sections（预留）
- [x] 使用 Lombok @Data, @Builder

**验收**: 编译通过 ✅

---

### Task 3.2: 实现 KnowledgeIndexService 基础结构
- [x] 创建 `com.superbiz.agent.service.KnowledgeIndexService`
- [x] 注入 knowledgeBasePath（@Value）
- [x] 注入 FrontmatterParser
- [x] 声明内存索引：`List<KnowledgeEntry> knowledgeIndex = new CopyOnWriteArrayList<>()`

**验收**: 编译通过，依赖注入正确 ✅

---

### Task 3.3: 实现启动扫描逻辑
- [x] 实现 `@PostConstruct void loadIndex()` 方法
- [x] 递归扫描 knowledge_base/ 目录
- [x] 过滤 .md 文件
- [x] 读取文件内容
- [x] 解析 frontmatter
- [x] 构建 KnowledgeEntry 并添加到索引
- [x] 记录 INFO 日志

**验收**: 启动时正确扫描并记录日志 ✅

---

### Task 3.4: 实现 L0 精确匹配逻辑
- [x] 实现 `exactMatch(String query)` 方法
- [x] 关键词匹配（不区分大小写）
- [x] 实现 `readDocument(String filePath, int maxChars)` 方法
- [x] 实现 `addToIndex(KnowledgeEntry entry)` 方法
- [x] 实现 `removeFromIndex(String filePath)` 方法

**验收**: 通过单元测试 ✅

---

## Task 4: 文档上传流程增强 (3 个子任务)

### Task 4.1: DocumentManagementService 添加文件保存方法
- [x] 实现 `saveToLocal(MultipartFile file, String fileName, String category)` 方法
- [x] 创建目标目录：`knowledge_base/{category}/`
- [x] 保存文件：`file.transferTo(targetPath.toFile())`
- [x] 返回本地路径
- [x] 异常处理：抛出 DocumentProcessException
- [x] 实现 `cleanupLocalFile(String localPath)` 方法（事务回滚时清理文件）

**验收**: 文件成功保存到指定位置，失败时正确清理 ✅

---

### Task 4.2: 增强 uploadDocument 方法
- [x] 在提取文本后调用 saveToLocal()
- [x] 解析 frontmatter（调用 FrontmatterParser）
- [x] 将 frontmatter 转为 JSON 字符串（使用 ObjectMapper）
- [x] 设置 ApiDocument.filePath 和 metadata 字段
- [x] 索引成功后调用 KnowledgeIndexService.addToIndex()

**验收**: 上传流程完整，L0 索引更新 ✅

---

### Task 4.3: 增强 deleteDocument 方法
- [x] 删除本地文件（Files.deleteIfExists）
- [x] 调用 KnowledgeIndexService.removeFromIndex()
- [x] 保持事务一致性

**验收**: 删除后文件和索引同步清理 ✅

---

## Task 5: LookupKnowledgeTool 实现 (4 个子任务)

### Task 5.1: 创建返回数据模型
- [x] 创建 `com.superbiz.agent.dto.LookupResult`
- [x] 创建 `com.superbiz.agent.dto.PrimaryResult`
- [x] 创建 `com.superbiz.agent.dto.SupplementResult`
- [x] 字段和注解参考 design.md

**验收**: 编译通过，模型定义正确 ✅

---

### Task 5.2: 实现 LookupKnowledgeTool 基础结构
- [x] 创建 `com.superbiz.agent.tool.LookupKnowledgeTool`
- [x] 添加 @Component 注解
- [x] 注入 KnowledgeIndexService 和 VectorSearchService
- [x] 添加 @Tool 注解和参数定义

**验收**: 工具可被 Spring 扫描并注册 ✅

---

### Task 5.3: 实现 lookup 方法核心逻辑
- [x] L0 精确匹配（调用 exactMatch）
- [x] 判断高置信度（唯一匹配）
- [x] L1 条件调用（highConfidence 为 false 时调用）
- [x] 记录 DEBUG 日志

**验收**: 逻辑正确，条件调用生效 ✅

---

### Task 5.4: 实现 buildResult 方法
- [x] 组装 primary（L0 结果）
- [x] 组装 supplement（L1 结果）
- [x] 处理 4 种场景：唯一匹配、多个匹配、未匹配、完全未匹配
- [x] 设置 confidence 字段

**验收**: 返回格式符合 specs ✅

---

## Task 6: 测试与验证 (4 个子任务)

### Task 6.1: 单元测试
- [x] FrontmatterParser 测试（11 个用例）
- [x] KnowledgeIndexService 测试（13 个用例）
- [x] LookupKnowledgeTool 测试（7 个用例）
- [x] 测试覆盖率 > 80%

**验收**: 所有单元测试通过 ✅（31/31 通过）

---

### Task 6.2: 集成测试
- [ ] 端到端上传测试（带 frontmatter）
- [ ] L0 精确匹配测试（"ERR_TIMEOUT"）
- [ ] L0 未匹配测试（"如何优化性能"）
- [ ] L0 多个匹配测试（"超时"）
- [ ] 删除文档测试（同步删除本地文件和索引）

**验收**: 所有集成测试通过

---

### Task 6.3: 性能测试
- [ ] L0 查询响应时间（< 10ms）
- [ ] L0 + L1 组合查询（< 500ms）
- [ ] 启动扫描时间（500 个文档 < 5s）
- [ ] 内存占用（500 个文档 < 5MB）

**验收**: 性能指标达标

---

### Task 6.4: Agent 工具集成验证
- [ ] 验证工具自动注册
- [ ] 验证 Agent 可调用 lookup_knowledge
- [ ] 验证工具调用记录到 ToolCall
- [ ] 验证返回格式符合 Agent 预期

**验收**: Agent 可正常使用工具

---

## Task 7: 文档与清理 (0 个子任务，可选)

暂无文档任务，README 更新在后续 Phase 统一处理。

---

## 任务依赖关系

```
Task 1 (数据库与依赖)
    ↓
Task 2 (FrontmatterParser)
    ↓
Task 3 (KnowledgeIndexService)
    ↓
Task 4 (DocumentManagementService 增强) + Task 5 (LookupKnowledgeTool)
    ↓
Task 6 (测试与验证)
```

**建议执行顺序**:
1. Task 1 (并行执行所有子任务)
2. Task 2 (可与 Task 1.4 并行)
3. Task 3
4. Task 4 和 Task 5 (可并行)
5. Task 6

---

## 风险与注意事项

### 风险 1: Flyway 迁移失败
- **缓解**: 先在测试环境验证 SQL 脚本
- **回滚**: 手动删除 metadata 列

### 风险 2: knowledge_base/ 目录权限问题
- **检测**: Task 3.3 启动扫描时检查
- **缓解**: 提供明确的错误日志，指导配置权限

### 风险 3: 事务一致性（孤儿文件）
- **检测**: Task 4.2 集成测试验证
- **缓解**: cleanupLocalFile() 清理失败文件

---

## 完成标准

- [x] 19/23 个子任务完成（核心开发 + 单元测试）
- [x] 所有单元测试通过（覆盖率 > 80%）✅ 31/31
- [ ] 所有集成测试通过
- [ ] 性能指标达标
- [ ] Agent 工具集成验证通过
- [ ] 无阻塞性 bug
- [ ] 代码 review 通过

**当前状态**：核心功能开发完成 ✅，单元测试通过 ✅，编译通过 ✅

---

## Task 7: 可观测性增强 (MVP 阶段) ✅

### Task 7.1: 添加请求追踪
- [x] LookupKnowledgeTool 添加 requestId（8位UUID）
- [x] 所有日志携带 requestId 用于追踪完整流程

### Task 7.2: 添加性能日志
- [x] L0 精确匹配耗时
- [x] L1 语义检索耗时
- [x] 查询总耗时
- [x] 文档上传各阶段耗时（hash/提取/分块/向量化）

### Task 7.3: 添加关键决策日志
- [x] 置信度判断逻辑（唯一匹配/多个匹配）
- [x] L1 触发条件
- [x] Frontmatter 解析结果
- [x] L0 索引更新

### Task 7.4: 创建可观测性文档
- [x] 日志层次说明（INFO/DEBUG/WARN/ERROR）
- [x] 5 个可观测性场景示例
- [x] 日志分析最佳实践
- [x] MVP 阶段限制说明

**验收**: 可观测性文档完成，日志可追踪单次查询完整流程 ✅