Codex 5.3 Refactor Note: Canonical refactor plan: docs/CODEX-5.3-REFACTOR-PLAN.md. This document is retained for historical and implementation context during the refactor.

W10 SMO Decision Implementation

✅ A. Summary

W10 implements SMO Decision (Status + Notes) - the final stage where SMO reviews a candidate escalated to TO_SMO and finalizes an internal decision (APPROVED/REJECTED/KIV). The decision is immutable once created, triggers candidate status updates, audit logging, and a domain event emission for future notification routing (W16).

Key Features:

• SMO/Admin finalize decision with status + optional notes
• Notes required for REJECTED/KIV; optional for APPROVED
• Decision immutable once created (409 Conflict on retry)
• Candidate status transitions: TO_SMO → APPROVED/REJECTED/KIV
• Audit logging for decision + status change
• Domain event DecisionUpdated emitted (stub; W16 will route to Company-All)

---

📋 B. Routes

Pages

• /candidates/[id]?tab=smo-decision
  • Tab-based UI in existing Candidate Detail page
  • Candidate name/code + status badge
  • Decision form (editable only for SMO/Admin when status=TO_SMO)
  • Decision history (read-only if decision exists)

API Endpoints

1. GET /api/candidates/[id]/decision

   • Auth required (HR/Manager/SMO/Admin can view)
   • Returns: { candidateId, decision: { id, decision, notes, decidedBy, decidedAt } }
   • Returns null if no decision exists yet

2. POST /api/candidates/[id]/decision

   • SMO/Admin only
   • Body: { decision: APPROVED|REJECTED|KIV, notes?: string }
   • Validates: candidate.status == TO_SMO, notes required if REJECTED/KIV
   • Returns 409 if decision already exists (immutable)
   • Returns: { success: true, status, decision, decidedAt }

---

💾 C. Data Model Changes

Prisma Schema (No changes needed)

The following already exist in /prisma/schema.prisma:

enums:

• CandidateStatus includes: APPROVED, REJECTED, KIV (already present)
• DecisionType includes: APPROVED, REJECTED, KIV (already present)
• AuditEventType includes: DECISION_FINALIZED, CANDIDATE_STATUS_UPDATED (already present)

models:

• Decision model with fields:
  • id (primary key)
  • candidateId (unique, foreign key)
  • decision (DecisionType)
  • notes (nullable text)
  • decidedByUserId (foreign key to User)
  • decidedAt (datetime)
  • createdAt (datetime)
• Candidate model updated with:
  • decidedAt (optional datetime)

No migration required - schema already includes Decision model and required enums.

---

🎨 D. UI Components

Files Created/Updated

src/app/(app)/candidates/[id]/page.tsx - UPDATED

• Added SMO Decision tab button + tab navigation logic
• Tab switches between:
  • hr-screening → <HrScreeningTab />
  • manager-review → <ManagerReviewTab />
  • smo-decision → <SmoDecisionTab /> (NEW)
• Status badge styling updated for TO_SMO (purple), APPROVED (green), REJECTED (red), KIV (orange)

src/app/(app)/candidates/[id]/_tabs/SmoDecisionTab.tsx - NEW

UI Sections:

1. Editable Mode (candidate.status == TO_SMO, user is SMO/Admin)

   • Warning banner: "⚠️ Internal Decision: Do not contact applicant from this system."
   • Decision form:
     • Radio buttons: APPROVED, REJECTED, KIV
     • Textarea: Notes (required if REJECTED/KIV; optional if APPROVED)
     • Buttons: "Finalize Decision" (primary), "Cancel" (secondary)
   • Real-time validation display

2. Read-Only Mode (decision already exists)

   • Success banner: "✓ Decision finalized (read-only)"
   • Card showing:
     • Decision (color-coded badge)
     • Notes (if any)
     • Decided By (name + email)
     • Decided At (datetime)

3. Not Eligible Mode (candidate.status != TO_SMO)

   • Warning banner: "⚠ Not in SMO review stage. Current status: [status]"

---

⚙️ E. API Logic

File: src/app/api/candidates/[id]/decision/route.ts - NEW

GET /api/candidates/[id]/decision

// Auth required (HR/Manager/SMO/Admin)
1. requireAuth() → verify user
2. Check allowedRoles = ['HR', 'MANAGER', 'SMO', 'ADMIN'] → 403 if not
3. Fetch candidate by id → 404 if not found
4. Query Decision record by candidateId
5. Return { candidateId, decision: {...} or null }

POST /api/candidates/[id]/decision

// Auth + role check
1. requireAuth() → verify user
2. Check auth.role in ['SMO', 'ADMIN'] → 403 if not

