# Amendment to Task P.7.1.2 – Working Documents & Official Documents UX

## Design Revision

Following the UX review, the document experience will be refined to better reflect the actual CRM business process.

The terminology **Draft PDF** is too technical for end users and should not be the primary wording exposed in the UI.

The new UX separates documents into three business levels.

---

# Level 1 — Working Documents

Purpose:

Internal working documents used during quotation preparation.

Source:

Live quotation data.

Characteristics:

* Generated from current database values.
* Changes whenever quotation data changes.
* Used internally only.
* Not legally or commercially binding.
* Not intended for customer delivery.
* Not part of audit history.

UI terminology:

```text
Working Documents
```

Primary document:

```text
Preview PDF
```

The UI should avoid exposing the technical term **Draft PDF**.

Instead:

```text
Preview PDF
```

or

```text
Working Copy
```

may be displayed.

Available actions:

```text
Generate
Preview
```

No Download button is required unless business rules explicitly allow downloading internal working copies.

---

# Level 2 — Official Documents

Purpose:

Business-approved immutable documents.

Source:

Approved Snapshot.

Characteristics:

* Generated only after approval.
* Immutable.
* Stored as document artifact.
* Used for audit.
* Used for revision history.
* Used as official company record.

UI terminology:

```text
Official Documents
```

Primary document:

```text
Approved PDF
```

Available actions:

```text
Preview
Download
```

No Generate button should appear here because approval already created the official document.

---

# Level 3 — Customer Package

Purpose:

Deliverable package sent to customers.

Source:

Approved PDF

plus

Document Library appendices.

Example:

```text
Approved PDF

+

SLA

+

Warranty

+

Datasheet

+

Drawing
```

Characteristics:

* Generated after document assembly.
* Built from official documents.
* Represents exactly what customers receive.
* May be regenerated if append documents change.

Available actions:

```text
Generate Package

Preview Package

Download Package

Send Package (future)
```

---

# Relationship Between Document Types

Business flow becomes:

```text
Quotation

↓

Working Documents

↓

Approval

↓

Official Documents

↓

Customer Package

↓

Email Customer
```

This hierarchy should be reflected visually.

---

# Documents Tab Layout

Replace the previous layout with:

```text
Documents

────────────────────────

Working Documents

Preview PDF

[Generate]

[Preview]

────────────────────────

Official Documents

Approved PDF

[Preview]

[Download]

────────────────────────

Customer Package

Status

Included Documents

Warnings

[Generate Package]

[Preview Package]

[Download Package]

[Send Package]
```

The **Send Package** action remains disabled until P.7.2.

---

# Customer Package Tab

The dedicated Customer Package tab remains.

It focuses on operational details:

* Package status
* Included documents
* Assembly warnings
* Generated time
* Generated by
* Page count
* Checksum
* Generate / Regenerate
* Preview
* Download

This tab is not responsible for previewing individual PDFs.

---

# UX Rules

Working Documents

* Can always regenerate.
* Uses live quotation data.
* Intended for internal review.

Official Documents

* Never regenerate from this screen.
* Always read-only.
* Represents approved business record.

Customer Package

* Always assembled from Official Documents.
* Must never assemble from Working Documents.
* If no Approved PDF exists, package generation must fail with a business-readable message.

---

# Business Rules

Customer Package must always use:

```text
Approved PDF

+

Active Document Library files
```

Customer Package must never use:

```text
Working Documents

Preview PDF

Draft runtime output
```

This guarantees that every package delivered to a customer is assembled from approved, auditable content.

---

# Acceptance Criteria (Additional)

* "Draft PDF" is no longer the primary UI terminology.
* Documents are clearly separated into Working Documents, Official Documents, and Customer Package.
* Customer Package assembly is based exclusively on Approved PDF.
* UI hierarchy reflects the CRM document lifecycle.
* The new terminology is reusable across future modules such as Purchase Order, Service Report, Inspection Report, and Work Order.

---

## Implementation Status - 2026-07-01

Status: Completed

Implemented:
- Added `Documents` and `Customer Package` tabs on quotation detail.
- Split document UX into `Working Documents`, `Official Documents`, and `Customer Package`.
- Added explicit `Official Documents` preview/download actions and kept `Customer Package` operational detail in a dedicated tab.
- Updated customer package assembly so the main source is the approved PDF, not the working quotation render.
- Updated customer package error mapping so missing approved PDF shows business-readable guidance.

Verification:
- `npm exec tsc --noEmit` -> PASS
- `node --import tsx --test src/features/crm/quotations/customer-package.test.ts` -> PASS
- `npm run build` -> PASS

Implementation report:
- [task-p.7.2.1-working-official-documents-ux-2026-07-01.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-p.7.2.1-working-official-documents-ux-2026-07-01.md)
