111 lines
5.1 KiB
Markdown
111 lines
5.1 KiB
Markdown
# 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.
|