跳到正文

ADR-0054:统一转换与确切输出预检 ​

状态:已接受。

问题 ​

分别调用导入、编辑和导出时,调用方需要合并各阶段损失,且仅检查编辑目标会漏掉未编辑内容在目标格式中的损失。预检后再次解析或编码也可能产生不同结果。

决定 ​

在模型模块提供 DocumentConversion 同步编排。适配器提供真实 Reader/Target,布局入口通过显式 DocumentBackend 提供目标,核心不依赖具体适配器或后端。

prepare 固定输入、策略和编辑配置,依次导入、校验编辑、编码完整目标,保存有限编码字节及实际损失。preview 使用 PREVIEW 阶段,发布成功返回 ACTUAL 报告;两者的 issues 相同。发布不再调用源、编辑回调或编码器。

共享策略覆盖顺序为 operation → feature → format → default。默认 ERROR;WARN/IGNORE 只改变警告可见性,实际降级和损失均保留。PRESERVE 只有真实保留路径才能使用。旧适配器入口保持默认行为。

边界 ​

  • Web 目标检查全部正文及页区,沿既有映射报告格式降级;无映射注释须明确 DISCARD。
  • DOCX 输入把现有语义导入诊断转换成 OOXML_MARKUP 实际损失;没有原包保留通道。目标自定义字体角色须明确降级,其余没有实现的结构仍失败。
  • 布局目标保留显式字体、角色、页区、导航和输入注释;缺字替换另报实际损失。后端负责其格式支持,不靠策略放宽错误。
  • 路径发布采用同目录临时文件和原子替换,最终取消检查先于替换;借用流不关闭、不刷新,I/O 失败可留下部分流字节。
  • 输出编码和报告有独立预算;这是有界准备结果,不是全流程恒内存。自定义 Reader/Writer 为可信调用方代码。

验证 ​

见统一转换 API及阶段四十七。DOCX 结构保留和 PDF 语义恢复继续按各自契约验收,不能通过设置 PRESERVE 得到不存在的能力。