# CONTEXT.md — domain glossary

Terms the team and the code use, one meaning each. When a word here clashes with a
table name or an older label in the UI, this file wins for new code, docs and specs.
Decisions that are hard to reverse are in `docs/adr/`.

## Orders

**Combined Order** (`combined_orders`, also "checkout", "purchase" in the rating module)
: Everything the customer bought in one checkout. Every checkout creates exactly one,
  on web and in the app, and every `orders` row belongs to one (0 orphans in the
  2026-10-19 copy). It holds what the checkout shares: the shipping address
  (`shipping_address`), the shipping cost (`shipping_cost`, charged once), the coupon
  (`coupon_*`), the Paymera payment (`payment_id`) and the grand total including
  shipping. Its id is the **invoice number** (`invoice_number()`), and it is the unit of
  an order rating. A Combined Order may span several sellers by design: that is why it
  is split into Child Orders.

**Child Order** (`orders`)
: One seller's share of a Combined Order: one row per seller per checkout. It has its
  own `code`, delivery status, payment status, payment method, seller confirmation,
  staff follow-up (Confirm / Deliver Orders) and Kapitano Logistic handover. Sellers,
  staff and couriers work on Child Orders; customers used to see them as separate
  "orders" on `/purchase_history`.

**Coupon of a Combined Order** (agreed 2026-10-20)
: One coupon per checkout. Its minimum and value are judged on the total of the whole
  Combined Order (products + tax of every live Child Order, never shipping), never on one
  Child Order alone, and customers see it once, on the Combined Order's totals. The
  per-Child-Order amount (`orders.coupon_discount`) is a bookkeeping split so each seller
  order has an amount to collect and settle. A Single Order's coupon applies to that
  order. See ADR 0003.

**Single Order**
: A Combined Order with exactly one Child Order (1,322 of 1,604 checkouts, 82%, in the
  2026-10-19 copy). It is not a separate record type and has no column of its own: it is
  the one-child case of a Combined Order.

**Order Line** (`order_details`)
: One product variant in a Child Order: `product_id`, `variation` (the variant text,
  e.g. `Red-XL`), `quantity`, and `price` / `tax` as **line totals** (unit × quantity) in
  BASE. A line has its own delivery status (a line can be `returned` while its order is
  not).

**Void** (`order_is_void()`)
: A Child Order that is cancelled or fully returned. It counts for nothing in totals.

## Statuses

**Delivery status** lives on the Child Order and on each Order Line
(`pending → confirmed → picked_up → on_the_way → delivered`, plus `cancelled`,
`returned`). Child Orders of one Combined Order regularly differ (59 checkouts in the
2026-10-19 copy).

**Combined delivery status** (`combined_delivery_status()`)
: Derived, never stored: the least advanced status among the live (non-void) Child
  Orders; with none live, `returned` if any part came back, else `cancelled`.

**Editable** (customer side, agreed 2026-10-20)
: A Child Order the customer may still change: delivery status `pending`, payment
  status `unpaid`, its seller has not answered yet (`seller_confirmed_at` and
  `seller_unavailable_at` both empty; an in-house order has no seller step), its payment
  method is not Paymera (the amount is fixed in the payment link), and it was placed
  after `stock_on_confirm_since` (older orders took their stock at placement). Once the
  seller answers, staff confirm, or anything is paid, the customer can only cancel (same
  pending + unpaid rule as today) or ask customer service. Because nothing is paid while
  an order is editable, an edit only changes the amount still to be paid: there is no
  extra charge, refund or store credit. See ADR 0001.

**Payment status** (`paid` / `unpaid`) lives on the Child Order and its lines. Cash on
delivery is settled per Child Order (the accountant marks each one paid), so Child
Orders of one Combined Order regularly differ (49 checkouts). A Paymera payment is one
payment for the whole Combined Order and marks every Child Order paid at once.

**Combined payment status** (customer pages, agreed 2026-10-20)
: Derived, never stored, over the live Child Orders: `Paid` when all are paid, `Unpaid`
  when none is, `Partly paid` when mixed; an unpaid Paymera purchase reads
  `Payment not completed`. Each Child Order still shows its own status.

## Customer order pages (`/purchase_history`)

**Order entry** (agreed 2026-10-20)
: One item of the customer's order list = one Combined Order. A Single Order shows as
  one row; a Combined Order as a card with its Child Orders under it. Pagination and
  sorting count entries, not Child Orders. See ADR 0002.

**Order page** (agreed 2026-10-20)
: The one details page for a Combined Order. It shows what the Child Orders share once
  (address, payment method, totals, invoice, rating) and one section per Child Order
  (seller, code, statuses, lines, edit / cancel). Reached through any of its Child
  Orders' existing URLs (`/purchase_history/details/{encrypt(child id)}`), which scroll
  to that Child Order's section.

**Status filter match** (agreed 2026-10-20)
: A delivery- or payment-status filter matches an entry when **any** of its Child
  Orders has that status; the entry is then shown whole, with the matching Child
  Orders marked and expanded.

**Order edit** (agreed 2026-10-20)
: A customer's change to an Editable Child Order: a line's quantity, its variant (same
  product), or removing a line (removing the last line is a cancel, not an edit). No
  adding products. Money rules are in ADR 0003.

**Basket fingerprint**
: A hash of a Child Order's lines (id, variation, quantity), computed on the fly and
  never stored. A form that shows a basket sends the fingerprint it showed; a save whose
  fingerprint no longer matches is refused, because someone changed the basket in
  between. See ADR 0004.