task-h.1 complate
This commit is contained in:
phaichayon
302
plans/task-h.1.md
Normal file
302
plans/task-h.1.md
Normal file
@@ -0,0 +1,302 @@
|
||||
# Task H.1: PDF Generation Stabilization
|
||||
|
||||
## Goal
|
||||
|
||||
Stabilize Task H PDF generation before starting Task I.
|
||||
|
||||
Task H already added:
|
||||
|
||||
* pdfme server-side generation
|
||||
* preview/download PDF APIs
|
||||
* approved PDF generation
|
||||
* approved snapshot persistence
|
||||
* approved PDF attachment metadata
|
||||
* quotation detail PDF actions
|
||||
|
||||
Task H.1 focuses on validation, hardening, and documentation.
|
||||
|
||||
---
|
||||
|
||||
## Must Read
|
||||
|
||||
```txt
|
||||
docs/implementation/technical-debt.md
|
||||
docs/adr/0008-attachment-storage-strategy.md
|
||||
|
||||
src/features/foundation/pdf-generator/**
|
||||
src/features/foundation/document-template/**
|
||||
src/features/crm/quotations/document/**
|
||||
src/features/crm/quotations/**
|
||||
src/features/foundation/approval/**
|
||||
src/app/api/crm/quotations/[id]/pdf-preview/route.ts
|
||||
src/app/api/crm/quotations/[id]/pdf-download/route.ts
|
||||
src/app/api/crm/quotations/[id]/approved-pdf/route.ts
|
||||
src/db/schema.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scope 1: Smoke Test With Real Quotation
|
||||
|
||||
Create or identify one real quotation record in dev database.
|
||||
|
||||
The record must include:
|
||||
|
||||
```txt
|
||||
customer
|
||||
contact
|
||||
enquiry optional
|
||||
at least one item
|
||||
quotation customer role
|
||||
scope topic
|
||||
exclusion topic
|
||||
payment topic
|
||||
approved status or approval flow completed
|
||||
```
|
||||
|
||||
Then verify:
|
||||
|
||||
```txt
|
||||
Preview PDF
|
||||
Download PDF
|
||||
Generate Approved PDF
|
||||
View Approved PDF
|
||||
```
|
||||
|
||||
If no real record exists, create a minimal seed/dev fixture.
|
||||
|
||||
Rules:
|
||||
|
||||
* dev fixture must be organization-scoped
|
||||
* do not hardcode organizationId
|
||||
* do not pollute production seed
|
||||
* place fixture under dev-only seed or clearly named script
|
||||
|
||||
---
|
||||
|
||||
## Scope 2: PDF Output Validation
|
||||
|
||||
Check generated PDF for:
|
||||
|
||||
```txt
|
||||
file opens correctly
|
||||
page count is reasonable
|
||||
customer block appears
|
||||
quotation code appears
|
||||
item table appears
|
||||
total amount appears
|
||||
scope/exclusion/payment appears
|
||||
approval block appears
|
||||
signature placeholder appears
|
||||
```
|
||||
|
||||
If layout breaks:
|
||||
|
||||
* adjust mapping normalization
|
||||
* adjust template input preparation
|
||||
* do not rewrite template designer
|
||||
* do not hardcode quotation-specific hacks into generic pdf generator
|
||||
|
||||
---
|
||||
|
||||
## Scope 3: Approved PDF API Validation
|
||||
|
||||
Validate:
|
||||
|
||||
```txt
|
||||
GET /api/crm/quotations/[id]/pdf-preview
|
||||
GET /api/crm/quotations/[id]/pdf-download
|
||||
POST /api/crm/quotations/[id]/approved-pdf
|
||||
GET /api/crm/quotations/[id]/approved-pdf
|
||||
```
|
||||
|
||||
Expected behavior:
|
||||
|
||||
* preview returns inline PDF
|
||||
* download returns attachment PDF
|
||||
* approved-pdf POST only works for approved quotation
|
||||
* approved-pdf GET returns stored file if available
|
||||
* non-approved quotation cannot generate approved PDF
|
||||
|
||||
---
|
||||
|
||||
## Scope 4: Persistence Validation
|
||||
|
||||
After approved PDF generation verify:
|
||||
|
||||
```txt
|
||||
quotation.approvedPdfUrl populated
|
||||
quotation.approvedSnapshot populated
|
||||
quotation.approvedTemplateVersionId populated
|
||||
quotation attachment metadata created or updated
|
||||
audit log generated
|
||||
file exists in public/generated/quotations/<organizationId>/
|
||||
```
|
||||
|
||||
If any part is missing, fix only the persistence pipeline.
|
||||
|
||||
---
|
||||
|
||||
## Scope 5: Permission Validation
|
||||
|
||||
Verify permissions:
|
||||
|
||||
```txt
|
||||
crm.quotation.pdf.preview
|
||||
crm.quotation.pdf.download
|
||||
crm.quotation.pdf.generate_approved
|
||||
```
|
||||
|
||||
Check behavior for:
|
||||
|
||||
```txt
|
||||
super_admin
|
||||
admin
|
||||
regular user with permission
|
||||
regular user without permission
|
||||
```
|
||||
|
||||
Do not rewrite RBAC model.
|
||||
|
||||
---
|
||||
|
||||
## Scope 6: Error Handling
|
||||
|
||||
Improve user-safe/server-safe errors for:
|
||||
|
||||
```txt
|
||||
template not found
|
||||
template version not found
|
||||
mapping missing
|
||||
quotation not approved
|
||||
generated file missing
|
||||
pdfme generation error
|
||||
local storage write error
|
||||
permission denied
|
||||
```
|
||||
|
||||
Rules:
|
||||
|
||||
* API must return meaningful status codes
|
||||
* UI should show readable toast/message
|
||||
* do not expose stack trace to client
|
||||
|
||||
---
|
||||
|
||||
## Scope 7: Documentation / ADR
|
||||
|
||||
Update:
|
||||
|
||||
```txt
|
||||
docs/implementation/technical-debt.md
|
||||
```
|
||||
|
||||
Confirm or add:
|
||||
|
||||
```txt
|
||||
pdfme font fallback workaround
|
||||
local filesystem storage limitation
|
||||
missing object storage abstraction
|
||||
approved PDF lifecycle not immutable yet
|
||||
no full E2E test in CI yet
|
||||
```
|
||||
|
||||
Create ADR if not exists:
|
||||
|
||||
```txt
|
||||
docs/adr/0009-approved-document-storage-lifecycle.md
|
||||
```
|
||||
|
||||
Include:
|
||||
|
||||
```txt
|
||||
Current:
|
||||
local public/generated storage
|
||||
|
||||
Decision:
|
||||
acceptable for development/MVP only
|
||||
|
||||
Future:
|
||||
object storage abstraction
|
||||
signed URL
|
||||
immutable approved artifacts
|
||||
retention policy
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Scope 8: Optional Small Fix
|
||||
|
||||
If approval finalization already has a clean hook point, add a non-blocking TODO or optional manual trigger note for:
|
||||
|
||||
```txt
|
||||
auto-generate approved PDF after final approval
|
||||
```
|
||||
|
||||
Do not force automatic generation in Task H.1 if it risks breaking approval flow.
|
||||
|
||||
---
|
||||
|
||||
## ห้ามทำ
|
||||
|
||||
```txt
|
||||
object storage production
|
||||
signed URL service
|
||||
template designer
|
||||
mapping editor
|
||||
email notification
|
||||
report
|
||||
dashboard KPI
|
||||
large refactor
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Output
|
||||
|
||||
After completion, summarize:
|
||||
|
||||
1. Files Added
|
||||
2. Files Modified
|
||||
3. Smoke Test Record Used
|
||||
4. PDF APIs Verified
|
||||
5. Persistence Verified
|
||||
6. Permission Verified
|
||||
7. Error Handling Improved
|
||||
8. ADR / Technical Debt Updated
|
||||
9. Remaining Risks
|
||||
10. Task I Readiness
|
||||
|
||||
---
|
||||
|
||||
## Definition of Done
|
||||
|
||||
Task H.1 passes when:
|
||||
|
||||
✔ PDF preview works with a real quotation
|
||||
|
||||
✔ PDF download works with a real quotation
|
||||
|
||||
✔ Approved PDF generation works for approved quotation
|
||||
|
||||
✔ Approved PDF GET returns stored PDF
|
||||
|
||||
✔ Non-approved quotation cannot generate approved PDF
|
||||
|
||||
✔ approvedSnapshot is saved
|
||||
|
||||
✔ approvedPdfUrl is saved
|
||||
|
||||
✔ approvedTemplateVersionId is saved
|
||||
|
||||
✔ attachment metadata is created/updated
|
||||
|
||||
✔ audit log exists for approved PDF generation
|
||||
|
||||
✔ permissions are enforced
|
||||
|
||||
✔ errors are user-safe
|
||||
|
||||
✔ storage lifecycle ADR exists
|
||||
|
||||
✔ ready for Task I
|
||||
Reference in New Issue
Block a user