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