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

PDF Mapping Registry

This document is the source of truth for active quotation PDF field ownership.

PDF Field	Source Path	Transform	Example Value
customer_name	customer.name	direct	ALLA Demo Customer
customer_addr	customer.address	direct multiline	99/9 Rama IX Road, Bangkok 10310
customer_tel	customer.phone	direct	02-000-1000
customer_email	customer.email	direct	demo-customer@local.test
customer_att	quotation.attention	direct	Task H.1 Contact
project_name	quotation.projectName	direct	Task H.5 Audit Fixture
site_location	quotation.projectLocation	direct multiline	Bangkok HQ
tel_label	pdfme.labels.tel	static label	Tel
email_label	pdfme.labels.email	static label	Email
att_label	pdfme.labels.att	static label	Att
project_label	pdfme.labels.project	static label	Project
site_label	pdfme.labels.location	static label	Location
quotation_date	pdfme.quotation_date	formatPdfDate() canonical alias	16 Jun 2026
quotation_date_data	pdfme.quotation_date	active-template field-name mapping	16 Jun 2026
quotation_code	quotation.code	direct canonical alias	QT-H5-AUDIT
quotation_code_data	quotation.code	active-template field-name mapping	QT-H5-AUDIT
quotation_price_data	pdfme.quotation_price_data	buildPdfPriceTableData()	[["Price (Exclude VAT)", "฿125,000.00", " ", "THB"]]
quotation_price	pdfme.quotation_price	compatibility scalar	THB 125,000.00
currency	quotation.currency	compatibility scalar	THB
app1	signatures.preparedBy.name	direct	Task H.1 Admin
app1_position	signatures.preparedBy.position	position resolver	Sales Manager
app2	signatures.approvedBy.name	direct	Task H.1 Admin
app2_position	signatures.approvedBy.position	position resolver	Sales Manager
app3	signatures.authorizedBy.name	direct	Task H.1 Admin
app3_position	signatures.authorizedBy.position	position resolver	Sales Manager
topic	dynamic topic engine	runtime schema clone	topic label table
data_topic	dynamic topic engine	runtime schema clone	topic item table
topic_*	documentData.topics.all[*].topicType	runtime generated	Scope
item_topic_*	documentData.topics.all[*].items	formatTopicItems()	topic rows

Version Remap Rules

• template JSON changes must create a new crm_document_template_versions row instead of patching the old version in place
• active mappings are rebuilt only for fields or placeholder tokens that still exist in the new version
• previous approved snapshots may keep referencing retained inactive versions
• deleted fields from the previous version, such as exclusion_data and exclusion_label, must not remain active mappings on the new version

Alias Notes

• current PDFME schema uses field containers named quotation_date_data and quotation_code_data
• runtime normalization publishes both canonical aliases (quotation_date, quotation_code) and the active field-name mappings so preview, audit, and render stay aligned
• quotation_price_data is the canonical price table contract
• quotation_price and currency remain compatibility scalars because the active table content still embeds those placeholder tokens
• static labels are runtime-driven through documentData.pdfme.labels.*, not designer-only hardcoded text