# 4. Operations flows

How the warehouse runs on the system. Each flow names the screens (back office or RF), the state transitions and the controls that protect stock accuracy and billing.

## 4.1 Master data set-up (once per site / per storer)

1. Platform console provisions the tenant (plan, first warehouse, admin). Default zones (RECEIVING, AMB, CHILLED, FROZEN, PICK, STAGING, DAMAGED ...), system locations (DOCK-01, STAGE-01, DMG-01, QC-01 ...), reason codes and document sequences are created automatically.
2. Warehouse layout: generate locations per zone (aisle/bay/level/position ranges, capacity, mixing rules, ground level as pick face). Print location labels (ZPL).
3. Storers (clients): code, legal entity, contacts, settings (receiving tolerance %, RCR recipients, auto-send RCR), warehouse access.
4. SKUs per storer: control flags (lot, expiry, serial), shelf-life minimums, dimensions, packs (EACH/INNER/CASE/PALLET with qty in base and barcodes), storage condition and rotation (FIFO/FEFO/LIFO/FMFO). Bulk via Excel import (template provided).
5. Putaway rules per warehouse (criteria: storer, storage condition, category; strategy: SAME_SKU, EMPTY_LOCATION, ZONE_SEQUENCE, NEAREST_TO_DOCK, FIXED_LOCATION; target zones; capacity and mixing flags). Allocation rules per storer/SKU (rotation override, pick face first, full LPN first, min shelf life, allowed statuses, zones).
6. Billing contract per storer with tariff card, then ACTIVE. Without an active contract nothing is billed (the AI billing anomaly check flags this).
7. Users and roles (system roles: ADMIN, OPS_MANAGER, SUPERVISOR, CSO, WAREHOUSEMAN, INVENTORY_CONTROLLER, BILLING, CUSTOMER portal), warehouse access, storer scope for portal users. API keys and webhooks for the storer's ERP.

## 4.2 Inbound

```
ASN: DRAFT/EXPECTED -> SCHEDULED (dock appointment) -> ARRIVED (gate) -> RECEIVING -> RECEIVED -> CLOSED
                                                                  \-> CANCELLED (with reason)
```

1. **ASN creation**: back office form, Excel import, public API (`/v1/asns`), SAP ORDERS IDoc, or AI document intake from a PO PDF/email (proposal accepted by a supervisor). Lines carry expected qty in pack units, lot/expiry expectations, external line references. Duplicate open external references per storer are rejected.
2. **Dock appointment** (optional): book a dock door and time window; the ASN becomes SCHEDULED.
3. **Arrival**: gate marks ARRIVED with vehicle, seal (intact?), driver, temperature on arrival; the ASN appears in the RF Receive list.
4. **Receiving (RF Receive screen or office receive)**: scan ASN/PO/container, scan item barcode (case or each barcode resolves the pack level), enter qty, lot and expiry when controlled (minimum inbound shelf life enforced), serials when controlled, condition GOOD/DAMAGED on RF (office receiving also allows REJECTED; damage needs a reason code; photo capture is not in the UI yet), LPN (scan existing or let the system create one; ZPL label via `GET /documents/labels/lpn/:lpnNumber`). Controls: over-receipt beyond the storer tolerance is refused unless `allowOver`; unexpected SKUs require explicit acceptance; idempotency key protects against double scans. Each receipt posts a RECEIPT movement to the dock location and creates a directed PUTAWAY task (DAMAGED goes to the damage zone).
5. **Putaway (RF)**: next task, scan source LPN, scan destination (suggested by the putaway engine; override allowed where rules permit), confirm. Capacity (max LPNs, weight) and mixing rules are enforced at confirm.
6. **Completion**: Mark received (all lines done) and Close. Closing with shortages requires `forceCloseShort`; discrepancies (OVER, SHORT, DAMAGED, UNEXPECTED_SKU, LOT/EXPIRY mismatch, SHELF_LIFE_BELOW_MIN) are recorded with resolution workflow. Closing generates the GRN (PDF) and the Receiving Confirmation Report, optionally emailed to the storer; the `asn.closed` event drives inbound billing and webhooks.
7. **Reversal**: a receipt line can be reversed (RECEIPT_REVERSAL movement) while the LPN is still at the dock.

KPIs: dock-to-stock hours, receiving accuracy (ASNs without discrepancy), overdue ASNs (AI receiving anomalies).

## 4.3 Inventory control

