Kanban Card Behaviors

Use cases and scenarios for the RES::KC (Kanban Cards) area of the Functional Domain Taxonomy. Kanban Cards are the central demand signal of the Arda replenishment system. Each card is associated with an Item and carries a serial number, a quantity, a card state, and a QR code that encodes a URL to the card’s detail page. Cards drive the procurement loop: they are created and printed during setup, triggered physically or digitally when stock is depleted, and transition through a state machine from AVAILABLE through the procurement lifecycle to FULFILLED.

RES::KC::0001 — Create and Print Kanban Card

An inventory manager creates one or more Kanban Cards for an item that has no pre-existing cards, specifying the number of cards, the quantity per card, and the print template. The system generates the card records and produces a printable PDF containing the card images. If cards already exist for the item, the manager can add cards, reprint selected cards, or remove cards.

Persona	Irene Itemsworth (Inventory Manager)
Depends	REF::ITM
Priority	MVP2-A

RES::KC::0001::0001.US — Create Cards for Item with No Existing Cards

The user navigates to the Item Management page (/items), selects an item, and clicks “Manage Cards.” The BFF calls GetItemCards(itemId) and the API returns an empty result (no existing cards). The system presents a card generation form prompting for: number of cards to print, item quantity per card, and print template. The user fills in the form (with keystroke validation and auto-completion) and clicks “Print Cards.” The BFF calls Generate Cards Image, which creates the card records in the backend and returns a PDF URL. The system opens the PDF for review and the user prints it to a local printer. After printing, the user is redirected to the Item Management page.

RES::KC::0001::0002.US — Add More Cards (Pre-Existing Cards Present)

The user selects “Manage Cards” for an item that already has cards. The BFF retrieves the existing card list (Page<Card>) and displays it. The user selects “Add Cards” and is shown an input form for the number of additional cards and the template. After filling in the form, the user clicks “Print Cards.” The BFF calls GenerateCards(itemId, number), which generates the new card records and returns a PDF URL. The PDF is displayed and printed. The user is returned to the Cards Management page for the item.

RES::KC::0001::0003.US — Reprint Selected Cards

The user selects “Manage Cards” for an item with existing cards and chooses “Reprint.” A reprint form is shown allowing the user to select specific cards and choose a template. The user fills in the form and clicks “Print Cards.” The BFF calls GenerateCardsImage([cards]), which regenerates the PDF for the selected cards. The PDF is displayed and printed. The user is responsible for managing any duplicate physical copies of the reprinted cards.

RES::KC::0001::0004.US — Remove Cards

The user selects “Manage Cards” for an item with existing cards and selects one or more cards to remove. The user confirms the “Remove” action. The BFF calls RemoveCards([cards]), which deactivates the selected card records in the backend. A confirmation shows the number of cards remaining. If cards remain for the item, the user is redirected to the Cards Management page for the item. If no cards remain, the user is redirected to the Item Management page. The user is responsible for physically disposing of the deactivated cards.

RES::KC::0001::0005.UC — Create Cards — No Pre-Existing Cards (Sequence)

Pre-condition: The user is logged in. The item exists in the catalog. No Kanban Cards exist for the item.

Post-condition: One or more Kanban Cards are created in the backend and a printable PDF is produced and sent to the local printer.

RES::KC::0001::0006.UC — Create Cards — Pre-Existing Cards Present (Sequence)

Pre-condition: The user is logged in. The item exists in the catalog. One or more Kanban Cards already exist for the item.

Post-condition: Cards are added, reprinted, or removed; the backend reflects the updated card set.

RES::KC::0002 — Print Kanban Cards

Kanban Cards that already exist for an item can be printed directly from the Item Management grid using the print button in the Quick Actions column. This use case covers the quick print flow (one click from the grid) as distinct from the card management flow in RES::KC::0001.

Persona	Irene Itemsworth (Inventory Manager)
Depends	RES::KC::0001
Priority	MVP2-A

RES::KC::0002::0001.US — Print Cards from Item Grid Quick Actions

The user is on /items and an item row shows a “Print N cards” button (printer icon with count) in the Quick Actions column. The user clicks the button. The frontend sends POST /api/arda/kanban/kanban-card/print-card with the body { ids: [<card-eIds>] }. The API returns { data: { url: "<PDF-URL>", job: "<uuid>", templateId: "<id>" } }. The frontend opens the PDF URL in a new browser tab. No browser print dialog is shown; the user uses the browser’s built-in print function from the new tab. Cards are marked as PRINTED after this action.

RES::KC::0002::0002.US — Print Card from Card Detail Page

The user navigates directly to /kanban/cards/<eId>?view=card (via QR scan or deep link) and clicks a print action on the card detail page. The same POST print-card endpoint is called for the card being viewed. The PDF URL is opened in a new tab. This scenario is the print entry point available when the user is viewing a card standalone, without the application grid visible.

RES::KC::0003 — View Card Details

A user navigates to the standalone card detail page for a specific Kanban Card, either by following a QR code deep link or by navigating to the card’s URL directly. The page shows the card’s serial number, associated item, current state, print status, and quantity.

