task-4.3.1

2026-06-29 11:57:37 +07:00
parent 0c0450b152
commit 94fe19c658
17 changed files with 836 additions and 174 deletions
--- a/plans/task-p.4.3.1.md
+++ b/plans/task-p.4.3.1.md
@@ -0,0 +1,413 @@
+# Task P.4.3.1 - PDF Runtime Regression Stabilization
+
+## Objective
+
+Stabilize the Task P.4.3 section-based PDF runtime refactor before moving to Product Item implementation.
+
+This task fixes regression only.
+
+Do NOT add new Product Item pages.
+Do NOT create new template JSON files.
+Do NOT change database schema.
+Do NOT change CRM Template UI.
+Do NOT introduce new user-facing behavior.
+
+---
+
+# Background
+
+After Task P.4.3, runtime audit still fails.
+
+Observed audit result:
+
+```text
+overallStatus = FAIL
+staticLabelsStatus = FAIL
+quotationCode = QT2606-1126
+templateName = ALLA Quotation Standard
+templateVersion = 1.0
+```
+
+Most runtime payloads pass, including:
+
+* documentData
+* quotation data
+* customer data
+* item rows
+* topic inputs
+* signatures
+* quotation price data
+* items_table
+
+However static label inputs are missing from `templateInput`.
+
+Failing fields:
+
+```text
+templateInput.tel_label
+templateInput.email_label
+templateInput.att_label
+templateInput.project_label
+templateInput.site_label
+```
+
+Expected values:
+
+```text
+tel_label = Tel
+email_label = Email
+att_label = Att
+project_label = Project
+site_label = Location
+```
+
+---
+
+# Root Cause Hypothesis
+
+The refactored section-based runtime likely preserved business data and dynamic section inputs, but dropped legacy/default static inputs during template input assembly.
+
+The missing values still exist in source document data:
+
+```text
+documentData.pdfme.labels.tel
+documentData.pdfme.labels.email
+documentData.pdfme.labels.att
+documentData.pdfme.labels.project
+documentData.pdfme.labels.location
+```
+
+but they are not merged into final `templateInput`.
+
+This indicates a regression in one of:
+
+* mapping resolver
+* static input resolver
+* render context construction
+* section composer input merge
+* template assembler input merge
+
+---
+
+# Scope
+
+Included:
+
+* Restore static label input compatibility
+* Verify final `templateInput` contains all legacy static inputs
+* Ensure new runtime preserves all old runtime input keys
+* Strengthen audit/regression coverage
+* Confirm ALLA and ONVALLA pass runtime audit
+
+Excluded:
+
+* Product Item page rendering
+* Product Item template creation
+* Template version publishing
+* Render Policy UI
+* New section visibility configuration
+* Database changes
+* API changes
+
+---
+
+# Required Investigation
+
+Before fixing, inspect the old and new runtime input construction path.
+
+Compare:
+
+## Old Runtime
+
+* how `tel_label`
+* `email_label`
+* `att_label`
+* `project_label`
+* `site_label`
+
+were added to `templateInput`
+
+## New Runtime
+
+* where `templateInput` is initialized
+* where mapping output is merged
+* where section inputs are merged
+* where static/default inputs are merged or lost
+
+Produce a short root-cause note before applying fixes.
+
+---
+
+# Implementation Requirements
+
+## 1. Introduce or Restore Static Input Resolution
+
+Ensure final `templateInput` always includes legacy static inputs.
+
+At minimum:
+
+```ts
+{
+  tel_label: 'Tel',
+  email_label: 'Email',
+  att_label: 'Att',
+  project_label: 'Project',
+  site_label: 'Location'
+}
+```
+
+Preferred source:
+
+```text
+documentData.pdfme.labels
+```
+
+Fallback source:
+
+```text
+hardcoded legacy defaults
+```
+
+The resolver must not duplicate dynamic mapping logic.
+
+---
+
+## 2. Recommended Component
+
+Add or restore a dedicated component:
+
+```text
+StaticInputResolver
+```
+
+Responsibilities:
+
+* resolve static labels
+* resolve legacy fixed inputs
+* normalize alias fields
+* provide fallback defaults
+* return template input patch
+
+It should run before final template assembly.
+
+Suggested pipeline:
+
+```text
+Document Data
+  -> Template Resolver
+  -> Mapping Resolver
+  -> Compatibility Adapter
+  -> Page Resolver
+  -> Render Policy Resolver
+  -> Static Input Resolver
+  -> Section Composer
+  -> Template Assembler
+  -> PDF Generator
+```
+
+---
+
+## 3. Preserve Legacy Input Contract
+
+The final `templateInput` must preserve all keys expected by legacy templates.
+
+Minimum required keys:
+
+```text
+customer_name
+customer_addr
+customer_tel
+customer_email
+customer_att
+project_name
+site_location
+quotation_date
+quotation_date_data
+quotation_code
+quotation_code_data
+quotation_price
+quotation_price_data
+currency
+exclusion_data
+app1
+app1_position
+app2
+app2_position
+app3
+app3_position
+tel_label
+email_label
+att_label
+project_label
+site_label
+topic_*
+item_topic_*
+items_table
+```
+
+---
+
+## 4. Template Assembler Merge Rule
+
+The assembler must merge template inputs in deterministic order.
+
+Recommended order:
+
+```text
+base mapped input
+static input patch
+section input patches
+diagnostic/debug input patch if any
+```
+
+Later patches may override earlier patches only when explicitly intended.
+
+No accidental null overwrite is allowed.
+
+---
+
+## 5. Null-safe Merge
+
+If a patch contains `null` or `undefined`, it must not overwrite a populated existing value unless explicitly allowed.
+
+Example rule:
+
+```text
+Do not overwrite "Tel" with null.
+Do not overwrite populated static labels with empty values.
+```
+
+---
+
+# Regression Requirements
+
+Run audit for at least:
+
+## ALLA
+
+* approved quotation fixture
+* quotation with topics
+* quotation with items
+
+## ONVALLA
+
+* active quotation fixture
+* quotation with topics
+* quotation with items
+
+Verify:
+
+```text
+overallStatus = PASS
+staticLabelsStatus = PASS
+findingCount = 0 FAIL
+```
+
+---
+
+# Verification Matrix
+
+## Runtime Payload
+
+Confirm final `templateInput` contains:
+
+```text
+tel_label = Tel
+email_label = Email
+att_label = Att
+project_label = Project
+site_label = Location
+```
+
+## Existing Dynamic Inputs
+
+Confirm no regression for:
+
+```text
+quotation_price_data
+exclusion_data
+topic_*
+item_topic_*
+items_table
+app1
+app1_position
+app2
+app2_position
+app3
+app3_position
+```
+
+## Routes
+
+Verify unchanged behavior for:
+
+```text
+GET /api/crm/quotations/[id]/document-preview
+GET /api/crm/quotations/[id]/pdf-preview
+GET /api/crm/quotations/[id]/pdf-download
+GET /api/crm/quotations/[id]/approved-pdf
+```
+
+---
+
+# Testing Requirements
+
+Run:
+
+```bash
+npm exec tsc --noEmit
+npm run build
+npm run audit:pdf
+```
+
+If project has targeted PDF audit commands, run those as well.
+
+---
+
+# Acceptance Criteria
+
+* Static label regression is fixed.
+* `overallStatus = PASS`.
+* `staticLabelsStatus = PASS`.
+* No failing runtime audit findings remain.
+* Legacy templates render as before.
+* ALLA and ONVALLA remain compatible.
+* Section-based runtime architecture from P.4.3 remains intact.
+* No Product Item feature implementation is introduced.
+* Runtime is safe to proceed to Task P.4.4.
+
+---
+
+# Out of Scope
+
+The following belongs to later tasks:
+
+## Task P.4.4
+
+* Product Item Engine
+* Product Item pagination
+* Product Item page rendering
+
+## Task P.4.5
+
+* New Product Item template versions
+* New template JSON files
+* Template seed/reseed support
+
+## Task P.4.6
+
+* CRM Template integration and activation flow
+
+## Task P.4.7
+
+* User-selectable render options
+* Optional section UI
+* Organization/customer render preferences
+
+---
+
+# Final Success Condition
+
+Task P.4.3.1 is complete only when the refactored section-based runtime produces a passing runtime audit with zero legacy input regressions.
+
+After this task passes, continue to Task P.4.4.