Purchase Order Behaviors

View Interactive Prototype →

Manages the procurement order lifecycle: creation (from the Order Queue, from Kanban Cards, from items, free-form, or by copy), line item management, submission to vendors, acceptance tracking, receiving against lines, and archiving. The order entity follows a ten-state lifecycle (NEW through CLOSED, CANCELLED, REJECTED, DISPUTED).

PRO::PO::0001 — Create Purchase Order

Create a new purchase order from various sources: order queue cards, item lists, direct input, or by copying an existing order.

Persona	David Dealsworth (Purchasing Manager)
Depends	PRO::OQ::0007, RES::KC
Status	Proposed
Priority	MVP2-B Partial

PRO::PO::0001::0001.UC — Create PO from Order Queue

| Priority | MVP2-B |

Create a PO draft from a vendor group in the Order Queue. The Purchasing Manager selects cards in a vendor group (or clicks “Order All”) and the system opens a PO side panel populated with vendor information, PO header fields, and one line per unique item. Cards transition from REQUESTING to REQUESTED via accept events fired at creation time. See PRO::OQ::0007 for the full queue-side interaction.

PRO::PO::0001::0002.UC — Create PO from Kanban Cards

| Priority | MVP2-B |

The user selects one or more cards from the Order Queue and initiates a new purchase order. The system validates that all selected cards belong to items with a compatible supplier or no supplier. Cards are grouped by item and unit of measure into individual order lines. Line quantity equals the sum of reorder quantities for the group. Unit costs, line costs, and goods value are calculated from the item’s ItemSupply pricing record. The cards are transitioned to REQUESTED state by the backend as part of order creation. The created PO is then displayed in edit mode for header review.

API route: POST /v1/order/order/from-kanban-cards with a list of card entity IDs; returns the created order record.

PRO::PO::0001::0003.UC — Create Empty Order

| Priority | MVP3 |

The system presents a blank order form. The user fills in header information and may add order lines. The order is persisted in NEW state with the following defaults: allowPartial = true, deliverBy = now + 7 days, status = NEW. No lines are created; the returned OrderRecord includes an empty page result for lines. No automatic notifications or workflow transitions are triggered; the user must orchestrate subsequent steps such as adding lines and submitting.

Precondition: The caller provides an OrderMetadata payload and author identifier.

Postcondition: A new order header version exists in the database with no lines. The returned OrderRecord includes pagination metadata pointing to the header’s line universe for subsequent line additions.

PRO::PO::0001::0004.UC — Create Order as Copy of Existing Order

| Priority | MVP3 |

The user selects an existing order from the list and requests a copy. The system creates a complete copy with the following modifications: history starts fresh at the time of the copy; attachments to Kanban Cards are not copied; item associations on each order line are reset to the current item version. If a referenced item has been deleted since the original order was placed, the corresponding line is marked invalid and the PO cannot be submitted until the line is corrected or removed.

Status: Not yet implemented. There is no service that clones an existing order. Callers needing copy semantics must orchestrate the process manually by reading the order via OrderRecordService.getParentChild and re-submitting adjusted payloads. A dedicated copy utility must be introduced before this capability is exposed in the product UI.

PRO::PO::0001::0005.UC — Create Order from Header and Lines

| Priority | MVP3 |

The user provides OrderHeader and OrderLines data directly. The system validates the supplied data, retrieves reference information for any item links, enriches line details from item supply data where fields are missing, and persists the order in NEW state. This use case supports programmatic or import-driven order creation where the full order structure is known upfront.

PRO::PO::0001::0006.UC — Create Order from List of Items

| Priority | MVP3 |

The user selects items from the Item List and initiates order creation. All selected items must share a compatible supplier. The system selects the supplier with the highest mention count across the selected items’ ItemSupply records as the primary supply and creates one order line per item with quantities sourced from that supplier’s reorder quantity. Lines are enriched from ItemSupply data.

PRO::PO::0001::0007.UC — Create Order from Item Identifiers

| Priority | MVP3 |

The user provides a list of item entity IDs and the system creates a full order: one header and one line per item. Items must share a compatible supplier. Quantities default to the supplier’s reorder quantity from the ItemSupply record. No Kanban Card associations are created. This use case supports direct ordering that bypasses the queue, for example when restocking without going through a physical kanban trigger.

