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

# Quickstart Guide: RFA Approval System Refactor

**Branch**: `1-rfa-approval-refactor`
**Prerequisites**: Docker Compose environment running (MariaDB, Redis)

---

## 1. Environment Setup

### 1.1 Database Schema

```bash
# Apply new SQL schema (ADR-009: no TypeORM migrations)
# File will be created in specs/03-Data-and-Storage/
mysql -u root -p lcbp3 < specs/03-Data-and-Storage/lcbp3-v1.9.0-rfa-approval-schema.sql
```

### 1.2 Seed Master Data

```bash
# Run seeder for Response Codes and default rules
cd backend
npx ts-node -r tsconfig-paths/register src/modules/response-code/seeders/response-code.seed.ts
```

**Expected Output**:
```
Seeding Response Codes...
✓ 1A-1G Engineering codes created
✓ 1A-1G Material codes created
✓ 1A-1G Contract codes created
✓ 1A-1G Testing codes created
✓ 1A-1G ESG codes created
✓ Codes 2, 3, 4 created (all categories)
✓ Default rules applied for all document types
Done! 55 response codes created.
```

---

## 2. Backend Setup

### 2.1 Install Dependencies

```bash
cd backend
npm install
```

### 2.2 Environment Variables

Add to `.env`:
```env
# Redis (for BullMQ and Redlock)
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# BullMQ Queues
BULLMQ_QUEUE_PREFIX=rfa
BULLMQ_REMINDER_QUEUE=rfa-reminders
BULLMQ_DISTRIBUTION_QUEUE=rfa-distribution

# Reminder Schedule
REMINDER_DAYS_BEFORE_DUE=2
ESCALATION_DAYS_AFTER_DUE_L1=1
ESCALATION_DAYS_AFTER_DUE_L2=3
```

### 2.3 Start Development Server

```bash
npm run start:dev
```

Verify modules loaded:
```
[Nest] 1234  - 01/01/2024, 09:00:00 AM     LOG [ReviewTeamModule] Module initialized
[Nest] 1234  - 01/01/2024, 09:00:00 AM     LOG [ResponseCodeModule] Module initialized
[Nest] 1234  - 01/01/2024, 09:00:00 AM     LOG [DelegationModule] Module initialized
[Nest] 1234  - 01/01/2024, 09:00:00 AM     LOG [ReminderModule] Module initialized
[Nest] 1234  - 01/01/2024, 09:00:00 AM     LOG [DistributionModule] Module initialized
```

### 2.4 Start Queue Workers

```bash
# Terminal 2 - Reminder processor
npx ts-node -r tsconfig-paths/register src/modules/reminder/processors/reminder.processor.ts

# Terminal 3 - Distribution processor
npx ts-node -r tsconfig-paths/register src/modules/distribution/processors/distribution.processor.ts
```

---

## 3. Frontend Setup

### 3.1 Install Dependencies

```bash
cd frontend
npm install
```

### 3.2 Start Development Server

```bash
npm run dev
```

### 3.3 Access URLs

- **RFA Review Page**: http://localhost:3000/dashboard/rfa/{id}/review
- **Review Teams Admin**: http://localhost:3000/dashboard/review-teams
- **Response Codes Admin**: http://localhost:3000/dashboard/response-codes
- **Delegation Settings**: http://localhost:3000/dashboard/delegation

---

## 4. First Time Setup

### 4.1 Create Review Team

```bash
# Using API
curl -X POST http://localhost:3001/api/v1/review-teams \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Structural Review Team",
    "description": "Team for structural drawings review",
    "projectId": "019505a1-7c3e-7000-8000-abc123def456",
    "defaultForRfaTypes": ["SDW", "DDW"]
  }'
```

### 4.2 Add Team Members

```bash
curl -X POST http://localhost:3001/api/v1/review-teams/{teamId}/members \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "userId": "019505a1-7c3e-7000-8000-abc123def789",
    "disciplineId": 1,
    "role": "LEAD"
  }'
```

### 4.3 Setup Reminder Rules

```bash
curl -X POST http://localhost:3001/api/v1/reminder-rules \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "RFA Due Soon Reminder",
    "triggerDaysBeforeDue": 2,
    "reminderType": "DUE_SOON",
    "recipients": ["ASSIGNEE", "MANAGER"],
    "messageTemplateTh": "RFA #{docNumber} ใกล้ครบกำหนดในอีก {days} วัน",
    "messageTemplateEn": "RFA #{docNumber} is due in {days} days"
  }'
```

### 4.4 Setup Distribution Matrix

