docs(data-process): 更新文件处理与切分设计

docs/data-process-design.md

@@ -65,10 +65,23 @@ pending ──start/generate──> running ──success──> completed
 | PUT | `/data-process/{id}/preview/{preview_id}` | 保存人工编辑 |
 | DELETE | `/data-process/{id}/preview/{preview_id}` | 删除预览条目 |
 
-上传批次先全部完成有界读取、UTF-8 解码和解析，再在单个事务中登记；任一文件
+上传批次先全部完成有界读取和解析，再在单个事务中登记；任一文件为空、超限、
-为空、超限、重复或格式非法时整批不落库。响应不回传整个文件，只返回文件 ID、
+重复或格式非法时整批不落库，暂存原件也会一并清理。响应不回传整个文件，只返回
-格式、字节数、记录数和 SHA-256。二进制文档必须由对应解析器显式处理；
+逻辑对象引用、文件 ID、格式、原始字节数、记录数和原始 SHA-256。二进制文档必须
-不支持的格式返回 415，绝不能静默替换成示例正文。
+由对应解析器显式处理；不支持的格式返回 415，绝不能静默替换成示例正文。
+
+原始上传字节与解析正文采用双层存储：原件默认保存在
+`backend/storage/data-process/<task_id>/<file_id>/v<version>/<安全文件名>`，数据库的
+`storage_object_id` 只保存 `local://data-process/...` 逻辑引用，不保存或返回宿主机
+绝对路径；完整解析正文继续保存在 `data_process_source_files.content`，列表摘要使用
+`content_preview`，因此 PDF、Office 等文件的预览无需反复解析原始二进制。可通过
+`DATA_PROCESS_STORAGE_DIR` 指定其他本地根目录；从 `start.sh` 启动时，该变量应在
+当前终端导出。历史 `db://data-process/...` 记录继续从数据库正文预览。
+
+单独删除源文件时先提交数据库软删除，再立即删除受控目录中的原件；若物理删除
+失败，接口仍按数据库结果返回成功并标记 `storage_cleanup_pending=true`，软删除记录
+中的逻辑引用可供运维补偿清理。任务软删除以及修改 `process_type` 导致的源文件
+软删除按留存数据处理，当前版本不自动物理清除。
 
 ### 结果与发布
 
@@ -95,31 +108,72 @@ pending ──start/generate──> running ──success──> completed
 
 ## 4. 格式解析与标准化
 
-首版文本解析支持 UTF-8/UTF-8 BOM 的 TXT、Markdown、CSV、JSON、JSONL。
+上传格式按处理类型约束：
-后续 PDF、DOCX、XLSX 必须接入明确的解析器后再开放前端选择。
 
-处理顺序固定为：
+- 结构化数据支持 JSON、JSONL/NDJSON、CSV/TSV 和 XLSX。XLSX 能识别纵向、
+  横向合并单元格组成的多级表头，并稳定展平为 `销售.Q1` 一类字段；公式只读取
+  文件中已缓存的计算结果，不在服务端执行。
+- 非结构化数据支持 UTF-8/UTF-8 BOM 的 TXT、Markdown、JSON/JSONL，以及
+  文本型 PDF、DOCX 和 PPTX。PDF 按页抽取文本，DOCX 抽取段落与表格，PPTX
+  抽取幻灯片文本与表格，随后统一进入切片算法。
+- 旧版二进制 DOC、XLS、PPT 不直接解析，返回 415 并提示分别转换为
+  DOCX、XLSX、PPTX。
+- 扫描 PDF 没有文本层时明确提示需要 OCR；当前流程不执行 OCR。加密、损坏或
+  超出页数/工作表/行列/解压规模限制的文件整批拒绝。
 
