# SNYT Warehouse Operations — ERP-portable Specification

## Sources of truth
- Focus **DIP NEW WH** and **WiWU-DIP WH** exported reports are manually uploaded every morning. No Focus API or direct mutation.
- Format: F3 warehouse, F4 as-on date, headings row 6, item/Barcode1/Description in A/B/C and Balance Quantity in J beginning row 7.
- Upload -> staged snapshot -> human review -> confirm. Never silently swap warehouse sources. Snapshot quantity is authoritative baseline; reset post-snapshot movement deltas on confirm, while preserving outstanding reservations separately.
- Product price, Regular/Clearance membership, New Arrival flag and photos must NOT be overwritten by stock import.

## WhatsApp request flow
- Each line `BARCODE_SUFFIX-QUANTITY` or `BARCODE_SUFFIX_QUANTITY`; do NOT guess ambiguous suffixes. Display every exact barcode-suffix candidate with image.
- Duplicate short codes in a single pasted order require explicit human review; do not silently aggregate.
- Destination is a generic inventory location: existing linked salesman's van, manually named person, shop, warehouse, or other. Do not force account registration.
- Choose source warehouse for each line; a single request can split across both and produce one STI per source.
- Reservation decreases available-to-promise, NOT physical stock. Concurrent reservations must be transactional and cannot oversubscribe.
- Focus STI numbers entered manually. Export exact template Excel and readable PNG for WhatsApp group.
- Warehouse prepares goods; shortages require updating both Focus STI and SNYT reservation and actual received quantities.
- Focus STR numbers entered manually and receipt confirmed by admin; stock leaves source and enters destination atomically. Admin confirmation credits stock immediately, no Flutter receipt needed yet. Future optional receiver confirmation.
- Posting must be idempotent and auditable; one STR must never affect balances twice. Linked van inventory must not duplicate stock balances.
- Dashboard displays each STI awaiting STR and removes only completed STI records. Partial receipts remain visible until resolved.

## Implemented October 17, 2026
- Separate warehouse migration (eight inventory workflow tables plus staged snapshot rows) installed; existing SNYT stock tables unchanged.
- Warehouse Operations admin page, WhatsApp suffix/duplicate preview, product candidates/images, dashboard pending count.
- Focus import: administrative XLSX upload; validates Focus header, selected warehouse, report date, unique SKUs, and nonnegative quantities; stages all rows for paginated review, requires explicit confirm; records snapshot history and updates warehouse baselines. Mismatch files rejected. Blank Balance Quantity interpreted as zero. Unique exact product matching only; unresolved products do not automatically map.
- Parser synthetic tests: valid DIP, leading zero barcode, blank balance zero, incorrect destination rejected.

## Demo sandbox implemented on the server (October 17, 2026)
- Separate isolated tables: warehouse_demo_stock, warehouse_demo_locations, warehouse_demo_orders, warehouse_demo_order_lines, warehouse_demo_allocations, warehouse_demo_documents, warehouse_demo_destination_stock.
- Seeded 2 demo source warehouses, 3 named demo salesmen, 1 demo shop and two additional demo destination warehouses; WhatsApp example suffixes have seeded quantities, some deliberately missing from one source.
- /warehouse-operations/demo creates new demo requests: WhatsApp suffix lookup, product candidate choice, duplicate review or explicit merge, editable quantities, per-source on-hand/reserved/available (both stores shown even when zero), destination selection, manual allocation DIP and WiWU-DIP, transactional reservation with stock locks and oversubscription rejection.
- Requests allocate to exactly the used warehouse(s), one Focus STI per source; copy each individual full Product SKU next to its requested qty, and manually enter the real Focus STI number for that source. Sort sections by warehouse and within them category A-Z then product name A-Z.
- Excel export contains the 9 source sample columns SERIES#, SN#, ITEM, BARCODE, DESCRIPTION, ITEM CATEGORY, REQUESTED QTY, WIWU-DIP WH AVAILABLE QTY, DIP WH AVAILABLE QTY, with separate sections and Focus STI numbers in one XLSX. This is a formatted recreation, **not a byte-for-byte copy** of the uploaded RABEE sheet.
- PNG export is a combined SNYT branded warehouse picking sheet with product thumbnails (local images), source-separated STI sections and Code39 machine-readable STI barcode only for supported Focus STI characters. Both exports blocked until all used warehouses have manually entered STI numbers.
- Demo STR admin confirmation atomically deducts isolated demo warehouse stock and credits isolated demo receiver balances, idempotent and restricted to approved status. Demo cancellation releases unposted reservations. No Focus system API connection.
- End-to-end production-database **transactional rollback** smoke test PASS: two warehouses/two STIs, one warehouse/one STI, duplicate reviewed, reserve without deduction, Excel+PNG generation, STR once only, destination credited, cancellation released, overbooking blocked. All smoke test writes rolled back, temp public test files removed.
- Demo transactions NEVER touch warehouse_balances, warehouse_snapshots, van_stock_items, catalog inventory, or real salesmen.

## Pending before enabling live operation
- **Live (non-demo) reservation, physical receipt and legacy salesman van-stock integration are NOT enabled.** Implement and QA against existing StockReplenishmentService before touching production stocks.
- UI to revise reserved quantities after warehouse picking (shortage/partial fulfillment), undo partial transfer, and full audit/reconciliation of live warehouse balances.
- Persist original Focus XLSX files as an archive, tighten unresolved exact SKU vs barcode mapping, stale snapshot/concurrent confirm protection, date/time movement reconciliation, daily live catalog availability, and browser/device QA.
- Excel formatting matches the sample column schema and styling concept, but sample workbook fidelity must be approved by the user after download. The PNG uses local thumbnails where available; scanner testing of Code39 against actual Focus STI number patterns is still needed.
- Do not modify unrelated migrations or publish an APK without explicit user authorization.