alla-allaos-fullstack/docs/implementation/task-p.7.1.1-customer-package-ui-integration-2026-06-30.md

Task P.7.1.1 Implementation Report - 2026-06-30

Scope

• Add quotation-detail UI actions for customer package generation, preview, and download.
• Reuse existing assembled PDF foundation from Task P.7 instead of creating a new document flow.
• Expose package status and included-document metadata in quotation detail.

Review Summary

Reviewed before implementation:

• AGENTS.md
• docs/standards/project-foundations.md
• docs/standards/architecture-rules.md
• docs/standards/ui-ux-rules.md
• docs/standards/task-review-checklist.md
• docs/standards/task-catalog.md
• docs/business/crm-terminology.md
• docs/implementation/task-p.7-implementation.md
• docs/implementation/task-p.7.1-implementation.md
• plans/task-p.7.1.1.md

Foundations reused:

• assembled quotation package generation and retrieval from src/features/foundation/document-assembly/server/service.ts
• artifact lifecycle from src/features/foundation/document-artifact/server/service.ts
• quotation detail page and React Query integration from src/features/crm/quotations/components/quotation-detail.tsx

Implementation

• Added POST alias on assembled-pdf route so the UI can call POST /api/crm/quotations/[id]/assembled-pdf exactly as the task specified while preserving the existing generate handler implementation.
• Extended quotation detail payload in quotation types and quotation server service with customerPackage summary metadata sourced from the active assembled_pdf artifact.
• Added client helpers in quotation api service for:
  • generateQuotationCustomerPackage()
  • downloadQuotationCustomerPackage()
• Added React Query mutation support that invalidates quotation detail/header and document queries after package generation.
• Added customer package UI helpers and tests for:
  • package status mapping
  • role labels for included documents
  • business-readable error mapping for forbidden, not-generated, and missing-required-document cases
• Added quotation-detail UI in quotation-detail.tsx:
  • Customer Package card
  • generate / regenerate action with confirmation dialog
  • preview action
  • blob-based download action with toast-driven errors
  • generated-at / generated-by / page-count / checksum display
  • included-document list and warning display
• Reused existing quotation PDF permissions in detail page route:
  • preview customer package -> crmQuotationPdfPreview
  • generate/download customer package -> crmQuotationPdfDownload

Design Notes

• No separate package-status endpoint was added. The UI reads status from the quotation detail payload because the active assembled artifact already provides the required metadata.
• Download intentionally uses fetch plus Blob instead of a raw anchor download so API errors can be converted into business-readable toast messages.
• Warning rows are displayed as server-provided messages because they may represent optional append-document gaps, not only fatal errors.

Verification

• npm exec tsc --noEmit -> PASS
• node --import tsx --test src/features/foundation/document-sequence/config.test.ts src/features/crm/quotations/customer-package.test.ts -> PASS
• npm run build -> PASS
• npm run audit:pdf -> FAIL on existing baseline issues unrelated to this task:
  • template-version-integrity: ACTIVE_VERSION_SCHEMA_DRIFT
  • audit:pdf:integrity: overall FAIL
  • topicRuntime: FAIL

Outcome

Task P.7.1.1 now gives the quotation detail page a usable customer-package workflow on top of the existing assembly foundation, including generation, preview, download, package metadata visibility, and clearer failure handling without introducing email delivery behavior.