# Merchant Onboarding Risk Identification and Automation — Phase 1

---

## CRED-5992 — 2025-11-28

### Overview

This change introduces a standard risk-mitigation profile for every merchant onboarded through the Admin panel. The profile records the types of solar business and operating conditions that the merchant is set up to service. It gives Operations, Credit, and Business teams a consistent way to identify, at application level, whether a solar case fits the merchant's declared onboarding scope.

During merchant creation or editing, the user must capture five risk-mitigation attributes: PM Suryaghar registration, supported solar power types, supported solar customer categories, security-cheque requirement, and servicing locations. These settings are stored independently of the main merchant record, so the merchant profile remains available for review and can be updated without changing the core merchant schema.

When an application is saved, the system reads the selected merchant's risk profile and compares it with the application's solar details. It saves a snapshot of the result on that application's element record. The Admin application list then shows an informational tooltip when the application's solar power type, customer category, or installation location is outside the merchant's configured scope. This makes the mismatch visible while the team is reviewing the case, without automatically approving, rejecting, or otherwise changing the application's workflow state.

The snapshot is deliberately held against the application rather than calculated only at display time. Consequently, users can see the risk result that was evaluated when the application was last saved, while merchant-level setup continues to be managed separately for future application updates.

---

### Business Flow

#### 1. Configure the Merchant Risk Profile

While adding or editing a merchant, the Admin user must provide all five fields below. The form prevents submission if any field is missing.

| Risk attribute | Merchant setup options | Business purpose |
|---|---|---|
| PM Suryaghar registration | Yes / No | Records whether the merchant is registered under PM Suryaghar. |
| Solar power type | On-Grid, Off-Grid, Hybrid; one or more may be selected | Defines the solar installation types the merchant is onboarded to serve. |
| Solar category | Residential, Bharat MSME, Urban C&I (MSME), Housing Society; one or more may be selected | Defines the customer/installation segments the merchant is onboarded to serve. |
| Security cheque required | Yes / No | Records whether security cheques are part of the merchant's risk-mitigation arrangement. |
| Servicing locations | One or more states | Defines the states in which the merchant is onboarded to operate. |

For a new merchant, the profile is created immediately after the merchant is saved. For an existing merchant, saving the edit form updates the same profile or creates it if it was not already present. This ensures there is one current risk profile per merchant.

#### 2. Capture the Application Context

When the relevant solar application details are saved, the system takes the merchant selected for the application and evaluates its profile against the case. The three case attributes used for matching are:

- **Solar power type:** the application's On-Grid, Off-Grid, or Hybrid value.
- **Solar category:** the application's customer type/category.
- **Installation location:** the application's installation-address state, converted to its state code before comparison.

PM Suryaghar registration and the security-cheque requirement are also copied into the application risk snapshot. They represent merchant-level risk facts in Phase 1; they are not currently compared with separate application values.

#### 3. Evaluate Merchant Onboarding Suitability

The application receives a five-key risk result. Every key starts at `0` and is set to `1` when the corresponding merchant condition is satisfied or recorded.

| Risk result | How it is determined |
|---|---|
| `pm_surayaghar` | Copied from the merchant's Yes/No PM Suryaghar setting. |
| `security_cheque` | Copied from the merchant's Yes/No security-cheque setting. |
| `solar_power_type` | `1` only when the application's solar power type is among the merchant's selected power types. |
| `solar_category` | `1` only when the application's customer category is among the merchant's selected categories. |
| `solar_location` | `1` only when the application's installation-state code is among the merchant's selected servicing states. |

For example, if a merchant is configured for **On-Grid**, **Residential**, and **Maharashtra**, an Off-Grid residential case in Maharashtra is flagged as outside the merchant's power-type onboarding. An On-Grid Urban C&I case in Gujarat is flagged for both category and location.

#### 4. Save the Application Risk Snapshot

The result is stored as JSON in `consumer_application_element.merchant_risk_mitigation`. It is therefore associated with the individual application and available to the application-list query and other downstream consumers of the application element.

