alla-allaos-fullstack/plans/task-p.7.2.1.md

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:

Working Documents

Primary document:

Preview PDF

The UI should avoid exposing the technical term Draft PDF.

Instead:

Preview PDF

or

Working Copy

may be displayed.

Available actions:

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:

Official Documents

Primary document:

Approved PDF

Available actions:

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:

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:

Generate Package

Preview Package

Download Package

Send Package (future)

---

Relationship Between Document Types

Business flow becomes:

Quotation

↓

Working Documents

↓

Approval

↓

Official Documents

↓

Customer Package

↓

Email Customer

This hierarchy should be reflected visually.

---

Documents Tab Layout

Replace the previous layout with:

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:

Approved PDF

+

Active Document Library files

Customer Package must never use:

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