Order Queue Behaviors

View Interactive Prototype →

Manages the queue of procurement demand signals — Kanban Cards in REQUESTING state — awaiting conversion into purchase orders. Use cases cover how cards enter the queue, how the queue is viewed and filtered, and how a purchasing manager initiates an order from accumulated demand.

PRO::OQ::0001 — Add Card to Order Queue

Request replenishment for an item by placing its Kanban Card into the procurement queue. The card transitions to REQUESTING and appears in the Order Queue under its supplier group.

Persona	Sam Scansworth (Shop Floor Worker), Irene Itemsworth (Inventory Manager)
Depends	RES::KC
Status	Proposed
Priority	MVP3

PRO::OQ::0001::0001.US — Add Card via Item List

The user navigates to /items, clicks an item row to open the item details panel, and clicks “Add to cart.” The system sends POST /v1/kanban/kanban-card/{eId}/event/request to the backend. The card transitions to REQUESTING. The frontend animates the card flying to the Order Queue badge, shows a toast notification “Cards sent to order queue,” and refreshes the badge count via GET /v1/kanban/kanban-card/count?status=REQUESTING.

Precondition: A Kanban Card exists in FULFILLED or AVAILABLE state, associated with an item that has ordering details configured. The “Add to cart” button is disabled when the card is already in REQUESTING, REQUESTED, or IN_PROCESS state.

Postcondition: The card appears in the Order Queue “Ready to Order” tab under its supplier group. The Order Queue sidebar badge count increments.

PRO::OQ::0001::0002.US — Add Card via QR Scan

The user navigates to /scan and points a device camera at the QR code printed on a physical Kanban Card. The frontend decodes the QR URL (format: /kanban/cards/{eId}?view=card&src=qr), fetches card details via GET /v1/kanban/kanban-card/{eId}, and displays a card preview showing serial number, item name, status, and an “Add to order queue” button. The button is disabled if the card is already in REQUESTING, REQUESTED, or IN_PROCESS state.

When the user taps “Add to order queue,” the system fires the request event, the card transitions to REQUESTING, a confirmation is shown, and the badge refreshes. On mobile, this flow supports batch scanning: after one card is added, the camera view reactivates for the next scan without requiring navigation. The QR scan path supports inline editing of item parameters (see PRO::OQ::0002) before the queue entry is confirmed.

Precondition: The user has a physical Kanban Card with a printed QR code. The card is in FULFILLED or AVAILABLE state. The device has a camera available.

PRO::OQ::0001::0003.US — Add Card via Card Detail Page

The user navigates directly to /kanban/cards/{eId}?view=card via a deep link, bookmark, or QR-scanned URL. This is the standalone card detail page — no sidebar and no application chrome are rendered. The page displays serial number, item name, status, quantity, and an “Add to order queue” button.

When the user clicks the button, the system fires the request event and transitions the card to REQUESTING. A toast confirmation is shown and the badge count refreshes. Because there is no sidebar visible on this page, the badge increment is deferred to the next time the user navigates to a page with application chrome.

Implementation note: The standalone card detail page does not currently include an “Add to order queue” action. This button must be added to support this entry point.

PRO::OQ::0001::0004.US — Physical Kanban Card Trigger

Persona	Sam Scansworth (Shop Floor Worker)
Status	Proposed
Priority	MVP3
When the backup bin is opened or the primary bin reaches the reorder point, the physical Kanban Card is placed in a visible trigger position — in front of the backup bin or in a dedicated order bin. This is a purely physical workflow with no digital counterpart. The card’s physical placement at the reorder point is the trigger for Sam to initiate a digital queue entry using one of the other entry points (QR scan or item list).

This use case informs card placement conventions, physical bin setup guides, and the rationale for printing QR codes on cards. It does not describe a system interaction but establishes the physical context in which the digital trigger actions are used.

PRO::OQ::0001::0005.UC — Add Card to Procurement Queue (Sequence)

