docs: 完成 MVP 架构设计文档

- 数据库设计：3张核心表 (diagnosis_record/case_library/api_document) - Agent架构：4 Agent协作 (Supervisor/Planner/Executor/Verifier) - 意图识别：L0正则+L1小模型Agent分层 - RAG两层加载：L1预加载通用知识 + L2按需加载具体文档 - Skill体系：/diagnose-by-orderid 标准化诊断流程 - Harness控制：5 Gates + 中断机制 - 会话管理：Redis临时存储 + 扩展方案 - 闭环机制：用户反馈 → BadCase → 优化 - 实施规划：3阶段13天
2026-06-22 18:47:00 +08:00
parent 80eada415d
commit 429413fe64
11 changed files with 5408 additions and 0 deletions
@@ -0,0 +1,265 @@
+# 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）
+❌ 案例合并功能
+```