438 lines
6.8 KiB
Markdown
438 lines
6.8 KiB
Markdown
# Task P.4.3 - PDF Runtime Refactoring (Regression-first)
|
|
|
|
## Objective
|
|
|
|
Implement the new section-based PDF runtime architecture designed in Task P.4.2.
|
|
|
|
This task is a **runtime refactor only**.
|
|
|
|
The primary objective is to replace the current page-index-driven runtime with the new section-based runtime **without changing the rendered output of existing templates**.
|
|
|
|
This task must not introduce new PDF layouts or Product Item pages yet.
|
|
|
|
---
|
|
|
|
# Prerequisites
|
|
|
|
Complete and reuse:
|
|
|
|
* Task P.4 Discovery
|
|
* Task P.4.1 Runtime Verification
|
|
* Task P.4.2 Runtime Design
|
|
|
|
Do not redesign the architecture.
|
|
|
|
Implement the approved design only.
|
|
|
|
---
|
|
|
|
# Primary Goal
|
|
|
|
Move from
|
|
|
|
```text
|
|
Hardcoded Page Index
|
|
|
|
↓
|
|
|
|
Topic Engine
|
|
|
|
↓
|
|
|
|
PDF
|
|
```
|
|
|
|
to
|
|
|
|
```text
|
|
Section-based Runtime
|
|
|
|
↓
|
|
|
|
Section Composer
|
|
|
|
↓
|
|
|
|
Template Assembler
|
|
|
|
↓
|
|
|
|
PDF
|
|
```
|
|
|
|
while maintaining identical output for all existing templates.
|
|
|
|
---
|
|
|
|
# Regression-first Rule
|
|
|
|
This task follows a strict Regression-first strategy.
|
|
|
|
Before introducing any new rendering capability:
|
|
|
|
* existing templates must continue producing identical PDFs
|
|
* preview, download and approved PDF must remain unchanged
|
|
* all regression tests must pass
|
|
|
|
Feature additions are intentionally deferred.
|
|
|
|
---
|
|
|
|
# Scope
|
|
|
|
Implement only runtime architecture.
|
|
|
|
Included
|
|
|
|
* runtime contracts
|
|
* compatibility adapter
|
|
* page resolver
|
|
* section composer
|
|
* render context
|
|
* topic engine refactor
|
|
* template assembler
|
|
* runtime diagnostics
|
|
|
|
Excluded
|
|
|
|
* Product Item page
|
|
* Product Item rendering
|
|
* new template JSON
|
|
* CRM Template UI
|
|
* user render options
|
|
* template version changes
|
|
* database changes
|
|
|
|
---
|
|
|
|
# Implementation Requirements
|
|
|
|
## Phase 1 — Runtime Contracts
|
|
|
|
Create runtime contracts.
|
|
|
|
At minimum
|
|
|
|
* SectionRole
|
|
* RenderContext
|
|
* ResolvedTemplate
|
|
* ResolvedPages
|
|
* BuiltSection
|
|
* RuntimeIssue
|
|
* AssembledTemplate
|
|
|
|
Responsibilities must match Task P.4.2.
|
|
|
|
---
|
|
|
|
## Phase 2 — Compatibility Adapter
|
|
|
|
Implement
|
|
|
|
TemplateCompatibilityAdapter
|
|
|
|
Responsibilities
|
|
|
|
* explicit marker support
|
|
* legacy marker inference
|
|
* normalize legacy templates
|
|
* expose Runtime Issues
|
|
|
|
Legacy templates must continue working without modification.
|
|
|
|
---
|
|
|
|
## Phase 3 — Page Resolver
|
|
|
|
Replace page-index assumptions.
|
|
|
|
The runtime must never depend on
|
|
|
|
```ts
|
|
schemas[1]
|
|
```
|
|
|
|
Responsibilities
|
|
|
|
* discover pages
|
|
* classify by SectionRole
|
|
* detect duplicates
|
|
* detect missing markers
|
|
* produce insertion anchors
|
|
|
|
---
|
|
|
|
## Phase 4 — Render Context
|
|
|
|
Introduce a shared runtime context.
|
|
|
|
Example
|
|
|
|
```ts
|
|
interface RenderContext {
|
|
documentData;
|
|
template;
|
|
mappings;
|
|
pages;
|
|
policies;
|
|
issues;
|
|
}
|
|
```
|
|
|
|
Every runtime component should consume RenderContext instead of receiving unrelated parameters.
|
|
|
|
The context must remain immutable where possible.
|
|
|
|
---
|
|
|
|
## Phase 5 — Section Registry
|
|
|
|
Implement a registry-based architecture.
|
|
|
|
Example
|
|
|
|
```ts
|
|
interface SectionBuilder {
|
|
role: SectionRole;
|
|
|
|
build(context: RenderContext): BuiltSection;
|
|
}
|
|
```
|
|
|
|
The runtime must discover builders through registration rather than hardcoded orchestration.
|
|
|
|
Section Composer must not know implementation details of builders.
|
|
|
|
---
|
|
|
|
## Phase 6 — Section Composer
|
|
|
|
Implement
|
|
|
|
SectionComposer
|
|
|
|
Responsibilities
|
|
|
|
* execute builders
|
|
* skip disabled sections
|
|
* collect Runtime Issues
|
|
* preserve logical order
|
|
* return assembled section outputs
|
|
|
|
The composer must not contain rendering logic.
|
|
|
|
---
|
|
|
|
## Phase 7 — Topic Engine Refactor
|
|
|
|
Refactor Topic Engine.
|
|
|
|
Current behavior
|
|
|
|
```text
|
|
Page Index
|
|
|
|
↓
|
|
|
|
Topic Engine
|
|
```
|
|
|
|
New behavior
|
|
|
|
```text
|
|
Resolved Page
|
|
|
|
↓
|
|
|
|
Topic Engine
|
|
```
|
|
|
|
The generated output must remain identical.
|
|
|
|
---
|
|
|
|
## Phase 8 — Template Assembler
|
|
|
|
Implement
|
|
|
|
TemplateAssembler
|
|
|
|
Responsibilities
|
|
|
|
* preserve existing pages
|
|
* assemble generated sections
|
|
* merge template inputs
|
|
* preserve page order
|
|
* return final template
|
|
|
|
No Product Item pages yet.
|
|
|
|
---
|
|
|
|
## Phase 9 — PDF Runtime Integration
|
|
|
|
Wire the new runtime into
|
|
|
|
* Preview
|
|
* Download
|
|
* Approved PDF
|
|
|
|
All three flows must use the same runtime.
|
|
|
|
No duplicated pipelines.
|
|
|
|
---
|
|
|
|
# Runtime Diagnostics
|
|
|
|
Implement RuntimeIssue collection.
|
|
|
|
Support
|
|
|
|
* MISSING_MARKER
|
|
* DUPLICATE_MARKER
|
|
* INVALID_TEMPLATE
|
|
* MISSING_MAPPING
|
|
* LEGACY_COMPAT_MODE
|
|
|
|
Diagnostics must be available during Preview for debugging.
|
|
|
|
---
|
|
|
|
# Backward Compatibility
|
|
|
|
Existing templates must continue working without modification.
|
|
|
|
Current
|
|
|
|
* ALLA
|
|
* ONVALLA
|
|
|
|
templates must render exactly as before.
|
|
|
|
No migration required.
|
|
|
|
---
|
|
|
|
# Refactoring Constraints
|
|
|
|
Do NOT
|
|
|
|
* modify template JSON
|
|
* introduce Product Item pages
|
|
* change template mappings
|
|
* modify database schema
|
|
* change API contracts
|
|
* change CRM Template UI
|
|
|
|
---
|
|
|
|
# Code Quality Requirements
|
|
|
|
* Single Responsibility Principle
|
|
* Dependency Injection where appropriate
|
|
* Immutable runtime contracts where practical
|
|
* No duplicated rendering logic
|
|
* No duplicated template resolution
|
|
* No duplicated mapping resolution
|
|
* Strong typing
|
|
* Comprehensive inline documentation for new runtime components
|
|
|
|
---
|
|
|
|
# Testing Requirements
|
|
|
|
Regression tests are mandatory.
|
|
|
|
Verify
|
|
|
|
## Runtime
|
|
|
|
* Preview
|
|
* Download
|
|
* Approved PDF
|
|
|
|
## Templates
|
|
|
|
* ALLA
|
|
* ONVALLA
|
|
|
|
## Rendering
|
|
|
|
* Topic rendering
|
|
* Signature placement
|
|
* Mapping resolution
|
|
* Pagination
|
|
|
|
Expected result
|
|
|
|
Rendered PDF must remain visually identical to the previous runtime.
|
|
|
|
---
|
|
|
|
# Deliverables
|
|
|
|
Implementation must include
|
|
|
|
* Runtime Contracts
|
|
* Compatibility Adapter
|
|
* Page Resolver
|
|
* RenderContext
|
|
* Section Registry
|
|
* Section Composer
|
|
* Refactored Topic Engine
|
|
* Template Assembler
|
|
* Runtime Diagnostics
|
|
* Updated Runtime Integration
|
|
* Regression Tests
|
|
|
|
---
|
|
|
|
# Acceptance Criteria
|
|
|
|
* No hardcoded page indexes remain.
|
|
* Runtime becomes section-based.
|
|
* Topic Engine no longer depends on page position.
|
|
* Legacy templates render without modification.
|
|
* Preview, Download and Approved PDF use one shared runtime.
|
|
* Existing PDF output remains unchanged.
|
|
* Runtime is ready for Product Item Engine implementation in Task P.4.4.
|
|
* No functional regression is introduced.
|
|
|
|
---
|
|
|
|
# Out of Scope
|
|
|
|
The following work belongs to later tasks:
|
|
|
|
**Task P.4.4**
|
|
|
|
* Product Item Engine
|
|
* Product Item pagination
|
|
* Product Item section rendering
|
|
|
|
**Task P.4.5**
|
|
|
|
* New PDF template versions
|
|
* Product Item template layout
|
|
|
|
**Task P.4.6**
|
|
|
|
* CRM Template integration
|
|
* Template activation
|
|
* Version publishing
|
|
|
|
**Task P.4.7**
|
|
|
|
* Render Policy configuration
|
|
* User-selectable section visibility
|
|
* Organization default rendering options
|
|
|
|
---
|
|
|
|
# Final Success Condition
|
|
|
|
At the end of Task P.4.3, the internal PDF runtime architecture shall be completely refactored to the new section-based design while producing identical output to the legacy runtime.
|
|
|
|
No new user-visible functionality is expected in this task. The success metric is architectural modernization with zero regression, providing a stable foundation for subsequent Product Item and optional section features.
|