ADR-0093：声明式导航与自生成文档恢复验收

状态

已采纳。

背景

既有 XML 可保存正文、页区、注释、引用和资源，但目录来自运行时 Navigation。恢复后若只提供字体重新导出，目录及其样式消失；从标题重新创建默认目录也无法还原原声明。同时，自生成文件恢复、外部文档识别和任意阅读器保留扩展信息是不同目标，需要分别定义完成条件。

决策

在模型模块增加不可变 DocumentNavigation，由 SectionedDocument.navigation 持有。它只表达自动选择当前顶层标题及最大级别、显式书签和目录文字／排版／颜色声明。标题来源与手工书签互斥；手工标题和目标都是字面值，最终绑定／编辑后验证目标和层级。编辑可用 editor.navigation(value) 明确修复声明，不级联删除静态目标。

目录条目排版是完整值；标题／页码排版及三处颜色按属性存在性保存，保留显式黑色与未声明的区别。未声明排版仍由布局层根据当前条目派生。模型不引用字体、文字排版模块、绘制颜色类型、页面位置、回调或后端句柄。

复用版本 1 XML 的根级 navigation，放在 page／页区声明之后、notes／正文／section 之前。保存器输出确定的枚举顺序，复用原 ID 映射、XML 安全转义及资源契约。renderSections／renderComplete 返回完整声明；无法承载它的 render／renderWithPageRegions 明确拒绝。包含导航的新 XML 需要支持本语法的编译器。

ComponentDocumentRenderer 在展开语义块前从当前模型解析声明，因此直接入口及 DocumentEngine 行为一致；最终分页后解析实际页码和链接。模型声明和非空运行时 Navigation 同时存在时拒绝冲突。既有运行时入口仍用于评论、表单及其他可信调用方配置，不反向序列化这些对象。

DOCX／HTML／Markdown 尚无此声明的完整原生映射：严格入口拒绝；统一转换使用 NAVIGATION + DISCARD 明确报损，WARN／IGNORE 都记录实际损失。reimportOnLoss 从本次真实字节建立模型，已丢导航不能通过恢复包返回。静态后端对交互数据的既有拒绝保持。

GAP-24 的验收边界

GAP-24 的目标是已支持声明式模型的自生成文档闭环，包含既有普通 XML 模板资源包和七种标准输出的显式恢复信息，不能要求序列化任意 Java 代码或推断任意外部文件。主题／变量／条件／循环的编写意图保存原 XML；展开模型保存完整已解析值。字体字节及许可显式传递，角色映射和兼容引擎配置仍由调用方明确提供。

四项完成条件分别是：受支持模型／资源的三轮恢复及实际编辑；可选内嵌、准确字节／资源绑定和异常策略；原包／原页面已支持路径的未编辑内容保留及旧恢复信息失效；按目标能力分组的 A→B→A、损失累计、独立文件检查、全部新页渲染及真实应用保存后回读。

Word 等应用可以删除或改写恢复信息。验收要求默认拒绝过期／缺失信息，只有显式策略和读取器才导入当前文件，不能回到旧模型；不要求扩展信息跨任意应用保存仍存在。任意外部 PDF／DOCX／HTML 识别和编辑能力继续分别归 GAP-10／12／18／20，更多系统及应用兼容归 GAP-14.2；这些未实现扩展不因 GAP-24 完成而关闭。

兼容性与验证

旧 SectionedDocument 两参数及 DocumentTemplate 既有构造器保留，默认无导航。新增 record 组件不承诺反射、解构、对象字符串或所有二进制调用方兼容；当前快照调用方应重新编译。无声明 XML 不额外输出 navigation。

验证完整声明和显式样式意图、静态目标删除拒绝／修复、自动当前标题、运行时冲突、共享文本／工作预算，以及 DOCX／Web 三动作。组合语料同时覆盖分节、共享页区、变体、图层、嵌套合并格、图片、注释、题注、引用和目录。独立坐标调用方及 Word 编辑／保存／重开分别提供证据，见阶段九十。