ADR-0002：首个 PDF 输出闭环
背景
第一阶段需要验证核心与后端的隔离，输出文字、图形和图片，并建立真实构建与验收证据。完整字体塑形与语义布局尚未建立。
决策
- 使用 Java 21、Gradle 9.2.1 和 Kotlin DSL，固定 Wrapper 分发校验值。
- 只创建模型、绘制 API、绘制核心、PDF 后端和示例 5 个模块。
- 采用不可变几何、指令、页面与 Display Document，使用任务内可变构建器生成快照。
- 输出 SPI 由调用方显式选择实现，核心不依赖 PDFBox。
- PDF 后端使用 PDFBox 3.0.8，JUnit 6.1.3 用于测试，版本目录与锁文件固定依赖。
- 页面原点为左上角，单位为 point。文字指定基线，图片按从上到下的 RGB 字节读取；后端统一转换方向。
- 初期使用逻辑字体族映射到 PDF 标准字体，不支持的文本明确失败。暂不实现字体嵌入、回退或塑形。
- 图片接口先接受不可变原始 RGB 像素，不加入文件解码、网络读取或额外解码依赖。
- 页面数、命令数、状态深度、累计图像像素、文本码点及路径段数设置显式预算。
- 后端拥有 PDF 内部资源；输出流由调用方拥有，失败保留原因与结构化位置。
考虑的替代方案
| 方案 | 取舍 |
|---|---|
| 同时实现段落布局和字体嵌入 | 扩大第一阶段范围，难以单独验证绘制与后端边界 |
| 直接使用 BufferedImage 作为公共图片类型 | 简化实现，但将公共契约绑定到 AWT；当前只在后端内部转换 |
| 开放任意对象作为绘制命令 | 难以验证可表示性；采用封闭的基础指令集合，后端 SPI 保持开放 |
| 依赖图中默认带上 PDF 后端 | 使用方便，但破坏核心可替换性；由调用方和示例选择后端 |
影响与限制
标准字体不嵌入，阅读器可能替换显示字体。首个闭环不宣称 PDF/A、一致的跨阅读器字形外观、复杂脚本支持或字节级确定性。
语义模型目前仅提供页面尺寸和元数据，尚未实现段落、表格与完整 Document Model。布局结果和文本测量接口按实际需求创建。
后端预算约束结构与内部分配，不是时间沙箱或总输出字节上限。调用方仍需控制输入对象规模、输出生命周期及任务运行环境。
com.mirakyux.export4j 作为当前源码包与本地构建分组，不表示已拥有 Maven Central 命名空间。正式发布前确认分组及兼容性。
验证
验证覆盖不可变快照、坐标、路径、图片方向、文字基线、矩阵组合、嵌套状态、裁剪、超限、不可表示文字、输出失败和并发隔离。
示例输出由独立 PDF 工具解析与渲染，不能仅依赖 PDFBox 自行读回。原始第三方许可、NOTICE 与依赖记录随代码维护。