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