diff --git a/docs/data-process-design.md b/docs/data-process-design.md index 8c99242..7b9cb48 100644 --- a/docs/data-process-design.md +++ b/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。二进制文档必须由对应解析器显式处理; -不支持的格式返回 415,绝不能静默替换成示例正文。 +上传批次先全部完成有界读取和解析,再在单个事务中登记;任一文件为空、超限、 +重复或格式非法时整批不落库,暂存原件也会一并清理。响应不回传整个文件,只返回 +逻辑对象引用、文件 ID、格式、原始字节数、记录数和原始 SHA-256。二进制文档必须 +由对应解析器显式处理;不支持的格式返回 415,绝不能静默替换成示例正文。 + +原始上传字节与解析正文采用双层存储:原件默认保存在 +`backend/storage/data-process///v/<安全文件名>`,数据库的 +`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 返回可定位错误。 -2. Unicode NFKC 标准化,统一 CRLF,清理 NUL、零宽字符和不可读控制字符。 -3. 结构化数据转为 canonical JSON;非结构化数据保留 Markdown 语义块。 -4. 若启用脱敏,替换邮箱、手机号和身份证号,同时保存各类型命中计数。 -5. 使用标准化正文的 SHA-256 去重;重复条目不进入生成阶段并计入 - `duplicate_count`。 +现代 Office 文件在交给解析库前检查 ZIP 成员路径、重复成员、加密标记、活动 +XML、单成员大小、总解压大小和压缩比,避免路径穿越、实体扩展与 ZIP bomb。 + +结构化选项按固定顺序执行,关闭某项时不会隐式执行对应业务变换: + +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 文本偏移为准。