- **Stock enquiry** by SKU, location, LPN, lot, status; movement register (append-only ledger) with reference links.
- **Moves** (RF Move or office): LPN or SKU qty from location to location; capacity/mixing checks; MOVE movement.
- **Holds**: scope BALANCE, LPN, LOT, SKU or LOCATION; sets status (HOLD, QUARANTINE, QC_PENDING ...) on the affected balances, which removes them from ATP; release restores AVAILABLE. Long-running holds are flagged by the AI inventory anomaly check.
- **Adjustments** (four-eyes): requester creates lines (SKU, location, LPN, lot, status change or qty delta, reason code with `requiresApproval`), submits; an approver (different user, permission `inventory.adjust.approve`) approves or rejects; posting writes ADJUST_IN/OUT or STATUS_CHANGE movements.
- **Cycle counts**: plan by zone/locations/SKU (CYCLE, SPOT, FULL), blind or not, tolerance %; release creates COUNT tasks; RF count entry per location (incl. empty locations); review shows system vs counted vs recount vs variance; approving variances posts COUNT_ADJUST movements through an adjustment. Short picks raise SPOT counts automatically.
- **Replenishment**: min/max per pick face (slotting); the scheduled job and `POST /outbound/replenishment/run` create REPLENISH tasks from reserve LPNs (FEFO respected).
- **Expiry sweep**: daily job moves expired AVAILABLE lots to EXPIRED; expiring stock report by bucket.
- **Serials**: captured at receipt (or on pick), tracked by location/LPN/order; serial-level allocation on orders.

## 4.4 Outbound

```
Order: OPEN -> (ON_HOLD) -> PARTIALLY_ALLOCATED/ALLOCATED -> RELEASED -> PICKING -> PICKED -> PACKED -> STAGED -> LOADED -> SHIPPED | SHORT_CLOSED
                                                                                                  \-> CANCELLED (releases allocations)
Wave:  PLANNED -> ALLOCATED -> RELEASED -> IN_PROGRESS -> COMPLETED
Load:  PLANNED -> LOADING -> LOADED -> DISPATCHED (goods issue) -> DELIVERED (POD)
```

1. **Orders** arrive via form, Excel, public API, ERP or AI intake. ATP check per line (on hand minus allocated, AVAILABLE only, shelf-life constraints).
2. **Allocation**: per order or per wave. Engine: allocation rule for storer/SKU (default rotation from SKU: FIFO by receipt, FEFO by expiry, LIFO, FMFO), pick-face-first, full-LPN-first for case/pallet quantities, min outbound shelf life, allowed statuses, zone restrictions, `SELECT ... FOR UPDATE SKIP LOCKED` to avoid two waves fighting over the same LPN. Shortages are recorded as `shortLines`.
3. **Waves**: group orders (by order, carrier, ship date, storer); allocate and release in one step; release creates PICK tasks (sequenced by zone pick sequence / location sequence); pick list PDF.
4. **Picking (RF)**: next task, scan source location, scan item/LPN, enter qty (defaults to task qty), scan destination tote/LPN. **Short pick**: operator enters picked qty (0 allowed) and short qty; the system records the exception, raises a SPOT count on the location, tries to re-allocate from other stock (never from the bucket that came up short) and creates replacement pick tasks. If the shortfall cannot be covered the order is flagged `shortPending` and cannot be packed until a CSO re-allocates or accepts the short shipment (`POST /outbound/orders/:id/accept-short`).
5. **Packing station**: start packing an order (creates the shipment), build cartons (dims, weight, contents by line/lot/serial), carton label ZPL via `GET /documents/labels/carton/:cartonId`, complete to print the packing list; the shipment moves to a staging lane (STAGED). Packing is blocked while the order has an unresolved short pick: the CSO either re-allocates (Allocate) or accepts the short shipment (Accept short).
6. **Loads and dispatch**: create a load (carrier, vehicle, driver, seal, dock), add shipments, confirm each shipment loaded (scan), dispatch with seal/temperature confirmation. Dispatch posts goods issue (SHIP movements, LPNs SHIPPED, serials SHIPPED), generates the delivery note(s) and gate pass, emits `order.shipped` (billing, webhooks, ERP outbox). POD capture closes the load as DELIVERED.
7. **Returns (RMA)**: request (customer ref, original order, expected lines), authorise, receive through a generated RETURN ASN (same RF receive flow), disposition per line (RESTOCK, QUARANTINE, SCRAP, RETURN_TO_SUPPLIER, REPAIR), close.

KPIs: order cycle time, pick accuracy (picks without short), on-time ship, late orders; workload forecast (AI) for labour planning.

## 4.5 3PL billing

