Orders: Data Model

The Orders module stores two tables — "order" and order_line — each an occurrence-carrying bitemporal table: every mutation appends a version row pairing what was attempted with the resulting state, rather than editing a row in place. Its subjects are the order (the header: status, priority, supplier, assignee) and its lines (item, quantity, confirmation, receiving progress). This page is the field-complete reference for both tables and their DTOs; for the module’s design and lifecycle, see Orders. See Data Models — Reading Guide for the shared envelope shapes referenced throughout.

Entities and relationships

order_line holds its parent order by a same-module order_ref column (no DB foreign key). Both the order’s supplier and a line’s item are floating references into other modules that freeze into version pins once the order is submitted; a line’s serviced demand items stay floating refs for the order’s whole life.

Stored shape

"order" (quoted identifier — order is a reserved word)

Column	Type	Null	Role
id	UUID	NOT NULL (PK)	identity
tenant_id	UUID	NOT NULL	identity
effective_as_of	timestamptz	NOT NULL	identity
recorded_as_of	timestamptz	NOT NULL, default now()	identity
previous	UUID	NULL	identity
eid	UUID	NOT NULL	identity
retired	boolean	NOT NULL, default false	bookkeeping
bts_author	varchar(255)	NOT NULL	bookkeeping
bts_author_sub	varchar(255)	NULL	bookkeeping
bts_created_by_sub	varchar(255)	NULL	bookkeeping
bts_note	varchar(512)	NULL	payload
created_by	varchar(255)	NOT NULL, default ‘system’	bookkeeping
created_at_effective	timestamptz	NOT NULL, default now()	bookkeeping
created_at_recorded	timestamptz	NOT NULL, default now()	bookkeeping
order_number	varchar(64)	NOT NULL	payload
kind	varchar(64)	NOT NULL	payload
outcome	varchar(16)	NOT NULL	payload
reason	varchar(64)	NULL	payload
notification_id	UUID	NULL	payload — see Schema notes
status	varchar(32)	NOT NULL	payload
priority	varchar(16)	NOT NULL	payload
assignee	varchar(255)	NULL	payload — plain text, not a reference; see Data Models — Reading Guide
notes	varchar(2048)	NULL	payload
internal_notes	JSONB	NULL	payload
s_supplier_entity_id	UUID	NULL	payload
s_supplier_affiliate_eid	UUID	NULL	payload
s_supplier_name	varchar(255)	NULL	bookkeeping
s_supplier_record_id	UUID	NULL	bookkeeping
s_supplier_retired	boolean	NOT NULL, default false	bookkeeping
s_supplier_provenance_updated_by	varchar(255)	NULL	bookkeeping
s_supplier_provenance_updated_at	bigint	NULL	bookkeeping
s_supplier_base	JSONB	NULL	payload
s_supplier_overrides	JSONB	NULL	payload

Unique constraints: order_committed_previous — UNIQUE partial index on (previous) WHERE outcome = 'COMMITTED', the P2-H1 committed-successor fork guard (PDEV-1166). Turns “at most one committed successor per row” into a database invariant.

order_line (table renamed from procurement_order_line)

Column	Type	Null	Role
id	UUID	NOT NULL (PK)	identity
tenant_id	UUID	NOT NULL	identity
effective_as_of	timestamptz	NOT NULL	identity
recorded_as_of	timestamptz	NOT NULL, default now()	identity
previous	UUID	NULL	identity
eid	UUID	NOT NULL	identity
retired	boolean	NOT NULL, default false	bookkeeping
bts_author	varchar(255)	NOT NULL	bookkeeping
bts_author_sub	varchar(255)	NULL	bookkeeping
bts_created_by_sub	varchar(255)	NULL	bookkeeping
bts_note	varchar(512)	NULL	payload
created_by	varchar(255)	NOT NULL, default ‘system’	bookkeeping
created_at_effective	timestamptz	NOT NULL, default now()	bookkeeping
created_at_recorded	timestamptz	NOT NULL, default now()	bookkeeping
order_ref	UUID	NOT NULL	identity
item_entity_id	UUID	NULL	payload
item_item_name	varchar(255)	NULL	bookkeeping
item_record_id	UUID	NULL	bookkeeping
item_retired	boolean	NOT NULL, default false	bookkeeping
item_provenance_updated_by	varchar(255)	NULL	bookkeeping
item_provenance_updated_at	bigint	NULL	bookkeeping
kind	varchar(64)	NOT NULL	payload
outcome	varchar(16)	NOT NULL	payload
reason	varchar(64)	NULL	payload
notification_id	UUID	NULL	payload
s_line_status	varchar(16)	NOT NULL	payload
s_quantity	JSONB	NOT NULL	payload
s_received	JSONB	NOT NULL	payload
s_demand	JSONB	NOT NULL	payload
s_confirmation	JSONB	NULL	payload

Unique constraints: order_line_committed_previous — the same P2-H1 fork guard as "order", UNIQUE partial index on (previous) WHERE outcome = 'COMMITTED'.

Projected shape

OrderPayload (the payload of EntityRecord<OrderPayload, OrderMetadata>)

Field	Type	Stored or computed	Notes
eId	EntityId	Stored	← eid
orderNumber	String	Stored
kind	OrderOccurrenceKind	Stored
outcome	OrderOutcome	Stored
reason	String?	Stored
notificationId	UUID?	Stored	see Schema notes
status	OrderStatus	Stored
supplier	SupplierBinding?	Stored	the s_supplier_* cluster, reference + base/override values
priority	OrderPriority	Stored
assignee	String?	Stored	plain text
notes	String?	Stored
internalNotes	List<String>	Stored	NULL stored as empty list