Full interaction sequence for adding a Kanban Card to the procurement queue. The card may be located via QR scan or via the Cards Management page. Once the card is located, the user clicks “Request Card” and the system fires the demand event, transitioning the card from its current state to REQUESTED and moving it to the Receiving station.

Pre-condition: The user is logged in. A Kanban Card exists in AVAILABLE, DEPLETED, IN_USE, or FULFILLED state.

Post-condition: The card is in REQUESTED state and appears in the procurement queue. The user receives confirmation with card information.

PRO::OQ::0002 — Inline Field Editing During Replenishment Trigger

During the “Add to Cart” mobile flow, the user should be able to edit item parameters — minimum stock level, reorder quantity, supplier URL — inline without navigating to a separate reference data page.

Persona	Sam Scansworth (Shop Floor Worker), Irene Itemsworth (Inventory Manager)
Depends	PRO::OQ::0001
Status	Proposed
Priority	MVP3

PRO::OQ::0002::0001.US — Update Minimums at Point of Use

While holding an item or card at the shelf, the user notices the minimum stock level is wrong and wants to correct it before adding the card to the queue. The system should allow adjusting the minimum quantity directly in the queue-entry flow on the QR scan or item details panel, without navigating away to the full Item edit page.

This prevents the common failure mode where a user notices a data problem but does not fix it because fixing it requires navigating to a separate screen and losing their current context. The correction should take effect immediately and persist for all future replenishments of that item.

PRO::OQ::0002::0002.US — Update Reorder Quantities from Shop Floor

While adding an item to the queue from a mobile device, the user observes that the reorder quantity is incorrect relative to the physical bin capacity or usage rate. The system should allow the reorder quantity to be changed inline before the queue entry is confirmed.

This is distinct from adjusting the PO line quantity (which happens later, in the Order Queue or PO draft): inline editing updates the ItemSupply record so that the corrected quantity is used in all future orders, not just the current one.

PRO::OQ::0002::0003.US — Proactive Data Correction at Point of Use

Persona	Irene Itemsworth (Inventory Manager)
Status	Proposed
Priority	MVP3
When Irene identifies a wrong URL or ordering link on an item while preparing to add it to the queue, she should be able to remove or replace the link immediately without leaving the queue-entry flow. The current Order Line STALE and INVALID state handling catches changed items after the fact but does not cover the scenario where the user proactively spots and corrects a bad URL at the point of discovery.

This scenario partially overlaps with inline vendor data completion (PRO::OQ::0006) but focuses specifically on correcting an existing, incorrect URL rather than adding a missing one. The distinction matters because the UI interaction and validation requirements differ.

PRO::OQ::0003 — View and Filter Order Queue

Display the Order Queue with cards grouped by vendor and order mechanism, searchable and filterable.

Persona	David Dealsworth (Purchasing Manager)
Depends	GEN::LST::0001, GEN::LST::0003, GEN::LST::0004, GEN::LST::0006
Status	Proposed
Priority	MVP2-B Partial

PRO::OQ::0003::0001.UC — View Procurement Queue

| Priority | MVP2-B |

The Purchasing Manager navigates to the procurement queue, which displays cards in REQUESTED, IN_PROCESS, or READY states grouped by supplier. From this view, three state-transition actions are available: Procure (transition from REQUESTED to IN_PROCESS), Receive (transition from IN_PROCESS to READY), and Fulfill (transition directly to FULFILLED, skipping FULFILLING).

The Fulfill action bypasses intermediate states by design to simplify card management at this stage. Depending on the order mechanism configured for each item, the Procure action either opens vendor links in the browser, generates text for email copy-paste, or produces a table for inclusion in a formal PO document — all in separate windows alongside the main procurement page.

PRO::OQ::0003::0002.UC — View Order Queue (Actor-Goal)

| Priority | MVP2-B |

