taks-p.4.3

plans/task-p.4.2.md

@@ -0,0 +1,475 @@
+# 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.