OrderLinePayload (the payload of EntityRecord<OrderLinePayload, OrderLineMetadata>)

Field	Type	Stored or computed	Notes
eId	EntityId	Stored	← eid
orderRef	UUID	Stored
item	ItemReference.Value?	Stored	the item_* cluster
kind	OrderLineOccurrenceKind	Stored
outcome	OrderOutcome	Stored
reason	String?	Stored
notificationId	UUID?	Stored
lineStatus	LineStatus	Stored	← s_line_status
quantity	GeneralizedQuantity	Stored	← s_quantity
received	GeneralizedQuantity	Stored	← s_received
demand	Set<UUID>	Stored	← s_demand
confirmation	Confirmation?	Stored	← s_confirmation

Note: the business-layer readings effectiveLineQty and openOf are computed over OrderLineState but are not projected onto any wire DTO.

OrderReadingsDto (GET .../order/{eId}/readings)

Field	Type	Stored or computed	Notes
confirmed	Boolean	Computed	every live line has a non-null confirmation
receiving	Boolean	Computed	some live line has non-zero received
reading	String	Computed	"RECEIVING" if receiving, else "CONFIRMED" if confirmed, else "SUBMITTED"

OrderCommitResponse / OrderLineCommitResponse (mutation responses)

Field	Type	Notes
occurrence	OccurrenceDto	see the shared envelope in Data Models — Reading Guide
record	EntityRecord<OrderPayload, OrderMetadata> (or the line equivalent)

Cross-module references

Column	Target	Kind	Freezes
s_supplier_entity_id, s_supplier_affiliate_eid	Business Affiliate — BusinessRole (VENDOR)	floating	at Submit
s_supplier_record_id	Business Affiliate BusinessRole version row	version-pin	stamped by resolution while DRAFT, or by the retirement cascade
s_supplier_name, s_supplier_retired, s_supplier_provenance_*	Business Affiliate BusinessRole	value-snapshot	refreshed while DRAFT
item_entity_id	Item	floating	at Submit
item_record_id	Item version row	version-pin
item_item_name, item_retired, item_provenance_*	Item	value-snapshot	the denormalized effective Item (PDEV-1418)
s_demand	Demand — DemandItem	floating (line-carried, no FK)	never — membership checked live
notification_id (line)	Demand ProductionDelivery, or null for manual repair	floating	stamped by the receipt listener
assignee	none — plain text, not a reference	—	never a reference at Phase 2; see Data Models — Reading Guide

order_line.order_ref is a same-module parent-child link (child holds the parent’s eid; no FK, no child table).

API surface

Orders is Designed — build pending. The routes below are the designed shape; the live /v1/order/... endpoints in the API Endpoint Catalog belong to the client-side purchase-order capability this module replaces, not to an earlier version of it.

Both subjects follow the request/response call-shape convention in The Orders v2 Call Shape.

order

Method	Path	Purpose	Main refusals
POST	order/create	Create an order (DRAFT)
POST	order/update-supplier	Choose or override the supplier binding
POST	order/reset-to-supplier	Discard per-order supplier overrides
POST	order/update-details	Set priority/assignee/notes	DRAFT only
POST	order/submit	Freeze and transmit (DRAFT → SUBMITTED)	needs ≥1 line, linked+unretired supplier
POST	order/close	SUBMITTED → CLOSED
POST	order/cancel	DRAFT → CANCELED
POST	order/delete	Tombstone a terminal order
POST	order/annotate	Set internal notes
GET	order/{eId}?effectiveasof&recordedasof	An order as of a coordinate	tombstoned = 404
GET	order/{eId}/log?page&size	Occurrence log, most recent first
GET	order/{eId}/readings?effectiveasof&recordedasof	The CONFIRMED/RECEIVING reading

order-line

Method	Path	Purpose	Main refusals
POST	order-line/add-line	Add a line (from demand, from item, or free-form)
POST	order-line/update-line	Set the requested quantity
POST	order-line/attach-demand / detach-demand	Adjust serviced demand items
POST	order-line/remove-line	Tombstone a line while composing
POST	order-line/annotate-line	Append a note occurrence
POST	order-line/close-line	Close a line
POST	order-line/record-receipt / reverse-receipt	Manual repair of received quantity
POST	order-line/record-acknowledgment	Record the vendor’s answer
GET	order-line/{eId}?effectiveasof&recordedasof	A line as of a coordinate	removed = 404
GET	order-line/{eId}/log?page&size	Occurrence log
GET	order-line/by-order/{orderId}?effectiveasof&recordedasof	Live lines of an order

Notifications

Listens for DemandNotification.ProductionRecorded/ProductionRevoked (reconciles received quantity), and for item/business-role change notifications (keeps the floating references current while DRAFT). Emits nothing of its own beyond two implementation-only occurrences (SYNC_ITEM, SYNC_SUPPLIER) that keep the denormalized snapshots in sync — they carry no model signature.

Schema notes

• order.notification_id has no observed writer. No order-subject occurrence kind was found stamping a non-null value onto this column — it’s declared and read, but nothing in the current code path sets it.
• OrderLineOccurrenceKind’s own KDoc disagrees with its enum body. The KDoc says “NINE” model line-subject kinds; the enum body declares 10 model kinds plus the implementation-only SYNC_ITEM, for 11 total.
• assignee is plain text, not a version pin, despite the domain design describing it as one — see the Staff note in Data Models — Reading Guide. The model reserves the shape; nothing populates it at Phase 2.