Implementation Plan: RFA Approval System Refactor

Branch: 1-rfa-approval-refactor | Date: 2026-05-11 | Spec: spec.md

Input: Refactor RFA approval system to TeamBinder/InEight-style with Review Teams, Response Codes, Delegation, Auto-Reminders, and Distribution Matrix

Summary

ปรับปรุงระบบการอนุมัติเอกสาร RFA ให้รองรับ:

Review Teams by Discipline - กำหนผู้ตรวจสอบตามสาขาวิชาแทนรายบุคคล พร้อม Parallel Review
Master Approval Matrix - Response Codes มาตรฐาน 1A-1G, 2, 3, 4 ตามหมวดงาน (Engineering, Material, Contract, Testing, ESG)
Delegation & Proxy - มอบหมายงานแทนเมื่อไม่อยู่ พร้อมตรวจจับ Circular Delegation
Auto-Reminders & Escalation - แจ้งเตือนอัตโนมัติตาม SLA และ Escalate 2 ระดับเมื่อ Overdue
Distribution Matrix - กระจายเอกสารอัตโนมัติหลังอนุมัติผ่าน BullMQ

Technical approach: สร้าง Entities ใหม่ (ReviewTeam, ReviewTask, ResponseCodeMatrix, Delegation, DistributionMatrix) และ integrate กับ Unified Workflow Engine (ADR-001) และ BullMQ (ADR-008)

Technical Context

Language/Version: TypeScript 5.x, NestJS 10.x (Backend), Next.js 14.x (Frontend)
Primary Dependencies: TypeORM (Database), BullMQ (Queue/Reminders), CASL (Authorization), Zod (Validation), Redis (Cache/Locking)
Storage: MariaDB 10.11 (Primary), Redis 7.x (Cache/Queue)
Testing: Jest (Backend), Playwright (Frontend), Min 70% backend coverage, 80% business logic
Target Platform: Web Application (NestJS API + Next.js Frontend)
Project Type: Full-stack (backend + frontend)
Performance Goals: Approval API response <500ms, Parallel Review aggregation <200ms, Distribution queue processing <5 min
Constraints: ADR-019 UUID (no parseInt), ADR-009 No TypeORM Migrations, ADR-002 Document Numbering with Redlock, ADR-018 AI Boundary
Scale/Scope: 100+ concurrent RFAs, 50+ Review Teams per project, 1000+ Distribution recipients

Constitution Check

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-018 AI Boundary	✅ PASS	No AI involvement in approval workflow
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

Post-Design Re-check: Required after data-model.md and contracts generated

Project Structure

Documentation (this feature)

specs/1-rfa-approval-refactor/
├── plan.md              # This file
├── spec.md              # Feature specification
├── research.md          # Phase 0 research
├── data-model.md        # Phase 1 data model
├── quickstart.md        # Phase 1 setup guide
├── contracts/           # Phase 1 API contracts
│   ├── review-team-api.yaml
│   ├── response-code-api.yaml
│   ├── delegation-api.yaml
│   └── distribution-api.yaml
└── tasks.md             # Phase 2 (generated by /speckit-tasks)

Source Code (repository root)

backend/
├── src/
│   ├── modules/
│   │   ├── review-team/          # NEW: Review Teams & Tasks
│   │   │   ├── entities/
│   │   │   ├── dto/
│   │   │   ├── review-team.service.ts
│   │   │   ├── review-team.controller.ts
│   │   │   └── review-task.service.ts
│   │   ├── response-code/        # NEW: Master Approval Matrix
│   │   │   ├── entities/
│   │   │   ├── dto/
│   │   │   └── response-code.service.ts
│   │   ├── delegation/           # NEW: Delegation & Proxy
│   │   │   ├── entities/
│   │   │   ├── dto/
│   │   │   └── delegation.service.ts
│   │   ├── reminder/             # NEW: Auto-Reminders
│   │   │   ├── entities/
│   │   │   ├── processors/
│   │   │   └── reminder.service.ts
│   │   ├── distribution/         # NEW: Distribution Matrix
│   │   │   ├── entities/
│   │   │   ├── processors/
│   │   │   └── distribution.service.ts
│   │   └── workflow-engine/      # EXISTING: Modified for Parallel Review
│       └── rfa/                  # EXISTING: Modified for Response Codes
└── tests/
    ├── unit/review-team/
    ├── unit/delegation/
    ├── integration/distribution/
    └── e2e/rfa-workflow/

frontend/
├── src/
│   ├── app/
│   │   ├── (dashboard)/
│   │   │   ├── review-teams/     # NEW: Review Team management UI
│   │   │   ├── response-codes/   # NEW: Master Matrix admin UI
│   │   │   ├── delegation/     # NEW: Delegation settings UI
│   │   │   └── rfa/
│   │   │       └── [id]/
│   │   │           └── review/   # MODIFIED: Parallel Review UI with Response Codes
│   │   └── api/
│   │       └── review-team/      # NEW: API routes
│   ├── components/
│   │   ├── review-task/          # NEW: Review Task cards, Aggregate status
│   │   ├── response-code/        # NEW: Response Code selector
│   │   └── delegation/           # NEW: Delegation form
│   └── hooks/
│       ├── use-review-teams.ts   # NEW
│       ├── use-response-codes.ts # NEW
│       └── use-delegation.ts     # NEW

Structure Decision: Full-stack implementation with 5 new backend modules (review-team, response-code, delegation, reminder, distribution) + modifications to existing rfa and workflow-engine modules. Frontend adds management UIs and enhances existing RFA review page.

Complexity Tracking

Violation	Why Needed	Simpler Alternative Rejected Because
5 new backend modules	Each domain (Review Teams, Response Codes, Delegation, Reminders, Distribution) has distinct business logic, lifecycle, and scaling needs	Single combined module would create tight coupling and maintenance burden
Parallel Review in Workflow Engine	Requires significant DSL extension to support concurrent tasks with consensus rules	Sequential review would not meet industry standard (TeamBinder/InEight) efficiency requirements
Master Approval Matrix with inheritance	Global + Project override needed for standardization while allowing project flexibility	Single global matrix wouldn't accommodate project-specific requirements (e.g., ESG varies by project type)

Phase Overview

Phase	Output	Purpose
Phase 0	research.md	Research technical patterns, validate Workflow Engine DSL extension
Phase 1	data-model.md, contracts/, quickstart.md	Design entities, API contracts, setup guide
Phase 2	tasks.md	Break into actionable tasks (via /speckit-tasks)

Next Steps

Phase 0: Generate research.md - Validate Workflow Engine DSL can support Parallel Review
Phase 1: Generate data-model.md and API contracts
Run: /speckit-tasks to create tasks.md
Run: /speckit-analyze to validate cross-artifact consistency

8.1 KiB Raw Blame History