PRO::PO::0001::0008.UC — Create Order from Demand Queue (Overview)

| Priority | MVP2-B |

The user navigates to the Order Queue, selects one or more cards from the same vendor group (using filtering and pagination as needed), and triggers “Create Order.” Depending on the vendor’s configured order mechanism:

• The system accesses the vendor’s online store and creates a cart with the items, presenting it for the user to complete the transaction.
• The system prepares an email or textual PO for the user to copy and paste into their ordering application.

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

Cross-reference: The full interaction sequence for this flow is documented in PRO::OQ::0007::0001 (Order Queue domain). The Order Queue scenario covers the demand-side interaction; this entry records the cross-domain participation in the PO creation lifecycle.

PRO::PO::0002 — View Purchase Orders

Browse, filter, sort, and inspect purchase orders across status groupings.

Persona	David Dealsworth (Purchasing Manager)
Depends	GEN::LST::0001, GEN::LST::0003, GEN::LST::0004, GEN::LST::0005, GEN::LST::0006
Status	Proposed
Priority	MVP3

PRO::PO::0002::0001.UC — List Purchase Orders

Query, filter, and sort Purchase Orders. POs are categorized into status groupings for display purposes:

• Draft: NEW
• Receiving: SUBMITTED, IN_PROCESS, PARTIALLY_RECEIVED
• Completed: RECEIVED, CLOSED, ARCHIVED, CANCELLED

Filtering uses the general DataAuthority query capability (POST /v1/order/order/query). Available filter fields include status, order_number, supplier_name, order_date_timestamp, deliver_by_timestamp, expedite, and allow_partial, as well as composite fields for delivery address, procurement contact, and sales contact. Results are sortable by any indexed field.

PRO::PO::0002::0002.UC — View Purchase Order Details

From any list, the user selects a PO to view its details. Three API paths are available depending on what information is needed:

• GET /v1/order/order/{eId} — returns the PO header only.
• GET /v1/order/order/full/{eId} — returns the PO header and all lines.
• GET /v1/order/order/lines/{eId} — returns the PO lines only.

The full view includes header fields, line items with quantities and costs, and the list of serviced Kanban Cards associated with each line.

PRO::PO::0002::0003.UC — View PO List and Details (Actor-Goal)

The Purchasing Manager navigates to the PO list view. POs are filterable by status groupings: Draft (NEW), Active (SUBMITTED, IN_PROCESS, PARTIALLY_RECEIVED), Completed (RECEIVED, CLOSED), and Cancelled. The user clicks a PO row to view its full details: header fields (vendor, dates, terms, contact info, notes), order lines (item name, SKU, quantity, unit cost, line total), and the list of Kanban Cards serviced by the order.

Postcondition: The actor can review PO history and current state, including which cards were fulfilled by each order.

PRO::PO::0002::0004.UC — View Order Details (E2E)

From the /order-queue page, the user clicks an order item row to open the Item Details Panel. The panel shows item metadata (name, SKU, description), a card preview (serial number, state, quantity), and Kanban Card information. Closing the panel returns to the Order Queue without losing the current tab selection or search filter state.

PRO::PO::0003 — Edit Purchase Order

Modify PO header fields, add or remove lines, and manage card associations on draft orders.

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

PRO::PO::0003::0001.UC — Add Cards to Existing Purchase Order

| Priority | MVP3 |

The Purchasing Manager selects additional cards in the Order Queue and chooses “Add to existing order,” then selects a draft PO in NEW state from a most-recent-first list. The system validates vendor compatibility: all selected cards must belong to items with a supply record matching the PO’s vendor. Cards compatible with existing PO lines (same item and unit of measure) are aggregated into those lines, increasing their quantity. Cards representing new items are added as new lines.

After the add completes, accept events are sent to the newly added cards, transitioning them from REQUESTING to REQUESTED. API route: PUT /v1/order/order/from-kanban-cards/{eId} with a list of card entity IDs.

Precondition: A PO exists in NEW state. Additional cards in REQUESTING state are available for the same vendor.

Postcondition: The existing PO has additional lines or augmented quantities. Newly added cards are in REQUESTED state.

