# Disbursement Update Documentation

## Overview
This update extends LendCore's loan disbursement capabilities to support both B2C and direct manual disbursement paths, with explicit support for full and net-of-interest modes. It also ensures the user, officer, and mobile API surfaces are aware of the chosen disbursement mode and method.

## Key Improvements

- Added support for `full` and `net` disbursement modes in both:
  - `B2C` / M-Pesa disbursement flows
  - direct `manual` disbursement flows
- Added explicit metadata tracking for disbursement transactions, including:
  - `disbursement_mode`
  - `disbursement_method`
  - `net_amount`
  - `manual_admin_disbursement`
- Exposed disbursement metadata in the mobile API via `LoanResource` and `TransactionResource`.
- Updated user and officer loan detail pages to display disbursement mode, method, and amount.
- Fixed M-Pesa B2C net disbursement so the actual requested amount is sent when `net` mode is selected.

## Files Changed

- `app/Models/Loan.php`
  - Added `latestDisbursementTransaction()` relationship to fetch the most recent disbursement transaction.

- `app/Services/LoanService.php`
  - Updated `disburseLoan()` to use `disbursementAmount` for B2C sending.
  - Added rich metadata to B2C and manual disbursement transaction records.
  - Ensured manual disbursement creates a completed transaction and activates the loan.

- `app/Services/TransactionService.php`
  - Added metadata-aware `recordDisbursementTransaction()` support.

- `app/Http/Resources/LoanResource.php`
  - Added `disbursement` payload object to API loan representations.

- `app/Http/Resources/TransactionResource.php`
  - Exposed disbursement metadata on transaction responses.

- `app/Http/Controllers/Api/LoanController.php`
  - Loaded `latestDisbursementTransaction` for API loan listing and details.

- `app/Http/Controllers/Web/LoanController.php`
  - Passed `disbursementTransaction` into the user loan detail view.

- `app/Http/Controllers/Officer/OfficerDashboardController.php`
  - Passed `disbursementTransaction` into the officer loan detail view.

- `resources/views/user/loans/show.blade.php`
  - Added disbursement summary for users showing method, mode, and amount.

- `resources/views/officer/loans/show.blade.php`
  - Added disbursement mode and method display to officer loan details.

## Behavior Notes

- `full` mode disburses the original loan principal amount.
- `net` mode disburses `principal - interest` and requires that the resulting amount is greater than zero.
- Manual disbursement is restricted when a pending B2C disbursement exists.
- Manual disbursements are recorded as completed transactions and immediately activate the loan.

## API Impact

- API `GET /loans` and `GET /loans/{loan}` now include:
  - `disbursement.status`
  - `disbursement.amount`
  - `disbursement.net_amount`
  - `disbursement.method`
  - `disbursement.mode`
  - `disbursement.reference`
  - `disbursement.mpesa_transaction_id`
  - `disbursement.processed_at`
- Transaction details now expose `disbursement_mode`, `disbursement_method`, and `manual_admin_disbursement`.

## Flutter Mobile Integration

- Updated the Flutter loan model in `lib/data/model/loan_model.dart` to parse the new `disbursement` object from the backend.
- The Flutter user loan detail page in `lib/presentation/screen/loans/loan_details_screen.dart` now displays:
  - disbursement status
  - disbursement mode (`full` or `net`)
  - disbursement method (`b2c` or `manual`)
  - disbursed amount and net amount when applicable
  - processed timestamp when available
- The loan list card now surfaces mode/method metadata for quick user visibility.
- These updates preserve the existing loan data model and UI layout while adding the new manual/net disbursement metadata.

## Validation

- PHP syntax validation was performed on modified PHP files after implementation.

## Recommended Next Steps

1. Review existing M-Pesa callback handlers to ensure the callback metadata remains consistent.
2. Test both B2C and direct manual disbursement flows with `full` and `net` modes.
3. Confirm mobile clients consume the new `disbursement` payload correctly.
4. Consider adding UI alerts or notes in the admin loan page for manual-disbursement-specific warnings.
