alla-allaos-fullstack/plans/task-p.4.3.1.md

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:

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:

templateInput.tel_label
templateInput.email_label
templateInput.att_label
templateInput.project_label
templateInput.site_label

Expected values:

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:

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:

{
  tel_label: 'Tel',
  email_label: 'Email',
  att_label: 'Att',
  project_label: 'Project',
  site_label: 'Location'
}

Preferred source:

documentData.pdfme.labels

Fallback source:

hardcoded legacy defaults

The resolver must not duplicate dynamic mapping logic.

---

2. Recommended Component

Add or restore a dedicated component:

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:

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:

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:

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:

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:

overallStatus = PASS
staticLabelsStatus = PASS
findingCount = 0 FAIL

---

Verification Matrix

Runtime Payload

Confirm final templateInput contains:

tel_label = Tel
email_label = Email
att_label = Att
project_label = Project
site_label = Location

Existing Dynamic Inputs

Confirm no regression for:

quotation_price_data
exclusion_data
topic_*
item_topic_*
items_table
app1
app1_position
app2
app2_position
app3
app3_position

Routes

Verify unchanged behavior for:

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:

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.

Additional Fix - Quotation Date Consistency

Runtime audit still fails because quotation_date and quotation_date_data are inconsistent with the approved snapshot.

Investigate the source and formatter for:

• templateInput.quotation_date
• templateInput.quotation_date_data
• approved snapshot quotation date values
• documentData.pdfme.quotation_date

Ensure both keys are generated from the same canonical source and formatter.

Required rule:

• quotation_date
• quotation_date_data

must always be identical unless a template explicitly maps them differently.

Preferred fix:

Create or reuse a single canonical PDFMe date formatter and assign both keys from the same value.

Do not patch one key independently. Do not change approved artifact retrieval behavior. Do not modify template JSON.

Acceptance:

• consistency.status = PASS
• inconsistentKeys = []
• overallStatus = PASS