alla-allaos-fullstack/docs/implementation/task-g-document-preview-foundation.md

Task G - Quotation Document Preview Foundation

Files Added

• src/features/foundation/document-template/types.ts
• src/features/foundation/document-template/service.ts
• src/features/foundation/document-template/queries.ts
• src/features/foundation/document-template/mutations.ts
• src/features/foundation/document-template/server/service.ts
• src/features/foundation/document-template/components/template-settings.tsx
• src/features/crm/quotations/document/types.ts
• src/features/crm/quotations/document/service.ts
• src/features/crm/quotations/document/queries.ts
• src/features/crm/quotations/document/server/service.ts
• src/features/crm/quotations/components/quotation-document-preview.tsx
• src/app/api/crm/quotations/[id]/document-data/route.ts
• src/app/api/crm/quotations/[id]/document-preview/route.ts
• src/app/api/crm/document-templates/route.ts
• src/app/api/crm/document-templates/[id]/route.ts
• src/app/api/crm/document-templates/[id]/versions/route.ts
• drizzle/0006_worried_mordo.sql

Files Modified

• src/db/schema.ts
• src/db/seeds/foundation.seed.ts
• src/lib/auth/rbac.ts
• src/config/nav-config.ts
• src/app/dashboard/crm/settings/templates/page.tsx
• src/app/dashboard/crm/quotations/[id]/page.tsx
• src/features/crm/quotations/components/quotation-detail.tsx
• src/features/crm/quotations/api/mutations.ts
• src/features/foundation/approval/mutations.ts
• docs/implementation/technical-debt.md

Schema Added

• crm_document_templates
• crm_document_template_versions
• crm_document_template_mappings
• crm_document_template_table_columns

API Routes Added

• GET /api/crm/quotations/[id]/document-data
• GET /api/crm/quotations/[id]/document-preview
• GET/POST /api/crm/document-templates
• GET/PATCH/DELETE /api/crm/document-templates/[id]
• GET/POST /api/crm/document-templates/[id]/versions

Preview UI Added

• Replaced quotation Document Preview placeholder with a production preview tab backed by real quotation data, template resolution, and mapped preview payloads.
• Added watermark/status behavior for non-approved quotations through normalized watermarkStatus.
• Preview now shows:
  • quotation header
  • customer block
  • project info
  • items table
  • price summary
  • scope / exclusion / payment topics
  • approval block
  • signature placeholders

Template Settings UI Added

• Replaced /dashboard/crm/settings/templates placeholder with a production listing page.
• Current UI is intentionally lightweight and read-focused:
  • template name and description
  • default badge
  • active/inactive badge
  • file type
  • latest version
  • version count
  • mapping count

Template Seed Added

• Foundation seed now upserts a default quotation pdfme template per organization.
• Seed picks template JSON by organization name:
  • ALLA_template_pdfme_fainal3.json
  • ONVALLA_template_pdfme_fainal3.json
• If the organization name does not match either branch, the seed falls back to a minimal schema payload.
• Seed also creates baseline placeholder mappings and a table mapping for quotation line items.

Mapping Resolver Added

• resolveTemplateForDocument()
• resolveTemplateMappings()
• mapDocumentDataToTemplateInput()

Behavior:

• resolves by documentType + productType + fileType
• falls back to default product type when no specific product template exists
• maps dot-path source fields into scalar, multiline, or table-ready template input

Approved Snapshot Prep Added

• prepareApprovedQuotationSnapshot(quotationId, organizationId)

Output contains:

• quotationId
• approvedAt
• documentData
• templateVersionId
• templateInput

Remaining Risks

• Mapping CRUD UI is not implemented yet, so template mappings remain seed-driven and read-only.
• pdfme preview is not canvas-accurate rendering; current preview is an application-native document view using the normalized document snapshot.
• Template resolution currently uses productType: default for quotation preview. Product-specific template selection can be added later once the business rule is finalized.
• No binary PDF generation, storage, or approved PDF URL persistence yet.

Task H Readiness

Task G leaves the repo ready for:

• actual pdfme generation service integration
• approved PDF snapshot persistence
• template version publishing workflow
• mapping editor or admin maintenance UI
• product-specific template resolution rules