ERP/docs/PILOT_READINESS.md

# Pilot readiness changes

This branch (`fix/pilot-readiness`) closes the gaps found when the MVP was
reviewed against `PRD.md` and `REVIEW.md`. This page records what changed,
the decisions taken along the way, and what is still open.

## What changed

### Tenant isolation and roles (PRD 5.1)
- Every role-limited API route goes through `authorize()` in
  `src/lib/server/auth.ts`: **401** when signed out, **403** for the wrong
  role. Cashiers can no longer read profit, expenses or purchases, or
  record expenses and purchases. Only the owner creates or edits products
  and prices.
- `PATCH /api/users/:id` deactivates and reactivates staff (managers: only
  their own cashiers). Deactivating or moving a user revokes their device
  sessions.
- `PATCH /api/branches/:id` renames a branch (owner only).
- Login and token refresh refuse an inactive or `SUSPENDED` business.
- Public signup refuses any address in `PLATFORM_ADMIN_EMAILS`.
- Ids in query strings and bodies are validated (400, not a 500), inventory
  routes check the product belongs to the tenant, and reconciliation
  lookups are tenant-scoped.

### Stock ledger and transfers (PRD 5.2)
- `StockMovement` is the ledger: a branch's stock of a product is the sum
  of its movements. Each movement names its cause, and `(type, refId)` is
  unique, so a replayed sale or retried transfer never moves stock twice.
- Sales and confirmed M-Pesa payments deduct stock; purchases of a
  catalogue product add it.
- `POST /api/stock/transfers` moves stock between branches.
  `POST /api/stock/adjustments` records opening stock, breakage and
  physical counts. `GET /api/stock` returns stock per branch with LOW/OUT
  flags (per-product `lowStockThreshold`, default 10).
- The admin **Stock** page (`/admin/stock`) covers all of this, plus the
  existing morning dispatch and evening count. The dashboard shows stock
  on hand per branch.

### Offline POS and sync (PRD 5.3, 5.5)
- `POST /api/transactions/cash` answers each sale with `saved`,
  `duplicate` or `rejected`. Previously a replayed sale was skipped
  silently, the device never marked it synced, and once more than 100 rows
  piled up every sync failed.
- The device queue (`src/lib/offlineQueue.ts`) is keyed by cashier and
  branch, sends only the signed-in cashier's sales, chunks to 50 per
  request, and stops retrying rejected sales (they are shown to the
  cashier instead).
- A service worker (`public/sw.js`) caches the app shell, and the last
  session and product list are kept on the phone, so the terminal opens
  and sells with no network.
- Sales can contain several products, the customer phone is optional for
  cash, and the terminal shows a printable receipt.

### Other
- "Today" and "this month" follow Africa/Nairobi, not the server's UTC
  clock (`src/lib/server/businessDay.ts`).
- M-Pesa is behind `FEATURE_MPESA` (off by default; out of scope for the
  pilot per PRD section 4).

## Decisions taken

| Decision | Why |
|---|---|
| Offline sales are always accepted, even if they take stock below zero. | The sale already happened. Refusing it would lose real cash. Negative stock is shown on the Stock page and fixed with a physical count. |
| Transfers are refused when the sending branch lacks the stock. | Transfers are made online by a manager, so they can be checked. |
| The server price is authoritative; a different price shown on the device is kept (`clientUnitPrice`) and flagged (`priceMismatch`). | Trusting the device's price would let a cashier under-charge. Overwriting it silently would hide a cash discrepancy. |
| A queued sale stays with the branch where it was recorded, even if the cashier has since moved. | That is where the stock left and the cash was taken. |
| A product deactivated while a phone was offline is still recorded at its price. | Same reason as the first row: the sale happened. |

## Rolling out to an existing database
- No migration is needed: new fields have defaults, and Mongoose creates
  the new indexes on start-up.
- Existing branches start with **no stock on record**. Before the pilot,
  each branch should record an opening count on the Stock page.
- Cashiers' phones upgrade their offline queue automatically; any unsynced
  sales from the old version are sent on the next sync.

## Testing
- `npm test` runs 37 API tests against an in-memory MongoDB, covering role
  enforcement, tenant isolation for sales, stock and transfers, suspension,
  the sync protocol (including a 120-sale backlog replayed twice), and the
  business day.
- The offline flow was also checked end to end in headless Chrome: sign
  in, stop the server, reload the terminal, record two sales, restart the
  server, confirm they sync once and deduct stock.

## Still open
- **Removing a branch.** Branches can be renamed but not removed. Someone
  needs to decide what happens to a removed branch's stock and history.
- **Setting branch prices.** Branch price overrides are applied everywhere,
  but there is no screen or API to set them yet.
- **Global email and phone uniqueness.** One person cannot work for two
  businesses, and signup reveals whether an address is already registered.
- **Isolation by convention.** Tenant filters are still written per route.
  The tests cover the sales, stock, transfer and access paths, not every
  route.
- **Concurrent transfers.** Two transfers submitted at the same moment
  could together send more than the branch holds.
- **Cash-basis profit.** The profit report counts all purchases in the
  period as cost of goods.
- **M-Pesa, if turned on.** Only one product per payment. A prompt that
  times out still needs a manual check before taking cash.
- **Not modelled yet:** invites and email verification, empty-bottle and
  deposit tracking, home-screen icons for the PWA.