# Distributor Condo Commission — Phase 1 Plan

Live Prawn internal documentation for condo group-buy distributor assignment and commission reporting.

**Module:** `LivePrawn_CondoGroupBuy` only  
**Status:** Phase 1 implemented (code) — requires `setup:upgrade` to apply schema  
**Last updated:** 2026-07-07

---

## Purpose

When a distributor introduces a condo, admin assigns that condo group to the distributor. All **processing** and **complete** condo group-buy orders for that condo appear in a read-only commission report.

**Payout is manual/outside Magento.** No approve/paid/void workflow in Phase 1.

---

## Commission formula

Per product line only (shipping excluded):

```
commission_per_kg = max(0, customer_bought_price - distribution_tier_base_price)
line_commission   = commission_per_kg × qty
```

| Input | Source |
|-------|--------|
| **Customer bought price** | `sales_order_item.price` (condo group-buy line price) |
| **Distributor base price** | Catalog tier price for **Distribution customer group ID 4** |
| **Qty** | `sales_order_item.qty_ordered` (kg) |

**Example:** Customer RM48/kg, base RM35/kg, qty 10kg → (48−35)×10 = **RM130**

Starter and Master distributors both use **group 4** tier price in Phase 1.

---

## Distributor assignment (condo group)

Columns on `liveprawn_condo_group`:

| Column | Purpose |
|--------|---------|
| `distributor_customer_id` | Assigned distributor customer |
| `distributor_tier` | `starter` or `master` (auto from group 11/12) |
| `distributor_commission_active` | 1 = active, 0 = inactive |
| `distributor_commission_note` | Admin notes |

### Validation rules

- Assigned customer must be in **Starter Distributor (11)** or **Master Distributor (12)**
- Group 11 → tier `starter`; group 12 → tier `master`
- Commission active requires `distributor_customer_id`
- Other customer groups are rejected

### Admin location

**Live Prawn → Condo Group Buy → Condo Groups → Edit → Distributor Assignment**

---

## Commission report

**Menu:** Live Prawn → Condo Group Buy → **Distributor Condo Commission**

### Included orders

- `is_condo_group_buy = 1`
- Order status: **`processing`** or **`complete`** only
- Condo group: `distributor_commission_active = 1` and distributor assigned
- Product lines only (`product_type = simple`) — shipping excluded

### Excluded

- pending payment, pending, canceled, closed, holded, payment review
- Orders from condos without active distributor assignment
- Shipping / delivery fee amounts

### Filters

- Distributor
- Condo group
- Delivery batch date
- Order date from / to

### CSV export

Available from report page. Payout tracking is **manual outside Magento**.

---

## Important warning — assignment changes

> **Do not change distributor assignment mid-batch unless previous payout for that batch is already settled.**

Phase 1 does **not** snapshot distributor on the order. The report uses the condo group’s **current** assignment when calculated. Changing assignment retroactively changes which distributor appears on historical orders in the report.

---

## What Phase 1 does not include

- Order-level distributor snapshot
- Payout status in Magento (pending/approved/paid/void)
- Auto commission on order complete
- Starter/Master separate base prices (groups 11/12 tier prices)
- Checkout or storefront changes
- Restaurant commission integration

---

## Phase 2 backlog (separate approval)

1. Snapshot distributor on order placement
2. Persist commission lines with payout status
3. Starter/Master tier base prices (groups 11/12)
4. Admin approve/paid/void workflow
5. Auto-generate lines on order complete

---

## Related docs

- `docs/distributor-partner-program-phase-1.md`
- `docs/distributor-partner-admin-sop.md`

---

## Post-deploy commands (after Kenny approves)

```bash
cd /var/www/html/airbenih_stg
php bin/magento setup:upgrade
php bin/magento cache:clean config layout block_html full_page
```

Do **not** run `setup:di:compile` unless separately approved.