The Purchasing Manager navigates to /order-queue. The system displays two tabs: “Ready to Order” (cards in REQUESTING state) and “Recent Orders” (cards in REQUESTED and IN_PROCESS states). Within each tab, cards are grouped by Vendor + Order Mechanism derived from the item’s primarySupply record.

Each group header shows the vendor name, order mechanism, card count, and unique item count. Groups where the vendor is missing are labeled “Unassigned vendor” and ordering actions are disabled. Groups where the order mechanism is missing are labeled “Unknown mechanism” and are also disabled. The actor can switch between grouping by Supplier and grouping by Order Method, and can search or filter cards by item name, SKU, or vendor.

Precondition: One or more cards are in REQUESTING, REQUESTED, or IN_PROCESS state.

Postcondition: The actor has a clear view of what needs to be ordered and from which vendors.

PRO::OQ::0003::0003.UC — View Order Queue (E2E)

| Priority | MVP2-B |

Load the /order-queue page with both tabs visible. The page fires two parallel card detail queries: one for REQUESTING state (for the “Ready to Order” tab) and one for REQUESTED and IN_PROCESS states (for the “Recent Orders” tab). The frontend performs client-side grouping by primarySupply.supplier and primarySupply.orderMethod. A search bar and grouping controls (Group by Supplier / Group by Order Method) are visible above the card list.

An alternate proposed API consolidates the two queries into a single POST /v1/order/queue/query endpoint that returns pre-grouped results with group-level aggregates (cardCount, itemCount) computed server-side. This avoids fetching all card details to the frontend and scales better as queue size grows.

PRO::OQ::0003::0004.UC — Filter and Sort Order Queue

| Priority | MVP2-B |

The actor switches the grouping view between “Group by Supplier” and “Group by Order Method.” Text entered in the search bar filters cards by item name, SKU, or vendor name in real time without a server round-trip. Group headers are collapsible via a click on the header row.

Switching from “Group by Supplier” to “Group by Order Method” regroups the same locally cached data without a new API call in the current implementation. In the proposed API model, a regrouping request fires a new query with the updated groupBy parameter to take advantage of server-side aggregation.

PRO::OQ::0003::0005.US — Physical-to-Digital Queue Bridge

Status	Proposed
Priority	MVP3

When workers drop physical Kanban Cards into a shared order bin at the end of a shift, the Purchasing Manager must later collect those cards, scan them, and verify each appears in the digital queue before placing orders. This bridge step ensures that physical and digital queues stay synchronized and that no demand signal is lost when the physical card collection workflow is in use.

This scenario motivates the QR scan entry point (PRO::OQ::0001::0002.US) as a workstation activity — not just a mobile single-scan flow — where multiple cards can be processed in sequence at a dedicated purchasing workstation.

PRO::OQ::0003::0006.UC — View Procurement Queue with State Transitions (Sequence)

Full interaction sequence for the procurement queue page. The queue displays cards in REQUESTED, IN_PROCESS, or READY states. Three state-transition actions are available: Procure (REQUESTED → IN_PROCESS), Receive (IN_PROCESS → READY), and Fulfill (READY or IN_PROCESS → FULFILLED, bypassing intermediate states by design). Depending on the order mechanism for the item, the Procure action opens vendor links, generates email copy-paste text, or produces a PO table — all in separate windows. The Fulfill action (“Release Card to Production”) transitions cards directly to FULFILLED, re-entering them in the production loop.

Pre-condition: The user is logged in. One or more cards are in REQUESTED, IN_PROCESS, or READY state.

Post-condition: The selected cards have been transitioned to the next state. The procurement page is refreshed.

Note: The Fulfill action in this scenario is equivalent to “Release Card to Production” — it transitions cards directly to FULFILLED, bypassing FULFILLING. This shortcut is intentional for the initial implementation; future versions may make this behavior configurable. Cross-reference: See PRO::OQ::0007 for the Create Order from Demand variant which opens vendor channels before transitioning card state.

