249 lines
5.0 KiB
Markdown
249 lines
5.0 KiB
Markdown
# 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
|