Persona	Irene Itemsworth (Inventory Manager), Sam Scansworth (Shop Floor Worker)
Depends	RES::KC::0001
Priority	MVP2-A

RES::KC::0003::0001.US — Navigate to Card Detail via Deep Link

The user navigates directly to /kanban/cards/[cardId] — either by clicking a shared URL, following a QR code scan, or using a deep link from another part of the application. The system renders the standalone card detail page (no app grid sidebar). The page displays the card’s serial number, item name, current card state, print status, and quantity. Action buttons relevant to the card’s current state are available (e.g., “Add to order queue” for AVAILABLE cards).

This page is the destination for QR code scans from physical cards. If the user is not authenticated when reaching this URL, they are redirected to the sign-in page and then returned to the card detail URL after authentication.

RES::KC::0004 — Card State Transitions

Kanban Cards move through a state machine driven by procurement events. The states are: AVAILABLE, REQUESTING, REQUESTED, IN_PROCESS, READY, FULFILLING, and FULFILLED. State transitions are fired by the procurement subsystem in response to user actions (adding to queue, creating a PO, submitting a PO, receiving, or cancelling). These functional scenarios describe the automatic state-machine behavior; the user-facing triggers are documented in the Procurement domain.

Persona	Irene Itemsworth (Inventory Manager), David Dealsworth (Purchasing Manager), Keisha Clerkson (Receiving Clerk)
Depends	PRO::PO, PRO::RCV
Priority	MVP2-A

RES::KC::0004::0001.FS — Card State Transition on PO Creation

When cards are associated with a new Purchase Order (or added to an existing one), the system fires an accept event for each card currently in REQUESTING state. The accept event transitions the card to REQUESTED. If the event fails for an individual card (for example, because the card’s state has changed concurrently), the operation reports the failure for that card but does not roll back successfully transitioned cards — partial success is accepted. This is the REQUESTING to REQUESTED leg of the procurement loop.

Implementation note: The OrderFromCardsService must be updated to fire accept; this is not yet implemented in the current codebase.

Scope: Lite (required by the simplified PO Spec V1).

RES::KC::0004::0002.FS — Card State Transition on PO Submit

When a Purchase Order is submitted, the system fires a start-processing event for each card in REQUESTED state that is associated with the PO. The start-processing event transitions the card to IN_PROCESS. Cards not in REQUESTED state are skipped for idempotency — if a card was already advanced or rolled back, the skip prevents double-transitions. The existing OrderLifecycle.startCards() implementation handles this transition.

Scope: Lite.

RES::KC::0004::0003.FS — Card State Transition on Receive

When a PO line is marked as received, the system fires a receive event for each card in IN_PROCESS state associated with that line. The receive event transitions the card directly to FULFILLED, bypassing the intermediate READY and FULFILLING states consistent with MVP0 and MVP1 behavior. A fulfilled card re-enters the pool of available demand signals for future replenishment cycles.

Scope: Full.

RES::KC::0004::0004.FS — Card State Rollback on PO Cancel

When a Purchase Order is cancelled, associated cards in REQUESTED state are rolled back by firing a shelve event, which returns them to REQUESTING state so they re-enter the Order Queue. Cards in IN_PROCESS state at the time of cancellation have undefined rollback behavior — automatic reversal may not be appropriate if the vendor has already been notified. The rollback behavior for IN_PROCESS cards is to be determined.

Scope: Full.

Cross-reference: See Purchase Order Behaviors for the user-facing PO lifecycle actions that trigger these transitions.

RES::KC::0004::0005.UC — End-to-End Card State Machine Traversal

An end-to-end test traversal exercises all implemented states in the card state machine by firing the event endpoints in sequence: event/request (AVAILABLE to REQUESTING), event/accept (REQUESTING to REQUESTED), event/start-processing (REQUESTED to IN_PROCESS), and the fulfill handler (IN_PROCESS to FULFILLED). At each step the card’s status field and lastEvent field are verified to reflect the transition. The minimum testable path covers AVAILABLE through IN_PROCESS plus the final fulfill transition. The full 7-state path (including READY and FULFILLING) is the complete state machine documented in the API specification.

RES::KC::0005 — Add Card to Order Queue

A user places a Kanban Card into the procurement queue by triggering the request event, which transitions the card from AVAILABLE (or FULFILLED) to REQUESTING. This use case is the entry point to the procurement loop and is documented primarily in the Procurement domain.

Persona	Irene Itemsworth (Inventory Manager), Sam Scansworth (Shop Floor Worker)
Depends	RES::KC::0001, RES::KC::0004
Priority	MVP2-A

Back-reference: Full behavioral description is in PRO::OQ::0001 — Add Card to Order Queue. This section records RES::KC as a secondary domain participant.

RES::KC::0005::0001.US — Add Card via Item List

From the /items page, the user clicks the cart icon in the Quick Actions column for an item with cards in AVAILABLE state. The frontend sends POST /api/arda/kanban/kanban-card/:eId/event/request for the card. The card transitions to REQUESTING state and the Order Queue sidebar badge count increments. A confirmation toast or visual feedback appears.

