583 lines
26 KiB
Markdown
583 lines
26 KiB
Markdown
# 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)
|