ADR-0103：用适配器有类型模型表达 Word 原生语义

• 状态：采用。
• 关联：GAP-12.1、GAP-12.2。

背景

通用文档模型能表达正文、表格、页区、图像和若干字段。Word 的浮动定位、文本框、评论范围、修订、内容控件、legacy 表单和目录字段存在独立语义。仅保留原包不能查询或编辑这些语义；把未知 XML 当成扩展字段会把格式细节和安全边界带入模型，也无法可靠更新文字范围。

决定

export4j-adapter-docx 提供不可变 DocxSemanticDocument，包裹 SectionedDocument，并保存有类型的绘图、评论、修订、控件和目录。模型不保存 ZIP／XML 字节、DOM、第三方句柄或隐藏恢复副本。格式专有数据留在适配器，不向通用模型、布局、所有后端和序列化器扩散。

原生读取先通过包、关系、XML、字段和资源安全检查，再抽取有类型对象，将其余正文交给已建立的样式、表格、页区和字段读取器。原生输出从模型创建全新的标准 OOXML 包，重新生成关系与媒体引用。原包编辑入口继续独立提供局部保留契约。

源范围使用稳定段落 ID 和原文 UTF-16。顺序编辑更新实际正文及所有范围；图片必须指向实际图像标记；文本框含真实语义块。修订接纳／拒绝修改模型中的实际内容或格式，被删除内容不能从原包恢复。

原生输出保存表单当前值与独立默认值；下拉选择写入标准当前索引。它不附加全局字段更新或给普通计算字段无条件设置脏标记，避免 Word 自动宽泛重算把用户输入重置为默认值。调用方显式声明的 TOC 更新标志保留；用实际页码重建目录缓存后清除该标志。应用最终页码采用定向计算字段更新，表单输入不参与。普通 DOCX 入口的既有默认行为不因此变更。

跨格式投影

semanticConversion(...).project() 和已有 conversion(...) 共同使用显式投影。评论、审阅、控件、目录和浮动版式等没有通用映射的行为逐项产生实际处理报告。拒绝、警告和忽略共用策略；忽略仍保留损失记录。图片变换实际栅格化，文本框实际展开块内容，不用改尺寸或只删标签冒充转换。

取舍

同一文档可选择原包局部保留、原生语义编辑或跨格式降级。三者有不同证据边界，不能互相替代。适配器模型扩大了公共 API 和锚点校验责任，但避免把 Word 专有对象加入所有核心层，也避免依赖原始 XML 维持编辑结果。

没有安全或有类型映射的结构仍拒绝或按已实现降级报告。模型不承诺任意 Word 扩展、自动执行外部字段，也不承诺跨格式逐像素一致。可复现契约见原生语义 API及专项验收。