// Validation
3. Parse body with decisionSchema
4. Fetch candidate by id → 404 if not found
5. Check candidate.status == TO_SMO → 400 if not
6. Check if Decision exists for candidateId → 409 if yes (immutable)

// Transactional update
7. BEGIN TRANSACTION
   a. Create Decision record:
      - candidateId, decision, notes, decidedByUserId, decidedAt
   b. Update Candidate:
      - status = APPROVED | REJECTED | KIV
      - statusUpdatedAt = now()
      - decidedAt = now()
8. COMMIT

// Audit + Events
9. logAuditEvent('DECISION_FINALIZED', userId, {
     candidateId, candidateCode, decision, hasNotes
   })
10. logAuditEvent('CANDIDATE_STATUS_UPDATED', userId, {
      candidateId, candidateCode, fromStatus: TO_SMO, toStatus, reason
    })
11. emitDomainEvent('DecisionUpdated', candidateId, {
      candidateId, candidateCode, decision, decidedBy, decidedAt, notes
    })

12. Return { success: true, status, decision, decidedAt }

---

🔐 F. RBAC Checks

Access Control Matrix

Action	HR	Manager	SMO	Admin	Candidate
View decision	✅	✅	✅	✅	❌
Finalize decision	❌	❌	✅	✅	❌
Edit draft	N/A	N/A	✅	✅	❌
View history	✅	✅	✅	✅	❌

Implementation

Endpoint Checks:

• GET /api/candidates/[id]/decision: Require role in [HR, MANAGER, SMO, ADMIN]
• POST /api/candidates/[id]/decision: Require role in [SMO, ADMIN]

UI Checks:

• Form editable only if: user.role in [SMO, ADMIN] AND candidate.status == TO_SMO
• Otherwise form locked with read-only message

---

📊 G. Audit Events

Events Logged

DECISION_FINALIZED

eventType: DECISION_FINALIZED
userId: {smо/admin user id}
details: {
  candidateId: string,
  candidateCode: string,
  decision: APPROVED | REJECTED | KIV,
  hasNotes: boolean
}

CANDIDATE_STATUS_UPDATED

eventType: CANDIDATE_STATUS_UPDATED
userId: {smo/admin user id}
details: {
  candidateId: string,
  candidateCode: string,
  fromStatus: TO_SMO,
  toStatus: APPROVED | REJECTED | KIV,
  reason: "Decision finalized"
}

Domain Event (Stub)

DecisionUpdated emitted to emitDomainEvent():

eventType: DecisionUpdated
aggregateId: candidateId
payload: {
  candidateId: string,
  candidateCode: string,
  decision: APPROVED | REJECTED | KIV,
  decidedBy: {userId},
  decidedAt: ISO string,
  notes: string | null
}

Note: Domain event currently logs to console. W16 will implement outbox table + notification routing to Company-All channel.

---

✅ H. Test Checklist

Prerequisites

• Database setup (Postgres with Prisma schema)
• Server running: npm run dev
• 3 test users: HR, SMO, Admin with valid JWT cookies

Test Case 1: View Decision (HR can view)

Setup:

1. Create candidate with status TO_SMO
2. As HR user, visit /candidates/[id]?tab=smo-decision

Expected:

• ✅ Form displays "Not in SMO review stage" (read-only)
• ✅ Cannot finalize decision

---

Test Case 2: Finalize Decision - Approve (SMO only)

Setup:

1. Create candidate with status TO_SMO
2. As SMO user, visit /candidates/[id]?tab=smo-decision

Actions:

1. Select "APPROVED" radio button
2. (Optional) Add notes
3. Click "Finalize Decision"

Expected:

• ✅ Form validates
• ✅ API POST /api/candidates/[id]/decision returns 200
• ✅ Candidate status updated to APPROVED
• ✅ decidedAt set to current timestamp
• ✅ Form switches to read-only "Decision finalized"
• ✅ Decision card shows: APPROVED (green badge), notes (if provided), decided by, decided at
• ✅ Audit logs written: DECISION_FINALIZED + CANDIDATE_STATUS_UPDATED
• ✅ Domain event emitted to console: [DomainEvent] DecisionUpdated: {...}

---

Test Case 3: Finalize Decision - Reject with Notes (SMO only)

Setup:

1. Create candidate with status TO_SMO
2. As SMO user, visit /candidates/[id]?tab=smo-decision

Actions:

1. Select "REJECTED" radio button
2. Type notes: "Does not meet technical requirements"
3. Click "Finalize Decision"

Expected:

• ✅ Form validates (notes required for REJECTED)
• ✅ API POST returns 200
• ✅ Candidate status updated to REJECTED
• ✅ Decision card shows: REJECTED (red badge), notes, decided by, decided at
• ✅ Audit logs written
• ✅ Domain event emitted

