task-p.7

docs/implementation/task-p.7-implementation.md

@@ -0,0 +1,110 @@
+# Task P.7 Implementation Report
+
+## Scope
+This report documents implementation completed for
+[task-p.7.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/plans/task-p.7.md).
+
+Focus round:
+- add reusable Document Assembly foundation on top of existing PDF and storage runtime
+- integrate default quotation assembly flow
+- store assembled PDFs as separate artifacts
+- record implementation and verification outputs
+
+---
+
+## Review Inputs
+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/adr/0008-attachment-storage-strategy.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0008-attachment-storage-strategy.md)
+- [docs/adr/0009-approved-document-storage-lifecycle.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0009-approved-document-storage-lifecycle.md)
+- [docs/adr/0013-pdf-visual-parity-strategy.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/adr/0013-pdf-visual-parity-strategy.md)
+- [docs/implementation/task-p.6-implementation.md](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/docs/implementation/task-p.6-implementation.md)
+
+Foundations reused:
+- quotation PDF generation from [src/features/foundation/pdf-generator/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/pdf-generator/server/service.ts)
+- artifact lifecycle from [src/features/foundation/document-artifact/server/service.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-artifact/server/service.ts)
+- static append document storage from [src/features/foundation/document-library](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-library)
+
+---
+
+## What Changed
+### 1. New generic assembly foundation
+Added [src/features/foundation/document-assembly](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/features/foundation/document-assembly) with:
+- policy model for ordered `generated` and `document_library` sources
+- deterministic document-library resolution using brand/product-type fallback rules
+- PDF readability validation and page counting
+- server-side merge using `@pdfme/pdf-lib`
+- optional-source warnings and required-source business errors
+
+### 2. Separate assembled artifact lifecycle
+Assembled quotation PDFs now persist as a separate `assembled_pdf` artifact and do not replace:
+- preview/download quotation runtime output
+- approved quotation PDF artifact
+
+Stored metadata includes:
+- source quotation id and code
+- resolved assembly policy
+- resolved source artifacts
+- warnings
+- checksum, file size, page count
+- generation timestamp and actor
+
+### 3. Quotation integration routes
+Added quotation endpoints:
+- [src/app/api/crm/quotations/[id]/assembled-pdf/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/quotations/[id]/assembled-pdf/route.ts)
+- [src/app/api/crm/quotations/[id]/assembled-pdf/download/route.ts](/C:/Users/mtpphtaps/Documents/gitea/alla-allaos-fullstack/src/app/api/crm/quotations/[id]/assembled-pdf/download/route.ts)
+
+Behavior:
+- `POST` generates and persists assembled quotation PDF
+- `GET` previews stored assembled PDF inline
+- `GET /download` returns stored assembled PDF as attachment
+
+### 4. Default quotation policy
+Initial policy now resolves:
+1. generated quotation PDF
+2. active SLA document as required
+3. active warranty as optional
+4. datasheet as optional
+5. drawing as optional
+
+Brand and product type are normalized from quotation/runtime data so legacy codes such as `dockdoor` and `solarcell` align with document-library dimensions.
+
+---
+
+## Design Decisions
+### Keep approved PDF flow unchanged
+P.7 adds a new assembly layer instead of altering the existing approved-PDF runtime. This keeps prior acceptance from P.4-P.6 stable.
+
+### Prefer artifact metadata over new schema
+`crm_document_artifacts.metadata` already supports rich JSON payloads, so P.7 can store assembly provenance without a migration.
+
+### Deterministic fallback over manual selection
+Document-library resolution currently prefers:
+- exact brand over `generic`
+- exact product type over `all`
+- then stable code ordering
+
+This gives predictable output now while keeping room for future render configuration UI.
+
+---
+
+## Deliverables Completed
+- generic document assembly service and types
+- document-library resolution and PDF merge helpers
+- quotation assembled PDF generation and retrieval flow
+- new assembled preview/download APIs
+- focused assembly tests
+- implementation and verification reports
+
+---
+
+## Known Gaps
+- No UI trigger was added in this round; API/service foundation is ready first.
+- Datasheet and drawing remain optional and depend on library coverage being seeded or uploaded.
+- Assembly policy is code-based for now; no admin configuration UI yet.
+
+---
+
+## Outcome
+P.7 now gives the system a reusable server-side PDF assembly foundation and enables quotation PDFs to be merged with active document-library appendices into a separately stored customer-facing artifact.