# 文档模块需求文档

## 1. 模块定位

Documents 模块负责文件上传、文件管理、文本抽取和知识库入库入口。

该模块是复试题快速适配的关键模块。拿到题目材料后，用户需要能快速上传文档，并让 Agent 在对话中使用这些文档。

## 2. 模块目标

- 支持上传题目材料和知识库文件。
- 保存文件元数据。
- 支持按场景关联文件。
- 提供文档入库入口。
- 为 Agent Core 的 RAG 模块提供文件内容。

## 3. 职责边界

### 3.1 负责

- 文件上传页面。
- 文件保存。
- 文件元数据记录。
- 文件与场景关联。
- 文本抽取入口。
- 触发 RAG 入库。

### 3.2 不负责

- 不负责具体向量检索算法。
- 不负责 embedding 生成细节。
- 不负责 Agent 对话编排。
- 不负责模型回答。

## 4. 支持文件类型

V1 必须支持：

| 类型 | 扩展名 | 说明 |
|---|---|---|
| 文本文档 | `.txt` | 第一优先级，最稳定 |
| Markdown | `.md` | 适合准备知识库和规则 |
| PDF | `.pdf` | 复试常见材料格式，V1 抽取纯文本 |
| Word | `.docx` | 复试常见材料格式，V1 抽取段落文本 |

后续增强：

| 类型 | 扩展名 | 说明 |
|---|---|---|
| Excel | `.xlsx` | 后续可作为业务数据源或结构化表格导入 |

## 5. 数据模型需求

建议模型：`UploadedDocument`

字段：

| 字段 | 类型 | 说明 |
|---|---|---|
| `id` | int | 主键 |
| `scenario_id` | string | 关联场景 ID |
| `original_name` | string | 原始文件名 |
| `file` | FileField | Django FileField 相对路径，不保存用户本机绝对路径 |
| `file_type` | string | 文件类型 |
| `size` | int | 文件大小 |
| `status` | string | `uploaded` / `indexed` / `failed` |
| `error_message` | text | 入库失败原因 |
| `created_at` | datetime | 上传时间 |
| `updated_at` | datetime | 更新时间 |

## 6. 页面需求

### 6.1 文件上传页

路径：`/documents/upload/`

页面元素：

- 场景选择下拉框。
- 文件选择按钮。
- 上传按钮。
- 支持类型提示。
- 上传结果提示。

### 6.2 文件列表页

路径：`/documents/`

展示内容：

- 文件名。
- 所属场景。
- 文件类型。
- 文件大小。
- 入库状态。
- 上传时间。
- 入库按钮。

## 7. RAG 入库流程

用户上传文件后，可以手动触发入库。

流程：

1. 用户上传文件。
2. 系统保存文件和元数据。
3. 用户点击入库按钮。
4. Documents 模块读取文件文本。
5. 调用 `agent_core.rag.ingest`。
6. 入库成功后更新状态为 `indexed`。
7. 入库失败后更新状态为 `failed` 并保存错误信息。

## 8. 文本抽取需求

V1 文本抽取策略：

- `.txt`：按 UTF-8 读取，失败时尝试系统默认编码。
- `.md`：按 UTF-8 读取，保留标题和正文。
- `.pdf`：抽取纯文本，不要求 OCR、表格还原和复杂版式理解。
- `.docx`：抽取段落、标题和普通表格文本，不要求完整保留 Word 样式。

入库失败后的文档允许重新触发入库。重新入库前需要清理或覆盖同一 `document_id` 对应的旧 chunk，避免重复检索。

## 9. 验收标准

- 可以上传 `.txt`、`.md`、`.pdf`、`.docx` 文件。
- 上传后可以在文件列表看到记录。
- 文件可以关联到指定场景。
- 可以触发文件入库。
- 入库成功后状态变为 `indexed`。
- 入库失败时页面能显示失败原因。
- 入库失败的文档可以重新入库。