476 lines
5.7 KiB
Markdown
476 lines
5.7 KiB
Markdown
# Task P.4.2 - PDF Runtime Architecture & Section-based Rendering Design
|
|
|
|
## Objective
|
|
|
|
Design the next-generation PDF runtime architecture for the CRM document system.
|
|
|
|
The new runtime must support:
|
|
|
|
* Dynamic page insertion
|
|
* Section-based document composition
|
|
* Optional document sections
|
|
* Future extensibility
|
|
* Full backward compatibility
|
|
|
|
This is an architecture task only.
|
|
|
|
Do NOT modify production code.
|
|
|
|
Do NOT modify template JSON.
|
|
|
|
Do NOT modify database schema.
|
|
|
|
---
|
|
|
|
# Inputs
|
|
|
|
Reuse verified findings from
|
|
|
|
* Task P.4 Discovery
|
|
* Task P.4.1 Runtime Verification
|
|
|
|
Do not repeat discovery.
|
|
|
|
---
|
|
|
|
# Design Principles
|
|
|
|
The runtime must become
|
|
|
|
* page-role driven
|
|
* section-based
|
|
* version compatible
|
|
* renderer independent
|
|
* extensible
|
|
|
|
Business logic must not depend on page indexes.
|
|
|
|
---
|
|
|
|
# Core Architecture
|
|
|
|
The runtime shall assemble a document from independent sections.
|
|
|
|
Instead of
|
|
|
|
```text
|
|
Template
|
|
|
|
↓
|
|
|
|
Mutate Page 2
|
|
|
|
↓
|
|
|
|
Generate PDF
|
|
```
|
|
|
|
the runtime shall become
|
|
|
|
```text
|
|
Quotation Document Data
|
|
|
|
↓
|
|
|
|
Template Resolver
|
|
|
|
↓
|
|
|
|
Mapping Resolver
|
|
|
|
↓
|
|
|
|
Compatibility Adapter
|
|
|
|
↓
|
|
|
|
Page Resolver
|
|
|
|
↓
|
|
|
|
Section Composer
|
|
|
|
↓
|
|
|
|
Template Assembler
|
|
|
|
↓
|
|
|
|
PDF Generator
|
|
```
|
|
|
|
---
|
|
|
|
# Section-based Rendering
|
|
|
|
Introduce the concept of
|
|
|
|
Document Sections.
|
|
|
|
Examples
|
|
|
|
* Customer
|
|
* Product Items
|
|
* Topics
|
|
* Conditions
|
|
* Signature
|
|
* Attachments
|
|
* Appendix
|
|
* Warranty
|
|
* Cover
|
|
|
|
A section represents logical document content rather than physical pages.
|
|
|
|
A section may generate
|
|
|
|
* zero pages
|
|
* one page
|
|
* multiple pages
|
|
|
|
---
|
|
|
|
# Optional Sections
|
|
|
|
The runtime must support optional sections.
|
|
|
|
A section may be
|
|
|
|
* Required
|
|
* Optional
|
|
|
|
The runtime shall be capable of skipping optional sections without requiring another template version.
|
|
|
|
Examples
|
|
|
|
```text
|
|
Customer
|
|
Required
|
|
|
|
Product Items
|
|
Optional
|
|
|
|
Topics
|
|
Optional
|
|
|
|
Conditions
|
|
Optional
|
|
|
|
Signature
|
|
Required
|
|
```
|
|
|
|
This capability is architectural only.
|
|
|
|
No UI configuration is required in this task.
|
|
|
|
---
|
|
|
|
# Render Policy
|
|
|
|
Design a Render Policy abstraction.
|
|
|
|
Example
|
|
|
|
```ts
|
|
interface RenderPolicy {
|
|
section: PageRole;
|
|
|
|
enabled: boolean;
|
|
|
|
required: boolean;
|
|
|
|
visibleWhenEmpty: boolean;
|
|
}
|
|
```
|
|
|
|
The runtime shall evaluate Render Policy before rendering each section.
|
|
|
|
The policy source is intentionally undefined in this task.
|
|
|
|
Future tasks may provide it from
|
|
|
|
* user selection
|
|
* customer preference
|
|
* template defaults
|
|
* organization defaults
|
|
|
|
---
|
|
|
|
# Runtime Pipeline
|
|
|
|
Design
|
|
|
|
```text
|
|
Document Data
|
|
|
|
↓
|
|
|
|
Template Resolver
|
|
|
|
↓
|
|
|
|
Mapping Resolver
|
|
|
|
↓
|
|
|
|
Compatibility Adapter
|
|
|
|
↓
|
|
|
|
Page Resolver
|
|
|
|
↓
|
|
|
|
Render Policy Resolver
|
|
|
|
↓
|
|
|
|
Section Composer
|
|
|
|
↓
|
|
|
|
Customer Section
|
|
|
|
↓
|
|
|
|
Product Item Section
|
|
|
|
↓
|
|
|
|
Topic Section
|
|
|
|
↓
|
|
|
|
Condition Section
|
|
|
|
↓
|
|
|
|
Signature Section
|
|
|
|
↓
|
|
|
|
Template Assembler
|
|
|
|
↓
|
|
|
|
PDF Generator
|
|
```
|
|
|
|
Describe every stage.
|
|
|
|
---
|
|
|
|
# Runtime Components
|
|
|
|
Design responsibilities for
|
|
|
|
* Template Resolver
|
|
* Mapping Resolver
|
|
* Compatibility Adapter
|
|
* Page Resolver
|
|
* Render Policy Resolver
|
|
* Customer Section Builder
|
|
* Product Item Engine
|
|
* Topic Engine
|
|
* Condition Engine
|
|
* Signature Resolver
|
|
* Template Assembler
|
|
* PDF Render Gateway
|
|
|
|
Each component must have a single responsibility.
|
|
|
|
---
|
|
|
|
# Page Marker Strategy
|
|
|
|
Design page discovery using logical markers instead of indexes.
|
|
|
|
Support
|
|
|
|
* explicit page markers
|
|
* legacy inference
|
|
* fallback detection
|
|
|
|
The runtime must never rely on
|
|
|
|
```ts
|
|
schemas[1]
|
|
```
|
|
|
|
---
|
|
|
|
# Runtime Contracts
|
|
|
|
Define contracts for
|
|
|
|
* ResolvedTemplate
|
|
* ResolvedPages
|
|
* RenderPolicy
|
|
* BuiltSection
|
|
* RuntimeIssue
|
|
* AssembledTemplate
|
|
|
|
Document ownership and responsibilities.
|
|
|
|
---
|
|
|
|
# Compatibility Strategy
|
|
|
|
Support
|
|
|
|
* legacy templates
|
|
* future templates
|
|
|
|
without duplicating runtime logic.
|
|
|
|
Legacy templates shall work through the Compatibility Adapter.
|
|
|
|
---
|
|
|
|
# Future Extensibility
|
|
|
|
The architecture shall allow adding new document sections without changing existing section builders.
|
|
|
|
Examples
|
|
|
|
* Drawing
|
|
* Specification
|
|
* Gallery
|
|
* Warranty
|
|
* Appendix
|
|
* Inspection Report
|
|
|
|
A new section should require only
|
|
|
|
1. PageRole
|
|
2. Section Builder
|
|
3. Marker Rule
|
|
4. Assembly Rule
|
|
|
|
---
|
|
|
|
# Error Handling
|
|
|
|
Design behavior for
|
|
|
|
* missing marker
|
|
* duplicate marker
|
|
* missing mappings
|
|
* empty optional section
|
|
* empty required section
|
|
* invalid template
|
|
|
|
Runtime shall fail gracefully and accumulate Runtime Issues.
|
|
|
|
---
|
|
|
|
# Migration Strategy
|
|
|
|
Design migration from
|
|
|
|
Current Runtime
|
|
|
|
↓
|
|
|
|
Section-based Runtime
|
|
|
|
without breaking
|
|
|
|
* Preview
|
|
* Download
|
|
* Approved PDF
|
|
* Existing Template Versions
|
|
|
|
No database migration.
|
|
|
|
No API changes.
|
|
|
|
---
|
|
|
|
# Sequence Diagrams
|
|
|
|
Produce
|
|
|
|
* Current Runtime
|
|
* Proposed Runtime
|
|
|
|
including
|
|
|
|
* Render Policy
|
|
* Section Composition
|
|
|
|
---
|
|
|
|
# Component Diagram
|
|
|
|
Include
|
|
|
|
* Template Resolver
|
|
* Compatibility Adapter
|
|
* Page Resolver
|
|
* Render Policy Resolver
|
|
* Section Composer
|
|
* Section Builders
|
|
* Template Assembler
|
|
* PDF Generator
|
|
|
|
---
|
|
|
|
# Implementation Roadmap
|
|
|
|
Split implementation into phases.
|
|
|
|
Example
|
|
|
|
Phase 1
|
|
|
|
Runtime Contracts
|
|
|
|
Phase 2
|
|
|
|
Compatibility Adapter
|
|
|
|
Phase 3
|
|
|
|
Page Resolver
|
|
|
|
Phase 4
|
|
|
|
Section Composer
|
|
|
|
Phase 5
|
|
|
|
Product Item Engine
|
|
|
|
Phase 6
|
|
|
|
Template Upgrade
|
|
|
|
Phase 7
|
|
|
|
Regression Tests
|
|
|
|
Each phase must be independently testable.
|
|
|
|
---
|
|
|
|
# Constraints
|
|
|
|
* Architecture only.
|
|
* No production implementation.
|
|
* No template modification.
|
|
* No database changes.
|
|
* No API changes.
|
|
|
|
---
|
|
|
|
# Acceptance Criteria
|
|
|
|
* Runtime is section-based rather than page-index-based.
|
|
* Optional sections are supported by design.
|
|
* Product Item pages are independent from Topic pages.
|
|
* Existing template versions remain compatible.
|
|
* Future document sections can be added without redesigning the runtime.
|
|
* Template Version is used only for structural/layout differences, not for enabling or disabling document sections.
|
|
* The design is ready for implementation in Task P.4.3 with minimal architectural decisions remaining.
|