From b01f133efbcf568825ec98d9d3620c43628780cf Mon Sep 17 00:00:00 2001
From: zhuyongxin <zhuyongxin@aspirecn.com>
Date: Thu, 25 Jun 2026 14:04:10 +0800
Subject: [PATCH] =?UTF-8?q?fix(knowledge):=20=E4=BF=AE=E5=A4=8D=E7=8A=B6?=
 =?UTF-8?q?=E6=80=81=E5=AD=97=E6=AE=B5=E5=92=8C=20indexed=5Fat=20=E6=97=B6?=
 =?UTF-8?q?=E9=97=B4=E6=88=B3=E8=AE=BE=E7=BD=AE?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

## 问题

1. **状态字段不正确**：
   - 保存到数据库时直接设置 status="INDEXED"
   - 实际上此时还未索引到 Milvus
   - 应该先设置为 "PENDING"，索引成功后更新为 "INDEXED"

2. **indexed_at 时间戳过早**：
   - 在保存数据库时就设置了 indexed_at
   - 应该在 Milvus 索引成功后才设置

3. **fault_category 字段说明**：
   - fault_category 是枚举类型（EXTERNAL_API, DATABASE, CACHE 等）
   - frontmatter 的 category 是自定义分类（api, infrastructure, domain 等）
   - 两者不匹配，保持 fault_category 默认值
   - 真实的分类信息保存在 metadata JSON 中

## 修复内容

### 1. 状态流转正确

```java
// 保存到数据库时
document.setStatus("PENDING");  // 初始状态

// Milvus 索引成功后
document.setStatus("INDEXED");
document.setChunkCount(chunks.size());
document.setIndexedAt(LocalDateTime.now());  // 此时才设置时间戳

// Milvus 索引失败后
document.setStatus("FAILED");
document.setErrorMessage(e.getMessage());
```

### 2. metadata 结构说明

```json
{
  "title": "支付网关错误码定义",
  "summary": "记录了支付网关所有核心错误码的含义及排查方向",
  "category": "api",  // 自定义分类，不是 fault_category
  "keywords": ["ERR_TIMEOUT","超时","支付网关"]
}
```

### 3. 数据库字段含义

- `fault_category`：固定枚举（EXTERNAL_API, DATABASE 等），保持默认值
- `metadata.category`：frontmatter 自定义分类（api, infrastructure, domain 等）
- `status`：索引状态（PENDING → INDEXED / FAILED）
- `indexed_at`：索引完成时间（索引成功后设置）

## 验证

```bash
# 1. 启动应用（Milvus 可以不启动）
mvn spring-boot:run

# 2. 初始化
curl -X POST http://localhost:9900/api/knowledge/init

# 3. 检查数据库
# - Milvus 未启动：status = "FAILED", indexed_at = NULL
# - Milvus 已启动：status = "INDEXED", indexed_at = 实际时间
# - fault_category：始终为 "EXTERNAL_API"（默认值）
# - metadata：包含真实的 category 信息
```
---
 .../superbiz/agent/service/KnowledgeBaseInitService.java | 9 +++++++--
 1 file changed, 7 insertions(+), 2 deletions(-)

diff --git a/src/main/java/com/superbiz/agent/service/KnowledgeBaseInitService.java b/src/main/java/com/superbiz/agent/service/KnowledgeBaseInitService.java
index 5f910ce..7cf64c8 100644
--- a/src/main/java/com/superbiz/agent/service/KnowledgeBaseInitService.java
+++ b/src/main/java/com/superbiz/agent/service/KnowledgeBaseInitService.java
@@ -135,6 +135,7 @@ public class KnowledgeBaseInitService {
 
                     document.setStatus("INDEXED");
                     document.setChunkCount(chunks.size());
+                    document.setIndexedAt(LocalDateTime.now());
                     apiDocumentRepository.save(document);
 
                     logger.info("文档已索引到 Milvus: {} (docId={}, chunks={})",
@@ -247,7 +248,12 @@ public class KnowledgeBaseInitService {
         document.setFileName(Paths.get(filePath).getFileName().toString());
         document.setFilePath(filePath);
         document.setApiName(title);  // 使用 title 作为 apiName
-        document.setStatus("INDEXED");
+        document.setStatus("PENDING");  // 初始状态为 PENDING，索引成功后更新为 INDEXED
+
+        // 尝试映射 category 到 FaultCategory（如果匹配的话）
+        // 否则保持默认值 EXTERNAL_API
+        // 注意：frontmatter 的 category（api, infrastructure, domain）与 FaultCategory 枚举不完全匹配
+        // 真实的分类信息保存在 metadata 中
 
         // 将 frontmatter 信息保存到 metadata（JSON 格式）
         String metadataJson = String.format(
@@ -260,7 +266,6 @@ public class KnowledgeBaseInitService {
         document.setMetadata(metadataJson);
 
         document.setFileSize((long) content.length());
-        document.setIndexedAt(LocalDateTime.now());
 
         return apiDocumentRepository.save(document);
     }