Order Implementation Notes

This page collects implementation-level notes for the Order Management module: data model changes required by MVP2, UI/UX requirements and information structure, and the dependency relationships between orders, lines, and upstream entities (Kanban Cards, Items, Item Supplies).

---

Data Model Changes (MVP2)

Item Module

Item Entity

New and modified fields required to support purchase order creation:

• Item.description (Text): Allows users to provide a description of the item.
• Item.sku (Text): A code given to the item for identification within the tenant.
• Item.preferredSupply() (ItemSupply): Computed value providing the preferred supply source for the item:
  • If defaultSupply is not null, returns the ItemSupply whose supplier field matches defaultSupply from primarySupply or secondarySupply.
  • If defaultSupply is null, returns primarySupply if not null, otherwise secondarySupply (which may also be null).
  • Otherwise, returns the first ItemSupply entry if any exist, or null.
• Item.effectiveSupply(requestedSupplier: String = null) (ItemSupply): Computed value providing the effective supply source:
  • If requestedSupplier is not null, returns the ItemSupply whose supplier field matches. If none match, returns null.
  • If requestedSupplier is null, returns Item.preferredSupply().

ItemSupply Entity

• ItemSupply.name (Text): Holds the name of the item given by the supply source. Defaults to ItemSupply.sku.

Order Module

OrderLine Entity

Additional fields:

• title (Text): Holds the identification of the item being ordered by the line.

Kanban Card Module

No changes defined yet for MVP2.

---

UI/UX Requirements

Overview

Order Management functionality is accessed by users through the UI. The information structure below represents an abstract model of what users interact with — it does not prescribe actual UI layout. The different groupings could be implemented as nested menus, tabs within an Ordering section, or filters within a single screen.

Color Convention for Diagrams

• Gray boxes group information presentations sharing common actions.
• Blue boxes represent a list of elements (table component). A box joined below a blue box is accessible by selecting an element from that list.
• Green boxes show a read-only display of a single element.
• Pink boxes allow editing of a single element.
• Yellow boxes represent lookup and selection of a single element from a set.
• Red text represents actions available to the user.

User Information Structure (High-Level)

Detailed Information Structure

List Views

Order Queue

• Contents: Cards in REQUESTED state.
• Actions: Create Order, Add Lines to Order.

All Order Lists

• Contents: Orders.
• Actions (single select): View Header, View Lines, Annotate.
• Actions (multi-select): Print.

Open List (Draft Orders)

• Contents: Orders in NEW state.
• Actions (single select): Edit Header, Add Lines, Remove Line, Receive.
• Actions (multi-select): Submit, Cancel.

Submitted List

• Contents: Orders in SUBMITTED state.
• Actions (multi-select): Confirm, Receive, Complete, Archive.

Confirmed List

• Contents: Orders in CONFIRMED state.
• Actions (multi-select): Receive, Complete, Archive.

Receiving List

• Contents: Orders in RECEIVING state.
• Actions (multi-select): Receive, Complete, Archive.

Archive List

• Contents: Orders in ARCHIVED state.
• Actions: None.

Order Lines

• Contents: Order Lines for a given Order.
• Actions (single select): View Line, Annotate Line, Edit Line (only if Order in Open state).
• Actions (multi-select, Open/Submitted/Confirmed/Receiving): Receive.

Detail Views

View Header

• Contents: Properties of an Order Header. Complex properties may be shown in specialized sub-views (e.g., addresses).
• Actions: Same as the list view that originates it.

View Line Details

• Contents: Properties of an Order Line.
• Actions: Same as the Order Lines list view that originates it.

Editors

Header Form

• Contents: Properties of an Order Header (editable). Complex properties rendered and edited in specialized sub-views.
• Validation: Supplier must be compatible with all order lines; deliverBy date must be after orderDate.

Edit Line Form

• Contents: Properties of a single Order Line (editable).
• Validation: Same as Header Form.
• Navigation: User can save or cancel, then close, navigate to the next line, or navigate to the previous line.

Annotation

• Contents: The privateNotes property of an Order or Order Line, in editable long-text format.
• Actions: Save, Cancel; optionally navigate to the next or previous element if opened from a list view.

Receive

• Contents: Read-only order quantity + editable received quantity (receivedQuantity.amount), plus read-only unit.
• Actions: Save, Cancel; optionally navigate to next or previous element.

Lookup Views

Lookup views find and select a single element. They provide a text input for filtering, displaying minimal information for the user to make a selection.

Lookup Order

• Contents: Orders.
• Search: Order Number, Supplier Name.
• Display: Order Number, Supplier Name, Order Date, State.

Lookup Cards

• Contents: Kanban Card Details.
• Search: Item Name.
• Display: Item Name, Card Number, State.

Lookup Items

• Contents: Items.
• Search: Item Name, SKU, PrimarySupply.Supplier, SecondarySupply.Supplier.
• Display: Item Name, SKU, Location, Preferred Supplier.
• Additional Actions: Add New Item.

---

Kanban Card and Item Dependency Updates

Overview

Orders and Order Lines reference information from Kanban Cards, Items, Item Supplies, and Business Affiliates. When any of these upstream entities are updated, open orders need to react to keep their data current.

Propagation applies 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. See PRO::PO::0009 for the full data propagation specification.

Update Propagation Rules

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

Upstream Change	PO Field Updated
Supplier rename	OrderHeader.supplierName
Item name change	OrderLine.title
Item description change	OrderLine.description
ItemSupply price change	OrderLine.unitCost

Information Model Dependencies