pj0235-eai_agentplatform/docs/02_Architecture/AR03_Database_Arch.md

AR03 — 数据库架构设计

版本：V1.1 | 引擎：MySQL 8.0 | ORM：SQLAlchemy（现为 GORM） 完整建表 SQL 请见 docs/db_schema.md

⚠️ 本文档为 V1.1 设计期历史快照。 当前实现已切换为 MySQL 8.0 + FAISS 向量检索（ORM 由 SQLAlchemy 改为 GORM），并新增岗位/积分/证书/部门/消息等表，以 docs/db_schema.md 与 docs/changelog.md（V1.4–V1.7）为准。

---

1. ER 关系总图

user ──< media_file          (submitter_id / audit_by)
user ──< exam_record         (user_id)
product ──< course            (related_product_id)
course ──< question           (course_id, optional)
media_file ──< knowledge_chunk (media_file_id)
exam_paper ──< exam_record   (paper_id)

2. 表清单

#	表名	说明	核心字段数
1	user	用户账号	7
2	product	产品信息	16
3	course	课程内容	16
4	media_file	素材文件元数据	16
5	knowledge_chunk	AI 知识库文本块	6
6	question	题库题目	11
7	exam_paper	考试配置/组卷	11
8	exam_record	考试记录档案	12
9	system_config	系统参数配置	4

3. 索引策略

表	索引	类型	说明
user	role, status	BTREE	角色筛选、状态筛选
product	category, status	BTREE	分类筛选、状态筛选
course	category, status, related_product_id	BTREE	同上
media_file	status, submitter_id, (bind_type, bind_id), extracted	BTREE	审批列表、绑定查询、提取状态
knowledge_chunk	media_file_id	BTREE	关联查询
knowledge_chunk	content	FULLTEXT	AI 知识检索（MySQL 全文索引）
question	domain, course_id, status	BTREE	知识域筛选、课程筛选
exam_paper	type, status	BTREE	考试类型筛选
exam_record	user_id, paper_id, passed, submitted_at	BTREE	用户查记录、管理员查全部
system_config	config_key	UNIQUE	键查值

4. AI 知识检索说明

V1.1 使用 MySQL 全文索引（FULLTEXT）；现已升级为 MySQL 全文索引（关键词）+ FAISS 向量检索（语义）双路混合召回：

-- knowledge_chunk 表已建全文索引（关键词召回）
FULLTEXT INDEX ft_kc_content (content)

-- 检索查询
SELECT * FROM knowledge_chunk
WHERE MATCH(content) AGAINST(:keywords IN NATURAL LANGUAGE MODE)
LIMIT 10

检索流程（当前）：

1. 用户提问 → 关键词 + embedding 向量
2. MySQL FULLTEXT 关键词召回 + FAISS 语义向量召回，双路融合排序
3. 匹配段落作为上下文注入 LLM Prompt
4. LLM 基于上下文生成回答

演进说明： V1.1 曾为避免 embedding 依赖而仅用全文索引；平台升级后引入 FAISS 补足语义召回，见 docs/db_schema.md。

5. 文件存储策略

• 数据库只存元数据，不存文件二进制
• 物理文件存储在 backend/data/media/
• 目录结构：

  data/media/
  ├── upload/           # 上传文件存储（UUID 重命名）
  └── _preview_cache/  # 预览缓存（LibreOffice 转 PDF 后存放）
  

• 文件命名：UUID 重命名，杜绝路径穿越
• 文件扩展名白名单：ppt / pptx / pdf / doc / docx / mp4 / png / jpg / jpeg