alla-allaos-fullstack/docs/implementation/task-p.7-implementation.md

Task P.7 Implementation Report

Scope

This report documents implementation completed for 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
• docs/standards/project-foundations.md
• docs/adr/0008-attachment-storage-strategy.md
• docs/adr/0009-approved-document-storage-lifecycle.md
• docs/adr/0013-pdf-visual-parity-strategy.md
• docs/implementation/task-p.6-implementation.md

Foundations reused:

• quotation PDF generation from src/features/foundation/pdf-generator/server/service.ts
• artifact lifecycle from src/features/foundation/document-artifact/server/service.ts
• static append document storage from src/features/foundation/document-library

---

What Changed

1. New generic assembly foundation

Added 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
• 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.