PRO::OQ::0004 — Queue Aging Visibility

Time-in-state metrics for pre-order queue items. Shows how long each card has been in REQUESTING state, enabling prioritization and deferral decisions.

Persona	David Dealsworth (Purchasing Manager)
Depends	PRO::OQ::0003
Status	Proposed
Priority	MVP3

PRO::OQ::0004::0001.US — Time-in-State Display

The queue view shows how long each card has been in REQUESTING state so David can distinguish urgent items (those approaching stockout) from items that can wait for the next bulk order. The display should surface cards that have been waiting longest at the top of their group or with a visual indicator (e.g., color coding or elapsed-time badge).

This scenario extends the basic queue view (PRO::OQ::0003) with an additional data dimension and motivates adding an enteredStateAt timestamp to the card display payload.

PRO::OQ::0005 — Order Queue Grouping Rules

Define the grouping key and fallback behavior for the Order Queue display.

Persona	David Dealsworth (Purchasing Manager)
Status	Proposed
Priority	MVP2-B

PRO::OQ::0005::0001.FS — Grouping Key Definition

Cards in the Order Queue are grouped by Vendor + Order Mechanism. The group key is derived from the item’s primarySupply record: primarySupply.supplier (the vendor name) and primarySupply.orderMethod (the mechanism, such as ONLINE, EMAIL, or MANUAL).

Cards with no vendor assignment fall into an “Unassigned vendor” group. Ordering is disabled for this group because the system cannot determine where to place the order. Cards with no order mechanism fall into an “Unknown mechanism” group, also with ordering disabled. Each group header displays the vendor name, mechanism label, count of cards in the group, and count of unique items represented.

This grouping rule is enforced both in the current client-side implementation and in the proposed server-side queue/query endpoint.

PRO::OQ::0006 — Inline Vendor Data Completion

Groups with missing vendor have ordering disabled. This use case describes inline vendor data completion to unblock ordering directly from the queue view.

Persona	David Dealsworth (Purchasing Manager)
Depends	PRO::OQ::0005
Status	Proposed
Priority	MVP3

PRO::OQ::0006::0001.US — Add Missing Vendor Information During Purchasing

When David encounters an “Unassigned vendor” group while processing the queue, he should be able to add the vendor name, purchase URL, and order method inline — directly in the queue view — rather than navigating to a reference data page to complete the ItemSupply record.

This progressive data completion pattern reduces friction for new items that were added to the system before full supply chain information was known. After inline completion, the group gains a real vendor assignment and ordering is re-enabled without a page reload.

PRO::OQ::0007 — Create Order from Queue

Select cards from the same vendor group, trigger order creation, and complete the transaction through the vendor’s portal, email, or PO document.

Persona	David Dealsworth (Purchasing Manager)
Depends	PRO::OQ::0005, PRO::PO::0001
Status	Proposed
Priority	MVP2-B Partial

PRO::OQ::0007::0001.UC — Create Order from Accumulated Demand

| Priority | MVP2-B |

The user navigates to the Order Queue, selects cards from a vendor group (all cards for that vendor, or a subset), and triggers “Create Order.” Depending on the order mechanism configured for the vendor:

• For vendors with an online store URL, the system opens the vendor’s website and creates a cart with the selected items, presenting it to the user to complete the transaction.
• For email-based vendors, the system prepares a pre-populated email or textual PO for the user to review and send.
• For manual vendors, a table of items and quantities is generated for copy-paste into the vendor’s ordering system.

After the user confirms the order was placed, the system transitions the associated cards from REQUESTED to IN_PROCESS.

PRO::OQ::0007::0002.UC — Create Purchase Order from Order Queue (Actor-Goal)

| Priority | MVP2-B |

The Purchasing Manager selects cards in a vendor group (or clicks “Order All” for the entire group). The system opens a PO side panel populated with three sections:

