task p-4.5

2026-06-29 16:07:03 +07:00
parent aa73b9aed2
commit a1cac84e2b
19 changed files with 4812 additions and 413 deletions
--- a/plans/task-p.4.5.md
+++ b/plans/task-p.4.5.md
@@ -0,0 +1,413 @@
+# Task P.4.5 - Product Item Template Version
+
+## Objective
+
+Create new PDFMe quotation template versions that include a dedicated Product Item page between the existing Customer Detail page and Condition/Signature page.
+
+This task introduces the new document structure:
+
+```text
+Page 1
+Customer Detail
+
+Page 2
+Product Item Detail Table
+
+Page 3
+Condition and Signature
+```
+
+The implementation must preserve all existing template versions and must not modify the current production template JSON files.
+
+---
+
+# Prerequisites
+
+Completed:
+
+* Task P.4 Discovery
+* Task P.4.1 Runtime Verification
+* Task P.4.2 Runtime Architecture Design
+* Task P.4.3 Runtime Refactor
+* Task P.4.3.1 Runtime Regression Stabilization
+* Task P.4.4 Product Item Engine
+
+Runtime audit must currently pass before this task begins.
+
+---
+
+# Scope
+
+Included:
+
+* Create new PDFMe template JSON files
+* Add Product Item page layout
+* Add explicit section/page markers
+* Add `items_table` PDFMe table schema
+* Reposition existing condition/signature page to page 3
+* Ensure topic/signature runtime resolves by section markers, not page indexes
+* Add version/reseed support for new template versions
+* Add audit support for the new Product Item template version
+
+Excluded:
+
+* User selectable show/hide Product Table
+* Render Policy UI
+* CRM Template UI redesign
+* Database schema changes
+* Existing production template modification
+* Existing approved artifact rewrite
+
+---
+
+# Template Version Rule
+
+Do NOT modify existing files:
+
+```text
+src/pdfme_template/ALLA_template_pdfme_fainal3.json
+src/pdfme_template/ONVALLA_template_pdfme_fainal3.json
+```
+
+Create new files:
+
+```text
+src/pdfme_template/ALLA_template_pdfme_product_v1.json
+src/pdfme_template/ONVALLA_template_pdfme_product_v1.json
+```
+
+The old template versions must continue to work unchanged.
+
+---
+
+# New Page Structure
+
+New templates must have the following logical structure:
+
+```text
+Page 1: customer
+Page 2: product_items
+Page 3: topics / conditions / signature
+```
+
+If topics overflow, the runtime may generate additional topic pages after the Product Item page.
+
+If Product Item table overflows, PDFMe table pagination must handle additional pages.
+
+---
+
+# Page / Section Markers
+
+Add explicit runtime markers to new templates.
+
+Examples:
+
+```ts
+{
+  name: "__section_role__customer",
+  type: "text",
+  content: "customer"
+}
+```
+
+```ts
+{
+  name: "__section_role__product_items",
+  type: "text",
+  content: "product_items"
+}
+```
+
+```ts
+{
+  name: "__section_role__topics",
+  type: "text",
+  content: "topics"
+}
+```
+
+```ts
+{
+  name: "__section_role__signature",
+  type: "text",
+  content: "signature"
+}
+```
+
+Markers should not be visually disruptive.
+
+Runtime should prefer explicit markers over legacy inference.
+
+---
+
+# Product Item Page Requirements
+
+Product Item page shall contain:
+
+* Section title
+* Product item table
+* Table header
+* Dynamic rows
+* Total/summary area if currently supported by data model
+* Page continuation support
+
+Minimum table columns:
+
+| Column      | Source      |
+| ----------- | ----------- |
+| Item        | itemNumber  |
+| Description | description |
+| Qty         | quantity    |
+| Unit        | unitLabel   |
+| Unit Price  | unitPrice   |
+| Discount    | discount    |
+| Total       | totalPrice  |
+
+Optional future columns may be supported only if source data exists:
+
+* productCode
+* specification
+* remark / notes
+* brand
+* model
+
+Do not invent missing source fields.
+
+---
+
+# PDFMe Table Requirements
+
+Use official PDFMe table schema.
+
+The `items_table` field must use:
+
+```text
+type = table
+showHead = true
+repeatHead = true
+```
+
+The table must support:
+
+* multiple rows
+* long descriptions
+* automatic page break
+* repeated headers
+* numeric alignment
+* currency formatting from Product Item Engine
+
+Do not implement custom HTML rendering.
+
+---
+
+# Product Item Input Contract
+
+The template must consume the Product Item Engine output.
+
+Expected input key:
+
+```text
+items_table
+```
+
+The input shape must be compatible with PDFMe table.
+
+Example conceptual shape:
+
+```ts
+{
+  items_table: [
+    ["1", "Main equipment supply", "1", "Set", "1,717,102.00", "-", "1,717,102.00"]
+  ]
+}
+```
+
+The template must not format numbers itself.
+
+---
+
+# Mapping Requirements
+
+Add or update mapping support for the new version only.
+
+The new template version must include `items_table`.
+
+Required mapping:
+
+```text
+items_table -> documentData.items / Product Item Engine output
+```
+
+The mapping layer must not break legacy template version 1.0.
+
+New mappings must be version-specific.
+
+---
+
+# Runtime Integration
+
+The new template must work with the section-based runtime from P.4.3.
+
+Requirements:
+
+* customer section still renders on page 1
+* product_items section renders on page 2
+* topics/signature section renders after product_items
+* topic engine must not depend on fixed index
+* old templates must continue using legacy inference
+* new templates should use explicit markers
+
+---
+
+# Seed / Reseed Requirements
+
+Update seed or reseed logic to support publishing the new template version into DB.
+
+Do not auto-activate the new version unless explicitly required by the environment.
+
+Recommended behavior:
+
+* create version `product-v1` or `2.0`
+* keep old `1.0` active by default
+* allow manual activation through existing template management flow
+
+If UAT requires immediate testing, provide an explicit script flag to activate the product template version.
+
+---
+
+# Audit Requirements
+
+Update PDF audit tooling to understand the new template version.
+
+Audit must verify:
+
+* template has product_items section marker
+* `items_table` exists
+* `items_table` mapping exists
+* item table columns exist
+* old template still has no product page and remains valid
+* runtime input contains `items_table`
+* rendered PDF can be generated
+* no orphan mappings
+* no unmapped tokens
+
+---
+
+# Regression Requirements
+
+Run regression for both template versions:
+
+## Legacy Template 1.0
+
+Expected:
+
+* output remains unchanged
+* no product page required
+* audit PASS
+
+## Product Template Version
+
+Expected:
+
+* page 1 = customer detail
+* page 2 = product item table
+* page 3 = topics / condition / signature
+* `items_table` renders
+* PDF generation succeeds
+* audit PASS
+
+---
+
+# Verification Cases
+
+Test with quotation item counts:
+
+```text
+0 items
+1 item
+4 items
+30 items
+100 items
+long descriptions
+```
+
+Expected behavior:
+
+* 0 items: render empty state only if policy/template requires it
+* 1 item: one-row table
+* 4 items: standard UAT fixture
+* 30 items: table pagination
+* 100 items: multi-page table
+* long descriptions: dynamic row height and page break remain stable
+
+---
+
+# Backward Compatibility
+
+Must remain true:
+
+* existing template JSON files unchanged
+* existing DB active version remains valid
+* approved artifacts are not regenerated
+* old preview/download/approved flow remains PASS
+* no database migration required
+* no API contract change required
+
+---
+
+# Deliverables
+
+* `ALLA_template_pdfme_product_v1.json`
+* `ONVALLA_template_pdfme_product_v1.json`
+* Product Item page schema
+* Section markers in new templates
+* `items_table` schema
+* Version-specific mapping support
+* Seed/reseed update
+* Audit update
+* Regression verification report
+
+---
+
+# Acceptance Criteria
+
+* New product template JSON files are created.
+* Existing production template JSON files are not modified.
+* Product Item page appears between customer page and condition/signature page.
+* `items_table` uses official PDFMe table schema.
+* Product table supports repeated headers and automatic page breaks.
+* New template version can be seeded/reseeded into DB.
+* New template version can be activated through existing template management flow.
+* Legacy template version still passes audit.
+* Product template version passes audit.
+* Runtime audit remains PASS.
+* No existing approved PDFs are changed.
+
+---
+
+# Out of Scope
+
+## Task P.4.6
+
+* CRM Template UX refinement
+* Activation workflow improvements
+* Visual preview improvements
+* Admin helper controls
+
+## Task P.4.7
+
+* User-selectable Product Table visibility
+* Optional section UI
+* Organization/customer render preferences
+
+## Task P.4.8
+
+* Full visual parity tuning
+* PDF pixel-level polishing
+* Cross-branch template comparison
+
+---
+
+# Final Success Condition
+
+Task P.4.5 is complete when a new PDFMe quotation template version exists for both ALLA and ONVALLA, includes a Product Item page, renders `items_table` correctly, can be published as a version, and passes audit without modifying or breaking existing template version 1.0.