# Sales · MM2H

**Nav:** Sales hub (`SalesTabs`) → **MM2H** (between Memberships and Property Booking) → three stages: **Applicants** (the pipeline, `/manage/mm2h/applicants`) → **Approvals** (`/manage/mm2h/approvals`) → **Families** (`/manage/mm2h/families`). `/manage/mm2h` redirects to stage 1, query preserved. One application: `/manage/mm2h/applications/{uuid}`.

## What it does

Runs the **Malaysia My Second Home (MM2H)** product line — the long-stay visa PropertyLab refers to a
licensed agent — end to end, with all three stages of the standard funnel built from day one
(2026-10-11, owner request):

| Stage | Label | What it is |
|---|---|---|
| Pipeline | **Applicants** | `mm2h_applications` rows Immigration has not answered — Enquiry → Documents → Submitted. |
| Sales | **Approvals** | The same rows from Immigration's **approval letter** on — Approved → Endorsed — plus Rejected / Withdrawn / Lapsed, a filter away. This is where the commission is earned. |
| Referral & Repeat | **Families** | Approved applicants, with the **dependants** they added to the pass and the applicants they **referred** (and the commission those brought). |

**The money.** Each tier pays PropertyLab a fixed commission per approved applicant — the figure the
owner gave on 2026-10-11, seeded as `mm2h_tiers` rows and editable from the Applicants stage's
**Tiers** button:

| Tier | Commission PropertyLab receives | Published 2024 terms (reference only) |
|---|---|---|
| Silver | RM 10,000 | USD 150k deposit · RM 600k property · 5-year pass |
| Gold | RM 12,000 | USD 500k deposit · RM 1M property · 15-year pass |
| Platinum | RM 18,000 | USD 1M deposit · RM 2M property · 20-year pass |

The terms columns are for the applicant's reference and are used in no calculation. **Confirm the
three commission figures and the terms against the agent agreement** — they were keyed from the
owner's message and the published rules, not from a contract.

## How it works

**One table serves all three stages.** A row is added as an Enquiry with the same form it is edited
with; "moving to Approvals" is a status change (`advance`), never a copy.

**The ladder** (`Mm2hApplication::NEXT_STATUS` is the one place the order lives; the Show page prints
the next state the server sent):

| Status | Stage | Stamp |
|---|---|---|
| 1 Enquiry | Applicants | `created_at` |
| 2 Documents | Applicants | `documents_at` |
| 3 Submitted | Applicants | `submitted_at` — **refused without an applicant** (the application is filed in somebody's name) |
| 4 Approved | Approvals | `approved_at` — **the commission is earned** |
| 5 Endorsed | Approvals | `endorsed_at` — the pass is in the passport; terminal |
| 6 Rejected | Approvals (ended) | `ended_at` + reason — Immigration's answer, so only from the pipeline |
| 7 Withdrawn | Approvals (ended) | `ended_at` + reason — the applicant's choice, from any live state |
| 8 Lapsed | Approvals (ended) | `ended_at` + reason — approved but never completed; only from Approved, so a clawback has somewhere to be recorded |

- **Why approval, not endorsement, earns the commission:** the licensed agent collects its own fee in
  two parts — a deposit on signing, the balance within days of the Conditional Approval Letter — so
  that letter is when it can pay its referrers. Endorsement comes months later (fixed deposit, entry,
  Immigration), and the property purchase up to 12 months after that. Each move is a button a person
  presses, so an agent that pays on a different trigger just has the button pressed later.
- **Step back** (`stepBack`) undoes one move and clears the stamp being left. **Reopen** (`reopen`)
  puts an ended row back at the step its stamps say it had reached. Each row carries `end_options`
  — the ways out it may take — built from the same rule the repository refuses by, so the End modal
  never offers a refused move.
- **Abilities are decided on the server, once.** `PresentsMm2h::mm2hAbilities()` returns the `can` map
  every row carries (`edit / advance / step_back / end / reopen / assign / payout / delete`); the
  lists, the Show page and the modals draw only what it allows.

**The commission is the tier's figure, copied.** `Mm2hApplicationRepository::create()` writes
`commission_amount` from the tier the day the row is keyed; editing a tier prices the *next*
applicant, never an existing deal (the Tiers modal and the flash say so). Changing a row's tier on
edit re-copies it (the deal was keyed on the wrong tier). A signed, explained
`commission_adjustment` sits beside it — the booking model — and `commissionTotal()` is the sum.

**It divides like a booking** ("like how we do for property", owner 2026-10-11). The row carries a
`closing_mode_id` and `mm2h_application_assignments` rows (role key + admin + `role_share`), the
same shape as `engagement_assignments`; the maths is **`Src\Engagement\Support\CommissionSplit`**,
extracted from `Engagement::commissionBreakdown()` that day so both lines run one algorithm. With
no mode stamped, the manual-default mode applies (never the payment default — there is no project-fee
receipt). The **Team & split** modal mounts the shared `CommissionSplitEditor` with the pot as
`autoCommission`, an `autoLabel` naming the tier instead of the rate × price line, and `adjustable`
on, so the adjustment is offered without a booking. The assign endpoint takes the engagement Assign
modal's payload, validated by the same two traits (`ValidatesRoleAssignment`,
`ValidatesCommissionAdjustment`).

