# Bureau BRE Flow Modification: Waiting For Documents

---

## CRED-6227 — 2026-06-11

### Overview

Added support for capturing specific documents (such as Consent Logs, Co-applicant Consent Logs, Electricity Bill, and Bank Statement) when an application transitions to the `waiting for documents` state. This functionality integrates with the AutoDecision flow to conditionally bypass the full BRE job and trigger pure Rejection BRE logic when non-consent documents are still pending. It also programmatically appends necessary documents when the system automatically shifts an application to this status during the SSE MConnect flow.

---

### Logic Added / Changed

#### 1. New Documents in Frontend
- **Dropdown Updates:** Updated the `mandatory_document_list` dropdown `name` attributes from `mandatory_document_list` to `mandatory_document_list[]` to support multi-select.
- **New Options:** Appended **Applicant Consent** (`consent_logs`) and **Co-applicant Consent** (`co_app_consent_logs`) to the frontend dropdown menus.

#### 2. Data Persistence (Backend)
- **Table:** `consumer_application_element`
- **Column:** `mandatory_document_list`
- **Persistence Method:** Instead of introducing a new schema column, the architecture natively leverages the existing `saveMandatoryDocument` AJAX endpoint. Selected documents are persisted directly into the `mandatory_document_list` array format.

#### 3. AutoDecision Job Customization
- **Triggers:** The AutoDecision flow evaluates constraints in `ConsentController.php` (Consent trigger) and `ConsumerApplicationController.php` (20 fields submission trigger).
- **Condition A (Pure Consent):** If the application status is `waiting for documents` and the `mandatory_document_list` only contains consent-related items (`consent_logs`, `co_app_consent_logs`) or is empty, the standard `EventAutoDecision` executes the full AutoDecision algorithm.
- **Condition B (Mixed/Other Documents):** If `mandatory_document_list` contains items *other* than consent documents, the full AutoDecision job is bypassed. Instead, the soft bureau report is fetched and the system directly invokes Rejection BRE logic (`autoReject()` for Applicant, `autoRejectCoApplicantJSONBRE()` for Co-applicant). 
  - **Rejection State Update:** The `autoReject()` method inherently evaluates the Rejection BRE rules, dispatches webhook events, and sends rejection emails, but purposely does not mutate the application's `state` in the database. The surrounding controllers (in `ConsentController` and `ConsumerApplicationController`) now explicitly capture the boolean return value from `autoReject()`. If the applicant is rejected, the system manually updates the application `state` to `rejected` and records a transition entry in the `status_logs` table. Co-applicants are excluded from this manual state update by design.

#### 4. Automatic Consent Requirement Removal
- **Mechanism:** A public static helper method `removeConsentFromMandatoryList` was added to `ConsentController.php`.
- **Logic:** Whenever the system generates and logs the `consent_logs` or `co_app_consent_logs` document successfully, the controller flow explicitly invokes this helper method. The method queries the `consumer_application_element` row and actively scrubs the specified document requirement from the `mandatory_document_list` array. This ensures that the requirement is cleared instantly without manual intervention during both the UI consent flow (`addConstantDocument` in `ConsentController`) and the E-Sign API flow (`saveConsent` in `ConsumerApplicationController`).

#### 5. Programmatic "Waiting for Documents" Override
- **SSE Flow Context:** When the system pushes an application to `waiting for documents` natively without manual UI interaction (in the `sseSetStatus` method), a programmatic hook ensures the missing documents are explicitly persisted to block downstream flows.
- **Mappings:** 
  - If the generated system comment flags `"Electricity bill validation failed"`, the `electricity_bill` requirement is appended to the `mandatory_document_list`.
  - If the system comment flags `"Bank Statement required"`, the `bank_statement` requirement is seamlessly appended.

#### 6. Pirimid Banking Integration Enhancements
- **Conditional Approval BRE Bypass:** Within `Pirimid.php`, if the application state is `waiting for documents` and the `mandatory_document_list` contains documents other than `bank_statement` (or consent logs), the system evaluates a flag (`$skipApprovalBre`) to bypass the Approval BRE. The Rejection BRE is allowed to execute cleanly prior to this block.
- **Automatic Bank Statement Scrubbing:** A private helper `scrubBankStatementFromMandatoryList` was added to `Pirimid.php`. When the analytics webhook returns successfully, this method actively queries the `consumer_application_files` table to confirm the upload of bank statements for the specific applicant. It then dynamically scrubs any variation of `bank_statement` from the `mandatory_document_list`.

#### 7. Bug Fixes
- **autoBRE `count()` Fatal Error:** Fixed a syntax issue in `app/Http/Controllers/Admin/autoBRE.php`'s `checkAutoBREStatus` method where `count(null)` was executing on an empty Eloquent `first()` query. The validation now properly handles the object without assuming an array collection.

---

### Impact — Files Changed / Added

| File | Type | Change |
|------|------|--------|
| `resources/views/admin/modal/email_reminders.blade.php` | Modified | Updated mandatory document dropdown to support multi-select and added consent options |
| `resources/views/admin/consumer-application/edit.blade.php` | Modified | Updated mandatory document dropdown to support multi-select and added consent options |
| `resources/views/admin/bnpl-application/edit.blade.php` | Modified | Updated mandatory document dropdown to support multi-select and added consent options |
| `resources/views/admin/consumer-application/index.blade.php` | Modified | Updated jQuery validation references to target the new `mandatory_document_list[]` array name selector |
| `resources/views/admin/consumer-application/edit_v1.blade.php` | Modified | Updated mandatory document dropdown to support multi-select and added consent options |
| `app/Http/Controllers/ConsentController.php` | Modified | Added `removeConsentFromMandatoryList` helper method to automatically scrub consent documents; called this helper inside `addConstantDocument`; evaluates `mandatory_document_list` under the `waiting for documents` status to conditionally bypass AutoDecision; added manual `state` and `status_logs` update upon successful applicant `autoReject()` evaluation |
| `app/Http/Controllers/Admin/ConsumerApplicationController.php` | Modified | Called `removeConsentFromMandatoryList` inside `saveConsent` to auto-clear requirements during Digio flows; `getEditPostConsumerApplication` evaluates `mandatory_document_list` to bypass full AutoDecision; added manual `state` and `status_logs` update upon successful applicant `autoReject()` evaluation |
| `app/Console/Commands/AutoDecision.php` | Modified | Hooked `sseSetStatus` to explicitly append `electricity_bill` or `bank_statement` to `mandatory_document_list` whenever it triggers a programmatic transition to `waiting for documents` |
| `app/Pirimid.php` | Modified | Added `$skipApprovalBre` logic to bypass Approval BRE if non-bank-statement docs exist; added `scrubBankStatementFromMandatoryList` to remove bank statement requirements upon analytics webhook success |
| `app/Http/Controllers/Admin/autoBRE.php` | Modified | Fixed PHP 7.2+ `count()` fatal error inside `checkAutoBREStatus` by evaluating Eloquent objects correctly |