```bash
curl -X POST http://localhost:3001/api/v1/distribution-matrices \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "Shop Drawing Distribution",
    "documentTypeId": 1,
    "conditions": {
      "codes": ["1A", "1B", "2"]
    },
    "recipients": [
      { "recipientType": "ROLE", "recipientId": "SITE_TEAM", "deliveryMethod": "BOTH" },
      { "recipientType": "ROLE", "recipientId": "QS_TEAM", "deliveryMethod": "EMAIL" }
    ]
  }'
```

---

## 5. Test Workflow

### 5.1 Submit RFA with Review Team

```bash
# Submit RFA - triggers workflow and creates review tasks
curl -X POST http://localhost:3001/api/v1/rfa/{uuid}/submit \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "templateId": 1,
    "reviewTeamId": "019505a1-7c3e-7000-8000-abc123def456"
  }'
```

### 5.2 Check Review Tasks Created

```bash
# As reviewer, check inbox
curl http://localhost:3001/api/v1/review-tasks \
  -H "Authorization: Bearer $REVIEWER_TOKEN"
```

### 5.3 Complete Review with Response Code

```bash
curl -X POST http://localhost:3001/api/v1/review-tasks/{taskId} \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $REVIEWER_TOKEN" \
  -d '{
    "responseCodeId": "019505a1-7c3e-7000-8000-abc123def111",
    "comments": "Approved with minor comments on detail A3"
  }'
```

---

## 6. Verification Checklist

- [ ] Review Team created and visible in admin
- [ ] Review Team members assigned by discipline
- [ ] RFA submission creates parallel review tasks
- [ ] Response codes filtered by document category
- [ ] Code 3 triggers veto and returns workflow
- [ ] Reminders scheduled on due date
- [ ] Distribution executes after approval
- [ ] Delegation forwards tasks correctly
- [ ] Aggregate status shows real-time progress

---

## 7. Troubleshooting

### Queue Jobs Not Processing

```bash
# Check BullMQ board (if enabled)
open http://localhost:3001/admin/queues

# Or check Redis
redis-cli KEYS "bull*"
redis-cli LRANGE "bull:rfa-reminders:waiting" 0 -1
```

### Parallel Review Not Working

Check workflow-engine DSL configuration:
```bash
# Verify parallel gateway enabled
curl http://localhost:3001/api/v1/workflow-definitions/RFA_APPROVAL \
  -H "Authorization: Bearer $TOKEN"
```

### Response Codes Not Loading

```bash
# Verify seed data
mysql -u root -p lcbp3 -e "SELECT COUNT(*) FROM response_codes;"
# Expected: 55 rows minimum
```

---

## 8. Running Tests

### 8.1 Backend Unit + Integration Tests

```bash
cd backend

# Unit tests only (runs from src/)
npm test

# Tests in tests/ directory (Phase 9 stubs)
npx jest --rootDir . --testMatch '**/tests/**/*.spec.ts' --passWithNoTests

# Coverage report
npm run test:cov
```

### 8.2 Frontend Tests

```bash
cd frontend
npm test -- --watchAll=false
```

### 8.3 E2E Tests (requires seeded database)

```bash
cd backend
npm run test:e2e
```

---

## 9. New Phase 9 Components

| Component | Path | Description |
|-----------|------|-------------|
| `AggregateStatusService` | `backend/src/modules/review-team/services/` | Consensus % calculator |
| `ConsensusService` | `backend/src/modules/review-team/services/` | Triggers distribution after all tasks complete |
| `VetoOverrideService` | `backend/src/modules/review-team/services/` | PM force-approve with audit trail |
| `ParallelGatewayHandler` | `backend/src/modules/workflow-engine/dsl/` | DSL support for parallel review |
| `ReviewTaskInbox` | `frontend/components/review-task/` | Reviewer inbox with status filters |
| `ParallelProgress` | `frontend/components/review-task/` | Discipline track progress bar |
| `VetoOverrideDialog` | `frontend/components/review-task/` | PM override dialog with justification |

### New Admin URLs

- **Distribution Matrix**: http://localhost:3000/dashboard/admin/distribution-matrices
- **Reminder Rules**: http://localhost:3000/dashboard/admin/reminder-rules
- **Master Approval Matrix**: http://localhost:3000/dashboard/admin/approval-matrix

---

## 10. Next Steps

1. **Run Tests**: `npm test` (backend), `npm run test:e2e` (frontend)
2. **Load Test**: `k6 run load-tests/rfa-approval-load.js`
3. **Deploy**: Follow `specs/04-Infrastructure-OPS/04-08-release-management-policy.md`