**Payout** mirrors a booking commission claim: `claimed_at / claimed_amount / claim_reference` (the
invoice on the agent) and `paid_at / paid_amount` (what arrived); the state (awaiting / part-paid /
paid) and the balance are derived against the total. Refused until the row is Approved, Endorsed or
Lapsed (a clawback).

**Dependants are information, not money.** `dependants_count` + `dependants_note` feed the Families
stage; the commission is flat per applicant (owner, 2026-10-11 — no agent fee table found lists a
per-dependant fee). If an agent ever pays extra per family member, add a money line then.

**Sales dashboard.** `Manage\Sales\DashboardController` counts the approved + endorsed applications
as the `mm2h` stream (commission total, this month by `approved_at`, count) and merges them into the
recent-sales list, scoped like the other streams to the leads the viewer may see.

**Export.** `GET applications/export?stage=applicants|approvals` + the list's filters →
`App\Exports\Mm2hApplicationsExport` (`FromQuery`, id tiebreaker). The two lists share one
`ApplicationQueryRequest`; the stage scope is applied by the controller, never as a filter.

**Permissions.** Reading the line needs `view-sales`; every write needs `manage-sales` (routes). No
new permission, so nothing to seed.

## Related files

**Backend**
- `src/Mm2h/Mm2hApplication.php` — statuses, ladder, money, payout state, `generateRef()` (MM-YYYY-NNN)
- `src/Mm2h/Mm2hTier.php`, `src/Mm2h/Mm2hApplicationAssignment.php`
- `src/Mm2h/Repositories/Mm2hApplicationRepository.php` — create / update / advance / stepBack / end / reopen / assign / payout / delete
- `src/Mm2h/Repositories/Mm2hTierRepository.php`
- `src/Engagement/Support/CommissionSplit.php` — the shared split maths (also used by `Engagement`)
- `app/Http/Controllers/Concerns/PresentsMm2h.php` — stage scopes, `stageCounts`, the row shape, abilities, end options
- `app/Http/Controllers/Manage/Mm2h/ApplicantsController.php`, `ApprovalsController.php`, `FamiliesController.php`, `ApplicationsController.php` (show + every write + export), `TiersController.php`
- `app/Http/Requests/Manage/Mm2h/ApplicationQueryRequest.php`, `Applications/{Store,Update,End,Assign,Payout}Request.php`, `Tiers/{Store,Update}Request.php`
- `app/Exports/Mm2hApplicationsExport.php`
- `app/Http/Controllers/Manage/Sales/DashboardController.php` — the `mm2h` stream

**Frontend**
- `resources/js/Components/SalesTabs.vue` — the `mm2h` main tab + its three stages; `Layouts/ManageLayout.vue` `SALES_PREFIXES`
- `resources/js/Pages/Manage/Mm2h/Applicants.vue`, `Approvals.vue`, `Families.vue`, `Applications/Show.vue`
- `resources/js/Pages/Manage/Mm2h/Partials/ApplicationsTable.vue` (the shared list), `ApplicationForm.vue` + `ApplicationFormModal.vue`, `AssignTeamModal.vue`, `PayoutModal.vue`, `EndModal.vue`, `TiersModal.vue`, `badges.js`
- `resources/js/Components/Sales/CommissionSplitEditor.vue` — `autoLabel` + `adjustable` props (additive)
- `resources/js/Pages/Manage/Sales/Dashboard.vue` — the `mm2h` stream

**Migrations**
- `2026_10_11_000001_create_mm2h_tiers_table.php` (seeds the three tiers as literals)
- `2026_10_11_000002_create_mm2h_applications_table.php`
- `2026_10_11_000003_create_mm2h_application_assignments_table.php`

**Routes** — `routes/web.php`, the `mm2h` group (`manage.mm2h.*`), beside Renovation's.

**Tests** — `tests/Feature/Manage/Mm2h/ApplicationWorkflowTest.php`; `tests/Feature/Engagement/CommissionShareTest.php` still covers the extracted split maths from the engagement side.
