lcbp3/specs/1-rfa-approval-refactor/plan.md

# Implementation Plan: RFA Approval System Refactor

**Branch**: `1-rfa-approval-refactor` | **Date**: 2026-05-11 | **Spec**: [spec.md](./spec.md)

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

---

## Summary

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

```text
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)

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

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