ADR-0001：分层架构与格式边界

日期：2026-10-14
状态：已采纳。精确绘制路径已落实，完整布局与 DOCX 路径仍属后续计划。
来源：项目立项文档
后续细化：ADR-0003 允许 FontBox 及其 I/O 基础库封装在字体模块内部；PDFBox 文档与绘制 API 继续限定在 PDF 实现模块。

背景

文档语义、排版算法和 PDF 绘制具有不同职责。直接把 PDFBox 类型作为文档模型，会使布局依赖具体格式，也难以保留 DOCX 的流式结构。

项目需要复用成熟基础设施，同时保留自主的核心模型和可替换后端。

决策

采用 Document Model、Layout Engine、Layout IR、Display List 和 Backend 的分层数据流。
测量与布局不写目标文件，后端只执行既定绘制结果。
DOCX 通过独立导入器、导出器与文档模型映射，不强制经过分页绘制指令。
PDFBox 和 DOCX 专用实现依赖限于对应实现模块，公共 API 不暴露第三方实现类型。
自主设计模型与布局算法，通过依赖复用字体、图片和文件格式基础设施。
模块按真实需求逐步创建，不在第一阶段一次性建立全部规划模块。

考虑的替代方案

方案	取舍
在 PDFBox 对象上直接扩展布局	起步较快，但将语义模型和布局绑定到 PDF 实现
所有格式统一消费 Display List	便于页面输出，但难以保留 DOCX 的可编辑语义
从零实现格式、字体和解码	控制范围较大，但显著扩大成本，偏离当前目标
Fork 成熟排版框架	继承既有架构与维护约束，不符合自主设计核心的路线

影响

需要维护语义、布局与绘制之间的转换，初期接口设计成本增加。各层可以独立验证和替换，并能明确表达格式差异与信息损失。

PDF 与 DOCX 不承诺像素级一致，也不承诺任意文档无损互转。Java 21 与 PDFBox 的具体版本与兼容性不由本记录批准，实际采用时另行验证和登记。

验证方式

阶段一检查模块依赖无环、公共 API 无第三方类型泄漏。
验证直接绘制路径生成有效 PDF，并使用独立工具检查输出。
后续布局验证测量与输出分离、文本与分页结果可追踪。
DOCX 阶段验证模型映射及支持矩阵，不经过 Display List 反推语义。