-1. 严格解码并识别格式；非法字节或畸形 JSON/JSONL 返回可定位错误。
+现代 Office 文件在交给解析库前检查 ZIP 成员路径、重复成员、加密标记、活动
-2. Unicode NFKC 标准化，统一 CRLF，清理 NUL、零宽字符和不可读控制字符。
+XML、单成员大小、总解压大小和压缩比，避免路径穿越、实体扩展与 ZIP bomb。
-3. 结构化数据转为 canonical JSON；非结构化数据保留 Markdown 语义块。
+
-4. 若启用脱敏，替换邮箱、手机号和身份证号，同时保存各类型命中计数。
+结构化选项按固定顺序执行，关闭某项时不会隐式执行对应业务变换：
-5. 使用标准化正文的 SHA-256 去重；重复条目不进入生成阶段并计入
+
-   `duplicate_count`。
+1. `detect_structure`：展平嵌套对象；XLSX 上传解析阶段识别合并单元格和多级表头。
+2. `normalize_format`：字段名转 snake_case，执行 Unicode NFKC、换行和容器值规范化，
+   输出键顺序稳定的 canonical JSON；账号、邮编等字符串不会转成数值。
+3. `clean_invalid`：删除全空列和全空记录；存在 `id/uuid/key/code/*_id` 身份字段时，
+   删除身份字段残缺的行，但不会因备注等可选字段为空误删有效记录。
+4. `filter_anomaly`：仅对不少于 8 个样本的非身份数值字段使用 Tukey IQR 过滤离群行，
+   同时过滤明确乱码、不可打印或极端超长文本；小样本和 ID 字段不参与统计过滤。
+5. `deduplicate`：先按整行 canonical JSON 精确去重，再按非空
+   `id/uuid/key/code/*_id` 字段稳定保留首条；空关键值互不视为重复。
+6. `desensitize`：对结构化姓名字段和正文中的高置信上下文姓名、邮箱、手机号、
+   身份证号进行不可逆掩码，并分别记录命中数。
+
+非结构化“智能预处理”由六个可独立执行的底层选项组成：
+
+- `clean_invalid_content` 删除确定为空、不可读或纯重复符号的无效块。
+- `detect_document_structure` 识别 Markdown、中文章节和数字标题，切片不跨章节，
+  并在预览质量详情中保存 `heading_path`。
+- `merge_short_content` 在同一章节中合并短块，合并后不突破 `chunk_size`。
+- `filter_low_quality` 在生成前过滤乱码、不可打印、重复或极端超长内容。
+- `deduplicate_content` 先精确去重，再对足够长的内容进行保守近重复判断；数字或
+  否定含义变化时始终保留。
+- `preserve_context` 才启用相邻切片 overlap；关闭时切片不共享正文上下文，且上下文
+  永不跨文件或章节。
+
+表格、围栏代码块和连续列表保护是三个独立参数。启用时切点避开相应 Markdown
+块，关闭时允许按正常长度切分。
 
 脱敏是不可逆掩码：
 
 - 邮箱：`[EMAIL]`
 - 中国大陆手机号：`[PHONE]`
 - 18 位身份证号：`[ID_CARD]`
+- 高置信姓名：`[NAME]`
 
 源文件原文与脱敏后的预览分开保存，结果不得反向覆盖源文件。
 
 ## 5. 切片算法
 
-`fixed` 按目标 token 窗口切分；`semantic` 优先在空行、换行和中英文句末
+首阶段只提供三种切片策略：
-标点结束；`heading` 进一步优先在 Markdown/中文章节标题之前结束；
+
-`custom` 使用用户给定分隔符。
+- `structure` 先识别 Markdown、中文章节及编号标题，再由 LlamaIndex
+  `SentenceSplitter` 在章节内按段落和中英文句界限长；章节之间不共享 overlap。
+- `fixed` 使用 LlamaIndex `TokenTextSplitter` 按目标 token 窗口切分。
+- `custom` 使用用户给定分隔符，在找不到合适分隔点时回退到固定窗口。
+
+不提供 `semantic` 和旧 `heading` 配置；创建或更新任务时传入这些值会直接拒绝。
+LlamaIndex 只负责通用切分，原文 offset、行号、标题路径和 Markdown 保护块仍由
+项目适配层统一维护。
 
 首版使用可替换的确定性 token 估算器，中文字符、标点和英文词分别计数；
 所有偏移以 Python/JavaScript 都能稳定表达的 Unicode 文本偏移为准。