allagroup/alla-allaos-fullstack

Template

Fork 0

Files

phaichayon a1cac84e2b task p-4.5

2026-06-29 16:07:03 +07:00

8.3 KiB

Raw Blame History

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:

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:

src/pdfme_template/ALLA_template_pdfme_fainal3.json
src/pdfme_template/ONVALLA_template_pdfme_fainal3.json

Create new files:

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:

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:

{
  name: "__section_role__customer",
  type: "text",
  content: "customer"
}

{
  name: "__section_role__product_items",
  type: "text",
  content: "product_items"
}

{
  name: "__section_role__topics",
  type: "text",
  content: "topics"
}

{
  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:

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:

items_table

The input shape must be compatible with PDFMe table.

Example conceptual shape:

{
  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:

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:

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.

8.3 KiB Raw Blame History