# 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 向量检索（语义）双路混合召回**：

```sql
-- 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