SuperBizAgent-java/mvp/tables/文档元数据表-api_document.md

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