367 lines
7.1 KiB
Markdown
367 lines
7.1 KiB
Markdown
# 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)
|