SuperBizAgent-java/docs/tables/case_library.md

case_library - 案例库表

表定位

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

设计理念

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

核心价值：

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

MVP版本设计原则：

• ✅ 能用：满足基本案例推荐功能
• ✅ 简单：字段不多，逻辑清晰
• ✅ 可扩展：后续可增加字段

---

表结构（MVP版）

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：外部接口故障案例

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：内部错误案例

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：人工录入案例

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());

---

典型查询

精确匹配查询

-- 按错误码查询
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;

统计分析

-- 统计案例分布
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）
❌ 案例合并功能