PRO::PO::0003::0002.UC — Edit Purchase Order Header and Lines

| Priority | MVP2-B |

The actor opens a PO in NEW state from the Order Queue “Recent Orders” tab or the PO list. The system displays the PO with editable header and lines. The actor modifies fields: vendor name, contact information, shipping terms, delivery address, payment terms, line quantities, line descriptions, and notes. Changes are saved via PUT /v1/order/order/{eId}.

Card states are unchanged when header or line fields are edited; associated cards remain in REQUESTED. The following fields are system-managed and cannot be overwritten by the actor: orderNumber, status, and goodsValue.

Precondition: The PO exists in NEW state.

PRO::PO::0003::0003.UC — Update Order Header Properties

| Priority | MVP2-B |

From the Draft order list, the actor selects an order and clicks Edit. The system displays the PO header in edit mode, loading the current header information from the list cache. The actor updates fields, which are stored in a local copy without immediately persisting. On Save, the system calls PUT /v1/order/order/{eId} with the updated OrderHeaderInput. On success, the updated header is displayed. On error, validation messages are shown without losing the actor’s changes. Dismissing the edit view returns to the Draft order list.

Only orders in NEW state are editable; the Edit action is not available from the Receiving or Completed list views.

PRO::PO::0003::0004.UC — Add Lines from Kanban Cards

| Priority | MVP3 |

Given a Draft PO, the actor selects additional cards from the Order Queue and chooses “add to existing order.” The system presents a selector of orders in NEW state sorted by most-recently-updated first. After the actor selects an order, the system validates card compatibility and adds new lines (merging with existing lines where item and UOM match) or adds new lines for new items. Cards are transitioned to REQUESTED on addition. The refreshed Order Queue is displayed after dismissal.

PRO::PO::0003::0005.UC — Remove Line from Purchase Order

| Priority | MVP3 |

Given a Draft PO, the actor selects “Edit Lines” to open the line list. The actor selects a line and clicks “Remove.” The system removes the line via DELETE /v1/order/order/{eId}/lines/{lineEId} and displays the updated line list. If multiple lines need to be removed, the frontend loops through them and calls the API for each one; a batch remove endpoint may be provided in future.

Postcondition: The selected line is removed from the PO. Cards previously associated only with the removed line are returned to REQUESTING via shelve events.

PRO::PO::0003::0006.UC — Add Single Line to Order

| Priority | MVP2-B |

A single order line can be added to an existing order in two ways. First, from a Kanban Card: the line takes the values of the current version of the item referenced by the card (title, quantity, unit cost from the order’s supplier name). Second, as a blank line: the UI presents an item selector filtered to items that share the order’s vendor. The actor can type to filter items by name prefix, select from the list, or create a new item if the typed name does not match.

Bulk line addition from CSV is also supported. If the item name in the CSV matches an existing item (case-insensitive), that item is used. If not, the line is marked INVALID and must be corrected before the order can be submitted.

Implementation note: The addLine service enriches line fields from the item’s current version using OrderHelper.adjustLine but does not automatically rebalance the order header (goods value, supplier selection). Header adjustments require additional orchestration by calling OrderHelper.adjustHeader.

PRO::PO::0004 — Submit Purchase Order

Finalize a draft PO and advance it for vendor communication.

Persona	David Dealsworth (Purchasing Manager)
Depends	PRO::PO::0003
Status	Proposed
Priority	MVP2-B Partial

PRO::PO::0004::0001.UC — Submit Purchase Order

| Priority | MVP2-B |

The actor clicks “Submit PO.” The system validates required fields: vendor name must be present; at least one line must exist; all lines must have a non-empty title and non-null quantity. On validation success, the system sends start-processing events to all cards in REQUESTED state across all PO lines, transitioning them to IN_PROCESS. The PO status advances to SUBMITTED.

Validation error messages:

• “Vendor name is required.” if vendor name is absent.
• “Add at least one line item.” if no lines exist.
• “All lines must have a title and quantity.” if any line is missing required fields.

API route: PUT /v1/order/order/{eId}/submit

PRO::PO::0004::0002.UC — Submit and Release (Skip Receiving)

| Priority | MVP3 |

