docs(mvp): organize mvp documentation

2026-07-09 13:40:08 +08:00
parent 9c9a0024d4
commit 841437fa06
57 changed files with 452 additions and 675 deletions
@@ -0,0 +1,41 @@
+# Agent 步骤表：agent_step
+
+**状态**：当前表  
+**来源**：`V005__create_session_storage.sql`、`V006__fix_agent_step_json_to_text.sql`、`AgentStep`
+
+## 定位
+
+`agent_step` 记录一次诊断过程中每个 Agent 步骤的模型输入、输出、耗时和 Token 消耗。页面展示执行链路时应优先按 `step_index` 排序。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `session_id` | VARCHAR(64) | 是 | 关联 `diagnosis_session.session_id` |
+| `step_index` | INT | 是 | 步骤序号，从 0 开始 |
+| `agent_name` | VARCHAR(32) | 是 | Agent 名称，例如 planner、executor、verifier、composer |
+| `model_input` | TEXT | 否 | 模型输入摘要；`V006` 已从 JSON 改为 TEXT |
+| `model_output` | TEXT | 否 | 模型输出摘要；`V006` 已从 JSON 改为 TEXT |
+| `thought` | TEXT | 否 | Agent 思考过程或调试摘要 |
+| `has_tool_call` | BOOLEAN | 否 | 本步骤是否触发工具调用 |
+| `duration_ms` | INT | 否 | 本步骤耗时 |
+| `token_count` | INT | 否 | 本步骤 Token 消耗 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `idx_session_step` | `session_id, step_index` | Trace 页面按会话和步骤顺序查询 |
+| `idx_agent_name` | `agent_name` | 按 Agent 类型筛选 |
+
+## 关系
+
+- `agent_step.session_id` 逻辑关联 `diagnosis_session.session_id`。
+- `tool_invocation.step_id` 可关联 `agent_step.id`，但当前允许为空且不强制外键。
+
+## 注意点
+
+- 前端展示步骤时应按 `step_index` 排序，而不是按 `created_at` 或数据库返回顺序。
+- Verifier 应在 Executor 循环完成后出现；如果 `step_index` 中 Verifier 提前，通常意味着编排或记录顺序有问题。
@@ -0,0 +1,40 @@
+# MVP 数据表索引
+
+**更新日期**：2026-07-09  
+**状态**：当前表文档入口
+
+本目录保存当前 MVP 使用的数据表说明。详细结构以 Flyway migration 和实体类为准；本目录用于面试讲解、排查索引和快速理解数据流。
+
+## 当前表
+
+| 表 | 用途 | 文档 |
+|---|---|---|
+| `diagnosis_session` | 会话级主记录，保存 query、状态、最终答案和自评估 | [诊断会话表-diagnosis_session.md](诊断会话表-diagnosis_session.md) |
+| `agent_step` | Agent 步骤记录，按 `step_index` 回放执行链路 | [Agent步骤表-agent_step.md](Agent步骤表-agent_step.md) |
+| `tool_invocation` | 工具调用记录，支撑 Trace、Verifier 和评测 | [工具调用表-tool_invocation.md](工具调用表-tool_invocation.md) |
+| `api_document` | 知识库文档元数据，和向量库 chunk 通过 `doc_id` 关联 | [文档元数据表-api_document.md](文档元数据表-api_document.md) |
+| `knowledge_domain` | 知识域元数据，支撑 RAG domain hint 和检索策略 | [知识域表-knowledge_domain.md](知识域表-knowledge_domain.md) |
+| `case_library` | 用户反馈沉淀出的高质量诊断案例 | [案例库表-case_library.md](案例库表-case_library.md) |
+
+## 已归档表
+
+| 表 | 归档原因 | 文档 |
+|---|---|---|
+| `diagnosis_record` | 已由 `V007` 删除，被 `diagnosis_session + agent_step + tool_invocation` 替代 | [archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md](archive/2026-07-09-doc-cleanup/旧诊断记录表-diagnosis_record.md) |
+
+## 核心关系
+
+```text
+diagnosis_session.session_id
+  -> agent_step.session_id
+  -> tool_invocation.session_id
+  -> case_library.diagnosis_id
+
+api_document.doc_id
+  -> vector chunk metadata.docId / doc_id
+
+knowledge_domain.domain_id
+  -> api_document metadata.category / vector chunk metadata.category
+```
+
+当前实现主要使用逻辑关联，不依赖数据库外键。
@@ -1,332 +0,0 @@
-# api_document - 文档元数据表
-
-## 表定位
-
-**文档管理表**：管理接口文档的元信息，不负责文档检索（检索由 Milvus 负责）
-
-## 设计理念
-
-### 文档管理，不是文档检索
-
-**核心定位**：
- MySQL 负责文档元数据管理（状态、版本、去重）
- Milvus 负责文档内容存储和检索
- 通过 doc_id 关联两者
-
-**MVP版本原则**：
- ✅ 最简字段，满足基本管理需求
- ✅ 文件去重（基于 file_hash）
- ✅ 状态追踪（索引进度）
- ✅ 硬删除（同步删除 Milvus 数据）
- ❌ 暂不支持：软删除、启用开关、版本管理（Phase 2）
-
---
-
-## 表结构（MVP版）
-
-```sql
-CREATE TABLE api_document (
-    -- 主键
-    id BIGINT PRIMARY KEY AUTO_INCREMENT,
-    doc_id VARCHAR(64) UNIQUE NOT NULL COMMENT '文档唯一ID（UUID），关联Milvus',
-    
-    -- 文档分类
-    fault_category VARCHAR(32) DEFAULT 'EXTERNAL_API' COMMENT '文档类别',
-    fault_source VARCHAR(128) COMMENT '文档归属（省份/服务名）',
-    api_name VARCHAR(128) COMMENT '接口名称',
-    version VARCHAR(32) DEFAULT 'v1.0' COMMENT '文档版本',
-    
-    -- 文件信息
-    file_name VARCHAR(256) NOT NULL COMMENT '原始文件名',
-    file_path VARCHAR(512) COMMENT '文件存储路径',
-    file_hash VARCHAR(64) COMMENT '文件MD5 hash（用于去重）',
-    file_size BIGINT COMMENT '文件大小（字节）',
-    
-    -- 索引状态
-    status VARCHAR(16) DEFAULT 'PENDING' COMMENT '索引状态（PENDING/PROCESSING/INDEXED/FAILED）',
-    chunk_count INT DEFAULT 0 COMMENT '分块数量',
-    error_message TEXT COMMENT '失败原因',
-    
-    -- 时间字段
-    indexed_at DATETIME COMMENT '索引完成时间',
-    created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
-    updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
-    
-    -- 索引
-    UNIQUE INDEX uk_file_hash (file_hash),
-    INDEX idx_doc_id (doc_id),
-    INDEX idx_fault_source (fault_source),
-    INDEX idx_status (status),
-    INDEX idx_created_at (created_at)
-) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='文档元数据表（MVP版）';
-```
-
---
-
-## 字段说明
-
-| 字段 | 类型 | 必填 | 说明 |
-|------|------|------|------|
-| doc_id | VARCHAR(64) | 是 | **核心**：文档唯一ID，关联 Milvus |
-| fault_category | VARCHAR(32) | 否 | 文档类别 |
-| fault_source | VARCHAR(128) | 否 | 文档归属（省份/服务名）|
-| api_name | VARCHAR(128) | 否 | 接口名称 |
-| version | VARCHAR(32) | 否 | 文档版本 |
-| file_name | VARCHAR(256) | 是 | 原始文件名 |
-| file_path | VARCHAR(512) | 否 | 文件存储路径 |
-| file_hash | VARCHAR(64) | 否 | **去重关键**：文件MD5 |
-| file_size | BIGINT | 否 | 文件大小 |
-| status | VARCHAR(16) | 是 | **状态追踪**：PENDING/PROCESSING/INDEXED/FAILED |
-| chunk_count | INT | 否 | 分块数量 |
-| error_message | TEXT | 否 | 失败原因 |
-| indexed_at | DATETIME | 否 | 索引完成时间 |
-
---
-
-## 核心设计决策
-
-### 1. doc_id：MySQL 与 Milvus 的桥梁
-
-```
-作用：
- MySQL：通过 doc_id 管理文档元数据
- Milvus：每个 chunk 的 metadata 中携带 doc_id
-
-关联关系：
-api_document (MySQL)
-    doc_id: doc-001
-    ↓ 1:N
-Milvus chunks
-    chunk_1: {doc_id: 'doc-001', text: '...', vector: [...]}
-    chunk_2: {doc_id: 'doc-001', text: '...', vector: [...]}
-
-管理操作：
- 删除文档：
-  DELETE FROM milvus_collection WHERE metadata["doc_id"] == 'doc-001';
-  DELETE FROM api_document WHERE doc_id = 'doc-001';
-```
-
-### 2. file_hash：文件去重
-
-```
-去重流程：
-1. 用户上传文件
-   ↓
-2. 计算文件 MD5
-   file_hash = md5(file_content)
-   ↓
-3. 检查是否已存在
-   SELECT * FROM api_document WHERE file_hash = 'abc123...';
-   ↓
-4a. 如果存在 → 提示"文档已存在"
-4b. 如果不存在 → 继续导入
-
-唯一约束：UNIQUE INDEX uk_file_hash (file_hash)
-```
-
-### 3. status：状态追踪
-
-```
-状态流转：
-PENDING (待处理)
-    ↓
-PROCESSING (处理中)
-    ↓ 成功
-INDEXED (已索引)
-    ↓ 失败
-FAILED (失败)
-
-用途：
- 批量导入时监控进度
- 失败重试
- 统计索引成功率
-```
-
-### 4. 硬删除策略（MVP）
-
-```
-删除文档时：
-1. 删除 Milvus 中的所有分块
-2. 删除 MySQL 元数据
-3. 可选：删除原始文件
-
-特点：
- 简单直接
- 数据彻底删除
- 不可恢复（需谨慎）
-
-Phase 2 可增强：
- 软删除（archived_at）
- 启用开关（enabled）
-```
-
---
-
-## 数据流
-
-### 场景1：导入新文档
-
-```
-1. 用户上传文件
-   ↓
-2. 计算 hash
-   ↓
-3. 检查去重（MySQL）
-   ↓
-4. 插入元数据（status=PROCESSING）
-   ↓
-5. 后台处理：解析 → 分块 → 向量化 → 存入 Milvus
-   ↓
-6. 更新状态（status=INDEXED, chunk_count=15）
-```
-
-### 场景2：删除文档
-
-```
-1. 用户删除文档
-   ↓
-2. 删除 Milvus 数据（WHERE metadata["doc_id"] == 'xxx'）
-   ↓
-3. 删除 MySQL 元数据
-   ↓
-4. 可选：删除原始文件
-```
-
-### 场景3：重新索引
-
-```
-1. 删除旧数据（Milvus + MySQL）
-   ↓
-2. 重新导入（同场景1）
-```
-
---
-
-## 典型查询
-
-```sql
-- 查看文档列表
-SELECT doc_id, file_name, version, status, chunk_count, indexed_at
-FROM api_document
-WHERE fault_source = '广东'
-  AND status = 'INDEXED'
-ORDER BY indexed_at DESC;
-
-- 查询失败的文档
-SELECT doc_id, file_name, error_message
-FROM api_document
-WHERE status = 'FAILED';
-
-- 统计各状态文档数量
-SELECT status, COUNT(*) as count
-FROM api_document
-GROUP BY status;
-```
-
---
-
-## 与 Milvus 的协作
-
-### Milvus Collection Schema
-
-```python
-{
-  "collection_name": "api_doc_collection",
-  "fields": [
-    {"name": "id", "type": "VARCHAR", "is_primary": true},
-    {"name": "content", "type": "VARCHAR"},
-    {"name": "vector", "type": "FLOAT_VECTOR", "dim": 1536},
-    {"name": "metadata", "type": "JSON"}
-  ]
-}
-
-# metadata 结构
-{
-  "doc_id": "doc-001",           # 关联 MySQL
-  "_source": "/path/to/file",
-  "_file_name": "xxx.docx",
-  "chunkIndex": 0,
-  "totalChunks": 15
-}
-```
-
-### Java 代码示例
-
-```java
-// 插入时携带 doc_id
-Map<String, Object> metadata = new HashMap<>();
-metadata.put("doc_id", docId);  // 关联 MySQL
-metadata.put("_source", filePath);
-metadata.put("chunkIndex", chunkIndex);
-
-// 删除文档的所有分块
-String expr = String.format("metadata[\"doc_id\"] == \"%s\"", docId);
-milvusClient.delete(DeleteParam.newBuilder()
-    .withCollectionName(COLLECTION_NAME)
-    .withExpr(expr)
-    .build());
-```
-
---
-
-## 数据示例
-
-```sql
-- 外部接口文档
-INSERT INTO api_document VALUES
-(1, 'doc-001', 'EXTERNAL_API', '广东', '社保查询', 'v2.1',
- '广东社保查询v2.1.docx', '/docs/guangdong/social-v2.1.docx',
- 'abc123...', 1048576,
- 'INDEXED', 15, NULL, '2024-06-15 10:30:00', NOW(), NOW());
-
-- 内部服务文档
-INSERT INTO api_document VALUES
-(2, 'doc-002', 'INTERNAL_ERROR', 'order-service', '订单服务API', 'v1.0',
- '订单服务API文档.pdf', '/docs/internal/order-service-api.pdf',
- 'def456...', 2097152,
- 'INDEXED', 20, NULL, '2024-06-14 15:20:00', NOW(), NOW());
-
-- 处理失败的文档
-INSERT INTO api_document VALUES
-(3, 'doc-003', 'EXTERNAL_API', '江苏', '公积金查询', 'v1.5',
- '江苏公积金查询.html', '/docs/jiangsu/fund-v1.5.html',
- 'ghi789...', 512000,
- 'FAILED', 0, '不支持HTML格式', NULL, NOW(), NOW());
-```
-
---
-
-## 数据量预估
-
-```
-预估：100-200 条
- 外部接口文档：50-100 条
- 内部服务文档：20-50 条
- 其他文档：30-50 条
-
-存储：
- 单条记录：约 1KB
- 200 条：约 200KB
-
-结论：数据量很小
-```
-
---
-
-## MVP 版本的简化
-
-```
-Phase 1（当前）：
-✅ 基础字段和表结构
-✅ 文件去重（file_hash）
-✅ 状态追踪（status）
-✅ 硬删除
-✅ 通过 doc_id 关联 Milvus
-
-Phase 2（未来增强）：
-❌ enabled（启用开关）
-❌ archived_at（软删除）
-❌ batch_id（批次管理）
-❌ status 细化
-❌ tags（标签分类）
-```
@@ -1,4 +1,6 @@
-# diagnosis_record - 诊断记录表
+# diagnosis_record - 旧诊断记录表
+
+> 归档说明：`diagnosis_record` 已在 `V007__drop_diagnosis_record.sql` 中删除，当前主模型是 `diagnosis_session + agent_step + tool_invocation`。本文只用于追溯早期设计。

 ## 表定位

