taks-p.4.3

2026-06-29 11:18:08 +07:00
parent 2540d52670
commit 0c0450b152
20 changed files with 4900 additions and 505 deletions
--- a/plans/task-p.4-discovery-report.md
+++ b/plans/task-p.4-discovery-report.md
@@ -0,0 +1,582 @@
+# Task P.4 Discovery Report
+
+## Scope
+
+This report documents the mandatory discovery phase for `task-p.4.md` before any implementation begins.
+
+Task P.4 requires:
+
+- introducing a dedicated Product Item page between the existing Customer Detail page and Condition + Signature page
+- using the existing CRM template management workflow
+- creating new template versions only
+- preserving backward compatibility for existing quotation template versions
+
+No implementation has been performed at the time of writing this report.
+
+---
+
+## 1. Existing Architecture
+
+### 1.1 CRM Template Module
+
+The CRM template settings page is served by:
+
+- [src/app/dashboard/crm/settings/templates/page.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/dashboard/crm/settings/templates/page.tsx:9)
+
+This page:
+
+- checks access with `crmDocumentTemplateRead`
+- prefetches quotation PDFMe templates via `documentTemplatesQueryOptions({ documentType: 'quotation', fileType: 'pdfme' })`
+- renders the admin UI through `TemplateSettings`
+
+The main template admin UI lives in:
+
+- [src/features/foundation/document-template/components/template-settings.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/template-settings.tsx:720)
+
+This module already supports:
+
+- template metadata CRUD
+- template version CRUD
+- raw `schemaJson` editing
+- mapping CRUD
+- version activation
+- template detail inspection
+
+Important internal UI areas:
+
+- template metadata dialog: [template-settings.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/template-settings.tsx:241)
+- version dialog: [template-settings.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/template-settings.tsx:292)
+- version JSON editing: [template-settings.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/template-settings.tsx:360)
+- template detail card and version tabs: [template-settings.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/components/template-settings.tsx:527)
+
+### 1.2 Template APIs
+
+Template/version/mapping APIs already exist and are reused by the CRM settings route group:
+
+- [src/app/api/crm/document-templates/[id]/versions/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/document-templates/[id]/versions/route.ts:1)
+- [src/app/api/crm/settings/document-templates/versions/[id]/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/route.ts:1)
+- [src/app/api/crm/settings/document-templates/versions/[id]/mappings/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/settings/document-templates/versions/[id]/mappings/route.ts:1)
+
+### 1.3 Document Template Foundation
+
+The main document-template business logic is centralized in:
+
+- [src/features/foundation/document-template/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts:1)
+
+Important responsibilities already covered:
+
+- template resolution for runtime documents
+- version resolution
+- mapping resolution
+- mapping-to-input transformation
+- active/default template handling
+
+Key functions:
+
+- `resolveTemplateMappings`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts:168)
+- `createDocumentTemplateVersion`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts:424)
+- `updateDocumentTemplateVersion`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts:449)
+- `setDocumentTemplateVersionActive`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts:474)
+- `resolveTemplateForDocument`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts:612)
+- `mapDocumentDataToTemplateInput`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts:745)
+
+### 1.4 Quotation Document Runtime
+
+Quotation document runtime logic is handled in:
+
+- [src/features/crm/quotations/document/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/service.ts:263)
+
+Key functions:
+
+- `buildQuotationDocumentData`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/service.ts:263)
+- `getQuotationDocumentPreviewData`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/service.ts:661)
+- `prepareApprovedQuotationSnapshot`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/service.ts:718)
+
+Topic-based dynamic layout is currently handled by:
+
+- [src/features/crm/quotations/document/server/pdf-topic-engine.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/pdf-topic-engine.ts:66)
+
+Formatting helpers are in:
+
+- [src/features/crm/quotations/document/server/pdfme-transforms.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/pdfme-transforms.ts:86)
+
+### 1.5 PDF Generation Foundation
+
+PDF generation is centralized in:
+
+- [src/features/foundation/pdf-generator/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts:99)
+
+Important capabilities already provided:
+
+- font loading
+- PDFMe plugin registration
+- preview PDF generation
+- download PDF generation
+- approved PDF artifact generation and persistence
+
+Key functions:
+
+- `getPdfPlugins`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts:44)
+- `resolvePdfFonts`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts:53)
+- `generatePdfFromTemplate`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts:99)
+- `generateQuotationPdf`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts:300)
+- `generateQuotationPreviewPdf`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts:317)
+- `generateApprovedQuotationPdf`: [service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts:321)
+
+---
+
+## 2. Dependency Graph
+
+### 2.1 Runtime Flow
+
+Quotation to PDF currently flows as:
+
+1. quotation APIs request document data or document preview
+2. quotation server service builds normalized `documentData`
+3. runtime resolves the active template and active version
+4. runtime resolves mappings for the selected version
+5. document data is transformed into PDFMe `templateInput`
+6. topic engine clones and expands the topic page dynamically
+7. merged template plus merged inputs are passed to PDFMe generator
+8. resulting PDF is returned as preview, download, or approved artifact
+
+### 2.2 Route-Level Graph
+
+- document data route: [src/app/api/crm/quotations/[id]/document-data/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/quotations/[id]/document-data/route.ts:15)
+  - calls `buildQuotationDocumentData`
+- document preview route: [src/app/api/crm/quotations/[id]/document-preview/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/quotations/[id]/document-preview/route.ts:15)
+  - calls `getQuotationDocumentPreviewData`
+- PDF preview route: [src/app/api/crm/quotations/[id]/pdf-preview/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/quotations/[id]/pdf-preview/route.ts:15)
+  - calls `generateQuotationPreviewPdf`
+- PDF download route: [src/app/api/crm/quotations/[id]/pdf-download/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/quotations/[id]/pdf-download/route.ts:15)
+  - calls `generateQuotationPdf`
+- approved PDF route: [src/app/api/crm/quotations/[id]/approved-pdf/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/quotations/[id]/approved-pdf/route.ts:20)
+  - calls approved artifact retrieval/generation flow
+
+### 2.3 UI Preview Graph
+
+Client document preview uses:
+
+- [src/features/crm/quotations/document/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/service.ts:1)
+- [src/features/crm/quotations/document/queries.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/queries.ts:1)
+- [src/features/crm/quotations/components/quotation-document-preview.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/components/quotation-document-preview.tsx:1)
+
+This preview currently renders document data and item summaries for inspection, but it is not the PDF layout engine itself.
+
+---
+
+## 3. Current Template Lifecycle
+
+### 3.1 Storage Model
+
+Template entities are stored in:
+
+- `crm_document_templates`: [schema.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts:880)
+- `crm_document_template_versions`: [schema.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts:909)
+- `crm_document_template_mappings`: [schema.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts:933)
+- `crm_document_template_table_columns`: [schema.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts:957)
+
+### 3.2 Lifecycle Rules
+
+Observed lifecycle:
+
+1. create template metadata
+2. create template version with raw `schemaJson`
+3. add/update mappings for placeholders
+4. activate the desired version
+5. runtime automatically resolves the active version
+
+### 3.3 Selection Rules at Runtime
+
+Runtime template resolution is implemented in:
+
+- [resolveTemplateForDocument](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts:612)
+
+Selection behavior:
+
+- only active templates are considered
+- product-type-specific match is preferred
+- default product type fallback exists
+- active versions are filtered
+- the latest active version by creation order is selected
+
+### 3.4 Activation and Default Handling
+
+- default template normalization is handled by `normalizeDefaultTemplate`
+- version activation is handled by `setDocumentTemplateVersionActive`
+- inactive versions remain stored for traceability
+
+### 3.5 Template Source / Seed Coupling
+
+Current template source loading in seeds and audit utilities still points to:
+
+- `ALLA_template_pdfme_fainal3.json`
+- `ONVALLA_template_pdfme_fainal3.json`
+
+References:
+
+- [src/db/seeds/foundation.seed.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/seeds/foundation.seed.ts:854)
+- [scripts/pdf-audit-utils.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/scripts/pdf-audit-utils.ts:667)
+- [scripts/reseed-pdf-template-version.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/scripts/reseed-pdf-template-version.ts:1)
+
+This means any new product-item template version likely needs seed/audit support updates.
+
+---
+
+## 4. Runtime Rendering Flow
+
+### 4.1 Current Preview Builder
+
+`getQuotationDocumentPreviewData` currently does the following:
+
+1. builds quotation document data
+2. resolves the active quotation PDFMe template
+3. resolves version mappings
+4. maps document data to template inputs
+5. normalizes aliases between field names and placeholder tokens
+6. runs the topic engine
+7. returns merged template input plus rendered schema
+
+Reference:
+
+- [src/features/crm/quotations/document/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/service.ts:661)
+
+### 4.2 Topic Engine Behavior
+
+The existing topic engine:
+
+- clones template pages
+- assumes the dynamic topic page is at `targetPageIndex: 1`
+- looks for `topic` and `data_topic`
+- inserts repeated topic blocks
+- moves signature/keep-together fields to the last generated page when needed
+
+Key implementation details:
+
+- default options: [pdf-topic-engine.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/pdf-topic-engine.ts:14)
+- target page lookup: [pdf-topic-engine.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/pdf-topic-engine.ts:76)
+- dynamic field lookup: [pdf-topic-engine.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/pdf-topic-engine.ts:83)
+- page break behavior: [pdf-topic-engine.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/pdf-topic-engine.ts:147)
+- keep-together footer/signature handling: [pdf-topic-engine.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/pdf-topic-engine.ts:169)
+
+### 4.3 PDF Generator Runtime
+
+The generator currently registers these PDFMe plugins:
+
+- `text`
+- `image`
+- `line`
+- `table`
+
+Reference:
+
+- [src/features/foundation/pdf-generator/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts:44)
+
+This is important because Product Item page support should reuse the existing official PDFMe `table` plugin instead of introducing a custom renderer.
+
+---
+
+## 5. Existing PDF Templates
+
+### 5.1 Located Template Files
+
+Current PDFMe template assets found in the repository:
+
+- [src/pdfme_template/ALLA_template_pdfme_fainal3.json](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/pdfme_template/ALLA_template_pdfme_fainal3.json)
+- [src/pdfme_template/ONVALLA_template_pdfme_fainal3.json](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/pdfme_template/ONVALLA_template_pdfme_fainal3.json)
+
+### 5.2 Current Page Count
+
+Both templates currently contain exactly 2 pages.
+
+### 5.3 Page Purposes
+
+For `ALLA_template_pdfme_fainal3.json`:
+
+- Page 1
+  - company header
+  - customer detail
+  - quotation meta
+  - project fields
+  - quotation price summary table
+- Page 2
+  - dynamic topic label/table placeholders
+  - closing message
+  - signature blocks
+
+Observed markers from template JSON:
+
+- page 1 price table field `quotation_price_data`
+- page 2 dynamic topic fields `topic` and `data_topic`
+- page 2 static closing/signature fields `Please_do_not`, `yours_faithfuly`, `app1`, `app2`, `app3`
+
+Relevant references:
+
+- quotation price table marker: [ALLA template](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/pdfme_template/ALLA_template_pdfme_fainal3.json:345)
+- topic marker: [ALLA template](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/pdfme_template/ALLA_template_pdfme_fainal3.json:962)
+- topic data marker: [ALLA template](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/pdfme_template/ALLA_template_pdfme_fainal3.json:1031)
+
+### 5.4 Base PDF Structure
+
+The current templates use PDFMe object-style `basePdf` with width/height/padding and static schema, not an imported fixed PDF file path.
+
+This is favorable for dynamic table layout and page growth.
+
+---
+
+## 6. Product Item Flow
+
+### 6.1 Data Origin
+
+Quotation product items originate from:
+
+- `crm_quotation_items`: [schema.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/schema.ts:613)
+
+Current persisted fields include:
+
+- `itemNumber`
+- `productType`
+- `description`
+- `quantity`
+- `unit`
+- `unitPrice`
+- `discount`
+- `discountType`
+- `taxRate`
+- `totalPrice`
+- `notes`
+
+### 6.2 Server Mapping
+
+Quotation item records are normalized in:
+
+- [src/features/crm/quotations/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/server/service.ts:208)
+
+Quotation document data currently exposes item fields in:
+
+- [src/features/crm/quotations/document/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/service.ts:564)
+
+Currently exposed document item fields:
+
+- `itemNumber`
+- `productTypeCode`
+- `productTypeLabel`
+- `description`
+- `quantity`
+- `unitCode`
+- `unitLabel`
+- `unitPrice`
+- `discount`
+- `discountTypeCode`
+- `taxRate`
+- `totalPrice`
+- `notes`
+
+### 6.3 Existing Table Mapping Support
+
+There is already existing seed/audit support for an `items_table` mapping:
+
+- [scripts/pdf-audit-utils.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/scripts/pdf-audit-utils.ts:312)
+
+Current seeded columns:
+
+- `Item` → `itemNumber`
+- `Description` → `description`
+- `Qty` → `quantity`
+- `Unit` → `unitLabel`
+- `Unit Price` → `unitPrice`
+- `Total` → `totalPrice`
+
+This suggests the architecture already anticipated table-based quotation item rendering, even though the currently active production template files are still only 2 pages.
+
+### 6.4 Gaps Against P.4 Requirements
+
+Task P.4 requires these columns or concepts:
+
+- product code
+- description
+- specification
+- quantity
+- unit
+- unit price
+- discount
+- amount
+- remark
+
+Observed current gap:
+
+- no dedicated `specification` field was found in `crm_quotation_items`
+- `remark` appears to correspond most closely to `notes`, unless business rules say otherwise
+
+This is a discovery risk and must be resolved before final implementation behavior is locked in.
+
+---
+
+## 7. Layout Engine Assessment
+
+### 7.1 What Already Exists
+
+The current layout foundation already supports:
+
+- page cloning
+- dynamic page generation
+- page splitting based on vertical overflow
+- repeated topic block creation
+- keep-together footer/signature placement
+
+This is provided by:
+
+- [src/features/crm/quotations/document/server/pdf-topic-engine.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/pdf-topic-engine.ts:66)
+
+### 7.2 What Does Not Yet Exist Explicitly
+
+No dedicated runtime was found yet for:
+
+- dynamic product item page insertion between page 1 and topic/signature page
+- generic dynamic page marker resolution
+- generalized page numbering helper
+- product-table-specific pagination layer separate from topic engine
+
+### 7.3 Key Constraint
+
+The existing topic engine is hard-wired to `targetPageIndex: 1`, which currently means:
+
+- it expects the dynamic topic page to be page 2
+- it expects signature fields on that same logical target page
+
+If a new Product Item page is inserted between the current page 1 and current page 2 without changing runtime behavior, the topic engine will target the wrong page.
+
+This is the most important architecture finding of the discovery phase.
+
+---
+
+## 8. Files Expected to Be Modified
+
+Likely implementation touchpoints:
+
+- [src/features/crm/quotations/document/server/pdf-topic-engine.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/pdf-topic-engine.ts:66)
+- [src/features/crm/quotations/document/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/document/server/service.ts:661)
+- [src/features/foundation/document-template/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-template/server/service.ts:612)
+- [scripts/pdf-audit-utils.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/scripts/pdf-audit-utils.ts:312)
+- [scripts/reseed-pdf-template-version.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/scripts/reseed-pdf-template-version.ts:1)
+- possibly [src/db/seeds/foundation.seed.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/db/seeds/foundation.seed.ts:854)
+
+Possible UI/admin edits may be needed only if additional metadata or better preview labeling is required, but no mandatory UI gap was found yet for basic version creation and activation.
+
+---
+
+## 9. New Files Expected to Be Created
+
+Expected new template assets:
+
+- `src/pdfme_template/ALLA_template_pdfme_product_v1.json`
+- `src/pdfme_template/ONVALLA_template_pdfme_product_v1.json`
+
+No separate parallel rendering pipeline should be created.
+
+---
+
+## 10. Backward Compatibility Analysis
+
+Backward compatibility is achievable if the implementation follows these rules:
+
+1. do not modify existing `*_fainal3.json` template files
+2. create new template versions only
+3. keep runtime able to render both old and new version structures
+4. make topic-page resolution robust enough to support the new page sequence
+5. avoid changing existing approved PDF artifact behavior
+
+Why compatibility is realistic:
+
+- runtime already resolves active versions dynamically
+- template mappings are version-specific
+- old versions remain stored
+- admin UI already supports multiple versions and activation switching
+
+Main compatibility risk:
+
+- current topic engine assumes old page order and must be generalized without breaking old templates
+
+---
+
+## 11. Risk Assessment
+
+### 11.1 High Risk
+
+- topic engine currently assumes page 2 is the dynamic topic/signature page
+- inserting a new middle page will break runtime unless page targeting becomes marker-based or otherwise dynamic
+
+### 11.2 Medium Risk
+
+- current quotation item payload does not clearly expose a standalone `specification` field
+- page numbering requirement exists in Task P.4, but current templates do not expose obvious page-number fields
+- reseed/audit utilities still point to legacy file names and will need alignment for new template assets
+
+### 11.3 Lower Risk
+
+- CRM settings workflow itself is already sufficient for version CRUD
+- PDF generator already registers the official PDFMe `table` plugin
+- template storage model already supports table mappings
+
+---
+
+## 12. Migration Strategy
+
+Recommended migration path:
+
+1. generalize runtime topic page detection so it is not tied to fixed page index 1
+2. create new Product Item template JSON files for ALLA and ONVALLA
+3. add or update mappings for the product item table placeholders
+4. ensure new versions can be created and activated through the existing template settings flow
+5. update reseed/audit helpers to recognize the new product template source files where needed
+6. verify all runtime modes
+
+Required verification modes:
+
+- document preview route
+- PDF preview route
+- PDF download route
+- approved PDF generation
+- old template version behavior
+- new template version behavior
+
+---
+
+## 13. Final Discovery Conclusion
+
+Task P.4 should proceed by extending the current document-template and quotation-document runtime foundations, not by creating a new rendering path.
+
+The critical architecture change is:
+
+- make the topic/signature dynamic-page resolution independent from the old hardcoded second-page layout
+
+Once that is in place, the new Product Item page can be introduced as a new template version while preserving existing templates unchanged.
+
+---
+
+## References Reviewed
+
+### Governance and Standards
+
+- [AGENTS.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/AGENTS.md)
+- [docs/standards/project-foundations.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/project-foundations.md)
+- [docs/standards/architecture-rules.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/architecture-rules.md)
+- [docs/standards/ui-ux-rules.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/ui-ux-rules.md)
+- [docs/standards/task-catalog.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/task-catalog.md)
+- [docs/standards/task-review-checklist.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/task-review-checklist.md)
+
+### ADRs and Business Docs
+
+- [docs/adr/0008-attachment-storage-strategy.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0008-attachment-storage-strategy.md)
+- [docs/adr/0009-approved-document-storage-lifecycle.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0009-approved-document-storage-lifecycle.md)
+- [docs/adr/0012-approval-signature-strategy.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0012-approval-signature-strategy.md)
+- [docs/adr/0013-pdf-visual-parity-strategy.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0013-pdf-visual-parity-strategy.md)
+- [docs/business/pdf-mapping-registry.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/business/pdf-mapping-registry.md)
+- [docs/business/pdf-placeholder-registry.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/business/pdf-placeholder-registry.md)
+
+### Implementation Lineage
+
+- [docs/implementation/task-g-document-preview-foundation.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-g-document-preview-foundation.md)
+- [docs/implementation/task-h-pdf-generation-persistence.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-h-pdf-generation-persistence.md)
+- [docs/implementation/pdfme-runtime-audit.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/pdfme-runtime-audit.md)
+- [docs/implementation/pdfme-legacy-audit.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/pdfme-legacy-audit.md)