Class OrderService

Read today's commercial gross total and per-product counts from durable facts.

The use case adds nothing to the read: it neither totals, groups, sorts, nor labels. Everything it reports is reconstructed from committed finalization facts, so a confirmed order contributes exactly once no matter how often this is called, and no browser or process-local counter exists that a reload or restart could lose.

Read one order's append-only finalization fact.

This is the durable "what did this order enter service as" record, kept separately from current state so that later state changes — fulfillment transitions now, metadata edits from MVP-TASK-024 — cannot rewrite it. It resolves to null for an unknown identity, so a caller can tell "no such order" from "finalized without optional metadata"; reading it mutates nothing.

Finalize a commercial order after a confirmed checkout.

The sequence is price, reserve, charge, then one atomic commit. Pricing happens first so an unavailable product is rejected before any provider is contacted. The stable application-owned operationId is supplied by the caller and is reused for every transport attempt of the same checkout operation, and that same value is the immutable order identity, so a repeat of one operation is recognizable instead of becoming a second charge (MVP-PAY-001-S04). Only a confirmed succeeded result reaches persistence: every other outcome class leaves no order, no sale, and no attempt row behind.

The operation is reserved in persistence before the provider boundary is crossed, and the reservation is what decides a duplicate rather than the order two requests happen to arrive in. A duplicate is answered from durable facts instead of being charged again:

• the same identity with different contents is refused outright, because the original operation may already have been charged for something else;
• a completed operation replays the order it already finalized;
• an operation recorded as unresolved replays OrderCheckoutUnresolvedError, because its outcome is still unknown and re-sending it could take a second payment (MVP-PAY-001-S03);
• an operation that is still pending raises OrderCheckoutInProgressError, so the original initiator stays the only one that may cross the provider boundary.

The three non-success classes are deliberately not one failure, because they differ in the one thing that decides whether paying again is safe:

• a definitive refusal (rejected or cancelled) is a certainty that no money was captured, so it raises OrderCheckoutDeclinedError and the caller may state that the order is not paid and that continuing is safe (MVP-PAY-001-S02);
• lost certainty (unknown) durably records the attempt as unresolved and raises OrderCheckoutUnresolvedError, because the application must not claim it failed, must not retry it blindly, and must not count it as a sale (MVP-PAY-001-S03, MVP-REL-001-S02, MVP-SALES-001-S07);
• a confirmed charge that could not be committed raises OrderCheckoutIncompleteError, the separate case where money was captured but no order exists.

Only the confirmed succeeded result reaches order persistence, so an unresolved attempt finalizes no order, contributes no item snapshot, and therefore enters neither the kitchen queue nor commercial sales.

Finalize an explicitly non-commercial order without invoking checkout.

The checkout collaborator is deliberately present at this common finalization boundary so the bypass is testable. Only the repository is called: it snapshots products and commits the order and items together. The collaborator is retained for commercial finalization in the next slice.

Read the active kitchen queue oldest-queued-first.

The use case adds no ordering of its own: the repository already returns durable rows in queue-entry order, and the optional queue number is never used to sort or identify an order. Later fulfillment tasks extend the same read rather than replacing it.

Read delivered order snapshots and history in delivery-time order.

Read every checkout attempt the application could not resolve.

This is the operator-facing half of MVP-PAY-001-S03: an unknown outcome must be visible rather than quietly dropped, and that visibility has to outlive the page which produced it. The list is therefore reconstructed from durable rows on every read, so a reload, a second browser, and a restarted process all show exactly the same attempts.

It reports attempts and nothing more. There is deliberately no way from here to retry or settle one: reconciliation semantics do not exist yet, and offering a control that implied they did would be worse than showing the uncertainty honestly.

Deliver one ready order and thereby remove it from the active kitchen queue.

This is the third and last named forward transition, and it is the only operation that changes an order's queue membership. It still goes through the identical conditional boundary: the update applies only while the order holds READY_TO_DELIVERED's source state and commits with its history row in one transaction, so a repeated or racing hand-off is rejected instead of appending a second delivery fact.

Nothing is deleted. The order leaves the active queue because Delivered is not an active status, so the queue read no longer returns it; the order itself, its immutable item snapshots, and every transition it ever underwent remain durable. The rejection is the same indistinguishable one used by the earlier transitions, because a missing order and an already-delivered order are not different problems for the caller to act on.

There is deliberately no reverse operation: undoing a hand-off needs a recovery flow that this task excludes, and a silent reversal would contradict a fact the customer may already have acted on.

Advance one preparing order to Ready using the same conditional history boundary.

Read every committed operational metadata correction in chronological order.

Correct one ready order back to Preparing, preserving every earlier transition.

Correct one preparing order back to Queued, appending rather than erasing history.

Advance one queued order to Preparing.

This is the fast forward operation the kitchen queue offers, and it is not a general state setter: the only transition it can perform is the declared QUEUED_TO_PREPARING pair, and the repository applies it conditionally on the order still being queued. An order that has already moved — because the operator tapped twice, or because another browser advanced it — is therefore rejected rather than silently advanced again or driven past a state the transition does not allow.

The same rejection covers a missing order, so the response never distinguishes the two and cannot be used to discover which order identities exist.

Read one order's appended fulfillment history oldest first.

The records are returned exactly as committed; a later correction adds to this sequence rather than replacing it.

Correct the only mutable finalized-order fields while preserving their history.