# Deviation Module (Credit & Disbursement)

---

## Ticket: CRED-6074 — 2026-08-18

### Overview

This document outlines the complete workflow, optimizations, and rules for the **Credit and Disbursement Deviation Modules**. The deviation module allows internal teams (Makers and Checkers) to record, review, and approve or reject special exceptions (deviations) on consumer loan applications.

Recent optimizations under **CRED-6074** focused on validation refactoring, batched notifications, Microsoft Teams channel integration, and UI/UX improvements to provide a more responsive and error-free experience.

---

### Module Architecture

The module is divided into two primary categories, each with its own UI section on the consumer application edit page:
1. **Credit Deviations** (`deviations.blade.php`): Focuses on underwriting exceptions (e.g., Credit Score, Income, Age, FOIR).
2. **Disbursement Deviations** (`disbursement-deviations.blade.php`): Focuses on post-approval funding exceptions.

Both categories are powered by a shared backend controller (`ApplicationDeviationController.php`) which handles CRUD operations, logging, and status transitions.

---

### Workflow & Rules

#### 1. Stage Blockers (When can deviations be added?)

- **Credit Deviations**:
  - **Blocked Early Stages**: Cannot be added if the application is in *In Process, Incomplete Form, Form Completed, or Waiting For Documents*.
  - **Blocked Late Stages**: Cannot be added if the application is in *Disbursement Checklist Done, Ready For Disbursement, Disbursement Query, Rejected, Aborted, Disbursed, Cancelled, Nach Registered, or Closed*.
  - **Allowed Stages**: Intermediate stages like *Waiting For Decision* or *Approved*.

- **Disbursement Deviations**:
  - Unrestricted by specific stage arrays in the frontend, but generally utilized post-approval during the disbursement checklist/query phases.

#### 2. Auto-Fill & Data Population

- **Credit Deviations**:
  - Automatically populates the `application_details` textarea when a deviation type is selected (e.g., pulls the actual Credit Score or Monthly Income from the database).
- **Disbursement Deviations**:
  - **Removed (CRED-6074)**: Auto-population logic was removed. The `application_details` field remains blank by default to prevent unwanted concatenation (e.g., appending address pincode strings automatically).

#### 3. Maker / Checker Action Flow

- **Maker (Creator)**:
  - Selects the deviation type, adds details, and assigns a specific **Checker**.
  - A deviation is created in a `Pending` state.
  - A batched email notification is sent to the assigned Checker(s).
- **Checker (Approver)**:
  - Receives an email notification with a direct link to the deviation.
  - Can click **Approve** or **Reject**.
  - **Mandatory Comments**: The UI uses SweetAlert2 to prompt the Checker for a mandatory comment before the status can be updated.
  - Upon submission, the UI displays a loading spinner to prevent duplicate requests.

#### 4. Notifications & MS Teams Integration

- **Email Notifications**:
  - Handled via `Deviation-Mail` (for new deviations) and `Deviation-Status-Mail` (for status updates).
  - Employs batched emails (`whereIn('id', $checkerIds)`) to minimize SMTP execution time.
- **Microsoft Teams Integration**:
  - Only triggers for **Disbursement** deviations.
  - Routes notifications to the `Slack::$CASE_REVIEWS` Teams webhook channel.
  - Credit deviations do not currently send Slack/Teams webhook notifications.

---

### Technical Impact — Files Changed / Maintained

| File | Type | Description |
|------|------|-------------|
| `app/Http/Controllers/Admin/ApplicationDeviationController.php` | Core Controller | Handles `saveDeviation`, `getLogs`, `getStatus`, and batched `sendNotification()`. |
| `resources/views/admin/consumer-application/sections/deviations.blade.php` | View (Credit) | Frontend logic for Credit Deviations, including stage blocker constants. |
| `resources/views/admin/consumer-application/sections/disbursement-deviations.blade.php` | View (Disbursement) | Frontend logic for Disbursement Deviations, featuring loading states and blank default details. |
| `app/ApplicationDeviation.php` | Model | Eloquent model for deviation records. |
| `app/DeviationType.php` | Model | Eloquent model for deviation types (Credit vs Disbursement). |
| `app/Slack.php` | Service | Manages webhook payloads. Refactored to remove staging tokens and route to the correct MS Teams channels. |

---