SuperBizAgent-java/docs/tables/api_document.md

api_document - 文档元数据表

表定位

文档管理表：管理接口文档的元信息，不负责文档检索（检索由 Milvus 负责）

设计理念

文档管理，不是文档检索

核心定位：

• MySQL 负责文档元数据管理（状态、版本、去重）
• Milvus 负责文档内容存储和检索
• 通过 doc_id 关联两者

MVP版本原则：

• ✅ 最简字段，满足基本管理需求
• ✅ 文件去重（基于 file_hash）
• ✅ 状态追踪（索引进度）
• ✅ 硬删除（同步删除 Milvus 数据）
• ❌ 暂不支持：软删除、启用开关、版本管理（Phase 2）

---

表结构（MVP版）

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）

---

典型查询

-- 查看文档列表
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

{
  "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 代码示例

// 插入时携带 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());

---

数据示例

-- 外部接口文档
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（标签分类）