### 背景与目标
- 现状：当前 RAG 仅支持纯文本（.txt/.md/.json），解析简单，未考虑结构化要素、页码、表格、段落层级，也缺乏对常见办公文档的支持。
- 目标：将项目从“面向 VTuber 的轻量文本 RAG”升级为“企业数字人助手的通用 RAG”，支持主流办公文档，保证解析质量、可维护性与可扩展性。

### 选型与方案对比
- 优先约束与建议
  - 你的项目是 Python/FastAPI，不适用 EF；建议按“Controller-Service-Interface”思想塑形：
    - Router 视为 Controller
    - 解析/索引逻辑落在 Service
    - 用抽象基类定义 Parser 接口作为“相应接口”
  - Windows 环境优先；避免复杂的 C 依赖；命令示例不要用 Linux 连接符。

- 解析库选型对比
  - unstructured
    - 优点：统一 API，支持 PDF/DOCX/PPTX/HTML/EML/图片-OCR 等，产出带结构的元素列表
    - 风险：安装略重（尤其 Windows 下 OCR/依赖），解析速度受依赖环境影响
  - Apache Tika（Server）
    - 优点：解析面广、工业级稳定；语言无关，通过 HTTP 使用
    - 风险：需运行 Java 进程，部署与运维成本提升
  - 自研多适配器（推荐为基础方案）
    - 组合专用库：PyMuPDF（PDF）、python-docx（DOCX）、python-pptx（PPTX）、pandas/openpyxl（XLSX/CSV）、BeautifulSoup/Readability（HTML）、mail-parser（EML）
    - 优点：安装相对可控、按需裁剪、性能可预测；易于在 Windows 落地
    - 风险：需要写适配器与兼容处理；对边角格式覆盖要花精力

- 推荐架构
  - 基础层：自研“多适配器解析层”（Windows 友好、轻依赖）
  - 可选增强：集成 unstructured/Tika 作为回退与补充（例如遇到复杂 PDF/图片）

### 目标支持的文档类型
- 文本类：txt、md、json（保留）
- 办公文档：pdf、docx、pptx、xlsx、csv
- 网页/邮件：html、eml
- 图片（可选）：png、jpg（OCR）
- 压缩包（扩展）：zip（解包后按文件类型递归解析）

### 数据与接口设计
- 数据模型扩展（RAG 元数据）
  - 新增字段：document_id、file_name、file_type、hash、page_number、section_title、element_type（段落/表格/标题…）、created_at、source_path
  - 维护“文件 → 索引块 ID 列表”的映射，以便“按文件删除/重建索引”
- 接口与分层
  - Interface：DocumentParser（parse(file_bytes, filename) -> List[ParsedElement]）
  - Service：DocumentParserService（注册/路由到不同解析器，清洗/归一化）、RAGIndexService（入库/去重/删除/重建）
  - Controller（FastAPI Router）：/rag/add-file(s)、/rag/add-zip、/rag/delete-file、/rag/list-files、/rag/reindex-file
  - Chunk 策略：结构感知（优先按标题/段落/页分割，再按字符长度做二次切片）

### 详细执行步骤
- 第1步：依赖与环境
  - 必选（建议尽量轻量）：PyMuPDF、python-docx、python-pptx、pandas、openpyxl、beautifulsoup4、mail-parser、charset-normalizer
  - 可选（增强）：unstructured、pytesseract（需安装 Windows 版 Tesseract 并配置 PATH）
  - 在 Windows 用逐条 pip 安装（不要使用“&&”连接多条命令）

- 第2步：抽象接口与注册表
  - 新建接口：DocumentParser（抽象类），定义 parse(file_bytes, filename) 返回 ParsedElement 列表，元素包含 text、metadata（page/section/type）
  - 新建注册表：ParserRegistry，按扩展名选择解析器；支持优先级与回退（例如 PDF：先 PyMuPDF，失败再 pdfminer 或 unstructured）

- 第3步：实现适配器（按优先级）
  - PDFParser（PyMuPDF）：提取每页文本、标题（可基于字体大小/位置启发）、表格（可选引入 camelot/borb，复杂度较高，可后续）
  - DocxParser（python-docx）：保留段落/标题层级；表格按行拼接为 TSV/Markdown
  - PptxParser（python-pptx）：按幻灯片顺序抽取文本框与备注；图片 OCR（可选）
  - Excel/CSV Parser（pandas/openpyxl）：小表格转为 Markdown 表；大表仅抽样/列名+前几行
  - HtmlParser（BeautifulSoup + readability-lxml 或 trafilatura）：正文抽取 + 标题层级
  - EmlParser（mail-parser）：主题/发件人/收件人/正文（忽略附件或递归处理附件）
  - ImageParser（可选 OCR）：pytesseract/PaddleOCR；标注 page=1、element_type=image_ocr
  - JsonParser：结构化扁平化（key 路径 + 值），或保留为原生片段

