task-h.5.3

docs/business/pdf-mapping-registry.md

@@ -1,6 +1,6 @@
 # PDF Mapping Registry
 
-This document is the source of truth for current quotation PDF field ownership.
+This document is the source of truth for active quotation PDF field ownership.
 
 | PDF Field | Source Path | Transform | Example Value |
 | --- | --- | --- | --- |
@@ -11,12 +11,18 @@ This document is the source of truth for current quotation PDF field ownership.
 | `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` |
-| `quotation_date` | `pdfme.quotation_date` | `formatPdfDate()` | `16 Jun 2026` |
-| `quotation_code` | `quotation.code` | direct | `QT-H5-AUDIT` |
-| `quotation_price` | `pdfme.quotation_price` | `formatPdfCurrency()` | `THB 128,400.00` |
-| `currency` | `quotation.currency` | direct | `THB` |
-| `exclusion_data` | `pdfme.exclusion_data` | `formatTopicItems()` | `[["Civil work by customer"]]` |
-| `items_table` | `items` | `normalizePdfmeTable()` with table columns | item rows |
+| `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` |
@@ -28,7 +34,17 @@ This document is the source of truth for current quotation PDF field ownership.
 | `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 still uses field containers named `quotation_date_data` and `quotation_code_data`
-- runtime normalization now publishes both the canonical placeholder keys (`quotation_date`, `quotation_code`) and the container keys so preview/audit/render stay aligned during the freeze window
+- 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

docs/business/pdf-placeholder-registry.md

@@ -11,11 +11,18 @@ This registry freezes the placeholder naming contract for quotation PDF template
 | `customer_att` | mapped | DB mapping | quotation attention |
 | `project_name` | mapped | DB mapping | project name |
 | `site_location` | mapped | DB mapping | project location |
-| `quotation_date` | mapped | DB mapping | formatted date |
-| `quotation_code` | mapped | DB mapping | quotation document code |
-| `quotation_price` | mapped | DB mapping | formatted total amount |
-| `currency` | mapped | DB mapping | currency code/label |
-| `exclusion_data` | mapped | DB mapping | exclusion rows as `string[][]` |
+| `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 |
@@ -24,13 +31,17 @@ This registry freezes the placeholder naming contract for quotation PDF template
 | `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, not in DB mapping rows |
+| `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 labels, not placeholders
-- keep canonical business placeholders as `quotation_date` and `quotation_code`; container aliases like `quotation_date_data` and `quotation_code_data` are tolerated only as schema field names during the current freeze window
+- 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