---

Test Case 4: Finalize Decision - Reject without Notes (validation)

Setup:

1. Same as Test Case 3
2. As SMO user

Actions:

1. Select "REJECTED" radio button
2. Leave notes empty
3. Click "Finalize Decision"

Expected:

• ✅ Validation error: "Notes are required for Reject or KIV decisions"
• ✅ Form does NOT submit
• ✅ Candidate status NOT updated

---

Test Case 5: Finalize Decision - KIV with Notes

Setup:

1. Create candidate with status TO_SMO
2. As SMO user

Actions:

1. Select "KIV" radio button
2. Type notes: "Need more time to assess"
3. Click "Finalize Decision"

Expected:

• ✅ Form validates
• ✅ API POST returns 200
• ✅ Candidate status updated to KIV
• ✅ Decision card shows: KIV (orange badge), notes, decided by, decided at
• ✅ Audit logs written

---

Test Case 6: Immutability - Second Submit (409)

Setup:

1. Run Test Case 2 (decision finalized as APPROVED)
2. As SMO user, still on /candidates/[id]?tab=smo-decision

Actions:

1. Manually craft POST request:

   curl -X POST /api/candidates/{id}/decision \
     -H "Content-Type: application/json" \
     -d '{"decision": "REJECTED", "notes": "change my mind"}'
   

Expected:

• ✅ API returns 409 Conflict
• ✅ Error message: "Decision already finalized (immutable)"
• ✅ Candidate status NOT changed
• ✅ No new audit logs

---

Test Case 7: Wrong Status - Cannot Finalize

Setup:

1. Create candidate with status NEW (not TO_SMO)
2. As SMO user, visit /candidates/[id]?tab=smo-decision

Actions:

1. Try to finalize decision

Expected:

• ✅ Form shows: "Not in SMO review stage. Current status: NEW"
• ✅ Cannot finalize
• ✅ Form is read-only

---

Test Case 8: Non-SMO User Cannot Finalize

Setup:

1. Create candidate with status TO_SMO
2. As HR user, visit /candidates/[id]?tab=smo-decision

Actions:

1. Try to finalize decision

Expected:

• ✅ Form shows: "Not in SMO review stage" (read-only message)
• ✅ No form input controls visible OR disabled
• ✅ Cannot submit

---

Test Case 9: Admin Can Finalize (role override)

Setup:

1. Create candidate with status TO_SMO
2. As Admin user, visit /candidates/[id]?tab=smo-decision

Actions:

1. Select "APPROVED" radio button
2. Click "Finalize Decision"

Expected:

• ✅ Form validates
• ✅ API POST returns 200
• ✅ Candidate status updated to APPROVED
• ✅ All same as SMO user (admin has permission)

---

Test Case 10: API - Unauthenticated Request

Setup:

1. No valid JWT cookie

Actions:

1. POST /api/candidates/[id]/decision (no auth)

Expected:

• ✅ API returns 401 Unauthorized

---

Test Case 11: API - Missing Candidate

Setup:

1. Valid JWT, SMO role
2. Non-existent candidateId

Actions:

1. POST /api/candidates/invalid-id/decision

Expected:

• ✅ API returns 404 Not Found
• ✅ Error: "Candidate not found"

---

Test Case 12: Audit Log Verification

Setup:

1. Run Test Case 2 (finalize as APPROVED)

Actions:

1. Query AuditLog table:

   SELECT * FROM AuditLog 
   WHERE eventType IN ('DECISION_FINALIZED', 'CANDIDATE_STATUS_UPDATED')
   ORDER BY createdAt DESC LIMIT 2;
   

Expected:

• ✅ Two rows created in order:
  • DECISION_FINALIZED: {candidateId, decision: APPROVED, hasNotes: false}
  • CANDIDATE_STATUS_UPDATED: {fromStatus: TO_SMO, toStatus: APPROVED, reason}
• ✅ Both logged with correct userId

---

Test Case 13: Domain Event - Console Verification

Setup:

1. Run Test Case 2

Actions:

1. Check server console output during POST request

Expected:

• ✅ Console logs:

  [DomainEvent] DecisionUpdated: {
    aggregateId: '...',
    payload: {
      candidateId: '...',
      decision: 'APPROVED',
      decidedBy: '...',
      decidedAt: '2026-01-23T...',
      notes: null
    }
  }
  

---

📝 Notes

• No offer letter upload in W10 (out of scope per requirements)
• Decision immutable once created; no edit endpoint
• Domain event stub only - W16 will implement notification routing
• Next step (W11+): Offer flow, notification center, approval workflows