# Sale Import — function reference

How Barker's sales become brewman Sale Vouchers: what every function does, what it takes,
what it returns, and what it writes. The code docstrings are the primary source; this page is
the map.

## Pipeline

```
routers/sales_import.py            thin HTTP layer (auth + permission only)
  └─ services/sales_import/        the subsystem (this package)
       __init__.py                 public surface: preview, execute, load/save mapping, cost_centres
       service.py                  orchestration: fetch → map categories → plan → apply → shape schema
       products.py                 provisioning: which brewman product/SKU does a Barker line mean?
       vouchers.py                 planning + persistence: planned vouchers, signatures, write/delete
       barker_client.py            adapter: Barker's /api/export/sales → typed payloads
```

Dependency direction: `service → vouchers → products`, and `service → products`. Nothing
imports upward, `__init__.py` re-exports only the public five, and the mapping table
(`barker_products`) is written only inside `products.py`.

## The three kinds of logic

Every product/SKU function mixes three concerns; knowing which one you are looking at is
half the reading:

1. **Identity policy** (ADR-0004) — *what a Barker line means*: the standing mapping, once
   made, is served verbatim; a Barker product's other SKUs bind next; the slugified name is
   only the resolver for a product never mapped before.
2. **Normalization + validity mechanics** — *how matching is decided*: names and units are
   compared in slug form; "active" means the version's date range covers the business date.
3. **Session discipline** — *incidental machinery*: the session runs with `autoflush=False`,
   so every write flushes before returning or later lookups in the same run won't see it.

## Invariants worth remembering

- **`autoflush=False`**: `db.add(...)` is invisible until `db.flush()`. Provisioning writes
  flush before returning; a failed run rolls back whole (`get_session`), so `execute`'s
  single `db.commit()` is the only durable write.
