docs(requirements): 统一需求文档中文命名

docs/需求分析/5.文档模块需求.md

@@ -0,0 +1,132 @@
+# 文档模块需求文档
+
+## 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`。
+- 入库失败时页面能显示失败原因。
+- 入库失败的文档可以重新入库。