task-h.4

plans/task-h.3.md

@@ -0,0 +1,530 @@
+# Task H.3: Approval Signature Strategy
+
+## Goal
+
+ทำให้ PDF ใบเสนอราคาสามารถแสดงข้อมูลผู้จัดทำ ผู้อนุมัติ และผู้มีอำนาจอนุมัติได้อย่างถูกต้อง
+
+รองรับทั้ง:
+
+```txt
+Preview PDF
+Approved PDF
+Approved Snapshot
+Document Artifact
+```
+
+โดยข้อมูลลายเซ็นต้องมาจาก Approval Workflow จริง ไม่ใช่ค่าคงที่ใน Template
+
+---
+
+# Background
+
+Task H.2 เพิ่ม:
+
+```txt
+Dynamic Topic Engine
+PDFME Runtime Mapping
+Template Mapping Resolver
+```
+
+Task H.1 เพิ่ม:
+
+```txt
+Approved Snapshot
+Artifact Storage
+```
+
+Task H.3 จะเติมส่วนที่ยังขาด:
+
+```txt
+Prepared By
+Approved By
+Authorized By
+Position
+Approval Timeline Resolution
+```
+
+---
+
+# Current Problem
+
+Template ปัจจุบันมี placeholder เช่น:
+
+```txt
+app1
+app1_position
+
+app2
+app2_position
+
+app3
+app3_position
+```
+
+แต่ยังไม่มี strategy กลางสำหรับดึงข้อมูลจริงจาก:
+
+```txt
+quotation
+approval workflow
+approval actions
+membership
+business role
+```
+
+---
+
+# Scope H3.1 Signature Data Contract
+
+Create:
+
+```txt
+src/features/crm/quotations/document/signature.types.ts
+```
+
+Define:
+
+```ts
+type SignatureBlock = {
+  preparedBy: {
+    name: string;
+    position: string;
+  };
+
+  approvedBy: {
+    name: string;
+    position: string;
+  };
+
+  authorizedBy: {
+    name: string;
+    position: string;
+  };
+};
+```
+
+---
+
+# Scope H3.2 Position Resolution Strategy
+
+Create:
+
+```txt
+src/features/crm/quotations/document/signature-position.ts
+```
+
+Resolve position from:
+
+```txt
+membership.businessRole
+```
+
+Recommended mapping:
+
+```txt
+sales
+→ Sales Engineer
+
+sales_support
+→ Sales Support
+
+sales_manager
+→ Sales Manager
+
+department_manager
+→ Department Manager
+
+top_manager
+→ General Manager
+```
+
+Rules:
+
+Do NOT hardcode display strings inside PDF generator.
+
+Source from:
+
+```txt
+crm_job_title
+```
+
+master option when available.
+
+Fallback:
+
+```txt
+businessRole label
+```
+
+---
+
+# Scope H3.3 Prepared By Resolution
+
+Prepared By source:
+
+Priority:
+
+```txt
+quotation.salesmanId
+```
+
+Fallback:
+
+```txt
+quotation.createdBy
+```
+
+Output:
+
+```txt
+preparedBy.name
+preparedBy.position
+```
+
+Rules:
+
+Must resolve display name.
+
+Never use raw user id.
+
+---
+
+# Scope H3.4 Approved By Resolution
+
+Resolve from approval workflow history.
+
+Source:
+
+```txt
+crm_approval_actions
+```
+
+Rules:
+
+Find latest approved action from:
+
+```txt
+sales_manager
+```
+
+or
+
+```txt
+department_manager
+```
+
+depending on workflow configuration.
+
+Output:
+
+```txt
+approvedBy.name
+approvedBy.position
+```
+
+---
+
+# Scope H3.5 Authorized By Resolution
+
+Resolve from final approval step.
+
+Source:
+
+```txt
+crm_approval_actions
+```
+
+Rules:
+
+Find final approved action.
+
+Expected role:
+
+```txt
+top_manager
+```
+
+Output:
+
+```txt
+authorizedBy.name
+authorizedBy.position
+```
+
+---
+
+# Scope H3.6 Signature Resolver
+
+Create:
+
+```txt
+src/features/crm/quotations/document/server/signature-resolver.ts
+```
+
+Expose:
+
+```ts
+resolveQuotationSignatures(
+  quotationId,
+  organizationId
+)
+```
+
+Returns:
+
+```ts
+SignatureBlock
+```
+
+Responsibilities:
+
+```txt
+load quotation
+load approval history
+resolve users
+resolve positions
+build final signature object
+```
+
+---
+
+# Scope H3.7 PDF Mapping Integration
+
+Update:
+
+```txt
+src/features/crm/quotations/document/server/service.ts
+```
+
+Inject:
+
+```txt
+signatures.preparedBy.name
+signatures.preparedBy.position
+
+signatures.approvedBy.name
+signatures.approvedBy.position
+
+signatures.authorizedBy.name
+signatures.authorizedBy.position
+```
+
+Into:
+
+```txt
+documentData
+templateInput
+approvedSnapshot
+```
+
+---
+
+# Scope H3.8 PDFME Placeholder Mapping
+
+Update seed mappings.
+
+Expected:
+
+```txt
+app1
+→ signatures.preparedBy.name
+
+app1_position
+→ signatures.preparedBy.position
+
+app2
+→ signatures.approvedBy.name
+
+app2_position
+→ signatures.approvedBy.position
+
+app3
+→ signatures.authorizedBy.name
+
+app3_position
+→ signatures.authorizedBy.position
+```
+
+Rules:
+
+Idempotent seed.
+
+Update existing mappings if incorrect.
+
+---
+
+# Scope H3.9 Approved Snapshot Integration
+
+Update:
+
+```txt
+prepareApprovedQuotationSnapshot()
+```
+
+Snapshot must store:
+
+```txt
+resolved signatures
+```
+
+Purpose:
+
+Future PDF regeneration must preserve:
+
+```txt
+who approved
+who authorized
+```
+
+even if users later change.
+
+---
+
+# Scope H3.10 Preview Behavior
+
+Preview PDF:
+
+```txt
+resolve live signatures
+```
+
+Approved PDF:
+
+```txt
+prefer approved snapshot signatures
+```
+
+Rules:
+
+Approved artifact must remain immutable.
+
+---
+
+# Scope H3.11 UI Visibility
+
+Update quotation detail.
+
+Add section:
+
+```txt
+Approval Signatures
+```
+
+Display:
+
+```txt
+Prepared By
+Approved By
+Authorized By
+```
+
+with:
+
+```txt
+name
+position
+approval timestamp
+```
+
+if available.
+
+---
+
+# Scope H3.12 Verification
+
+Create:
+
+```txt
+scripts/verify-task-h3.js
+```
+
+Verify:
+
+```txt
+preparedBy exists
+approvedBy exists
+authorizedBy exists
+
+app1 mapped
+app2 mapped
+app3 mapped
+
+snapshot contains signatures
+
+approved PDF contains names
+```
+
+---
+
+# ADR
+
+Create:
+
+```txt
+docs/adr/0012-approval-signature-strategy.md
+```
+
+Freeze:
+
+```txt
+Prepared By rule
+Approved By rule
+Authorized By rule
+Position resolution rule
+Snapshot immutability rule
+```
+
+---
+
+# Explicit Non-Scope
+
+Do NOT implement:
+
+```txt
+Digital signature
+Image signature
+Certificate signature
+PKI
+e-Signature
+QR verification
+Stamp image upload
+```
+
+Only text-based approval identity.
+
+---
+
+# Output
+
+1. Files Added
+2. Files Modified
+3. Signature Resolution Strategy
+4. Position Resolution Strategy
+5. PDF Mapping Changes
+6. Snapshot Changes
+7. Verification Result
+8. ADR Added
+9. Remaining Risks
+
+---
+
+# Definition of Done
+
+✔ Prepared By resolves correctly
+
+✔ Approved By resolves correctly
+
+✔ Authorized By resolves correctly
+
+✔ Position resolves correctly
+
+✔ PDF Preview displays signatures
+
+✔ Approved PDF displays signatures
+
+✔ Approved Snapshot stores signatures
+
+✔ app1/app2/app3 mappings work
+
+✔ Artifact remains immutable
+
+✔ ADR created