- **The mapping is standing truth**: once a Barker SKU has a mapping row, it is served
  verbatim forever. Barker renames and units changes after first mapping are ignored — the
  drift is visible in the preview (which shows Barker's names) and fixed by editing brewman
  by hand.
- **Slug identity**: names and units match through `_normalize` (trim, casefold, punctuation
  stripped, whitespace/underscores → hyphens). "Butter Chicken", "Butter-Chicken" and
  "butter   chicken" are one product. The stored `handle` is never read.
- **Ambiguity fails hard**: if a slug matches more than one active product (only possible
  via manual brewman edits), the import raises 409 naming the candidates — no guessing.
- **Creation cannot clash**: branch 3 creates only when no active version's slug matches, so
  the name and handle exclusions can never be hit by the import.
- **Per-SKU mapping**: `barker_products` holds one row per Barker SKU, so one Barker product
  can span several brewman SKUs; branch 2 binds a new Barker SKU to the product its sibling
  SKUs already use.
- **Legacy forever-versions**: old products have `valid_from = NULL` (active since forever);
  the name search links to them like any other active version.
- **Idempotence**: a day whose booked vouchers match the plan is skipped entirely
  (signature equality), so re-running the same range is a no-op.

---

## `barker_client.py` — the Barker adapter

Pure adapter: GETs Barker's export endpoint and validates the payload. Raises
`BarkerError` on anything unusable; callers translate that to HTTP 502.

| Function / class | What | Inputs | Outputs |
| --- | --- | --- | --- |
| `fetch_sales(start_date, finish_date)` | Fetch and validate one date range of Barker sales | start and finish business dates | `BarkerSales` (validated pydantic model) |
| `BarkerSaleLine` | One POS sale line: product/SKU ids, `name`, `units`, sale category, `quantity`, `price`, `tax_rate`, `discount` | Barker payload (camelCase aliases) | typed line |
| `BarkerSaleDay` | One business date with its lines | Barker payload | typed day (`.date_`, `.lines`) |
| `BarkerSaleCategory` | A sale category id and name | Barker payload | typed category |
| `BarkerSales` | The whole export: `sales` days + `sale_categories` | Barker payload | typed export |
| `BarkerError` | Raised when Barker is unreachable or the payload is unusable | — | exception |

---

## `products.py` — provisioning

### Public seam

**`resolve_product(db, line, date_) -> ProvisionedProduct`**
The single entry point; the planning loop learns only this.
- *Inputs*: session, the Barker line, the line's business date.
- *Outputs*: `ProvisionedProduct(product_id, sku_id, disposition)`.
- *Resolution order* (ADR-0004): Barker SKU mapped → return verbatim; else Barker product
  mapped (sibling SKU row) → place this SKU under that product; else match the active
  product by normalized name → use it or create → place the SKU. The mapping row is written
  whenever a binding is established.
- *Writes*: the mapping row always; SKU and product rows only when creating. Flushes.
- *Errors*: 409 when the normalized name matches more than one active product.

**`ProvisionedProduct`** (frozen dataclass) — `product_id`, `sku_id`, `disposition`.

**`Disposition`** — what provisioning did: `mapped` (served from the standing mapping,
nothing written), `linked` (new binding to an existing product — sibling-SKU branch or
name-resolved), `created` (a new product and its first SKU). This is what the preview's
insert-vs-update classification will read.

**`existing_binding(db, sku_id) -> tuple[product_id, sku_id] | None`** — read-only lookup
of the mapping row; also branch 1's lookup, and used by preview so it never provisions.

### Implementation (private)

| Function | What | Inputs | Outputs / Errors |
| --- | --- | --- | --- |
| `_normalize(value)` | The slug comparison form of a name or units: trim, casefold, punctuation stripped, whitespace/underscores → hyphens | raw string | normalized string |
| `_find_product_id_by_name(db, name, date_)` | The one active product whose normalized name matches | session, Barker name, date | product id or None; **409** naming candidates when several match |
| `_find_or_create_sku(db, product_id, line, date_)` | Reuse the product's active SKU whose normalized units match; else add a SKU under it | session, product id, line, date | `sku_id` |
| `_create_product(db, line, date_)` | New product ("Menu Items", All Purchases) + first SKU; cannot clash — only called when no active slug matches | session, line, date | `product_id` |
| `_create_sku(db, product_id, line, date_)` | New SKU row + first version | session, product id, line, date | `sku_id` |
| `_write_mapping(db, line, product_id, sku_id)` | Insert the mapping row if absent or correct it, then flush (autoflush off) | session, line, ids | None |

Constants: `MENU_ITEM_GROUP_ID`, `ALL_PURCHASES_ID` (the imported product's account).

---

## `vouchers.py` — planning and persistence

### Plan side

**`PlannedLine`** (dataclass) — one aggregated sale line: `product_id`/`sku_id` (None when
not provisioned), `name`, `units`, `quantity`, `rate`, `tax_rate`, `discount`. `amount` =
`quantity × rate × (1 + tax) × (1 − discount)` at paise precision (ADR-0001). `signature()`
is the fingerprint compared against booked vouchers.

**`PlannedVoucher`** (dataclass) — one planned Sale Voucher: `business_date`,
`sale_category_id`/`name`, `cost_centre_id`, sorted `lines`. `amount` sums lines;
`narration` renders the standard import narration; `signature()` = `(cost_centre_id, sorted
line signatures)`.

**`build_planned_vouchers(db, day, mapping, provision) -> dict[cost_centre_id, PlannedVoucher]`**
- *Inputs*: session, a Barker day, the category→cost-centre mapping, `provision` flag.
- *What*: groups lines by sale category, aggregates lines with identical
  (SKU, price, tax, discount) by summing quantity, resolves ids — through
  `resolve_product` when `provision=True` (preview=False never writes) — and drops
  categories absent from the mapping (preview surfaces them in the editor instead).
- *Outputs*: plans keyed by cost centre — the same key booked vouchers are keyed by, which
  is what makes the comparison possible.

### Comparison side

| Function | What | Inputs | Outputs |
| --- | --- | --- | --- |
| `existing_vouchers(db, business_date)` | Booked Sale Vouchers for a day, keyed by the cost centre of their credit journal | session, date | `dict[cost_centre_id, Voucher]` |
| `voucher_signature(voucher)` | Fingerprint of a booked voucher in the plan's shape: credit cost centre + sorted (SKU, qty, rate, tax, discount) at the same quantisation | voucher | signature tuple |

### Persistence side

| Function | What | Inputs | Outputs / Errors |
| --- | --- | --- | --- |
| `create_voucher(db, plan, user_id)` | Write one plan as a read-only Sale Voucher: synthetic batches (`quantity_remaining=0`), two journals on All Purchases (credit sale-category cost centre, debit Production). No commit | session, plan, user | None; **422** if a line lacks a SKU (defence in depth) |
| `delete_voucher(db, voucher)` | Delete a booked Sale Voucher and its import-created batches (only when no other inventory references them; purchased batches survive) | session, voucher | None |
| `check_locks(db, business_dates)` | Refuse the run when a target date is locked for SALE vouchers | session, dates | None; **423** with the lock message |
| `all_purchases_account_types(db)` | Account types of All Purchases, for the lock check | session | `list[int]` |

---

## `service.py` — orchestration and settings

### Mapping settings (public API)

| Function | What | Inputs | Outputs / Errors |
| --- | --- | --- | --- |
| `load_mapping(db)` | Standing category→cost-centre mapping from `DbSetting` (today-valid row) | session | `dict[category_id, cost_centre_id]`, `{}` when never saved |
| `save_mapping(db, mapping)` | Validate and persist the mapping, committing immediately; drops null-cost-centre entries | session, `MappingUpdate` | None; **422** for Purchase/Production targets or unknown cost centres |
| `cost_centres(db)` | Cost centres a category may map to (all, minus Purchase and Production) | session | `list[CostCentreLink]` |

### Planning helpers (private)

| Function | What | Inputs | Outputs |
| --- | --- | --- | --- |
| `_category_names(sales_days)` | Every category in the fetched data with its name | Barker days | `dict[category_id, name]` |
| `_require_mapping(db, categories)` | Load the mapping and refuse while any fetched category is unmapped | session, categories | complete mapping; **422** naming all missing |
| `_to_schema_voucher(plan, action, existing_amount)` | Shape a plan into the API's `VoucherPlan` | plan, action, booked amount or None | `schema.VoucherPlan` |
| `_day_plan(db, day, mapping, provision)` | Plan one day against what is booked for it | session, day, mapping, provision | `schema.DayPlan` |
| `_plan_from(business_date, expected, existing)` | Decide actions: `skip` when signatures match, `replace` when a voucher exists but differs, `create` when none; day action = the common action or `mixed`; a day whose booked vouchers have no plan also reports `replace` (they will be removed) | date, plans, booked | `schema.DayPlan` |

### The two entry points

**`preview(db, request) -> PreviewResponse`** — read-only.
Fetches Barker (502 on failure), plans mapped categories with `provision=False` (no
writes at all), lists never-provisioned product labels (`new_products`), and returns every
category ever seen — mapped or not — for the mapping editor. Lenient by design: it never
fails on unmapped categories, or the mapping editor could never be filled in.

**`execute(db, request, user_id) -> ExecuteResponse`** — writes.
Strict: 422 while any fetched category is unmapped. Checks locks (423) across the whole
range first. Per day, in order: load booked → plan with provisioning → delete every booked
voucher that has no matching plan (signature compare; a category no longer mapped/sold is
removed this way) → create the rest. `db.flush()` per day, one `db.commit()` at the end; any
failure rolls back the whole run.

---

## `routers/sales_import.py` — HTTP layer

Thin: permission gate + session + delegation. `POST /api/sales-import/preview`,
`POST /api/sales-import/execute`, `PUT /api/sales-import/mapping`,
`GET /api/sales-import/voucher/{id_}` (404 unless the voucher is a SALE voucher). Sale
vouchers are read-only everywhere else too — edit/delete are refused for imported ones.

## Decision records

- ADR-0001 — sale vouchers are valued at POS sale price.
- ADR-0002 — products are provisioned automatically by ID; versions carry master-data change.
- ADR-0003 — the handle is ignored; the name was made identity (partly superseded).
- ADR-0004 — the product mapping is standing truth; slug-normalized names and units are the
  first-sight resolvers; renames and units changes after mapping are ignored.