commit task-p.7.2.1

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

@@ -0,0 +1,73 @@
+# 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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/AGENTS.md)
+- [docs/standards/project-foundations.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/project-foundations.md)
+- [docs/standards/architecture-rules.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/architecture-rules.md)
+- [docs/standards/ui-ux-rules.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/ui-ux-rules.md)
+- [docs/standards/task-review-checklist.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/standards/task-review-checklist.md)
+- [docs/business/crm-terminology.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/business/crm-terminology.md)
+- [plans/task-p.7.2.1.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/plans/task-p.7.2.1.md)
+- [docs/implementation/task-p.7-implementation.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-p.7-implementation.md)
+- [docs/implementation/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)
+
+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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/components/quotation-detail.tsx)
+- quotation preview foundation in [quotation-document-preview.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/components/quotation-document-preview.tsx)
+- approved PDF storage/retrieval in [pdf-generator service](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts)
+- document assembly foundation in [document-assembly service](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-assembly/server/service.ts)
+
+## Implementation
+- Refactored quotation detail UI in [quotation-detail.tsx](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/components/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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/api/service.ts) so the UI can provide an explicit `Download` action for official documents.
+- Updated [customer-package helper](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/customer-package.ts) and [tests](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/crm/quotations/customer-package.test.ts) 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](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-assembly/server/service.ts) 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.