docs(design): 补全中文设计文档体系

docs/设计文档/模块设计/3.文档模块详细设计.md

@@ -0,0 +1,127 @@
+# 文档模块详细设计
+
+## 1. 模块目标
+
+Documents 模块让用户把复试题材料快速变成 Agent 可检索的知识库。V1 必须支持 `.txt`、`.md`、`.pdf` 和 `.docx`，保证常见复试材料可以进入 RAG。
+
+## 2. 职责边界
+
+负责：
+
+- 文件上传表单和页面。
+- 文件保存与元数据记录。
+- 读取文本内容。
+- 调用 Agent Core RAG 入库。
+- 更新入库状态。
+
+不负责：
+
+- 不实现向量检索算法。
+- 不生成模型回答。
+- 不直接写审计日志。
+
+## 3. 数据模型设计
+
+模型：`UploadedDocument`
+
+字段见 `docs/设计文档/3.数据库设计.md`。
+
+常量：
+
+```python
+STATUS_UPLOADED = "uploaded"
+STATUS_INDEXED = "indexed"
+STATUS_FAILED = "failed"
+SUPPORTED_EXTENSIONS = {".txt", ".md", ".pdf", ".docx"}
+```
+
+文件保存路径建议：
+
+```text
+uploads/<scenario_id>/<YYYYMMDD>/<uuid>_<original_name>
+```
+
+## 4. 文件上传流程
+
+1. GET `/documents/upload/` 渲染上传表单。
+2. POST 校验 `scenario_id` 和文件。
+3. 调用 Scenarios 服务确认场景存在。
+4. 校验扩展名和文件大小。
+5. 保存文件。
+6. 创建 `UploadedDocument(status="uploaded")`。
+7. 跳转文件列表页并展示成功提示。
+
+## 5. 文本抽取流程
+
+抽取函数：
+
+```python
+def extract_text(document: UploadedDocument) -> str:
+    """按文件类型抽取可入库纯文本，失败时抛出可展示的业务异常。"""
+```
+
+规则：
+
+- `.txt`：优先 UTF-8，失败时尝试系统默认编码。
+- `.md`：UTF-8 读取，保留标题、列表和正文。
+- `.pdf`：抽取纯文本，不要求 OCR、表格还原和复杂版式理解。
+- `.docx`：抽取段落、标题和普通表格文本，不要求完整保留 Word 样式。
+- 空文本视为失败。
+- 文件不存在视为失败。
+
+XLSX 暂不作为 V1 必须项，可作为后续结构化业务数据导入能力。
+
+## 6. RAG 入库触发流程
+
+POST `/documents/<id>/index/`
+
+1. 获取 `UploadedDocument`。
+2. 调用 `extract_text()`。
+3. 调用 `agent_core.rag.ingest.ingest_document()`，传入 `document_id`、`scenario_id`、文件名和抽取文本。
+4. 成功后更新 `status="indexed"`，清空 `error_message`。
+5. 失败后更新 `status="failed"`，写入 `error_message`。
+6. 重定向回文件列表页。
+
+入库动作必须使用 POST，避免 GET 触发写操作。
+
+已入库或失败文档允许重新入库。重新入库前需要按 `document_id` 清理或覆盖旧 chunk，避免重复检索。
+
+## 7. 页面设计
+
+文件列表页展示：
+
+- 文件名。
+- 场景 ID。
+- 文件类型。
+- 文件大小。
+- 状态。
+- 上传时间。
+- 入库按钮。
+- 错误信息。
+
+上传页展示：
+
+- 场景下拉框。
+- 文件控件。
+- 支持类型提示。
+- 表单错误。
+
+## 8. 异常处理
+
+| 异常 | 处理 |
+|---|---|
+| 场景不存在 | 表单错误 |
+| 文件为空 | 表单错误 |
+| 扩展名不支持 | 表单错误 |
+| 文件保存失败 | 页面提示失败 |
+| 文本为空 | 状态 failed |
+| RAG 入库失败 | 状态 failed 并保存原因 |
+
+## 9. 验收标准
+
+- 可以上传 `.txt`、`.md`、`.pdf` 和 `.docx`。
+- 文件列表可看到记录。
+- 文件可按场景关联。
+- 入库成功状态变为 `indexed`。
+- 入库失败状态变为 `failed` 且可查看原因。
+- 入库失败或已入库文档可重新入库。