349 lines
5.4 KiB
Markdown
349 lines
5.4 KiB
Markdown
# 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)
|