# 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.