The actor clicks “Submit and Release.” The system applies the same validation as Submit. On success, instead of transitioning cards to IN_PROCESS, the system sends receive events that transition cards directly from REQUESTED to FULFILLED. The PO status advances to RECEIVED or CLOSED. No receiving step is required.

This use case supports organizations that do not use a formal receiving workflow, or for orders where the goods are already on hand and the PO is being created retroactively for record-keeping purposes.

Postcondition: Cards are in FULFILLED and immediately available on the shop floor. The PO is complete.

PRO::PO::0004::0003.UC — Submit Order (API)

| Priority | MVP3 |

This use case describes the desired submission workflow that transitions a draft PO into an externally committed state: validates the order, transitions its status, and triggers downstream integrations such as vendor notification. Not yet implemented. The existing services expose CRUD helpers but do not change OrderStatus or initiate vendor communication. This use case tracks the outstanding design work.

PRO::PO::0004::0004.UC — Submit a Purchase Order (Lifecycle Stub)

| Priority | MVP3 |

Lifecycle sub-use-case placeholder for the submission step within the full PO process order flow. Detailed interaction flows and API routes are not yet defined. This stub reserves the identifier in the lifecycle taxonomy and signals that the implementation gap described in PRO::PO::0004::0003.UC must be closed before this placeholder can be replaced with a full specification.

PRO::PO::0004::0005.UC — Send Order via Email (E2E)

| Priority | MVP3 |

From the /order-queue page, the actor clicks the email/send action for a supplier group. A pre-populated email panel opens containing the vendor email address, a subject line with the PO number, and a body listing item names, SKUs, and quantities. The actor reviews the email, optionally edits the body, and sends. Cards associated with the order advance to REQUESTED on send confirmation.

PRO::PO::0005 — Post-Submission Order Tracking

Extend the PO lifecycle beyond SUBMITTED with mechanisms to track vendor responsiveness and trigger follow-up communication.

Persona	David Dealsworth (Purchasing Manager)
Depends	PRO::PO::0004
Status	Proposed
Priority	MVP3

PRO::PO::0005::0001.US — Vendor Acknowledgment Tracking

The accept signal exists in the PO lifecycle definition but has no UI or automated trigger for vendor-side acknowledgment. This story adds acknowledgment tracking to the post-submission workflow: the system provides a way for David to mark when a vendor confirms receipt of the order. An unacknowledged order that has been in SUBMITTED state for longer than a configurable threshold should surface as an action item.

PRO::PO::0005::0002.US — Order Aging Visibility

The PO list supports status filtering but does not display time-in-state metrics. David needs to see how long each order has been in SUBMITTED or IN_PROCESS state to identify vendors that need follow-up. This scenario adds an elapsed-time indicator to the PO list view, similar to the queue aging visibility requested for the Order Queue (PRO::OQ::0004).

PRO::PO::0005::0003.US — Vendor Follow-Up Action

A quick follow-up action from the PO detail screen, pre-populated with order context (vendor name, PO number, order date, items ordered), allows David to send a chaser to vendors that have not acknowledged or shipped. The follow-up should create a record so David can see when the last contact was made and avoid duplicate follow-ups.

PRO::PO::0006 — Generate PO Document

Produce vendor-ready PDF and email content from PO data.

Persona	David Dealsworth (Purchasing Manager)
Depends	PRO::PO::0004, SAC::PDF
Status	Proposed
Priority	MVP2-B

PRO::PO::0006::0001.UC — Generate PO PDF

The actor clicks “Generate PO.” The system shows a loading state (“Generating…”), assembles the PO payload, and sends it to the Documint service. On success:

• The PDF opens in a new browser tab using the same mechanism as card and label printing.
• The email body is copied to the clipboard.
• A confirmation toast reads: “PO generated. Email body copied to clipboard.”

On generation failure: “Couldn’t generate PO. Try again.” A retry button is shown; clipboard is not updated if generation failed.

On clipboard failure: “Clipboard permission blocked.” A manual “Copy email text” button is shown as a fallback.

Postcondition: The actor has a vendor-ready PDF and email text in the clipboard, ready to send.

PRO::PO::0006::0002.FS — PDF Generation via Documint

