模板变量命名规范与迁移指南

为什么变量名要统一？旧模板怎么改？这篇讲清楚。

一、命名规范

规则	说明	正确	错误
双大括号包裹	系统靠 {{ }} 识别变量	{{customer_name}}	customer_name ❌
snake_case	全小写 + 下划线	{{order_amount}}	{{orderAmount}} ❌
英文命名	便于统一维护	{{vehicle_brand}}	{{车辆品牌}} ❌

按业务模块加前缀，一眼看出变量归属：

前缀	业务模块	示例
customer_	客户	{{customer_name}}、{{customer_id_number}}
vehicle_	车辆	{{vehicle_brand}}、{{vehicle_mileage}}
product_	产品	{{product_name}}、{{product_display_name}}
contract_	合同	{{contract_number}}
order_	订单	{{order_amount}}、{{order_date}}
无前缀	通用字段	{{vin}}、{{license_plate}}、{{date_now}}

二、为什么要严格统一

系统的变量替换是精确匹配：{{customer_name}} 能替换，{{customerName}}、{{Customer_name}}、{{ customer_name }}（带空格）都不能。写错的变量不会有任何报错提示，而是原样留在正式合同里——这是最隐蔽也最常见的事故来源。

三、旧模板的三代写法

合同模板经历过三代写法，整理历史模板时都可能遇到：

代际	写法	示例	现状
第一代	驼峰裸词（docx 原文）	memberName、licensePlate	系统不识别，必须替换
第二代	双大括号旧变量名	{{service_fee}}、{{brand_models}}	系统不识别，必须替换
第三代	双大括号标准变量	{{order_amount}}、{{vehicle_model_name}}	✅ 当前标准

WARNING

系统没有旧变量自动兼容机制，两代旧写法都必须手工迁移。

四、迁移步骤

1. 盘点：在模板 HTML 中搜索 {、memberName 等，列出所有旧占位符。
2. 对照替换：按 一级合同模板变量说明 中的对照表逐一替换。
3. 注意一对多拆分：部分旧变量对应的新变量名变了，例如：
   • {{brand_models}} → {{vehicle_model_name}}（要「品牌+型号」用 {{vehicle_brand_model}}）
   • {{vehicle_properties}} → {{vehicle_type}}
   • {{table_mileage}} → {{vehicle_mileage}}
4. 测试验证：关联测试产品生成测试合同，逐项核对后再启用。

五、自定义变量规范

• 同样必须 snake_case；
• 不要与内置变量重名——内置变量优先，同名自定义值会被忽略；
• 适合放固定文案类内容：免赔额、赠品说明、特约条款编号等。