alla-allaos-fullstack/docs/implementation/task-p.7.2.1-working-official-documents-ux-2026-07-01.md

Task P.7.2.1 Implementation Report - 2026-07-01

Scope

• Apply the UX amendment that separates quotation documents into Working Documents, Official Documents, and Customer Package.
• Remove screen-level emphasis on technical wording such as draft-style PDF terminology.
• Enforce the business rule that customer package assembly must use the approved PDF, not a working quotation render.

Review Summary

Reviewed before implementation:

• AGENTS.md
• docs/standards/project-foundations.md
• docs/standards/architecture-rules.md
• docs/standards/ui-ux-rules.md
• docs/standards/task-review-checklist.md
• docs/business/crm-terminology.md
• plans/task-p.7.2.1.md
• docs/implementation/task-p.7-implementation.md
• docs/implementation/task-p.7.1.1-customer-package-ui-integration-2026-06-30.md

Skills used this round:

• kiranism-shadcn-dashboard for quotation detail page and feature-module conventions
• shadcn for card/tabs/button/dialog composition checks
• web-design-guidelines for post-change UI review against the Vercel guideline source

Foundations reused:

• quotation detail page shell in quotation-detail.tsx
• quotation preview foundation in quotation-document-preview.tsx
• approved PDF storage/retrieval in pdf-generator service
• document assembly foundation in document-assembly service

Implementation

• Refactored quotation detail UI in quotation-detail.tsx to add:
  • Documents tab
  • Customer Package tab
  • Working Documents section with Generate and Preview actions
  • Official Documents section with Preview and Download actions
  • Customer Package section with Generate Package, Preview Package, Download Package, and disabled Send Package
• Removed screen-level actions that promoted the old flat document UX, including the previous top-of-page customer package card and the old standalone Document Preview tab label.
• Kept the detailed package metadata view in a dedicated Customer Package tab for status, warnings, included documents, checksum, and generation metadata.
• Added approved-PDF download helper in quotation api service so the UI can provide an explicit Download action for official documents.
• Updated customer-package helper and tests to:
  • relabel main source as Approved PDF
  • map missing-approved-PDF failures to business-readable copy
  • keep permission and missing-document messages readable
• Updated document assembly service so the main package source now comes from getStoredApprovedQuotationPdf() instead of live working-document generation.

Business Rule Change

• Customer package assembly now uses:
  • approved PDF artifact
  • active document library appendices
• Customer package assembly no longer uses:
  • live working quotation PDF generation
  • preview/runtime-only working output

This aligns the package with the task requirement that customer-deliverable content must be assembled from approved, auditable documents only.

Verification

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

Web Review

Reviewed the updated quotation detail document surface against the fetched Vercel Web Interface Guidelines source.

Result:

• No blocking accessibility or interaction regressions found in the new Documents and Customer Package sections.
• Buttons remain text-labeled, destructive actions still use confirmation, and preview/download actions use links or explicit button handlers appropriately.

Known Follow-up

• I did not add URL-deep-link sync for the new tabs in this round; the page still follows the repo's existing local tab-state pattern.

Outcome

Task P.7.2.1 now presents quotation documents in the intended business hierarchy and makes customer package generation semantically depend on the approved document lifecycle, not on working previews.