# 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.