# 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)