alla-allaos-fullstack/plans/task-h.md

Task H: PDF Generation + Approved Document Persistence

ALLA OS CRM vNext

คุณคือ Senior Full-stack Engineer

ให้ implement PDF generation สำหรับ Quotation โดยต่อยอดจาก Task G

ต้องอ่านก่อน

docs/implementation/task-a-template-audit.md
docs/implementation/technical-debt.md
docs/adr/0008-attachment-storage-strategy.md

src/features/foundation/document-template/**
src/features/crm/quotations/document/**
src/features/crm/quotations/**
src/features/foundation/approval/**
src/db/schema.ts

Goal

สร้าง production foundation สำหรับ:

Generate PDF from pdfme template
Preview/download PDF
Persist approved PDF snapshot
Attach generated PDF metadata to quotation

Scope H1: PDF Generation Service

สร้าง service:

src/features/foundation/pdf-generator/**

Functions:

generatePdfFromTemplate(input)
generateQuotationPdf(quotationId)
generateQuotationPreviewPdf(quotationId)
generateApprovedQuotationPdf(quotationId)

Rules:

• ใช้ templateVersion + schemaJson จาก Task G
• ใช้ buildQuotationDocumentData
• ใช้ mapDocumentDataToTemplateInput
• ห้าม generate จาก client
• validate organizationId ทุกครั้ง

Scope H2: PDF Download APIs

เพิ่ม routes:

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

Behavior:

pdf-preview = generate PDF ชั่วคราวจาก current data
pdf-download = download quotation PDF
approved-pdf = generate/store approved PDF

Rules:

• preview/download ต้อง check permission
• approved-pdf ต้องอนุญาตเฉพาะ approved quotation
• response ต้องเป็น application/pdf
• filename ใช้ quotation code

Scope H3: Approved Snapshot Persistence

เมื่อ quotation approved แล้ว หรือเมื่อกด generate approved PDF:

ให้ persist:

approvedSnapshot
approvedPdfUrl
approvedAt
templateVersionId

ถ้า schema ยังไม่มี field บางตัว ให้เพิ่มอย่างระวัง

Snapshot ต้องเก็บ:

quotation data
items
customers
topics
approval timeline
templateVersionId
templateInput
generatedAt
generatedBy

Scope H4: Attachment Metadata Integration

หลัง generate approved PDF ให้สร้าง attachment metadata:

fileName
originalFileName
filePath
fileSize
fileType = application/pdf
description = Approved quotation PDF
uploadedBy
uploadedAt

ถ้ายังไม่มี storage provider จริง:

• ใช้ local/generated path placeholder ได้
• ระบุ technical debt ชัดเจน

Scope H5: Quotation UI Integration

ใน quotation detail:

เพิ่ม actions:

Preview PDF
Download PDF
Generate Approved PDF
View Approved PDF

Rules:

• Preview PDF ใช้ได้กับ draft/pending/approved
• Generate Approved PDF ใช้ได้เฉพาะ approved
• ถ้ามี approvedPdfUrl แล้ว แสดง View Approved PDF
• แสดง template version ที่ใช้

Scope H6: Approval Integration

หลัง final approval สำเร็จ:

quotation.status = approved

ให้เตรียม hook หรือ optional call:

prepareApprovedQuotationSnapshot()

ถ้า generate PDF อัตโนมัติยังเสี่ยง ให้ทำ manual action ก่อน

Recommendation:

Task H: manual generate approved PDF
Future: auto-generate after final approval

Permissions

เพิ่มถ้ายังไม่มี:

crm.quotation.pdf.preview
crm.quotation.pdf.download
crm.quotation.pdf.generate_approved

Audit

Audit actions:

crm_quotation_pdf_preview optional
crm_quotation_pdf_download optional
crm_quotation_pdf_generate_approved required

Preview/download audit ไม่บังคับ Generate approved PDF ต้อง audit

ห้ามทำ

Template drag/drop designer
Notification
Dashboard KPI
Report
External object storage production
Email sending

Output

สรุป:

1. Files Added
2. Files Modified
3. PDF Generator Added
4. API Routes Added
5. UI Actions Added
6. Approved Snapshot Persistence
7. Attachment Metadata Integration
8. Permission Added
9. Audit Integration
10. Remaining Risks
11. Task I Readiness

Definition of Done

Task H ผ่านเมื่อ:

✔ generate PDF จาก pdfme template ได้

✔ preview/download PDF ได้

✔ approved quotation generate approved PDF ได้

✔ approved snapshot ถูก persist

✔ attachment metadata ถูกสร้าง

✔ UI มี PDF actions

✔ permission guard ครบ

✔ audit generate approved PDF

✔ ยังไม่ทำ template designer

✔ ยังไม่ทำ notification/report