Skip to content

0031 — Warehouse order queue, courier details and 4 × 6 shipping label (Nov 2026)

Status: accepted for implementation (2026-11-02). Migration 122. Lives in the existing Accounts Portal (accounts.aimstoreorg.com) under the existing warehouse role. No Admin Portal or Android change.

What existed

  • The warehouse role (migration 036/060) could only read /orders with the customer's phone masked, and the portal's Warehouse role saw the generic order list.
  • The commerce orders row already carries the delivery snapshot (delivery_*), status, payment_status and a manual tracking_number; order_items carries product name, quantity and (migration 121) size.
  • There was no courier, AWB, shipment or label model, and no SKU column on shop_items.
  • Seller identity is saved in accounting.settings and already resolved for the tax invoice (service.resolveSeller).

Decisions

  1. The queue is derived, not pushed. A warehouse order is any orders row with payment_status IN ('paid','partially_refunded') and status IN ('confirmed','processing','shipped','delivered','completed'). Failed or pending payments, abandoned checkouts, cancelled orders and orders whose payment became Shopping Credit (ADR 0028: cancelled/refunded) are excluded by the same predicate. Because the queue is a query over the payment state machine's own result, a duplicate webhook cannot create a second entry and a missed notification loses nothing. The payment path is not touched. Every shop order is physical (digital gold / KARAT 24 never create orders rows), so there is no separate digital filter.
  2. One new table, accounting.warehouse_shipments, one row per order (UNIQUE order_id), in the accounting schema because accounting code must never write commerce tables (readonly_guard_test). Courier, mode and AWB are nullable so a partial save is possible; "label ready" is computed, never stored. version is the optimistic-concurrency token (stale save → 409), the AWB is unique per courier (AWB_IN_USE), and a row lock on the order serialises two staff saving at once.
  3. Stages. no row → New, row, incomplete → Shipping pending, complete → Label ready, then packed → dispatched; delivered is only ever the existing order status. Printing is not a stage. Dispatch calls the existing OrderRepo.SetOrderTrackingNumber and UpdateOrderStatusAdmin (legal-transition rules, audit) rather than writing orders, so customer order tracking keeps working and a cancelled/unpaid order cannot be dispatched. Dispatched is final on this screen.
  4. Permission. A new route-enforced permission manage_warehouse gates every /warehouse route; it is granted to the warehouse role (Super Admin holds all). The warehouse role still has no payment, GST, invoice, KYC, settings or user-admin permission; only this gate shows it customer contact, and only for orders in its queue. No new role.
  5. Label readiness (server-computed): eligible order, complete delivery snapshot (name, phone, address, city, state, 6-digit PIN), at least one product line, courier, mode, AWB, and a saved seller identity (GSTIN, legal name, registered address - the same rule the invoice uses). Until then the API answers LABEL_NOT_READY with the list of missing fields and the button stays disabled.
  6. Label. Generated in the browser from the saved shipment, the order's own address snapshot (never the customer's current profile) and the saved seller: 4 in × 6 in portrait, black on white, @page { size: 4in 6in; margin: 0 }, one sticker per page. Code 128 barcode of the AWB (or an optional separate courier barcode value); QR carries only AIM:<order number>:<AWB> - no customer data. Reprint reuses the saved AWB; every print/reprint is audited and does not change the order status.
  7. Notifications. A per-user "last seen" marker (accounting.warehouse_notification_state) drives an unread badge and a list of new orders; the portal polls every 30 s while visible. No third-party service.

What was deliberately not invented

  • SKU. shop_items has no SKU. The label and queue show itemCode = the first 8 hex characters of the product id, labelled SKU, and the real size and quantity. A true SKU needs a catalogue field the owner must define.
  • Return address. No separate return address is configured; the label uses portal_settings.company.returnAddress if saved, otherwise the saved registered address.
  • Courier integrations, tracking updates, delivered status. None. AWBs are typed by staff; nothing is fetched or assumed.
  • Multiple parcels. One AWB and one label per order. package_count is informational. An order whose product table does not fit is continued on a second sticker with the same AWB; no extra AWBs are created.
  • District. Not stored on the order; city, state and PIN are printed.
  • The original approved artwork was not available to the implementation; the layout follows the section list of the owner's brief (header/sold-by, order info with the small mode badge, deliver-to, QR, barcode, product table, two-line return address, handling icons, website footer).

Rollback

rollback_122.sql refuses while any shipment exists (export first). Redeploy the previous backend image before running it.

Amendment (2026-11-02): where the workspace lives, and wording

  • Root cause of "Not available yet". PR #151 mounted the workspace only at /simple/warehouse. The advanced portal's existing Operations → Deliveries (/deliveries) still rendered the live-mode ModuleNotAvailable placeholder, and its menu entry required access_accounting_data, which the Warehouse role does not hold. Nothing was wrong with the backend, the deploy or the permission grant.
  • Fix. The workspace is now one shared component (components/warehouse/warehouse-workspace.tsx) used by both /simple/warehouse and /deliveries. /deliveries renders it for anyone holding manage_warehouse (Warehouse, Super Admin); other roles keep the previous behaviour. The Deliveries nav item uses the new requiresAny: [access_accounting_data, manage_warehouse], honoured by both the sidebar and the route guard. The server gate is unchanged.
  • Label name. The owner's selected label is the 6 × 4 inch Portrait Shipping Label: 4 in wide, 6 in high, CSS page 4in 6in. It is not landscape.
  • Product ID is not a SKU. The label column and the order details now read "Product ID". There is still no SKU field in the catalogue.
  • Seller. Unchanged: read from the saved company profile (accounting.settings); nothing is hardcoded and no new approval step exists. If a field is genuinely unsaved, the portal names it.

Amendment 2 (2026-11-03): Warehouse Orders is its own module; Deliveries is separate again

  • Why PR #152 was reversed. #152 rendered the workspace inside Operations → Deliveries to make it visible. The owner wants two modules: Warehouse Orders (fulfilment) and Deliveries (tracking, which remains the original live-mode placeholder; no delivery tracking, courier API or proof of delivery was ever built).
  • Routes. /simple/warehouse (Simple view) and /warehouse (Advanced view, new "Warehouse → Warehouse Orders" sidebar group) both render the single WarehouseWorkspace; one API client, one backend queue. Label preview is /simple/warehouse/label/:id or /warehouse/label/:id depending on the view. /deliveries is restored to its pre-#151 content and its access_accounting_data rule; requiresAny was removed again.
  • Permissions. Advanced item requires manage_warehouse (Super Admin, Warehouse). The Warehouse role stays Simple-only: opening /warehouse redirects it to the same page in Simple view, and it still cannot open Deliveries or any accounting page. The server gate is unchanged.
  • View switching keeps you on Warehouse Orders (counterpartRoute); other pages still go to the new mode's home.