# 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