• Vendor section: name (from the group), contact email, phone, address (free text, editable).
• PO Header: PO number, date (defaults to today), delivery address, payment terms, shipping terms, notes.
• Lines: one line per unique item; quantity equals the sum of selected card reorder quantities.

The system simultaneously sends accept events to each selected card, transitioning them from REQUESTING to REQUESTED. The actor can edit header and line fields, add free-form lines not linked to cards, or remove lines (which returns associated cards to REQUESTING via shelve events). The side panel does not live-sync with the queue while open.

Precondition: One or more cards in a vendor group are in REQUESTING state. The group has a valid vendor and order mechanism.

Postcondition: A PO draft exists in the side panel with editable header and lines. Selected cards are in REQUESTED state.

PRO::OQ::0007::0003.UC — Create Purchase Order from Kanban Cards

| Priority | MVP2-B |

The user selects one or more cards from the Order Queue and clicks “Create Purchase Order.” The system validates the selected cards for compatibility: all cards must belong to items that have a compatible supplier or no supplier defined. If a compatible non-null supplier exists across the selected cards, that supplier becomes the PO supplier.

Cards are grouped by item and unit of measure into individual order lines. Each line’s quantity equals the sum of reorder quantities for its group. Unit costs, line costs, and goods value are calculated from the item’s supply pricing. Cards are transitioned to REQUESTED in the backend as part of order creation. The PO is then opened in edit mode so the user can review and modify header properties before saving.

API route for creation: POST /v1/order/order/from-kanban-cards with a list of card entity IDs.

PRO::OQ::0007::0004.UC — Process Order from Queue (E2E)

| Priority | MVP2-B |

From the /order-queue page, the user interacts with the CardStateDropdown component on a card row to advance it through lifecycle states. Each status change fires a targeted API call:

• Selecting “Accept” fires POST /event/accept, transitioning the card from REQUESTING to REQUESTED.
• Selecting “Start Processing” fires POST /event/start-processing, transitioning from REQUESTED to IN_PROCESS.

The card moves between the “Ready to Order” and “Recent Orders” tabs as its state changes. The badge count updates after each transition.

PRO::OQ::0007::0005.US — Ordering Context Preservation

Status	Proposed
Priority	MVP3
When David places orders with e-commerce vendors, he opens vendor item links from Arda and adds items to vendor shopping carts. Switching between the Arda browser tab and the vendor website tab causes him to lose track of quantities and which items remain to be ordered. The system should support split-screen helpers, a persistent quantity summary panel, or clipboard integration to keep the ordered quantities visible while David works across tabs.

This scenario describes a friction point in the current multi-tab ordering workflow and motivates design work on the order creation side panel to remain useful even when the user has navigated away from it.

PRO::OQ::0007::0006.US — Proactive Replenishment During Ordering

Status	Proposed
Priority	MVP3
While placing an order with a specific vendor, the system should surface items from that vendor that are approaching their reorder point but have not yet triggered a card (i.e., are still in AVAILABLE state with stock near the minimum). This “near trigger” visibility allows David to proactively include those items in the current order and avoid a separate ordering cycle a few days later.

This scenario motivates adding a “near reorder point” indicator to the vendor group view and a mechanism to add pre-trigger items to the current order without creating a card first.

Summary

Use Case	Scenarios	US	FS	UC
PRO::OQ::0001 Add Card to Order Queue	5	4	0	1
PRO::OQ::0002 Inline Field Editing During Replenishment Trigger	3	3	0	0
PRO::OQ::0003 View and Filter Order Queue	6	1	0	5
PRO::OQ::0004 Queue Aging Visibility	1	1	0	0
PRO::OQ::0005 Order Queue Grouping Rules	1	0	1	0
PRO::OQ::0006 Inline Vendor Data Completion	1	1	0	0
PRO::OQ::0007 Create Order from Queue	6	2	0	4
Total	23	12	1	10

---