task-p.7.1.1

plans/task-p.7.1.1.md

@@ -0,0 +1,366 @@
+# 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:
+
+```text
+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:
+
+```text
+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:
+
+```text
+Customer Package
+```
+
+Suggested actions:
+
+```text
+Generate Customer Package
+Download Customer Package
+Regenerate Package
+```
+
+Suggested display:
+
+```text
+Status: Not Generated / Generated / Failed
+Generated At
+Generated By
+Included Documents:
+- Quotation
+- SLA
+- Warranty
+- Datasheet
+Page Count
+File Size
+Checksum
+```
+
+---
+
+# API Usage
+
+## Generate
+
+Call:
+
+```http
+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:
+
+```http
+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:
+
+```ts
+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:
+
+```text
+crmQuotationGenerateCustomerPackage
+crmQuotationDownloadCustomerPackage
+```
+
+If permission model already has quotation PDF permissions, reuse only if semantically correct.
+
+---
+
+# Error Handling
+
+Handle:
+
+## Not Generated
+
+Show:
+
+```text
+Customer package has not been generated yet. Please generate it first.
+```
+
+## Missing Required Document
+
+Example:
+
+```text
+Cannot generate package because required SLA document is missing.
+```
+
+## Assembly Failure
+
+Show:
+
+```text
+Customer package generation failed. Please check document library configuration.
+```
+
+## Permission Denied
+
+Show:
+
+```text
+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:
+
+```bash
+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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-p.7.1.1-customer-package-ui-integration-2026-06-30.md)