# 0017. Shifts and Z-reports

- Status: Accepted
- Date: 2026-10-27

## Context

At the end of the day a shop counts its cash drawer and prints a Z-report: what was sold, what
tax was charged, how customers paid, and whether the drawer is over or short. A shop may have
several devices, and a table opened before a shift change may be paid after it. Each sale has
to be counted exactly once, without coordination between devices and without a server.

## Decision

- **A shift belongs to one device and its cash drawer.** It opens with a float, records cash
  paid in and out with a reason, and closes with the cash counted. Each device numbers its own
  shifts 1, 2, 3…; the number is the Z-report number.
- **Shifts are events** (`shift.opened`, `shift.cash_movement`, `shift.closed`), projected like
  orders: pure, idempotent, and an event that cannot apply is kept as a conflict.
- **Money is reported where it moved; a sale is reported where it closed.** Payments, closes and
  refunds carry the `shiftId` of the device's open shift. A Z-report counts:
  - **sales** (bill totals, SST per code and rate, service charge, discounts, voided lines):
    from the orders that **closed** in the shift;
  - **payments, refunds and cash rounding:** from those taken **in** the shift.

  An order opened in one shift and paid in the next is reported once, in the second.
- **The report is computed, never stored.** `shiftReport()` in `packages/core` rebuilds it from
  the events, so a reprint, the hub and the back office all get the same numbers.
- **Expected cash** is the opening float plus cash payments (after rounding and change), minus
  cash refunds, plus cash in, minus cash out. The variance is counted minus expected.
- **Settings (ADR 0014):**
  - each device can require an open shift to take payments (on by default, so every sale lands
    in a Z-report; order-taking phones can turn it off);
  - each outlet can choose a blind close (off by default), which hides the expected cash while
    counting and on X-reports, until the Z-report prints.

## Consequences

- Payments taken with shifts switched off belong to no shift. They still count in daily sales
  reports (M7), but in no Z-report.
- Open orders do not block closing a shift; the close screen warns about them, and they count in
  whichever shift they are paid in.
- `shiftId` was added to three existing payloads as an optional field without a schema version
  bump, which was safe before any release. Later payload changes need a new schema version.
- The event store copies `payload.shiftId` into an indexed column, so a report reads one shift's
  events without scanning the log.