@@ -1,265 +0,0 @@
-# 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）
-❌ 案例合并功能
-```
@@ -0,0 +1,66 @@
+# 工具调用表：tool_invocation
+
+**状态**：当前表  
+**来源**：`V005__create_session_storage.sql`、`V010__add_relevance_level_to_tool_invocation.sql`、`ToolInvocation`
+
+## 定位
+
+`tool_invocation` 记录 Agent 显式调用工具的事实，包括工具名、入参、输出摘要、检索层级、证据引用和失败信息。它是 Trace、Verifier、评测和人工排查的共同数据源。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `session_id` | VARCHAR(64) | 是 | 关联 `diagnosis_session.session_id` |
+| `step_id` | BIGINT | 否 | 可关联 `agent_step.id` |
+| `tool_name` | VARCHAR(64) | 是 | 工具名称，例如 `lookup_knowledge`、日志查询、指标查询 |
+| `input_params` | JSON | 是 | 工具入参 |
+| `output_preview` | TEXT | 否 | 工具输出摘要或前缀 |
+| `output_length` | INT | 否 | 工具输出字符数 |
+| `retrieval_layer` | VARCHAR(8) | 否 | 检索层级，例如 `L0`、`L1`、`L0+L1` |
+| `l0_match_count` | INT | 否 | L0 命中数量 |
+| `l1_match_count` | INT | 否 | L1 命中数量 |
+| `is_truncated` | BOOLEAN | 否 | 输出是否被截断 |
+| `relevance_level` | VARCHAR(20) | 否 | 归一化质量等级：`PRECISE`、`HIGHLY_RELEVANT`、`REFERENCE`、`DEDUPED` |
+| `dedup_reason` | VARCHAR(32) | 否 | 去重原因，例如 `doc_retrieved`、`domain_retrieved` |
+| `retrieval_details` | JSON | 否 | 检索明细、证据引用、Gatekeeper 可用导航信息 |
+| `duration_ms` | INT | 否 | 工具耗时 |
+| `success` | BOOLEAN | 否 | 工具是否成功 |
+| `error_message` | TEXT | 否 | 失败原因 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `idx_session_id` | `session_id` | 按会话查询工具调用 |
+| `idx_tool_name` | `tool_name` | 按工具类型排查 |
+| `idx_retrieval_layer` | `retrieval_layer` | 观察 RAG L0/L1 行为 |
+
+## 关系
+
+- `tool_invocation.session_id` 逻辑关联 `diagnosis_session.session_id`。
+- `tool_invocation.step_id` 可关联 `agent_step.id`，但当前不强制。
+
+## 关键 JSON
+
+`retrieval_details` 是扩展字段。当前重要结构包括：
+
+```json
+{
+  "evidence_status": "supported",
+  "evidence_refs": [
+    {
+      "raw_path": "$.logs[0]",
+      "text": "工具返回中可核对的最小证据文本"
+    }
+  ]
+}
+```
+
+## 注意点
+
+- Verifier 不应只信任 RAG 证据；所有工具只要能提供 `evidence_refs`，都应该进入可校验证据链。
+- `output_preview` 只适合展示和排查，不应被当成完整原始输出。
+- `$.no_evidence` 只代表“本次工具未命中证据”，不能推导为“故障不存在”。
@@ -0,0 +1,51 @@
+# 文档元数据表：api_document
+
+**状态**：当前表  
+**来源**：`V003__create_api_document.sql`、`V004__add_metadata_to_api_document.sql`、`ApiDocument`
+
+## 定位
+
+`api_document` 是知识库文档的 MySQL 元数据表。它不保存向量正文，正文切片和向量检索由 Milvus/Zilliz collection 承担；两侧通过 `doc_id` 和 chunk metadata 逻辑关联。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `doc_id` | VARCHAR(64) | 是 | 文档唯一 ID，关联向量库 chunk metadata |
+| `fault_category` | VARCHAR(32) | 否 | 文档类别，默认 `EXTERNAL_API`；实体侧使用 `FaultCategory` |
+| `fault_source` | VARCHAR(128) | 否 | 文档归属，例如服务名、省份或系统来源 |
+| `api_name` | VARCHAR(128) | 否 | 接口或文档主题名称 |
+| `version` | VARCHAR(32) | 否 | 文档版本，默认 `v1.0` |
+| `file_name` | VARCHAR(256) | 是 | 原始文件名 |
+| `file_path` | VARCHAR(512) | 否 | 文件存储路径 |
+| `file_hash` | VARCHAR(64) | 否 | 文件 MD5，用于去重 |
+| `file_size` | BIGINT | 否 | 文件大小，单位字节 |
+| `status` | VARCHAR(16) | 否 | 索引状态：`PENDING`、`PROCESSING`、`INDEXED`、`FAILED` |
+| `chunk_count` | INT | 否 | 向量库切片数量 |
+| `error_message` | TEXT | 否 | 索引失败原因 |
+| `metadata` | TEXT | 否 | frontmatter 元数据 JSON 字符串 |
+| `indexed_at` | DATETIME | 否 | 索引完成时间 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+| `updated_at` | DATETIME | 是 | 更新时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `uk_file_hash` | `file_hash` | 文件去重 |
+| `idx_doc_id` | `doc_id` | 按文档 ID 查询 |
+| `idx_fault_source` | `fault_source` | 按来源筛选 |
+| `idx_status` | `status` | 查看索引状态 |
+| `idx_created_at` | `created_at` | 按上传时间排序 |
+
+## 关系
+
+- `api_document.doc_id` 与向量库 chunk metadata 中的 `docId` / `doc_id` 逻辑关联。
+- `knowledge_domain.domain_id` 与文档 metadata 中的 `category` 形成领域聚合关系；当前没有数据库外键。
+
+## 注意点
+
+- 删除文档时需要同时处理 MySQL 元数据和向量库 chunk。
+- `metadata` 是 JSON 字符串，不是 MySQL JSON 列。
+- 表字段以 Flyway 为准；实体默认值和枚举可能与迁移脚本的 SQL 默认值存在历史差异，排查时优先看实际迁移和数据库结构。
@@ -0,0 +1,50 @@
+# 案例库表：case_library
+
+**状态**：当前表  
+**来源**：`V002__create_case_library.sql`、`CaseLibrary`
+
+## 定位
+
+`case_library` 保存高质量诊断案例，用于后续相似案例推荐和知识沉淀。当前自动沉淀路径来自 `useful` 用户反馈：系统把 `diagnosis_session` 中的 query 和 answer 映射为案例内容。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `case_id` | VARCHAR(64) | 是 | 案例唯一 ID |
+| `diagnosis_id` | VARCHAR(64) | 否 | 关联诊断会话；当前自动生成时存 `diagnosis_session.session_id` |
+| `source_type` | VARCHAR(16) | 否 | 来源类型：`AUTO` 或 `MANUAL` |
+| `fault_category` | VARCHAR(32) | 否 | 故障类别，实体侧使用 `FaultCategory` |
+| `fault_source` | VARCHAR(128) | 否 | 故障源，例如服务、系统或省份 |
+| `fault_target` | VARCHAR(256) | 否 | 故障目标，例如接口、方法、SQL 或组件 |
+| `error_code` | VARCHAR(64) | 否 | 错误码或异常类型 |
+| `title` | VARCHAR(256) | 是 | 案例标题 |
+| `root_cause` | TEXT | 是 | 根因分析 |
+| `solution` | TEXT | 是 | 解决方案 |
+| `reference_count` | INT | 否 | 被推荐次数 |
+| `created_by` | VARCHAR(64) | 否 | 创建人 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+| `updated_at` | DATETIME | 是 | 更新时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `idx_fault_category` | `fault_category` | 按故障类别筛选 |
+| `idx_error_code` | `error_code` | 按错误码精确匹配 |
+| `idx_fault_source` | `fault_source` | 按故障源筛选 |
+| `idx_fault_target` | `fault_target(100)` | 按故障目标筛选 |
+| `idx_diagnosis_id` | `diagnosis_id` | 追溯来源会话 |
+| `idx_reference_count` | `reference_count` | 推荐排序 |
+| `idx_created_at` | `created_at` | 时间排序 |
+
+## 关系
+
+- `case_library.diagnosis_id` 当前逻辑关联 `diagnosis_session.session_id`，不是旧的 `diagnosis_record`。
+- 人工录入案例可以不填写 `diagnosis_id`。
+
+## 注意点
+
+- 旧文档里提到的 `diagnosis_record` 已被 `V007` 删除，不再是当前主模型。
+- 当前自动沉淀仍比较粗：`root_cause` 和 `solution` 都可能来自完整 answer。后续可从结构化结论中拆分根因、证据和修复建议。
@@ -0,0 +1,36 @@
+# 知识域表：knowledge_domain
+
+**状态**：当前表  
+**来源**：`V009__add_knowledge_domain.sql`、`KnowledgeDomain`
+
+## 定位
+
+`knowledge_domain` 保存知识库领域级元数据，用来帮助 Planner/Executor 判断什么时候检索某一类知识，并为 RAG 的 domain hint、去重和可观测性提供基础信息。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `domain_id` | VARCHAR(64) | 是 | 领域 ID，通常对应文档 category，例如 `payment`、`infrastructure` |
+| `description` | VARCHAR(256) | 否 | 领域描述 |
+| `when_to_retrieve` | TEXT | 否 | 何时检索该领域的提示说明 |
+| `document_count` | INT | 是 | 当前领域文档数量 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+| `updated_at` | DATETIME | 是 | 更新时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| unique | `domain_id` | 保证领域 ID 唯一 |
+
+## 关系
+
+- `knowledge_domain.domain_id` 与 `api_document.metadata` 或向量库 chunk metadata 中的 `category` 逻辑关联。
+- 当前没有数据库外键，领域文档数量由服务逻辑维护。
+
+## 注意点
+
+- `when_to_retrieve` 是检索策略提示，不是事实证据。
+- Executor / Verifier 不能把领域描述当作诊断结论依据；事实仍应来自工具返回的证据块或证据引用。
@@ -0,0 +1,47 @@
+# 诊断会话表：diagnosis_session
+
+**状态**：当前主表  
+**来源**：`V005__create_session_storage.sql`、`V008__add_answer_to_diagnosis_session.sql`、`DiagnosisSession`
+
+## 定位
+
+`diagnosis_session` 是一次 Chat 或 AIOps 诊断的会话级主记录，负责保存用户问题、执行状态、最终答案、总体统计和自评估结果。
+
+## 字段
+
+| 字段 | 类型 | 必填 | 说明 |
+|---|---|---|---|
+| `id` | BIGINT | 是 | 自增主键 |
+| `session_id` | VARCHAR(64) | 是 | 会话唯一 ID，Trace API 和反馈接口使用它 |
+| `query` | TEXT | 是 | 用户原始问题或 AIOps 输入摘要 |
+| `status` | VARCHAR(16) | 否 | `PENDING`、`RUNNING`、`SUCCESS`、`FAILED` |
+| `agent_flow` | VARCHAR(32) | 否 | `CHAT` 或 `AI_OPS` |
+| `total_duration_ms` | INT | 否 | 总耗时，单位毫秒 |
+| `total_token_count` | INT | 否 | 总 Token 消耗 |
+| `step_count` | INT | 否 | Agent 步骤数 |
+| `tool_call_count` | INT | 否 | 工具调用次数 |
+| `answer` | LONGTEXT | 否 | 返回给用户的最终答案 |
+| `self_evaluation` | JSON | 否 | rule、verifier、aiops 等自评估结果容器 |
+| `feedback` | VARCHAR(16) | 否 | 用户反馈：`useful`、`not_useful` 或空 |
+| `created_at` | DATETIME | 是 | 创建时间 |
+| `updated_at` | DATETIME | 是 | 更新时间 |
+
+## 索引
+
+| 索引 | 字段 | 用途 |
+|---|---|---|
+| `session_id` unique | `session_id` | 会话唯一约束 |
+| `idx_created_at` | `created_at` | 按时间查询 |
+| `idx_status` | `status` | 按状态筛选 |
+| `idx_agent_flow` | `agent_flow` | 区分 Chat / AIOps |
+
+## 关系
+
+- `agent_step.session_id` 逻辑关联 `diagnosis_session.session_id`。
+- `tool_invocation.session_id` 逻辑关联 `diagnosis_session.session_id`。
+- `case_library.diagnosis_id` 在自动生成案例时保存 `diagnosis_session.session_id`。
+
+## 注意点
+
+- 当前没有数据库外键，Trace 聚合依赖 `session_id`。
+- `self_evaluation` 是扩展容器，里面可能包含 `rule_evaluation`、`verifier_evaluation`、`aiops_rule_evaluation`。