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
warehouserole (migration 036/060) could only read/orderswith the customer's phone masked, and the portal's Warehouse role saw the generic order list. - The commerce
ordersrow already carries the delivery snapshot (delivery_*),status,payment_statusand a manualtracking_number;order_itemscarries 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.settingsand already resolved for the tax invoice (service.resolveSeller).
Decisions¶
- The queue is derived, not pushed. A warehouse order is any
ordersrow withpayment_status IN ('paid','partially_refunded')andstatus 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 createordersrows), so there is no separate digital filter. - One new table,
accounting.warehouse_shipments, one row per order (UNIQUE order_id), in theaccountingschema 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.versionis 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. - Stages.
no row → New,row, incomplete → Shipping pending,complete → Label ready, thenpacked → dispatched;deliveredis only ever the existing order status. Printing is not a stage. Dispatch calls the existingOrderRepo.SetOrderTrackingNumberandUpdateOrderStatusAdmin(legal-transition rules, audit) rather than writingorders, so customer order tracking keeps working and a cancelled/unpaid order cannot be dispatched. Dispatched is final on this screen. - Permission. A new route-enforced permission
manage_warehousegates every/warehouseroute; it is granted to thewarehouserole (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. - 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_READYwith the list of missing fields and the button stays disabled. - 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 onlyAIM:<order number>:<AWB>- no customer data. Reprint reuses the saved AWB; every print/reprint is audited and does not change the order status. - 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_itemshas no SKU. The label and queue showitemCode= 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.returnAddressif 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_countis 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-modeModuleNotAvailableplaceholder, and its menu entry requiredaccess_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/warehouseand/deliveries./deliveriesrenders it for anyone holdingmanage_warehouse(Warehouse, Super Admin); other roles keep the previous behaviour. The Deliveries nav item uses the newrequiresAny: [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 singleWarehouseWorkspace; one API client, one backend queue. Label preview is/simple/warehouse/label/:idor/warehouse/label/:iddepending on the view./deliveriesis restored to its pre-#151 content and itsaccess_accounting_datarule;requiresAnywas removed again. - Permissions. Advanced item requires
manage_warehouse(Super Admin, Warehouse). The Warehouse role stays Simple-only: opening/warehouseredirects 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.