5.8 KiB
Task P.4.4 - Product Item Engine
Objective
Implement the Product Item Engine for the new section-based PDF runtime.
The Product Item Engine is responsible only for transforming quotation items into a PDFMe-compatible table model.
This task does not create or modify PDF templates.
This task does not insert Product Item pages.
This task prepares the runtime for Task P.4.5.
Prerequisites
Completed
- P.4 Discovery
- P.4.1 Runtime Verification
- P.4.2 Runtime Architecture Design
- P.4.3 Runtime Refactoring
- P.4.3.1 Runtime Regression Stabilization
Runtime audit must already pass before implementation begins.
Scope
Included
- Product Item Engine
- Product Item Builder
- Product Item Mapping
- PDFMe Table Model
- Pagination Model
- Runtime Contracts
- Unit Tests
Excluded
- PDF template JSON
- CRM Template UI
- Template Version
- Page insertion
- Product Item page rendering
- User render options
Architecture
The runtime shall use the existing section-based architecture.
Quotation Document
↓
Render Context
↓
Section Composer
↓
Product Item Engine
↓
BuiltSection
↓
Template Assembler
The engine must be completely isolated from
- Topic Engine
- Signature Resolver
- Customer Section
Responsibilities
The Product Item Engine shall
- read quotation items
- normalize data
- format values
- build PDFMe table rows
- calculate row metadata
- estimate pagination
- return a BuiltSection
The engine must not know
- page indexes
- template layouts
- template JSON
- page insertion
- section ordering
Input
Primary source
documentData.items
The engine shall not query the database.
It receives all data from RenderContext.
Output
Return
interface ProductItemSection extends BuiltSection {
role: SectionRole.ProductItems;
rows: ProductItemRow[];
pagination: PaginationModel;
tableModel: PdfmeTableModel;
}
The output must be renderer-independent.
Product Item Mapping
Support at minimum
| Column | Source |
|---|---|
| Item | itemNumber |
| Description | description |
| Qty | quantity |
| Unit | unitLabel |
| Unit Price | unitPrice |
| Discount | discount |
| Total | totalPrice |
If additional fields exist they should be supported when available.
Examples
- productCode
- specification
- remark
- model
- brand
Missing optional fields must not fail rendering.
Value Formatting
Use centralized formatters.
Never format inside templates.
Support
- currency
- decimal quantity
- percentage
- empty value normalization
Formatting must remain locale-aware.
PDFMe Table Model
Generate a canonical table model independent of template layout.
Example
interface PdfmeTableModel {
headers;
rows;
columnWidths;
alignments;
}
The template consumes this model later.
The engine must not know where the table is rendered.
Pagination Model
Implement pagination metadata.
The engine shall estimate
- row count
- page count
- header repetition
- orphan row prevention
- available content height
Do not insert pages.
Return only metadata.
Example
interface PaginationModel {
estimatedPages;
rowsPerPage;
headerRows;
footerRows;
}
Empty State
When quotation has zero items
Return an empty Product Item section.
Do not throw an exception.
Runtime decides whether the section is rendered.
Error Handling
Generate Runtime Issues for
- invalid quantity
- invalid price
- missing mandatory description
- invalid totals
Do not stop rendering because of one invalid row.
Product Item Builder
Create a dedicated builder.
Responsibilities
- invoke Product Item Engine
- produce BuiltSection
- register itself in Section Registry
The builder must not manipulate templates.
Unit Tests
Cover
- 0 items
- 1 item
- 10 items
- 100 items
- long descriptions
- missing optional fields
- currency formatting
- decimal quantities
- zero discount
- non-zero discount
Integration Tests
Verify
- Section Composer accepts Product Item Builder
- BuiltSection returned correctly
- Runtime diagnostics preserved
- Existing sections unaffected
No template rendering yet.
Performance Requirements
Support
- 500 quotation items
without significant performance degradation.
Avoid unnecessary cloning.
Avoid repeated formatting.
Code Quality
- Single Responsibility Principle
- Strong typing
- Immutable outputs
- No duplicated mapping logic
- Shared formatter usage
- Shared runtime contracts
- Builder registration through Section Registry
Deliverables
- Product Item Engine
- Product Item Builder
- Product Item Mapping
- PDFMe Table Model
- Pagination Model
- Runtime diagnostics
- Unit tests
- Integration tests
Acceptance Criteria
- Product Item Engine is independent from template layout.
- Engine produces canonical PDFMe table model.
- Engine does not manipulate templates.
- Engine does not insert pages.
- Engine returns pagination metadata only.
- Existing runtime regression tests remain PASS.
- Runtime audit continues to pass.
- Product Item Engine is ready for Task P.4.5.
Out of Scope
Task P.4.5
- New PDF template
- Product Item page
- PDFMe table rendering
- Page insertion
- Header repetition in rendered PDF
Task P.4.6
- CRM Template integration
- Template version management
- Preview integration
Task P.4.7
- Render Policy UI
- Optional section configuration
- User-selectable Product Item visibility
Final Success Condition
At the end of Task P.4.4, the runtime is capable of producing a fully normalized Product Item section and PDFMe table model, ready to be rendered by a future template, while the existing PDF output remains unchanged.