RES::KC::0005::0002.US — Add Card via Card Detail Page

The user navigates directly to /kanban/cards/<eId>?view=card and clicks “Add to order queue.” The same event/request endpoint is called for the card being viewed. No fly animation is shown because the application chrome (grid, sidebar) is not visible in the standalone card view. The button becomes disabled or changes state after the card transitions to REQUESTING.

RES::KC::0006 — Kanban QR Code

Every Kanban Card carries a QR code that encodes a URL pointing to the card’s detail page. Users on the shop floor can scan the QR code with a phone camera or a hardware barcode scanner to access the card’s information and take actions without navigating through the application.

Persona	Sam Scansworth (Shop Floor Worker), Keisha Clerkson (Receiving Clerk)
Depends	RES::KC::0001, OAM::IAM::0002
Priority	MVP2-A

RES::KC::0006::0001.US — QR Code Scan via Camera App

The user points their phone camera at a physical Kanban Card’s QR code. The mobile device’s camera app or browser decodes the URL embedded in the QR code and opens it in the browser. If the user is not logged in, they are redirected to the sign-in page (/signin); after successful authentication they are redirected back to the original card URL. The browser then requests the card detail page, the BFF calls getItem(itemId) on the Arda Items Data Authority, and the card detail (Card View/Action page) is displayed. The user can take any available action on the page (such as adding the card to the order queue or receiving it) or dismiss the page to return to the dashboard.

The QR code currently encodes an item-level URL based on the Coda implementation. Future versions may encode a card-specific URL to provide card-state and location information directly from the QR scan.

RES::KC::0006::0002.US — Scan Page Camera Interface

The user navigates to the /scan page by clicking the Scan button in the application header bar (UC-NAV-004). The scan page provides a hardware-scanner-friendly interface: a hidden text input accepts scanner keystrokes (simulated or physical), and the page layout shows action buttons (Add to order queue, Receive card, View/Edit details — initially disabled), a Filter button, and an empty AG Grid with columns for SKU, Item, Image, Classification, and Supplier. A “Waiting for first scan…” placeholder is visible. The application sidebar is not shown on this page.

When a QR code or barcode value is entered (via the hidden input from a hardware scanner, or simulated programmatically in tests), the application fetches the card via GET /api/arda/kanban/kanban-card/:cardId. The card appears in the scan grid and the action buttons become enabled. The user can then click “Receive card” to fulfill the card or “Add to order queue” to request it. Physical camera scanning is not exercisable in a headless test environment; automated tests must simulate scanner input by programmatically setting the hidden input value.

RES::KC::0006::0003.US — Navigate to Scan Page from Header

The user is on any authenticated application page and clicks the scan button (barcode/QR icon) in the header bar. The browser navigates to /scan. The scan page loads with the full interface described in RES::KC::0006::0002. This is the primary entry point to the scan workflow from the desktop application.

RES::KC::0006::0004.UC — QR Lookup Item via Browser Address Bar or Camera App (Sequence)

When a user scans a QR code directly into a browser address bar or camera app, all necessary information must be encoded in the URL because the scanning app cannot prompt the user for additional input. In the current implementation the QR code encodes an item-level URL; future versions may encode a card-specific URL. After navigating to the URL, the user is redirected to sign-in if not authenticated, then presented with the Card View/Action page where available actions can be taken.

Pre-condition: A physical Kanban Card with a printed QR code exists. The device has a browser or camera app capable of following the URL.

Post-condition: The Card View/Action page is displayed and the user can take an available action or dismiss to the dashboard.

RES::KC::0007 — Kanban State for Procurement

Kanban Card state is the backbone of the procurement loop. The state of all cards in the system determines what appears in the Order Queue, what Purchase Orders contain, and what remains to be received. This use case records the back-reference to the procurement domain.

Persona	David Dealsworth (Purchasing Manager), Keisha Clerkson (Receiving Clerk)
Depends	RES::KC::0004, PRO::OQ, PRO::PO, PRO::RCV
Priority	MVP2-A

Back-reference: Card state transitions triggered by procurement actions are documented in RES::KC::0004 above and cross-referenced from the Procurement domain:

• PRO::PO — Purchase Order creation and submission fire FS-CSM-001 and FS-CSM-002
• PRO::RCV — Receiving fires FS-CSM-003
• PRO::PO Cancel — Fires FS-CSM-004 rollback

Summary

Use Case	Scenarios	US	FS	UC
RES::KC::0001 Create and Print Kanban Card	6	4	0	2
RES::KC::0002 Print Kanban Cards	2	2	0	0
RES::KC::0003 View Card Details	1	1	0	0
RES::KC::0004 Card State Transitions	5	0	4	1
RES::KC::0005 Add Card to Order Queue	2	2	0	0
RES::KC::0006 Kanban QR Code	4	3	0	1
RES::KC::0007 Kanban State for Procurement	0	0	0	0
Total	20	12	4	4

---