fix(knowledge): 修复状态字段和 indexed_at 时间戳设置

## 问题

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 信息
```
This commit is contained in:
zhuyongxin
2026-06-25 14:04:10 +08:00
parent 3ed48e38cd
commit b01f133efb
@@ -135,6 +135,7 @@ public class KnowledgeBaseInitService {
document.setStatus("INDEXED"); document.setStatus("INDEXED");
document.setChunkCount(chunks.size()); document.setChunkCount(chunks.size());
document.setIndexedAt(LocalDateTime.now());
apiDocumentRepository.save(document); apiDocumentRepository.save(document);
logger.info("文档已索引到 Milvus: {} (docId={}, chunks={})", logger.info("文档已索引到 Milvus: {} (docId={}, chunks={})",
@@ -247,7 +248,12 @@ public class KnowledgeBaseInitService {
document.setFileName(Paths.get(filePath).getFileName().toString()); document.setFileName(Paths.get(filePath).getFileName().toString());
document.setFilePath(filePath); document.setFilePath(filePath);
document.setApiName(title); // 使用 title 作为 apiName 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 格式) // 将 frontmatter 信息保存到 metadata(JSON 格式)
String metadataJson = String.format( String metadataJson = String.format(
@@ -260,7 +266,6 @@ public class KnowledgeBaseInitService {
document.setMetadata(metadataJson); document.setMetadata(metadataJson);
document.setFileSize((long) content.length()); document.setFileSize((long) content.length());
document.setIndexedAt(LocalDateTime.now());
return apiDocumentRepository.save(document); return apiDocumentRepository.save(document);
} }