docs: 重构文档结构，分离学习笔记和 MVP 架构设计
**变更概述：** - 将 MVP 架构设计文档独立到项目根目录 `mvp/` - 整理 `docs/` 为纯学习和分析文档目录 - 按类型分类：learning（学习）、analysis（分析）、reports（报告）、guides（指南） **目录结构：** ``` mvp/ # MVP 架构设计（独立） ├── README.md # 数据库设计总览 ├── architecture/ # 架构文档 │ ├── agent-architecture-mvp.md │ ├── implementation-plan.md │ └── ... └── tables/ # 数据表设计 docs/ # 学习和分析文档 ├── learning/ # 学习笔记（00-08 编号） ├── analysis/ # 分析笔记 + 重构计划 ├── reports/ # 临时报告 └── guides/ # 指南文档 ``` **详细变更：** - docs/README.md → mvp/README.md（数据库设计入口） - docs/architecture/ → mvp/architecture/（架构设计） - docs/tables/ → mvp/tables/（数据表设计） - docs/学习笔记-*.md → docs/learning/07-*.md, 08-*.md - docs/项目学习路径.md → docs/learning/00-*.md - docs/功能分析报告.md → docs/analysis/ - docs/修复报告-*.md → docs/reports/ - docs/日志配置*.md → docs/guides/ 或 docs/reports/ - docs/design/ → docs/analysis/（问题分析和重构计划）
This commit is contained in:
zhuyongxin
@@ -0,0 +1,332 @@
|
||||
# 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（标签分类）
|
||||
```
|
||||
@@ -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）
|
||||
❌ 案例合并功能
|
||||
```
|
||||
@@ -0,0 +1,240 @@
|
||||
# diagnosis_record - 诊断记录表
|
||||
|
||||
## 表定位
|
||||
|
||||
**核心业务表**：存储每次诊断任务的完整记录
|
||||
|
||||
## 设计理念
|
||||
|
||||
### 兼容多种故障类型
|
||||
|
||||
**问题背景**：
|
||||
- 初始设计过于聚焦"外部接口故障"
|
||||
- 实际故障类型更丰富：空指针异常、数据库死锁、缓存穿透、线程池耗尽等
|
||||
|
||||
**解决方案**：
|
||||
- 字段泛化：business_id 替代 order_id，fault_source 替代 province
|
||||
- 增加分类：fault_category 显式区分故障类别
|
||||
- 增强错误信息：error_message、stack_trace 支持内部错误
|
||||
|
||||
---
|
||||
|
||||
## 表结构（v2.0）
|
||||
|
||||
```sql
|
||||
CREATE TABLE diagnosis_record (
|
||||
-- 主键
|
||||
id BIGINT PRIMARY KEY AUTO_INCREMENT,
|
||||
diagnosis_id VARCHAR(64) UNIQUE NOT NULL COMMENT '诊断唯一ID（UUID）',
|
||||
|
||||
-- 关联信息
|
||||
session_id VARCHAR(64) COMMENT '会话ID（关联Redis）',
|
||||
business_id VARCHAR(128) COMMENT '业务标识（订单号/请求ID/线程ID/任务ID...）',
|
||||
trace_id VARCHAR(64) COMMENT '链路追踪ID',
|
||||
|
||||
-- 故障分类（泛化设计）
|
||||
fault_category VARCHAR(32) COMMENT '故障类别（EXTERNAL_API/INTERNAL_ERROR/DATABASE/CACHE/NETWORK/THREAD/MEMORY/CONFIG）',
|
||||
fault_source VARCHAR(128) COMMENT '故障源（省份/服务名/类名/数据库实例...）',
|
||||
fault_target VARCHAR(256) COMMENT '故障目标（接口URL/方法名/SQL语句/缓存键...）',
|
||||
|
||||
-- 错误信息（通用）
|
||||
error_code VARCHAR(64) COMMENT '错误码（业务错误码/HTTP状态码/异常类名）',
|
||||
error_message TEXT COMMENT '错误消息',
|
||||
stack_trace TEXT COMMENT '堆栈信息（内部错误时记录）',
|
||||
|
||||
-- 诊断结果
|
||||
problem_type VARCHAR(32) COMMENT '问题类型（参数/网络/权限/逻辑/空指针/死锁...）',
|
||||
root_cause TEXT COMMENT '根因分析',
|
||||
solution TEXT COMMENT '修复方案',
|
||||
report_markdown TEXT COMMENT '完整诊断报告（Markdown格式）',
|
||||
|
||||
-- 评估指标
|
||||
status VARCHAR(16) DEFAULT 'PENDING' COMMENT '诊断状态（PENDING/RUNNING/SUCCESS/FAILED）',
|
||||
confidence INT COMMENT '诊断置信度（0-100）',
|
||||
duration INT COMMENT '诊断耗时（毫秒）',
|
||||
|
||||
-- 用户反馈
|
||||
feedback VARCHAR(16) COMMENT '用户反馈（useful/not_useful/null）TODO: 后续可拆分为独立反馈表',
|
||||
|
||||
-- 调试字段
|
||||
tool_calls JSON COMMENT '工具调用记录',
|
||||
|
||||
-- 元数据
|
||||
created_by VARCHAR(64) COMMENT '创建人',
|
||||
created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
|
||||
updated_at DATETIME DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP,
|
||||
|
||||
-- 索引
|
||||
INDEX idx_business_id (business_id),
|
||||
INDEX idx_trace_id (trace_id),
|
||||
INDEX idx_session_id (session_id),
|
||||
INDEX idx_fault_category (fault_category),
|
||||
INDEX idx_fault_source_target (fault_source, fault_target(100)),
|
||||
INDEX idx_error_code (error_code),
|
||||
INDEX idx_created_at (created_at),
|
||||
INDEX idx_status (status)
|
||||
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COMMENT='诊断记录表（v2.0 泛化版）';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 字段说明
|
||||
|
||||
### 核心字段
|
||||
|
||||
| 字段 | 说明 | 示例 |
|
||||
|------|------|------|
|
||||
| diagnosis_id | 诊断唯一标识 | diag-001 |
|
||||
| session_id | 会话ID（支持追问） | sess-abc |
|
||||
| business_id | **泛化**：业务标识 | 订单号/请求ID/线程ID |
|
||||
| trace_id | 链路追踪ID | trace-xyz |
|
||||
|
||||
### 故障分类字段（泛化设计）
|
||||
|
||||
| 字段 | 说明 | 外部接口示例 | 内部错误示例 |
|
||||
|------|------|-------------|-------------|
|
||||
| fault_category | 故障类别 | EXTERNAL_API | INTERNAL_ERROR |
|
||||
| fault_source | 故障源 | 广东 | order-service |
|
||||
| fault_target | 故障目标 | /api/v1/social | OrderController.create() |
|
||||
| error_code | 错误码 | 40003 | NullPointerException |
|
||||
|
||||
### fault_category 枚举值
|
||||
|
||||
```
|
||||
EXTERNAL_API - 外部接口调用失败
|
||||
INTERNAL_ERROR - 系统内部错误（空指针、NPE）
|
||||
DATABASE - 数据库问题（死锁、慢查询）
|
||||
CACHE - 缓存问题（穿透、雪崩）
|
||||
NETWORK - 网络问题（超时、连接失败）
|
||||
THREAD - 线程问题（线程池满、死锁）
|
||||
MEMORY - 内存问题（OOM、内存泄漏）
|
||||
CONFIG - 配置问题（配置错误、缺失）
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 数据示例
|
||||
|
||||
### 示例1：外部接口故障
|
||||
```sql
|
||||
INSERT INTO diagnosis_record VALUES (
|
||||
NULL, 'diag-001', 'sess-abc', '202406150001', 'trace-001',
|
||||
'EXTERNAL_API', '广东', '/api/v1/guangdong/social-security', '40003',
|
||||
'参数缺失：idCard', NULL,
|
||||
'参数问题', 'idCard字段缺失', '补充前端校验', '完整报告...',
|
||||
'SUCCESS', 85, 5234, NULL,
|
||||
NULL, NOW(), NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### 示例2：空指针异常
|
||||
```sql
|
||||
INSERT INTO diagnosis_record VALUES (
|
||||
NULL, 'diag-002', 'sess-def', 'req-xyz789', NULL,
|
||||
'INTERNAL_ERROR', 'order-service', 'OrderController.createOrder()', 'NullPointerException',
|
||||
'Cannot invoke "User.getName()" because "user" is null',
|
||||
'java.lang.NullPointerException: ...\n at OrderController.java:45\n ...',
|
||||
'空指针异常', 'createOrder方法中user对象为null', '添加空判断', '完整报告...',
|
||||
'SUCCESS', 90, 3456, NULL,
|
||||
NULL, NOW(), NOW()
|
||||
);
|
||||
```
|
||||
|
||||
### 示例3：数据库死锁
|
||||
```sql
|
||||
INSERT INTO diagnosis_record VALUES (
|
||||
NULL, 'diag-003', 'sess-ghi', 'txn-20240615-001', NULL,
|
||||
'DATABASE', 'mysql-master-01', 'UPDATE orders SET status=? WHERE order_id=?', '1213',
|
||||
'Deadlock found when trying to get lock', NULL,
|
||||
'数据库死锁', '两个事务互相等待对方释放锁', '调整事务加锁顺序', '完整报告...',
|
||||
'SUCCESS', 88, 4567, NULL,
|
||||
NULL, NOW(), NOW()
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 典型查询
|
||||
|
||||
### 按故障类别统计
|
||||
```sql
|
||||
SELECT
|
||||
fault_category,
|
||||
COUNT(*) as count,
|
||||
ROUND(AVG(duration), 2) as avg_duration_ms,
|
||||
ROUND(AVG(confidence), 2) as avg_confidence
|
||||
FROM diagnosis_record
|
||||
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY)
|
||||
GROUP BY fault_category
|
||||
ORDER BY count DESC;
|
||||
```
|
||||
|
||||
### 内部错误Top异常
|
||||
```sql
|
||||
SELECT
|
||||
error_code,
|
||||
fault_target,
|
||||
COUNT(*) as count
|
||||
FROM diagnosis_record
|
||||
WHERE fault_category = 'INTERNAL_ERROR'
|
||||
AND created_at >= DATE_SUB(NOW(), INTERVAL 30 DAY)
|
||||
GROUP BY error_code, fault_target
|
||||
ORDER BY count DESC
|
||||
LIMIT 10;
|
||||
```
|
||||
|
||||
### 诊断成功率
|
||||
```sql
|
||||
SELECT
|
||||
COUNT(*) as total,
|
||||
SUM(CASE WHEN status = 'SUCCESS' THEN 1 ELSE 0 END) as success,
|
||||
ROUND(SUM(CASE WHEN status = 'SUCCESS' THEN 1 ELSE 0 END) * 100.0 / COUNT(*), 2) as success_rate
|
||||
FROM diagnosis_record
|
||||
WHERE created_at >= DATE_SUB(NOW(), INTERVAL 7 DAY);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 核心设计决策
|
||||
|
||||
### 1. 一次诊断 = 一条记录
|
||||
- 用户发起一次诊断任务，创建一条记录
|
||||
- 不是聊天记录（不存多轮对话）
|
||||
- 追问对话上下文暂存 Redis（30分钟过期）
|
||||
|
||||
### 2. report_markdown 字段的必要性
|
||||
- 固化结果：Prompt变化不影响历史报告
|
||||
- 快速展示：不需要重新生成
|
||||
- 历史审计：可以看到当时的诊断结果
|
||||
|
||||
### 3. 字段泛化的好处
|
||||
- 支持多种故障类型（不限于外部接口）
|
||||
- 灵活填写（根据故障类型选择字段值）
|
||||
- 易于扩展（新增故障类型只需增加枚举值）
|
||||
|
||||
---
|
||||
|
||||
## 数据量预估
|
||||
|
||||
```
|
||||
场景：中型企业运维团队
|
||||
- 日均诊断：100 次
|
||||
- 月均诊断：3000 次
|
||||
- 年均诊断：36000 次
|
||||
|
||||
存储预估：
|
||||
- 单条记录：约 5KB（含报告）
|
||||
- 年存储量：36000 × 5KB = 180MB
|
||||
- 三年存储：540MB
|
||||
|
||||
结论：数据量不大，可以全量保留
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 版本历史
|
||||
|
||||
| 版本 | 日期 | 变更内容 |
|
||||
|------|------|---------|
|
||||
| v1.0 | 2024-06-15 | 初版，基础字段 |
|
||||
| v2.0 | 2024-06-22 | 字段泛化，支持多种故障类型 |
|
||||
Reference in New Issue
Block a user