合同模板里明明看得到完整的“{{客户名}}”，程序却没有替换，先检查它在文件中的结构。对于采用 WordprocessingML 的文档，可见的一段文字可能分布在多个文本元素中；只对每个元素分别执行字符串替换，不保证能找到跨元素的完整占位符。
本文面向将业务数据填入合同、报告模板的开发者，讨论这一步的匹配边界。花括号只是本文假设的占位约定，不代表某个产品或模板引擎的语法。下面的分段与用例是设计示意，未执行具体引擎或编辑器测试，也不适用于直接解释旧二进制格式文档。
页面上的连续文字，不等于文件中的单一节点
Microsoft 的 WordprocessingML 结构说明介绍：段落包含 run，run 表示具有一组共同属性的文本区域，其中可以包含一个或多个 Text 文本元素。显示出来的一段内容，不能仅凭外观判断它保存成几个 run 或 Text。
例如在一个合成样本中，两个相邻文本元素分别保存“{{客”和“户名}}”。把它们按阅读顺序连起来，是“{{客户名}}”；但分别搜索两个元素，没有任何一个单独包含完整标记。因此，缺少匹配未必是业务数据中没有这个字段，也不应先要求用户反复删除重打模板。
这只是说明一种可能的结构，不是说所有占位符都会被拆开，也不是断言某次加粗或保存必然造成分段。排障应查看实际模板中对应范围的结构，并记录模板版本、处理库和调用方式。
逐节点替换示例有自己的适用范围
官方 SAX 替换教程示例逐个读取 Text 元素，在该元素的字符串上执行 Replace；它也提醒，文档文本可能分散在多个 Text 元素中。这个示例能够解释流式读写，但不能直接当成处理任意模板字段的完整方案。
需要跨节点匹配时，应由实现明确如何建立逻辑文本与原结构位置的对应，允许跨越哪些边界，以及如何将替换结果写回。不能只把整个文档 XML 当普通字符串全局替换，也不能将一整段压成纯文本后声称格式和文档结构均未受影响。
还要定义替换结果的格式：新客户名称使用哪个位置的字符属性，原范围内不同格式如何处理，非目标文本是否保留原属性。这是方案要明确的规则，不能把某个算法采用的格式选择当成文件格式标准强制要求。
匹配范围必须有边界
逻辑上拼接文本，不代表可以跨任意结构搜索。正文段落、表格单元格、页眉页脚、字段、书签和修订内容，可能具有不同用途。一个字段名在正文和历史引用里各出现一次，也不一定都应填入当前业务值。
前述结构说明列出了正文、页眉、页脚、脚注等不同内容部分。因此，只处理主文档部分后没有发现残留，不能推断所有可见区域都已替换。实施方案应列出支持的部件和结构，无法处理的范围明确报出，不把“未扫描”记录成“没有占位符”。
对于修订、域代码或复杂结构，应按实际库的支持范围选择拒绝、保留或专门处理。不要为了让搜索命中而先删除结构标记，更不要自动接受全部修订。模板是否允许包含这些对象，是输入契约的一部分。
内容控件不等于花括号文本
若业务要求稳定标识字段，也可以评估受支持的结构化模板方案。Microsoft 的内容控件文档将内容控件描述为承载特定内容的容器，并另行介绍 XML 映射。添加一个内容控件，与建立它到业务数据的映射，是不同动作。
这份资料聚焦 Word 2013 的相关能力，不能据此推定某个在线编辑器或导入导出链路支持并保留同样的映射。采用结构化字段前，应验证创建、填充、在线修改、保存和重新打开的完整路径；在这些环节未核实之前，它只是一项待评估方案。
用同一字段的不同表示做一组小样本
先用虚构客户名称和脱敏模板副本测试，保留原件。下面只列待执行条件，不填写任何通过结果。测试目标不只是输出文件能够打开，还包括该填的字段填对、未匹配位置有说明、非目标内容与约定格式保留。
| 样本 | 核对什么 | 不能替代的证据 |
|---|---|---|
| 完整标记处于一个Text | 基本匹配、值与次数 | 跨节点匹配能力 |
| 同一标记分到相邻Text | 能否识别完整跨度 | 所有复杂结构均受支持 |
| 标记跨不同格式run | 替换后的格式规则 | 仅凭文字值正确判断无损 |
| 字段出现在约定的页眉或页脚 | 扫描范围与遗漏报告 | 正文替换成功 |
| 包含不支持结构 | 明确拒绝或保留说明 | 静默删除后仍能打开 |
记录输入模板摘要、业务字段、预期位置与次数、处理规则及实际结果。生成后重新打开，核对字段值、格式和非目标内容；需要导出时，再单独检查导出结果。API 返回成功、替换函数返回成功和文档达到交付要求，应分开记录。
将这一环节接入石墨办公文档中台私有部署相关业务流程前，可带上一份合成模板、数据字段约定和上述分段样本，预约接入演示，确认实际采用的生成方式、支持结构及回存责任。本文不预设产品采用 Open XML SDK 或某个模板引擎，也不宣称具备任意占位符的无损替换能力。也可以先看私有化部署方案，了解部署形态与交付范围。