# 文档元数据表：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 默认值存在历史差异，排查时优先看实际迁移和数据库结构。