alla-allaos-fullstack/plans/task-p.7.1.1.md

Task P.7.1.1 - Customer Package UI Integration

Objective

Add user-facing UI controls for generating, viewing, and downloading the assembled customer document package from the quotation detail page.

This task connects the existing Document Assembly API to the CRM UI.

It does not introduce SMTP, email sending, or notification automation.

---

Background

Completed:

• P.7 Document Assembly Framework
• P.7.1 Notification Foundation

Current backend APIs exist:

POST /api/crm/quotations/[id]/assembled-pdf
GET  /api/crm/quotations/[id]/assembled-pdf/download

However, users currently have no UI button to generate the assembled PDF before download.

This causes:

Assembled quotation PDF has not been generated yet.

when the download endpoint is called before package generation.

---

Scope

Included:

• Quotation detail UI integration
• Generate Customer Package action
• Download Customer Package action
• Package status display
• Included document list display
• Error handling for missing SLA or required documents
• Loading and success states
• Query/mutation integration
• Permission guard

Excluded:

• SMTP / Email provider configuration
• Sending customer email
• Notification event automation
• Render configuration
• User-selectable append documents
• Assembly policy editor

---

UI Placement

Add a section in quotation detail page.

Suggested label:

Customer Package

Suggested actions:

Generate Customer Package
Download Customer Package
Regenerate Package

Suggested display:

Status: Not Generated / Generated / Failed
Generated At
Generated By
Included Documents:
- Quotation
- SLA
- Warranty
- Datasheet
Page Count
File Size
Checksum

---

API Usage

Generate

Call:

POST /api/crm/quotations/[id]/assembled-pdf

Expected behavior:

• generate quotation PDF if needed
• resolve active SLA / append documents
• merge PDFs
• store final artifact
• return package metadata

---

Download

Call:

GET /api/crm/quotations/[id]/assembled-pdf/download

If package is not generated:

• show user-friendly message
• do not show raw API error only
• suggest generating package first

---

Client Service

Add client service methods.

Example:

generateQuotationCustomerPackage(quotationId: string)
downloadQuotationCustomerPackage(quotationId: string)
getQuotationCustomerPackageStatus(quotationId: string)

If a status endpoint does not exist yet, either:

• add one, or
• return status from existing quotation/detail payload if already available

---

React Query

Add mutation/query support:

• generate customer package mutation
• package status query
• invalidate quotation detail after successful generation
• invalidate document/artifact query if applicable

---

Permissions

Use existing or add permission:

crmQuotationGenerateCustomerPackage
crmQuotationDownloadCustomerPackage

If permission model already has quotation PDF permissions, reuse only if semantically correct.

---

Error Handling

Handle:

Not Generated

Show:

Customer package has not been generated yet. Please generate it first.

Missing Required Document

Example:

Cannot generate package because required SLA document is missing.

Assembly Failure

Show:

Customer package generation failed. Please check document library configuration.

Permission Denied

Show:

You do not have permission to generate or download customer package.

---

UX Rules

• Disable download button until package exists.
• Show loading state while generating.
• Allow regenerate after package exists.
• Confirm before regenerate if it overwrites or creates a new artifact version.
• Do not automatically email after generation.
• Do not automatically activate any template or library document.

---

Verification Scenarios

Test manually:

Scenario 1 - No Package

Open quotation detail.

Expected:

• status = Not Generated
• Download disabled
• Generate enabled

Scenario 2 - Generate Package

Click Generate Customer Package.

Expected:

• package generated
• included documents visible
• SLA listed if policy requires it
• Download enabled

Scenario 3 - Download Package

Click Download.

Expected:

• PDF downloads
• PDF includes quotation + SLA

Scenario 4 - Missing Required SLA

Temporarily remove/inactivate SLA.

Click Generate.

Expected:

• business-readable error
• no broken artifact

Scenario 5 - Regenerate

Click Regenerate.

Expected:

• new artifact created or existing artifact updated according to backend behavior
• UI status refreshes

---

Testing Requirements

Run:

npm run typecheck
npm run build
npm run audit:pdf

Add tests where practical for:

• mutation service
• UI state helper
• permission visibility
• error message mapping

---

Acceptance Criteria

• Quotation detail page has Customer Package section.
• User can generate assembled package from UI.
• User can download assembled package after generation.
• UI clearly shows package status.
• UI shows included documents such as SLA.
• Missing required SLA displays clear error.
• Download before generation is prevented in UI.
• Existing approved PDF actions remain unchanged.
• No email is sent in this task.
• Build and typecheck pass.

---

Out of Scope

P.7.2

• SMTP configuration
• Email provider settings
• Real email delivery verification

P.7.3

• Approval notification automation
• Request approval email
• Approve/reject email

P.7.4

• Send Customer Package Email
• Customer recipient selection
• Email history from quotation detail

---

Final Success Condition

Task P.7.1.1 is complete when users can generate and download the assembled Customer Package directly from quotation detail, confirm that SLA is included, and proceed to P.7.2 email configuration with a usable package artifact already available.

---

Implementation Status - 2026-06-30

Status: Completed

Implemented:

• Added Customer Package section on quotation detail page with generate, regenerate, preview, and download actions.
• Reused assembled quotation package APIs and existing quotation PDF permissions instead of adding a separate permission model.
• Extended quotation detail payload with active assembled artifact metadata so UI can show package status, generator, checksum, file size, page count, included documents, and warnings.
• Added customer-package error/status helpers and focused tests.
• Added POST /api/crm/quotations/[id]/assembled-pdf support by exporting the existing generate handler from the assembled-pdf route.

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 -> baseline FAIL unrelated to this task:
  • ACTIVE_VERSION_SCHEMA_DRIFT
  • topicRuntime / integrity summary failure

Implementation report:

• task-p.7.1.1-customer-package-ui-integration-2026-06-30.md