The system generates a vendor-ready PDF by sending the PO payload to the Documint service. The payload structure matches the Documint template mapping defined in the Simplified PO Spec V1, Section 10. PDF generation uses the same rendering path as card and label printing. The email body is a fixed template (not customizable per order); it is copied to the clipboard on successful generation. If clipboard access is blocked, a manual copy button appears as a fallback. The Documint service is treated as a synchronous dependency; failures are surfaced immediately with a retry option.

PRO::PO::0007 — Cancel Purchase Order

Cancel a draft PO, returning associated cards to the queue for potential re-ordering.

Persona	David Dealsworth (Purchasing Manager)
Status	Proposed
Priority	MVP3

PRO::PO::0007::0001.UC — Cancel Purchase Order

The actor opens a PO in NEW or SUBMITTED state and clicks “Cancel.” A confirmation dialog asks: “Cancel this purchase order?” On confirm, the system sends shelve events to all cards in REQUESTED state, reverting them to REQUESTING and returning them to the Order Queue. For cards in IN_PROCESS state, rollback behavior is TBD — cards in IN_PROCESS may have already been communicated to vendors, making automatic reversal complex. The PO status advances to CANCELLED.

Postcondition: REQUESTED cards are returned to the Order Queue. The PO is cancelled and read-only.

PRO::PO::0007::0002.UC — Cancel a Purchase Order (Lifecycle Stub)

Lifecycle sub-use-case placeholder for the cancellation step within the full PO process order flow. Detailed interaction flows and card rollback rules for IN_PROCESS state are not yet fully specified. This stub tracks the outstanding design work for IN_PROCESS card handling during cancellation.

PRO::PO::0007::0003.UC — Cancel Order from Queue (E2E)

From the /order-queue page, the actor initiates cancellation for a card. The card returns to its previous state (REQUESTING if it was REQUESTED). The item is removed from the current tab view, the badge count decrements, and the card becomes available for re-ordering in the “Ready to Order” tab.

PRO::PO::0008 — Order Data Rules

Data integrity rules governing line aggregation, validation, vendor compatibility, numbering, free-form lines, and editability.

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

PRO::PO::0008::0001.FS — Line Aggregation

| Priority | MVP2-B |

When creating a PO from multiple cards, cards belonging to the same item are aggregated into a single PO line. “Same item” is determined by matching Item entity ID (eId); if eId is missing, the system falls back to SKU matching. The aggregated line quantity equals the sum of reorder quantities from all contributing cards. Unit of measure defaults from the first card’s ItemSupply record. All contributing cards are tracked on the PO line via the servicedCards list.

This rule ensures that five cards for the same bolt item produce one PO line for five bolts rather than five separate single-bolt lines, reducing vendor communication overhead.

PRO::PO::0008::0002.FS — Snapshot Validation at Submit Time

| Priority | MVP3 |

At submit time, the system verifies that all cards contributing to PO lines are still in REQUESTED state. If any card’s state has changed since the PO draft was opened (for example, because another user cancelled it or a background process reverted it), the system shows an error and refreshes the card list in the side panel. User edits to the PO header are preserved during the refresh. The PO side panel does not live-sync with the Order Queue while it is open; this validation is the safety net for concurrent modifications.

PRO::PO::0008::0003.FS — Vendor Compatibility

| Priority | MVP2-B |

Each PO is scoped to a single vendor. The vendor is established by the Order Queue group from which the PO was created. When adding cards to an existing PO, the system validates that each card’s item has an ItemSupply record where the supplier matches the PO’s vendor. “Compatible vendor” means the item has a supply record whose supplier name matches the PO’s supplierName field. Cards without a matching supply record are rejected with a validation error.

PRO::PO::0008::0004.FS — PO Number Assignment

| Priority | MVP3 |

Each PO is assigned a unique number for identification and vendor communication. In the simplified (Lite) scope, the PO number is user-entered. In the full scope, the system auto-generates a unique number via ScopedSequenceService (format PO-000001) with an optional user override. The orderNumber field is system-managed and cannot be directly overwritten by the actor after assignment.

PRO::PO::0008::0005.FS — Free-Form PO Lines

| Priority | MVP2-B |

