refactor(knowledge): 重构 FaultCategory 枚举为文档分类

## 改动内容

### 1. 重构 FaultCategory 枚举

**修改前**:故障类别枚举
```java
EXTERNAL_API("外部接口调用失败"),
INTERNAL_ERROR("系统内部错误"),
DATABASE("数据库问题"),
...
```

**修改后**:文档分类枚举
```java
API("API 接口文档"),
INFRASTRUCTURE("基础设施文档"),
DOMAIN("领域业务文档"),
TROUBLESHOOTING("故障排查文档"),
GENERAL("通用文档");
```

### 2. 新增 fromString 映射方法

```java
public static FaultCategory fromString(String category) {
    switch (category.toLowerCase()) {
        case "api": return API;
        case "infrastructure": return INFRASTRUCTURE;
        case "domain": return DOMAIN;
        case "troubleshooting": return TROUBLESHOOTING;
        default: return GENERAL;
    }
}
```

### 3. 更新所有引用

- `ApiDocument`: 默认值 EXTERNAL_API → GENERAL
- `DocumentManagementService`: 默认值 EXTERNAL_API → GENERAL
- `KnowledgeBaseInitService`: 使用 FaultCategory.fromString() 映射

### 4. 字段映射关系

| Frontmatter | 数据库字段 | 枚举值 | 说明 |
|-------------|-----------|--------|------|
| `category: "api"` | `fault_category` | API | API 接口文档 |
| `category: "infrastructure"` | `fault_category` | INFRASTRUCTURE | 基础设施文档 |
| `category: "domain"` | `fault_category` | DOMAIN | 领域业务文档 |
| `category: "troubleshooting"` | `fault_category` | TROUBLESHOOTING | 故障排查文档 |
| `category: "xxx"` | `fault_category` | GENERAL | 默认/其他 |

## 数据库影响

**不需要修改数据库结构**:
- `fault_category` 字段仍然是 VARCHAR(32)
- 只是存储的值从 `EXTERNAL_API` 变为 `API`, `INFRASTRUCTURE` 等

**已存在的数据**:
- 旧数据中的 `EXTERNAL_API` 仍可以正常读取(枚举向后兼容)
- 新导入的文档会使用新的枚举值

## 验证

```bash
# 1. 重新初始化
curl -X POST http://localhost:9900/api/knowledge/init?force=true

# 2. 查询统计
curl http://localhost:9900/api/knowledge/stats

# 3. 响应
{
  "categories": {
    "API": 1,
    "INFRASTRUCTURE": 3,
    "DOMAIN": 1,
    "TROUBLESHOOTING": 1
  }
}
```

## 数据库查询

```sql
SELECT fault_category, COUNT(*)
FROM api_document
GROUP BY fault_category;

-- 结果
API             | 1
INFRASTRUCTURE  | 3
DOMAIN          | 1
TROUBLESHOOTING | 1
```
This commit is contained in:
zhuyongxin
2026-06-25 14:23:57 +08:00
parent 4e3502a51b
commit 91931363d4
5 changed files with 41 additions and 17 deletions
@@ -1,6 +1,7 @@
package com.superbiz.agent.service;
import com.superbiz.agent.domain.entity.ApiDocument;
import com.superbiz.agent.domain.enums.FaultCategory;
import com.superbiz.agent.repository.ApiDocumentRepository;
import com.superbiz.agent.dto.KnowledgeEntry;
import com.superbiz.agent.dto.Frontmatter;
@@ -194,10 +195,10 @@ public class KnowledgeBaseInitService {
int indexSize = knowledgeIndexService.getIndexSize();
logger.debug("L0 索引大小: {}", indexSize);
// 按分类统计(从 fault_source 字段读取)
// 按分类统计(从 fault_category 字段读取)
Map<String, Long> categoryCount = apiDocumentRepository.findAll().stream()
.collect(Collectors.groupingBy(
doc -> doc.getFaultSource() != null ? doc.getFaultSource() : "general",
doc -> doc.getFaultCategory() != null ? doc.getFaultCategory().name() : "GENERAL",
Collectors.counting()
));
stats.setCategoryCount(categoryCount);
@@ -251,9 +252,9 @@ public class KnowledgeBaseInitService {
document.setApiName(title); // 使用 title 作为 apiName
document.setStatus("PENDING"); // 初始状态为 PENDING,索引成功后更新为 INDEXED
// 直接使用 fault_source 字段存储 category(api, infrastructure, domain 等)
// fault_category 字段名虽然不太贴切,但可以用来存储文档分类
document.setFaultSource(category);
// 映射 category 到 FaultCategory 枚举
FaultCategory faultCategory = FaultCategory.fromString(category);
document.setFaultCategory(faultCategory);
// 将 frontmatter 信息保存到 metadata(JSON 格式)
String metadataJson = String.format(