# Sales, Deals and Financing (F&I) module: install notes

Builds on the Core, Inventory and CRM packages (it uses leads, customers, vehicles, tax rates, payment methods, document numbering,
the inventory status service and the CRM alert notification). Needs PHP extensions `bcmath` and `gd` (photo uploads); `exif` is optional (fixes sideways phone photos).

## 1. Copy files
Copy `app/`, `config/deals.php`, `database/`, `resources/`, `routes/deals.php`, `tests/` into the app.
These files REPLACE earlier versions: `config/navigation.php`, `database/seeders/DatabaseSeeder.php`.

## 2. Wire up
```php
// end of routes/web.php
require __DIR__.'/deals.php';
```
```bash
php artisan migrate
php artisan db:seed --class=DealsPermissionSeeder
php artisan test --filter="DealsTest|FinanceCalculatorTest"
composer require barryvdh/laravel-dompdf     # optional: enables "Download PDF"; without it that link opens the print view
```

## 3. Before first use
- **Agreement wording is a DRAFT** in `config/deals.php`. Have your lawyer approve it. Change `version` whenever the text changes; each issued agreement keeps the wording it was issued with.
- **Tax.** Deals use a tax rate from the `tax_rates` table (VAT 16%, zero-rated, exempt are seeded) and the "prices include tax" switch.
  Confirm with your accountant how VAT applies to the vehicles you sell (including used imports) and what KRA eTIMS requires.
  The document table already has `etims_invoice_no`, `etims_qr` and `etims_status` columns, but **no eTIMS connection is built**.
- **E-signatures.** The built-in signing pad is live (drawn signature, hash-bound to the document). The `esign_provider/reference/status` columns are there for an external provider; none is connected.
- **Discount policy** (settings, per company or branch): `sales.discount_approval_threshold_percent` (5), `sales.discount_director_threshold_percent` (10),
  `sales.min_deposit_percent` (20). A discount also needs approval if it takes the price below the vehicle's minimum price (manager) or below its landed cost (director).
- **Roles.** Defaults in `DealsPermissionSeeder`: Branch Manager approves up to the director limit and issues everything, but **cannot approve director-level discounts or release a vehicle with a balance** (those go to Super Admin).
  Sales Executives see their own deals, issue pro-formas and agreements, and manage trade-ins. Finance sees all deals, issues tax invoices and (with the core grants) records payments. Change the grants to fit how you work.

## How it fits together
- **Calculator:** `FinanceCalculator` is the only place deal arithmetic lives. The page calls `POST /deals/calculate`; saving a deal calls the same class again, so the screen and the stored figures cannot disagree.
  Interest is reducing balance or flat; the "true yearly cost" lets a customer compare the two fairly.
- **Deal flow:** Draft, then (Pending approval), Approved (terms final, vehicle held), Confirmed (agreement signed by both and deposit paid), Completed (paid, gate pass used, vehicle sold, lead won) or Cancelled.
  Changing terms after approval is allowed only if the discount does not grow beyond what was approved.
- **Documents:** pro-forma, agreement, tax invoice, receipts (one per payment) and gate pass are frozen, encrypted snapshots with a number and an integrity hash. Change a deal and the old document is flagged "out of date"; void and reissue to change one.
- **Gate pass:** needs a confirmed deal, a fully signed agreement, full payment and a tax invoice. A Super Admin can release against a balance with a written reason, which is printed on the pass.
  Only the last four characters of the collector's ID are stored. The QR opens the pass (sign-in required) so the guard sees if it has been used or voided.
- **Trade-ins:** five areas scored 1 to 5 give a grade A to E, which sets the deduction from market value; the offer is a person's decision. The customer's loan balance is cleared out of the credit. Photos are re-encoded (location data removed) and kept on the private disk.
- **Payments:** recorded by method with a reference (mobile-money codes cannot be reused); overpayment is refused; reversing a payment voids its receipt and any unused tax invoice or gate pass.

## Known gaps
M-Pesa STK Push (payments here are recorded by hand), finance-partner and application tracking beyond the lender name and reference, eTIMS submission, an external e-signature provider,
CRM and deal widgets on the dashboard, and a margin report.
Not run in the authoring environment (no PHP available): run the migrations and tests before relying on it.