1. Contract per storer: currency, billing cycle, storage method, caps, minimum monthly, fixed fee, payment terms, tax %, week start.
2. Tariff card: code, group (HANDLING_IN/OUT, STORAGE, VAS, FREIGHT, ADMIN, OTHER), charge unit (PER_CBM, PER_KG, PER_PALLET, PER_CASE, PER_PIECE, PER_LINE, PER_ORDER, PER_SHIPMENT, PER_DOCUMENT, PER_CONTAINER_20/40, PER_TRUCK, FLAT, storage units PER_CBM_WEEK/DAY, PER_PALLET_WEEK/DAY, MONTHLY_FLAT), rate or tiers, minimum charge, conditions (container size, ASN/order type, warehouse, task type), trigger (ASN_CLOSED, ORDER_SHIPPED, STORAGE_PERIOD, TASK_COMPLETED, MANUAL), validity.
3. Charge capture is event driven and idempotent: `asn.closed` -> inbound handling (metrics: CBM, kg, pallets, cases, pieces, lines, container size); `order.shipped` -> outbound handling; VAS and other manual charges from the Charges screen; waivers with reason.
4. Storage: the worker takes a daily snapshot per storer/warehouse (qty, CBM, pallet positions, inbound/outbound CBM, by temperature class). Methods: WEEKLY_CBM_OPENING_PLUS_IN (opening stock of the week plus inbound during the week), WEEKLY_CBM_PEAK, DAILY_CBM, DAILY_PALLET, WEEKLY_PALLET_PEAK, MONTHLY_FLAT with cap/overage. The storage report shows the weekly/daily computation before invoicing.
5. Invoice run per storer and period: pending charges plus storage lines, minimum monthly top-up, tax; DRAFT -> ISSUED (PDF, due date, optional email) -> payments (PARTIALLY_PAID/PAID) -> credit notes, disputes, cancellation. Charges flip to INVOICED.
6. Controls: AI billing anomaly check (active storers without contract, missing snapshots, zero-amount charges, duplicates, invoice drops); audit log on every change.

## 4.6 Integrations

- ERP (SAP): connector with credentials (encrypted), IDoc MATMAS -> items, ORDERS -> ASN (purchase orders) or outbound orders (per configuration); outbound documents (goods receipt / goods issue confirmations) queued in the ERP outbox for pickup or push. Message log with retry.
- Storer systems: API keys with scopes, webhooks for `asn.*`, `order.*`, `shipment.*`, `inventory.adjusted`, `invoice.issued` etc.
- Excel/CSV imports: SKU, LOCATION, ASN, ORDER, SERIAL, CUSTOMER, SUPPLIER with templates, dry run, per-row error report.

## 4.7 RF handheld screens

| Screen | Flow |
|--------|------|
| Menu | big tiles: Receive, Putaway, Pick, Replenish, Move, Count, Inquiry, My tasks, Sign out |
| Receive | scan ASN/PO/container -> lines with progress -> scan item -> qty/pack/lot/expiry/condition -> LPN -> confirm (green flash) -> next; Finish ASN |
| Task screens (Putaway, Pick, Replenish, Move tasks) | Get next task -> verify FROM (scan) -> verify LPN/SKU, qty (short pick path) -> verify TO (scan, override) -> confirm -> next task auto-loads; Exception button with coded reasons |
| Count | pick a released count or scan a location -> enter counted qty per SKU/LPN (blind hides system qty) -> submit |
| Move | scan LPN (or location + SKU + qty) -> scan destination -> confirm |
| Inquiry | scan anything: LPN, location, SKU code or item/pack barcode -> stock details |
| My tasks | tasks assigned to me, resume |

Scanner input: any hardware scanner that types the barcode followed by Enter works; the scan input is always focused after an action. Errors vibrate (when supported) and show a red banner with the server's reason (WRONG_LOCATION, WRONG_LPN, WRONG_SKU, INSUFFICIENT_STOCK ...).

## 4.8 Daily routine (suggested)

| When | Who | What |
|------|-----|------|
| Start of shift | Supervisor | Control tower: late orders, exceptions, AI inbox; assign/reprioritise tasks; check dock appointments |
| Continuous | Warehousemen | RF tasks in sequence; exceptions reported through the RF |
| Mid-day | CSO | Allocate new orders, build waves by carrier cut-off, resolve short picks |
| End of day | Supervisor | Close received ASNs, dispatch loads, review counts; storage snapshot runs automatically at the warehouse day-end hour |
| Weekly | Inventory controller | Cycle count plan (AI slotting and anomaly reports), stale holds, expiry report |
| Month end | Billing | Storage report review, invoice run, issue, send; AI billing anomaly check before invoicing |