allagroup/alla-allaos-fullstack
Template
2
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
Files
b7589017ab652cfc30bb7f305ab42000654034b0
alla-allaos-fullstack/plans/task-p.4-discovery-report.md
phaichayon 0c0450b152 taks-p.4.3
2026-06-29 11:18:08 +07:00

26 KiB
Raw Blame History

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:

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:

This module already supports:

  • template metadata CRUD
  • template version CRUD
  • raw schemaJson editing
  • mapping CRUD
  • version activation
  • template detail inspection

Important internal UI areas:

1.2 Template APIs

Template/version/mapping APIs already exist and are reused by the CRM settings route group:

1.3 Document Template Foundation

The main document-template business logic is centralized in:

Important responsibilities already covered:

  • template resolution for runtime documents
  • version resolution
  • mapping resolution
  • mapping-to-input transformation
  • active/default template handling

Key functions:

1.4 Quotation Document Runtime

Quotation document runtime logic is handled in:

Key functions:

Topic-based dynamic layout is currently handled by:

Formatting helpers are in:

1.5 PDF Generation Foundation

PDF generation is centralized in:

Important capabilities already provided:

  • font loading
  • PDFMe plugin registration
  • preview PDF generation
  • download PDF generation
  • approved PDF artifact generation and persistence

Key functions:

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

2.3 UI Preview Graph

Client document preview uses:

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:

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:

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:

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:

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:

4.3 PDF Generator Runtime

The generator currently registers these PDFMe plugins:

  • text
  • image
  • line
  • table

Reference:

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:

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:

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:

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:

Quotation document data currently exposes item fields in:

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:

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:

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:

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

ADRs and Business Docs

Implementation Lineage

Reference in New Issue View Git Blame Copy Permalink