If no merchant risk profile exists, the system saves the default result with all five values at `0`. Operationally, merchants should be configured through the add or edit page before applications are evaluated so that this default does not represent an incomplete setup.

#### 5. Show the Application-List Message

On the Admin consumer-application index, the system combines this risk message with other existing case indicators, such as "Disbursement post installation" and "New merchant case." The message appears as a tooltip on the application row.

The current Phase 1 tooltip evaluates the three comparative fields only:

- `solar_power_type = 0` adds **"power type"**;
- `solar_category = 0` adds **"category"**;
- `solar_location = 0` adds **"location"**.

When one or more fail, the user sees a message in the form:

> Merchant not on-boarded for this power type, category and location

Only the failed parts are included, with natural language joining for one, two, or three failures. PM Suryaghar and security-cheque values are retained in the application snapshot but do not currently add their own tooltip text. The tooltip is an operational alert only; it does not block the application, change its status, or trigger decisioning automation in Phase 1.

---

### Logic Added / Changed

#### 1. Merchant Profile Persistence
- Added the `merchant_risk_mitigation` table and `MerchantRiskMitigation` model.
- The profile is one-to-one with a merchant (`merchant_id` is unique), supports soft deletion, and is deleted with its merchant through the foreign-key relationship.
- Multi-select values are stored as comma-separated strings; the edit flow converts them back to arrays so the saved selections are pre-populated in the form.

#### 2. Required Merchant-Form Validation
- The add and edit merchant forms require all five risk-mitigation fields.
- Add and edit requests validate the two Yes/No fields and require at least one selected value for each of power type, category, and location.
- The add controller includes a defensive presence check and returns the user to the form with an error message if the profile is incomplete.

#### 3. Application-Level Evaluation
- The application save flow retrieves the selected merchant's risk profile.
- It compares application power type and customer category against the merchant's allowed lists.
- It resolves the application installation-state name to a state code and compares that code with the merchant's selected servicing locations.
- The resulting five-field JSON snapshot is saved to the application element.

#### 4. Application Index Visibility
- The application-list data preparation exposes the decoded risk snapshot for each result.
- The list-view tooltip builds a concise message for out-of-scope power type, category, and/or location.

#### 5. Deprecated Field Removal (TO be done at a later date except the babyready_user_id which is already modified)
- The following legacy fields are being removed from the `consumer_application_element` table: `loan_applied_for`, `loan_applied_for_mobile`, `loan_applied_for_relation`, `onefin_id`, `onefin_lead_id`, and `babyready_user_id`.

---

### Impact — Files Changed / Added

| File | Type | Change |
|---|---|---|
| `database/migrations/2025_11_24_191130_create_merchant_risk_mitigation_table.php` | Added / modified | Creates the merchant risk-profile table, including the five attributes, soft deletes, unique merchant relationship, and cascade delete. |
| `app/MerchantRiskMitigation.php` | Added | Defines the risk-profile model, casts the Yes/No fields, and provides the merchant relationship. |
| `app/Merchant.php` | Modified | Adds the one-to-one `risk_mitigation` relationship. |
| `app/Http/Requests/AddMerchantRequest.php` | Modified | Makes the five risk-mitigation fields mandatory for new merchants and supplies readable validation names. |
| `app/Http/Requests/EditMerchantRequest.php` | Modified | Makes the five risk-mitigation fields mandatory while editing merchants. |
| `resources/views/admin/merchant/add.blade.php` | Modified | Adds the required merchant-onboarding risk fields to the create form. |
| `resources/views/admin/merchant/edit.blade.php` | Modified | Adds the same fields to the edit form and displays saved multi-select values. |
| `app/Http/Controllers/Admin/MerchantController.php` | Modified | Validates, creates, loads, and updates the merchant risk profile. |
| `app/ConsumerApplicationElement.php` | Modified | Casts `merchant_risk_mitigation` as an array for application use. |
| `app/Http/Controllers/Admin/ConsumerApplicationController.php` | Modified | Calculates and stores the application risk snapshot; exposes it to application-list data. |
| `resources/views/admin/consumer-application/index.blade.php` | Modified | Displays the out-of-scope merchant-onboarding tooltip on application rows. |

---