# Task H: PDF Generation + Approved Document Persistence

## ALLA OS CRM vNext

คุณคือ Senior Full-stack Engineer

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

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

```txt
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 สำหรับ:

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

## Scope H1: PDF Generation Service

สร้าง service:

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

Functions:

```ts
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:

```txt
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:

```txt
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:

```txt
approvedSnapshot
approvedPdfUrl
approvedAt
templateVersionId
```

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

Snapshot ต้องเก็บ:

```txt
quotation data
items
customers
topics
approval timeline
templateVersionId
templateInput
generatedAt
generatedBy
```

## Scope H4: Attachment Metadata Integration

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

```txt
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:

```txt
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 สำเร็จ:

```txt
quotation.status = approved
```

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

```ts
prepareApprovedQuotationSnapshot()
```

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

Recommendation:

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

## Permissions

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

```txt
crm.quotation.pdf.preview
crm.quotation.pdf.download
crm.quotation.pdf.generate_approved
```

## Audit

Audit actions:

```txt
crm_quotation_pdf_preview optional
crm_quotation_pdf_download optional
crm_quotation_pdf_generate_approved required
```

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

## ห้ามทำ

```txt
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