lcbp3/specs/200-fullstacks/204-rfa-approval-refactor/plan.md

Implementation Plan: RFA Approval System Refactor

Feature Branch: 204-rfa-approval-refactor Parent Feature: RFA Approval Refactor Version: 1.0.0 Status: Planning

---

🏗️ Architectural Overview

เราจะปรับปรุงระบบ RFA Approval โดยใช้ Domain-Driven Design (DDD) และ Unified Workflow Engine (ADR-001) โดยเน้นไปที่ความยืดหยุ่นของ Review Teams, มาตรฐาน Response Codes, และระบบ Delegation/Escalation ที่อัตโนมัติ

Core Components

1. Review Team Module: จัดการสมาชิกตาม Discipline และ Default Rules
2. Approval Matrix Service: ประมวลผลกฎ Response Codes และ Implications (Cost/Schedule)
3. Task Orchestrator: ควบคุม Parallel Review และ Lead Consolidation logic
4. Delegation Manager: ตรวจสอบสิทธิ์และสลับผู้รับผิดชอบงานตามระยะเวลา
5. Reminder & Escalation Engine: ใช้ BullMQ ในการส่งการแจ้งเตือนแบบ Progressive (3-strike)
6. Distribution Engine: ทำงานแบบ Async เพื่อกระจายเอกสารตาม Matrix หลังการอนุมัติ

---

🛡️ Security & Integrity (Tier 1)

Gate	Status	Notes
ADR-019 UUID	✅ PASS	All new entities use publicId (string UUID), internal id (number) with @Exclude()
ADR-009 No Migrations	✅ PASS	Schema changes via SQL files in specs/03-Data-and-Storage/
ADR-002 Document Numbering	✅ PASS	Existing RFA numbering reused, no new numbering needed
ADR-008 BullMQ	✅ PASS	Reminders, Distribution, Escalation all use BullMQ
ADR-016 CASL	✅ PASS	Reviewer permissions via CASL ability checks
ADR-023/023A AI Boundary	✅ PASS	No AI involvement in approval workflow (Ollama on Admin Desktop only)
ADR-007 Error Handling	✅ PASS	BusinessException/WorkflowException for approval errors
No any types	✅ PASS	Strict TypeScript enforced
No console.log	✅ PASS	NestJS Logger for backend, removed for frontend commits

---

🗺️ Implementation Roadmap

Phase 0: Research & Foundation (Validated)

• วิเคราะห์ความแตกต่างระหว่างระบบปัจจุบันกับ TeamBinder/InEight
• ตรวจสอบความพร้อมของ Workflow Engine สำหรับ Parallel Tasks
• กำหนด Schema พื้นฐานสำหรับ Entities ใหม่

Phase 1: Data Model & Contracts (Next Step)

• สร้าง SQL schema สำหรับ ReviewTeam, ReviewTask, Delegation, ApprovalMatrix
• อัปเดต Data Dictionary ใน specs/03-Data-and-Storage/
• นิยาม API DTOs และ Response Interfaces ใน NestJS

Phase 2: Core Logic & Services

• พัฒนา ReviewTeamService และ DelegationService
• พัฒนา ApprovalMatrixService (Logic: Lead Consolidation, Category Filtering)
• พัฒนา RemindersProcessor (Logic: 3-Strike Escalation via BullMQ)

Phase 3: Workflow Integration

• อัปเดต RFA Workflow DSL ให้รองรับ Parallel Review Step
• เชื่อมต่อ Event Hooks สำหรับ Auto-Distribution (Transmittal generation)
• พัฒนา Proxy Logic ใน Task Manager สำหรับ Delegation

Phase 4: Frontend UI/UX

• พัฒนา Horizontal Stepper สำหรับ Parallel Review visualization
• พัฒนา Delegation Settings UI และ Matrix Management Dashboard
• ปรับปรุง RFA Detail page ให้รองรับ Side Panel layout (Discipline details)

