operations-service/docs/api/internal-workflow-contracts.md

Internal Workflow Contracts

Purpose

operations-service exposes workflow-shaped internal endpoints that restaurant BFFs can consume without inventing their own orchestration payloads.

Endpoint Surface

• GET /internal/operations/config?locationId=<id>
• POST /internal/operations/decision
• GET /internal/operations/waiter/assignments?contextId=<id>
• POST /internal/operations/orders
• GET /internal/operations/customer/status?contextId=<id>
• GET /internal/operations/customer/orders/<orderId>?contextId=<id>
• GET /internal/operations/customer/history?contextId=<id>
• GET /internal/operations/pos/summary?contextId=<id>
• GET /internal/operations/pos/transactions/<transactionId>?contextId=<id>
• POST /internal/operations/pos/payments
• GET /internal/operations/admin/config?contextId=<id>
• POST /internal/operations/admin/service-window

Stage 46 Runtime Shape

This repo now orchestrates restaurant workflow over the shared lifecycle store exposed by operations-dal.

That means:

• submitted orders are persisted as shared order/check records
• customer status reads come from persisted restaurant state rather than static arrays
• customer detail and history no longer need to be projected from the status summary payload
• POS summary reads only served checks that remain payable
• POS detail can resolve a specific check directly from the shared lifecycle store
• payment capture updates persisted check state and appends lifecycle events

Contract Intent

• waiter assignments surface floor-facing table attention derived from shared order/check state
• customer status, detail, and history all reflect the same lifecycle that waiter and POS flows observe
• POS payment only opens for served orders with outstanding balance
• POS detail stays lifecycle-backed even when the check is not yet payable, which keeps downstream error handling honest
• restaurant-admin configuration remains control-plane oriented and intentionally separate from order persistence

Remaining Limitation

• Kitchen ticket creation and kitchen state feedback still depend on kitchen-service propagation alignment in the Stage 50 companion task.