alla-allaos-fullstack/docs/business/pdf-placeholder-registry.md

PDF Placeholder Registry

This registry freezes the placeholder naming contract for quotation PDF templates.

Placeholder	Type	Ownership	Notes
customer_name	mapped	DB mapping	customer display name
customer_addr	mapped	DB mapping	multiline address
customer_tel	mapped	DB mapping	customer phone
customer_email	mapped	DB mapping	customer email
customer_att	mapped	DB mapping	quotation attention
project_name	mapped	DB mapping	project name
site_location	mapped	DB mapping	project location
tel_label	mapped	DB mapping	static label from pdfme.labels.tel
email_label	mapped	DB mapping	static label from pdfme.labels.email
att_label	mapped	DB mapping	static label from pdfme.labels.att
project_label	mapped	DB mapping	static label from pdfme.labels.project
site_label	mapped	DB mapping	static label from pdfme.labels.location
quotation_date	mapped	token alias	canonical formatted date token
quotation_date_data	mapped	DB mapping	active field-name mapping for date
quotation_code	mapped	token alias	canonical quotation code token
quotation_code_data	mapped	DB mapping	active field-name mapping for code
quotation_price_data	mapped	DB mapping	canonical price table string[][]
quotation_price	mapped	DB mapping	compatibility scalar token inside price table
currency	mapped	DB mapping	compatibility scalar token inside price table
app1	mapped	DB mapping	prepared by name
app1_position	mapped	DB mapping	prepared by position
app2	mapped	DB mapping	approved by name
app2_position	mapped	DB mapping	approved by position
app3	mapped	DB mapping	authorized by name
app3_position	mapped	DB mapping	authorized by position
topic	reserved	dynamic topic engine	base runtime topic label template
data_topic	reserved	dynamic topic engine	base runtime topic rows template
item_topic	legacy reserved token	dynamic topic engine	allowed in schema token inventory, never stored as DB mapping row
topic_*	generated	dynamic topic engine	runtime-only generated keys
item_topic_*	generated	dynamic topic engine	runtime-only generated keys
quotation_date_labe	static visual	designer-owned	tolerated typo-like visual label
quotation_code_lable	static visual	designer-owned	tolerated typo-like visual label
line	static visual	designer-owned	readonly line artifact, no mapping

Naming Rules

• do not store topic_* or item_topic_* keys in crm_document_template_mappings
• keep topic and data_topic reserved for runtime schema cloning
• treat typo-like names such as quotation_date_labe and quotation_code_lable as static visual fields, not business placeholders
• when the designer removes a field from the next template version, the remap script must not carry that mapping forward
• approved snapshots remain immutable to the template version they were generated from, even after that version becomes inactive