SuperBizAgent-java/mvp/tables/case_library.md

# case_library - 案例库表

## 表定位

**知识沉淀表**：存储高质量诊断案例，支持相似案例推荐

## 设计理念

### 知识沉淀，系统越用越智能

**核心价值**：
- 质量过滤：只存储高质量案例（成功诊断 + 用户反馈有用）
- 知识沉淀：历史诊断经验可复用
- 提升准确率：相似问题提供历史参考
- 加速诊断：快速推荐相似案例

**MVP版本设计原则**：
- ✅ 能用：满足基本案例推荐功能
- ✅ 简单：字段不多，逻辑清晰
- ✅ 可扩展：后续可增加字段

---

## 表结构（MVP版）

```sql
CREATE TABLE case_library (
    -- 主键
    id BIGINT PRIMARY KEY AUTO_INCREMENT,
    case_id VARCHAR(64) UNIQUE NOT NULL COMMENT '案例唯一ID（UUID）',
    
    -- 来源关联
    diagnosis_id VARCHAR(64) COMMENT '关联诊断记录（可选，人工录入时为空）',
    source_type VARCHAR(16) DEFAULT 'AUTO' COMMENT '来源类型（AUTO:自动生成/MANUAL:人工录入）',
    
    -- 案例分类
    fault_category VARCHAR(32) COMMENT '故障类别（EXTERNAL_API/INTERNAL_ERROR/DATABASE...）',
    fault_source VARCHAR(128) COMMENT '故障源（省份/服务名/类名...）',
    fault_target VARCHAR(256) COMMENT '故障目标（接口URL/方法名/SQL...）',
    error_code VARCHAR(64) COMMENT '错误码',
    
    -- 案例内容
    title VARCHAR(256) NOT NULL COMMENT '案例标题（简短描述）',
    root_cause TEXT NOT NULL COMMENT '根因分析',
    solution TEXT NOT NULL COMMENT '解决方案',
    
    -- 简单统计
    reference_count INT DEFAULT 0 COMMENT '引用次数（被推荐的次数）',
    
    -- 元数据
    created_by VARCHAR(64) COMMENT '创建人',
    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
    
    -- 索引
    INDEX idx_fault_category (fault_category),
    INDEX idx_error_code (error_code),
    INDEX idx_fault_source (fault_source),
    INDEX idx_fault_target (fault_target(100)),
    INDEX idx_diagnosis_id (diagnosis_id),
    INDEX idx_reference_count (reference_count),
    INDEX idx_created_at (created_at)
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='案例库表（MVP版）';
```

---

## 字段说明

| 字段 | 类型 | 必填 | 说明 |
|------|------|------|------|
| case_id | VARCHAR(64) | 是 | 案例唯一标识（UUID）|
| diagnosis_id | VARCHAR(64) | 否 | 关联诊断记录（人工录入时为空）|
| source_type | VARCHAR(16) | 是 | 来源：AUTO（自动）/MANUAL（人工）|
| fault_category | VARCHAR(32) | 否 | 故障类别 |
| fault_source | VARCHAR(128) | 否 | 故障源 |
| fault_target | VARCHAR(256) | 否 | 故障目标（与 diagnosis_record 一致）|
| error_code | VARCHAR(64) | 否 | 错误码 |
| title | VARCHAR(256) | 是 | 案例标题 |
| root_cause | TEXT | 是 | 根因分析（核心内容）|
| solution | TEXT | 是 | 解决方案（核心内容）|
| reference_count | INT | 是 | 引用次数（用于排序）|

---

## 核心设计决策

### 1. 案例来源

```
来源1：自动生成（source_type=AUTO）
├─ 触发条件：诊断成功 + 用户反馈"有用"
├─ 关联诊断：diagnosis_id 不为空
└─ 质量保证：用户验证过

来源2：人工录入（source_type=MANUAL）
├─ 运维团队总结的经典案例
├─ diagnosis_id 为空
└─ 质量最高

注意：诊断失败或用户反馈"无用"的不自动生成案例
```

### 2. 简化的评分机制（MVP）

