Purchase Order Feature

The Purchase Order (PO) feature closes the Kanban replenishment loop by giving the Procurement Manager (David) a structured workflow for grouping cards into supplier orders, submitting them, and marking them received. It replaces the ad-hoc, per-card ordering approach from Demo202509 with a cohesive PO lifecycle.

Procurement Workflow Overview

The end-to-end procurement flow has six stages:

1. Cards for items appear in the Items view once scanned at the reorder point.
2. Cards are added to the Order Queue by moving them to the REQUESTED state (via the accept signal).
3. The Procurement Manager reviews the Order Queue. Cards are grouped by Vendor and Order Method.
4. The manager selects cards and creates a Purchase Order. For online orders, the item URL opens in the browser. For email or phone orders, a side panel renders the email text for copy-paste. In a future iteration, the system will send the email directly.
5. Submitting the PO moves the selected cards to IN_PROCESS (via start-processing).
6. When goods arrive, the Receiving Clerk confirms delivery, moving cards to FULFILLED (via receive).

Card State Transitions Driven by PO Actions

PO Action	Backend Signal	Card Transition
Create PO / add cards	accept	REQUESTING to REQUESTED
Submit PO	start-processing	REQUESTED to IN_PROCESS
Submit and Release (shortcut)	receive	REQUESTED to FULFILLED
Receive against PO	receive	IN_PROCESS to FULFILLED

READY and FULFILLING states are bypassed for now and are reserved for the future Kanban Loops feature.

Feature Scope (Full Design)

The full PO feature includes:

• Order Queue — grouped view by Vendor plus Order Mechanism, with “Order All” and “Order Selected” actions.
• PO Creation — from Order Queue cards or directly from Items; side panel with vendor fields, PO header, and aggregated order lines.
• PO Editing — full editability of header, lines, and quantities; add or remove free-form lines.
• PO Submission — validate, advance card states, and persist the PO record.
• PDF Generation — send PO payload to Documint, open the resulting PDF (same mechanism as card and label printing), and copy the email body to clipboard.
• Receiving — receive shipments against submitted POs and advance card states to FULFILLED.
• Submit and Release — a shortcut that skips the formal receiving step for operations without a receiving dock.

UI Structure

The PO module uses four view types, following the general List View Behaviors contract:

List Views — Order Queue (grouped by vendor + order mechanism), Open Orders, Submitted Orders, Confirmed Orders, Receiving, Archive, and Order Lines within a PO.

Detail Views — Read-only PO header and line detail panels with action buttons (submit, edit, receive, print).

Editors — PO header form (vendor, dates, annotations), line edit form (quantity, unit price, notes), and receive form (received quantities).

Lookups — Order lookup (search existing POs), card lookup (add kanban cards to a PO), and item lookup (add items directly).

Actions follow a color-coded convention: gray groupings, blue tables, green read-only fields, pink editors, yellow lookups, red destructive actions. UI-specific requirements (field placement, validation timing, responsive breakpoints) are documented in the Implementation Notes.

Personas Involved

• Inventory Manager (Irene) / Shop Worker (Sam) — scans cards, triggering the REQUESTING state and populating the Order Queue.
• Procurement Manager (David) — reviews the Order Queue, creates and submits POs, generates PDFs for vendor communication.
• Receiving Clerk (Keisha) — receives shipments, closes the loop by marking cards FULFILLED.

Related Specifications

• Demo202509 Use Cases: View Procurement Queue, Add Card to Procurement Queue, Release Card to Production from Receiving, Create Vendor Carts.
• Full Kanban Card State Machine: /technical-documentation/contents/2_design/2_functional/information-structure/domain-model/actions/kanban/kanban.md