Users can add PO lines that are not linked to any catalog item or Kanban Card. All fields on free-form lines are free text: title, description, quantity, unit, vendor SKU, and notes. Free-form lines do not have servicedCards and do not trigger any card state transitions. They are used for one-off purchases, services, or items that are not in the catalog. API route: POST /v1/order/order/{eId}/lines.

PRO::PO::0008::0006.FS — PO Editability Guard

| Priority | MVP3 |

POs are editable only when in NEW state. Header and line mutations are rejected by the backend for POs in any other state. This is enforced via the OrderHeader.isEditable computed property. After a PO is submitted, it becomes a read-only snapshot of the purchasing commitment. The Edit action is not presented in the UI for POs outside NEW state.

PRO::PO::0009 — Data Propagation

Keep PO header and line data current when source entities change, using the notification-update pattern. Propagation applies only to POs in editable (NEW) state.

Persona	David Dealsworth (Purchasing Manager)
Status	Proposed
Priority	MVP3

PRO::PO::0009::0001.FS — Update Propagation for PO Data

When upstream entities change, open PO fields are updated automatically using the observer/notification pattern:

• Supplier rename propagates to the PO header supplierName field.
• Item name or description change propagates to the corresponding PO line title and description fields.
• ItemSupply price change propagates to the PO line unitCost field.

Propagation is applied only to POs in NEW state. Submitted POs (SUBMITTED and beyond) are frozen snapshots: they record the prices and names at the time of submission and are not retroactively updated. This ensures that submitted POs serve as reliable records of what was ordered at what price.

PRO::PO::0010 — Vendor-Specific Purchasing Knowledge

The ItemSupply entity stores vendor SKU, order method, order URL, order quantity, unit cost, lead time, and supplier contact information. It is the authoritative record for “how to buy this item from this vendor.”

Persona	David Dealsworth (Purchasing Manager)
Depends	REF::SPL
Status	Proposed
Priority	MVP3

PRO::PO::0010::0001.US — Store Vendor-Specific Purchasing Knowledge

The ItemSupply entity already stores vendor SKU, item specifications, pack sizes, ordering URLs, and ordering instructions. All PO creation flows draw from ItemSupply data to pre-populate line details: title, quantity, unit cost, and vendor SKU are all sourced from the matching ItemSupply record for the PO’s vendor. When ItemSupply records are complete and accurate, PO creation requires minimal manual data entry.

This use case motivates maintaining high-quality ItemSupply records and ties to the continuous improvement loop (PRO::E2E::0003): every correction to an ItemSupply record improves future PO creation quality.

PRO::PO::0011 — Validate Quantities Against Physical Reality

Physical validation workflow: check the point of use when queue quantities seem wrong.

Persona	David Dealsworth (Purchasing Manager)
Depends	RES::FAC
Status	Proposed
Priority	MVP3

PRO::PO::0011::0001.US — Check Point-of-Use for Questionable Quantities

When David sees a reorder quantity in the queue that seems unreasonably high or low, he wants to verify it against the actual shelf, bin, or workstation before placing the order. The system should surface item location information — facility, zone, bin — alongside the PO line quantity so David can physically inspect the location or ask someone on the floor to verify.

This scenario requires linking item location data (RES::FAC) to the Order Queue and PO line display. It motivates adding a “point-of-use” context panel or tooltip to queue items, showing where in the facility the item is used and what the current bin setup looks like.

Summary

Use Case	Scenarios	US	FS	UC
PRO::PO::0001 Create Purchase Order	8	0	0	8
PRO::PO::0002 View Purchase Orders	4	0	0	4
PRO::PO::0003 Edit Purchase Order	6	0	0	6
PRO::PO::0004 Submit Purchase Order	5	0	0	5
PRO::PO::0005 Post-Submission Order Tracking	3	3	0	0
PRO::PO::0006 Generate PO Document	2	0	1	1
PRO::PO::0007 Cancel Purchase Order	3	0	0	3
PRO::PO::0008 Order Data Rules	6	0	6	0
PRO::PO::0009 Data Propagation	1	0	1	0
PRO::PO::0010 Vendor-Specific Purchasing Knowledge	1	1	0	0
PRO::PO::0011 Validate Quantities Against Physical Reality	1	1	0	0
Total	40	5	8	27

---