```
MVP版本：只按 reference_count 排序
- 引用次数多的排前面
- 简单有效

Phase 2 可增强：
- 增加 useful_count（用户反馈有用次数）
- 增加 score（综合评分）
- 增加 is_featured（人工标记的经典案例）
```

### 3. 与 diagnosis_record 的关系

```
关系：一对一（可选）
- 一次诊断 → 可以生成一个案例
- 通过 diagnosis_id 关联
- diagnosis_id 可为空（人工录入案例）

流程：
diagnosis_record（成功）
    ↓
用户反馈"有用"
    ↓
自动生成 case_library
    ↓
后续可人工修正、合并相似案例
```

---

## 数据示例

### 示例1：外部接口故障案例
```sql
INSERT INTO case_library VALUES
(1, 'case-001', 'diag-001', 'AUTO', 'EXTERNAL_API', '广东', '/api/v1/guangdong/social-security', '40003', 
 '广东社保查询idCard字段缺失', 
 '请求报文中未传入idCard字段，导致参数校验失败', 
 '前端表单增加idCard必填校验；后端增加参数校验提示', 
 15, 'system', NOW(), NOW());
```

### 示例2：内部错误案例
```sql
INSERT INTO case_library VALUES
(2, 'case-002', 'diag-045', 'AUTO', 'INTERNAL_ERROR', 'order-service', 'OrderController.createOrder()', 'NullPointerException',
 '订单服务创建订单空指针异常',
 'OrderController.createOrder()方法中user对象为null，未做空判断',
 '在第45行添加空判断：if (user == null) throw new BizException("用户信息不存在")',
 8, 'system', NOW(), NOW());
```

### 示例3：人工录入案例
```sql
INSERT INTO case_library VALUES
(3, 'case-003', NULL, 'MANUAL', 'DATABASE', 'mysql-master-01', 'UPDATE orders SET status=? WHERE order_id=?', '1213',
 '订单库存更新死锁通用处理',
 '两个事务互相等待对方释放锁',
 '调整事务加锁顺序：统一先锁订单，再锁库存；或使用乐观锁',
 3, 'admin', NOW(), NOW());
```

---

## 典型查询

### 精确匹配查询
```sql
-- 按错误码查询
SELECT * FROM case_library
WHERE error_code = '40003'
ORDER BY reference_count DESC
LIMIT 5;

-- 按故障类别 + 错误码 + 故障目标查询
SELECT * FROM case_library
WHERE fault_category = 'INTERNAL_ERROR'
  AND error_code = 'NullPointerException'
  AND fault_target = 'OrderController.createOrder()'
ORDER BY reference_count DESC
LIMIT 5;
```

### 统计分析
```sql
-- 统计案例分布
SELECT 
  fault_category,
  COUNT(*) as count,
  AVG(reference_count) as avg_reference
FROM case_library
GROUP BY fault_category
ORDER BY count DESC;

-- Top 引用案例
SELECT title, reference_count, created_at
FROM case_library
ORDER BY reference_count DESC
LIMIT 10;
```

---

## 与 Milvus 的配合

### 混合检索策略

```
1. 精确匹配（MySQL）
   - 按 error_code 查询
   - 按 fault_category + fault_source 查询
   - 优点：快速、准确

2. 语义检索（Milvus）
   - 将案例内容向量化
   - 按语义相似度查询
   - 优点：能找到相似但不同错误码的案例

3. 混合策略（推荐）
   Step 1: 先精确匹配（MySQL）
   Step 2: 如果结果 < 3 个，补充语义检索（Milvus）
   Step 3: 合并去重，按 reference_count 排序
   Step 4: 返回 Top 5
```

---

## 数据量预估

```
预估：500-1000 条
- 初期：每月新增 10-20 条
- 稳定期：每月新增 5-10 条
- 总量：1-2 年达到稳定

存储：
- 单条记录：约 2KB
- 1000 条：约 2MB

结论：数据量很小
```

---

## MVP 版本的简化

```
Phase 1（当前）：
✅ 基础字段和表结构
✅ 自动生成案例
✅ 人工录入案例
✅ 按 reference_count 简单排序

Phase 2（未来增强）：
❌ useful_count + score（复杂评分）
❌ 版本管理
❌ 标签分类（tags）
❌ 案例合并功能
```