Phase 5: Testing & Validation

• Unit Tests สำหรับ Lead Consolidation rules
• E2E Tests สำหรับ Delegation expiry และ Escalation flow
• โหลดเทสต์สำหรับ Distribution Matrix (Concurrent approvals)
• Performance Tests สำหรับ Approval Matrix Service
  • Load testing กับ 1000+ response code rules
  • Benchmark consensus calculation กับ 10+ disciplines
  • Query performance test สำหรับ review_tasks กับ indexes
  • Document SLA targets: Approval lookup < 100ms, Consensus calc < 500ms

---

📐 Technical Decisions

Decision 1: Lead Consolidation Logic (Parallel Review)

เราจะใช้ Lead Consolidation แทน Majority Vote เพื่อให้สอดคล้องกับมาตรฐานอุตสาหกรรม โดย Lead Discipline จะได้รับสิทธิ์ในการ "สรุปผล" หลังจากทุก Discipline ทำงานเสร็จ หรือสามารถ override ได้ตามสิทธิ์ PM

Decision 2: Single-Level Delegation

เพื่อป้องกันความซับซ้อนของ Circular Dependency และ Audit Trail เราจะจำกัดการมอบหมายงานให้เพียง 1 ระดับ เท่านั้น (A -> B) โดย B ไม่สามารถส่งต่อให้ C ได้ในฐานะผู้ใช้ปกติ

Decision 3: 3-Strike Progressive Escalation

การยกระดับจะใช้ระบบ 3 ครั้ง (Reminders) ต่อระดับความสำคัญ ก่อนจะย้ายงานไปให้ผู้บังคับบัญชา (L1 -> L2) และเมื่อถึงระดับสูงสุดจะส่ง Daily Reminder จนกว่าจะจบงาน

---

⚠️ Potential Blockers

• Workflow DSL Flexibility: ความสามารถของ Engine ปัจจุบันในการจัดการ Parallel Tasks ที่รอการ Consolidation
• Migration of Existing RFAs: แผนการจัดการ RFA ที่กำลังอยู่ในกระบวนการ (In-flight) ระหว่างการเปลี่ยนผ่านระบบ
• CASL Matrix Overlap: ความซับซ้อนของสิทธิ์เมื่อมีทั้ง Delegation และ Review Team roles ซ้อนทับกัน

---

🔗 Cross-Spec Dependencies

Dependencies จาก 302-ai-model-revision

Component	Impact	Coordination
BullMQ Infrastructure	ใช้ queue ai-realtime และ ai-batch ร่วมกัน	ตรวจสอบว่า Reminder/Escalation jobs ไม่ชนกับ AI jobs
QdrantService	อาจใช้สำหรับ RFA document search	ตรวจสอบ projectPublicId filtering ถ้ามี integration
Ollama on Desk-5439	Shared GPU resource	Schedule Reminder batch jobs นอกช่วง AI peak

Shared Entities/Services

• Audit Logging: ใช้ audit_logs table ร่วมกัน — ตรวจสอบ action types ไม่ซ้ำกัน
• Notification System: ใช้ BullMQ + notification service ร่วมกัน — ตรวจสอบ queue priority

Deployment Sequence Recommendation

1. Phase 1-2 ของ AI Model Revision (เสร็จก่อน)
2. Phase 1-3 ของ RFA Approval Refactor (ใช้ BullMQ ที่ setup แล้ว)
3. Phase 4+ ทั้งสอง features ทำพร้อมกันได้

---

🔗 References

• Spec File: specs/200-fullstacks/204-rfa-approval-refactor/spec.md
• Research File: specs/200-fullstacks/204-rfa-approval-refactor/research.md
• Cross-Spec: specs/300-others/302-ai-model-revision/plan.md (BullMQ/Qdrant shared infrastructure)
• ADR-001: Unified Workflow Engine
• ADR-019: Hybrid Identifier Strategy
• ADR-008: BullMQ Notification Strategy