414 lines
7.0 KiB
Markdown
414 lines
7.0 KiB
Markdown
# 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.
|