合同模板常见问题排查

按「现象 → 原因 → 处理」组织，遇到合同生成异常时对照排查。

一、变量没有被替换

现象：生成的合同里还留着 {{customer_name}} 或 memberName 这类原文。

可能原因	排查方法	处理
变量名拼错	对照 常用变量说明 逐字符核对	改为标准变量名
大小写/格式不对	检查是否有大写字母、驼峰、多余空格	改为全小写 snake_case
使用了旧占位符	搜索 memberName、{{service_fee}} 等旧写法	按 对照表 迁移
自定义变量与内置变量重名	检查自定义变量 JSON 的键名	改名——内置变量优先，重名的自定义值不生效

二、变量替换成了空白

现象：变量消失了，但位置是空的。

• 该业务数据本身为空（如客户没填地址、产品没配服务电话）——去对应资料页补录；
• {{company_seal_image}} 空白 → 产品未配置公章图片，属正常行为；
• {{customer_signature}} 空白 → 客户尚未签署，属正常行为，签署后重新导出即出现；
• {{warranty_coverage}} 显示为固定文字「（详见本合同保障范围条款）」→ 当前系统设计如此，不是故障。

三、证件类型显示不对

现象：客户的证件是港澳通行证，合同上却显示「身份证」。

原因：系统只对 身份证/护照/军官证/营业执照 四种类型做中文转换，其他类型默认回退显示「身份证」。 处理：涉及其他证件类型时，不要依赖 {{customer_id_type}}，可在备注中说明，或联系技术人员确认后再用。

四、日期格式不符合预期

系统所有日期变量统一输出中文格式 2026年6月10日，不提供 2026-06-10 格式。排版时按中文格式预留宽度即可。

五、修改模板后旧合同没变化

这是设计如此：合同生成时内容已固化为快照，之后改模板只影响新生成的合同。如需更新某份已生成的合同，需要在订单中重新生成合同（注意：重新生成会覆盖原快照）。

六、生成合同报错「合同模板不存在或已停用」

• 检查该产品是否已关联合同模板（产品管理 → 模板）；
• 检查关联的模板状态是否为「启用」；
• 多模板时注意是否关联错了模板版本。

七、PDF 排版错乱

合同 PDF 由 Dompdf 引擎渲染，对 CSS 支持有限：

症状	原因	处理
分栏错位	用了 flex/grid/float	改用 <table> 布局
样式丢失	样式写在外部 class 里	改为内联 style=""
中文乱码/方块	字体声明缺失	模板外层 div 声明 font-family:'source-han-sans','Source Han Sans SC','Microsoft YaHei',sans-serif;
图片过大撑破版式	公章/签名图未限宽	图片加 style="max-width:120px;" 约束

八、仍然无法解决

收集以下信息再反馈给技术人员：

1. 模板名称及关联产品；
2. 出问题的变量原文（截图或复制文本）；
3. 测试订单编号；
4. 期望效果 vs 实际效果截图。