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