ADR-0049：语义页区、XML 分节与 DOCX 映射
- 状态：已采纳
- 日期：2026-10-21
- 扩展：ADR-0048
背景
仅保存页区段落不足以表达报告标志、表格式页脚和各节纸张／页码。把这些内容留在组件绘制层会使 XML 与 DOCX 无法保留相同语义。
决定
- PageRegion 保存有序 Paragraph／Table 块，复用现有图片、两层块格与 PAGE/PAGES 字段；源块／行内项／表格槽／文字有固定上限。它是不可变值类，保留原 List 构造器、Builder 与 text-only paragraphs 入口；后者遇到表格会失败，不过滤内容。
- Section 增加 PageRegions，旧四参构造器仍为无页区；SectionedDocument 检查全树 ID，并允许同类区域在多节间共享相等不可变来源。模型仍只依赖模型值，不引入字体、组件、绘制或后端类型。
- DocumentTemplate 增加静态 SectionNode 列表，renderSections 共享一次数据快照和所有绑定计数。旧正文及单节页区入口遇到分节明确拒绝；Java 旧四／五参模板构造器保留。记录组件形状有变化，不能宣称二进制 record 解构兼容。
- XML 的根或节首配置页面与固定区域，节内普通语法复用原编译器；不新增第二套 XML 解析器／绑定器。原始位置、片段拒绝、全部分支、离线资源、预算与取消约束保持。根区域作为节默认值，局部覆盖和显式清空不泄漏到后节。
- PageRegionTemplates 在固定的一页局部语义布局上解析最终 PAGE/PAGES，再调用现有 DocumentPainter。它遍历全部真实文字叶及表格格诊断，不能使用仅段落视图；溢出失败，不让后端再排版。诊断使用固定区串接源 UTF-16 和最终物理页。
- DOCX 直接映射标准页区 part、各自关系、媒体、原生字段和节配置。源、图片和 ZIP 限额跨所有 part 共用；同一表格源跨不同宽节生成独立物理网格。缺省引用按 OOXML 继承，清空使用显式空 part。
- 固定高度不是 OOXML 的标准语义。导出同时保存标准正文边距／页区距离和可忽略几何；导入标准 Word 区域必须显式指定缺失的几何及字段宽度。错误关系、类型、ID 和几何不能以允许损失掩盖。
边界与后果
默认页区的文本、图片、表格、页码和分节已形成模型／XML／PDF／DOCX 闭环。链接／引用、首页奇偶 XML／DOCX、背景前景 XML 和连续分节不由本决定扩展。Java 既有高级模板仍可显式组合。
模型和模板保留旧源码入口，新 record 组件和 PageRegion 类型形状需要调用方重新编译。没有新增生产依赖。自动 Word 打开／更新、保存及 PDF 导出分别验收，不能从本地语义往返推断一般 Word 无损兼容。证据见阶段四十二。