- 第4步：文本清洗与结构化分块
  - 统一清洗：去除多余空白、控制字符；标准化换行；合并相邻小块
  - 结构化分块策略：
    - 第一层：按页、标题、段落、表格分
    - 第二层：对超过 chunk_chars 的块再按字符长度切片，保留 parent_section/page 的信息
  - 元数据写入：file_type、page_number、section_title、element_type

- 第5步：RAG 引擎与索引层改造
  - add_texts 增强：支持传入富元数据；索引保存时将 meta.json 扩展；embeddings.npy 不变
  - 新增“文件映射索引”：
    - files.json：保存 document_id -> {file_name, hash, chunk_index_list, created_at}
    - 支持按 document_id 删除重建
  - 去重策略：hash（文件）+ hash（规范化片段）避免重复索引

- 第6步：API（Controller）增强与一一对应 Service/接口
  - 保持路由简洁，新增/增强：
    - POST /rag/add-file：单文件（支持二进制办公文档），调用 DocumentParserService → RAGIndexService
    - POST /rag/add-files：多文件批量
    - POST /rag/add-zip：自动解压并批量解析
    - DELETE /rag/delete-file?document_id=xxx
    - GET /rag/list-files
    - POST /rag/reindex-file?document_id=xxx
  - 为每个路由配套一个 Service 类与接口（抽象基类），满足你的一一对应要求

- 第7步：配置项扩展（conf.yaml）
  - rag_config：
    - enable_parsers: [pdf, docx, pptx, xlsx, csv, html, eml, image]
    - parser_priority: {pdf: [pymupdf, unstructured], docx: [python-docx]}
    - max_file_size_mb、max_batch_files、allow_ocr: true/false
    - table_handling: simple|markdown|skip
  - 解析失败与回退策略可配置

- 第8步：错误处理与可观测性
  - 解析超时/大小限制/类型白名单/异常捕获（返回可读的错误信息）
  - 解析日志：统计每类文件耗时、成功率；记录跳过/失败原因
  - 指标：索引块数量、维度、搜索耗时、索引大小

- 第9步：性能与质量验证
  - 测试集覆盖：
    - PDF（扫描版/文本版/带表格）、长 DOCX、复杂 PPTX、宽表格 XLSX、超链接 HTML、较长邮件 EML、混合 ZIP
  - 指标：
    - 解析速度（每百页/每百张表）、RAG 检索 hit 率、响应延迟、内存峰值
  - 回归测试：同文档重复上传去重验证；删除/重建一致性验证

### 依赖与安装建议（Windows）
- 基础依赖（按需单条安装）：
  - pip install pymupdf
  - pip install python-docx
  - pip install python-pptx
  - pip install pandas openpyxl
  - pip install beautifulsoup4 lxml readability-lxml
  - pip install mail-parser
- 可选增强：
  - pip install unstructured
  - OCR（选其一）：安装 Windows 版 Tesseract（配置 PATH）后，pip install pytesseract；或 pip install paddleocr（注意其依赖）

优缺点与风险
- 优点
  - 全面支持主流办公文档，结构化分块使检索更准确
  - 模块化设计，易扩展新格式/新策略
  - Windows 友好，按需安装、逐步上线
- 风险
  - 解析库安装/兼容性问题（尤其 unstructured/OCR）
  - 复杂 PDF/表格的解析质量不稳定
  - 大文件/批量处理的资源消耗与超时控制
- 应对建议
  - 分阶段启用（先 PDF/DOCX/HTML，再 PPTX/XLSX/EML，再 OCR）
  - 提供回退策略（unstructured/Tika）
  - 加入大小限制、页数阈值、后台任务队列

### 里程碑与工期（建议）
- 第1周：接口与服务分层、注册表、PDF/DOCX/HTML 上线
- 第2周：PPTX/XLSX/CSV/EML，表格转 Markdown，文件映射索引与删除/重建
- 第3周：可选 OCR、ZIP 批量、性能调优、指标与日志完善
- 第4周：灰度与回归测试、文档与使用指南

### 你可以立即着手的清单
- 定稿配置项与支持格式白名单
- 创建 DocumentParser 接口与 ParserRegistry
- 实现 PDFParser、DocxParser、HtmlParser
- 扩展 /rag/add-file 支持二进制办公文档与批量
- 扩展元数据与文件映射索引，支持按文件删除/重建
- 准备一套企业文档样本用于回归测试

简评
- 可行性：高；按“自研适配器 + 回退库”的混合策略能平衡安装复杂度与解析覆盖率。
- 风险：主要集中在复杂 PDF/表格与 OCR；建议后置、分阶段启用。
- 建议：先确保 PDF（文本版）和 DOCX 的解析质量与分块策略稳定，再逐步引入其他格式和 OCR。