@open-mercato/core 0.6.7-develop.6842.1.8cd8a8883c → 0.6.7-develop.6859.1.e4727b568a

package/src/modules/sales/commands/documents.ts

@@ -665,6 +665,41 @@ function cloneJson<T>(value: T): T {
   return JSON.parse(JSON.stringify(value)) as T;
 }
 
+/**
+ * Persists document-level custom fields supplied on a create input.
+ *
+ * Order and quote creates used to accept `customFields` at the HTTP boundary
+ * (`splitCustomFieldPayload` folds `cf_*` keys into it) and then drop the values
+ * on the floor, because the create schemas never declared the key and the
+ * handlers never wrote it — only updates did. Callers therefore had to create,
+ * then immediately update, to get custom fields to stick.
+ */
+async function setDocumentCustomFieldsIfSupplied(
+  em: EntityManager,
+  params: {
+    entityId: string;
+    recordId: string;
+    organizationId: string;
+    tenantId: string;
+    customFields: unknown;
+  },
+): Promise<void> {
+  const { customFields } = params;
+  if (customFields === undefined || customFields === null) return;
+  const values =
+    typeof customFields === "object" && !Array.isArray(customFields)
+      ? (customFields as Record<string, unknown>)
+      : {};
+  if (!Object.keys(values).length) return;
+  await setRecordCustomFields(em, {
+    entityId: params.entityId,
+    recordId: params.recordId,
+    organizationId: params.organizationId,
+    tenantId: params.tenantId,
+    values: normalizeCustomFieldValues(values),
+  });
+}
+
 async function resolveCustomerSnapshot(
   em: EntityManager,
   organizationId: string,
@@ -4186,6 +4221,20 @@ async function restoreOrderGraph(
       organizationId: snapshot.order.organizationId,
     },
   );
+  let existingLines: SalesOrderLine[] = [];
+  if (order) {
+    existingLines = await em.find(
+      SalesOrderLine,
+      { order },
+      { orderBy: { lineNumber: "asc" } },
+    );
+    await assertShippedOrderGraphRestorable(
+      em,
+      order,
+      existingLines,
+      snapshot,
+    );
+  }
   if (!order) {
     order = em.create(SalesOrder, {
       id: snapshot.order.id,
@@ -4270,11 +4319,6 @@ async function restoreOrderGraph(
   }
   applyOrderSnapshot(order, snapshot.order);
   await em.flush();
-  const existingLines = await em.find(
-    SalesOrderLine,
-    { order: order.id },
-    { fields: ["id"] },
-  );
   const existingAdjustments = await em.find(
     SalesOrderAdjustment,
     { order: order.id },
@@ -4782,6 +4826,13 @@ const createQuoteCommand: CommandHandler<
             tenantId: quote.tenantId,
             tagIds: parsed.tags,
           });
+          await setDocumentCustomFieldsIfSupplied(em, {
+            entityId: E.sales.sales_quote,
+            recordId: quote.id,
+            organizationId: quote.organizationId,
+            tenantId: quote.tenantId,
+            customFields: parsed.customFields,
+          });
         },
       ],
       { transaction: true },
@@ -5804,6 +5855,13 @@ const createOrderCommand: CommandHandler<
             tenantId: order.tenantId,
             tagIds: parsed.tags,
           });
+          await setDocumentCustomFieldsIfSupplied(em, {
+            entityId: E.sales.sales_order,
+            recordId: order.id,
+            organizationId: order.organizationId,
+            tenantId: order.tenantId,
+            customFields: parsed.customFields,
+          });
         },
       ],
       { transaction: true },
@@ -6625,6 +6683,34 @@ const quoteAdjustmentDeleteSchema = z.object({
 
 const SHIPPED_QUANTITY_TOLERANCE = 1e-6;
 
+// Locked outright on a shipped line: none of these may move at all.
+const SHIPPED_LINE_NUMERIC_PRICING_FIELDS = [
+  "unitPriceNet",
+  "unitPriceGross",
+  "discountAmount",
+  "discountPercent",
+  "taxRate",
+] as const;
+
+// Line totals are derived, not authored: clients recompute and echo them on every
+// submit, so raising the quantity of a shipped line legitimately changes them. They
+// are still writable straight through, so they cannot simply be ignored either.
+// The invariant that separates a quantity edit from moving money is the per-unit
+// economics — total per unit must stay put, whatever the quantity does. That also
+// keeps discounted lines working, since a proportional total scales with quantity.
+const SHIPPED_LINE_DERIVED_TOTAL_FIELDS = [
+  "totalNetAmount",
+  "totalGrossAmount",
+] as const;
+
+type ShippedLineComparable = Pick<
+  SalesLineSnapshot,
+  | "quantity"
+  | "quantityUnit"
+  | (typeof SHIPPED_LINE_NUMERIC_PRICING_FIELDS)[number]
+  | (typeof SHIPPED_LINE_DERIVED_TOTAL_FIELDS)[number]
+>;
+
 const hasNumericChange = (
   next: number | null | undefined,
   previous: number | null | undefined,
@@ -6634,6 +6720,17 @@ const hasNumericChange = (
   return Math.abs(next - previous) > SHIPPED_QUANTITY_TOLERANCE;
 };
 
+const hasExactNumericChange = (
+  next: number | null | undefined,
+  previous: number | null | undefined,
+): boolean => {
+  if (next === undefined || next === null) {
+    return previous !== undefined && previous !== null;
+  }
+  if (previous === undefined || previous === null) return true;
+  return Math.abs(next - previous) > SHIPPED_QUANTITY_TOLERANCE;
+};
+
 const hasUnitChange = (
   next: string | null | undefined,
   previous: string | null | undefined,
@@ -6644,6 +6741,111 @@ const hasUnitChange = (
   return next.trim().toLowerCase() !== normalizedPrevious;
 };
 
+const hasExactUnitChange = (
+  next: string | null | undefined,
+  previous: string | null | undefined,
+): boolean =>
+  (next ?? "").trim().toLowerCase() !==
+  (previous ?? "").trim().toLowerCase();
+
+function hasShippedLineTotalChange(
+  next: Partial<ShippedLineComparable>,
+  previous: ShippedLineComparable,
+  nextQuantity: number | null | undefined,
+  exact: boolean,
+): boolean {
+  const numericChange = exact ? hasExactNumericChange : hasNumericChange;
+  const previousQuantity = previous.quantity;
+  const canScale =
+    typeof previousQuantity === "number" &&
+    Math.abs(previousQuantity) > SHIPPED_QUANTITY_TOLERANCE &&
+    typeof nextQuantity === "number";
+
+  return SHIPPED_LINE_DERIVED_TOTAL_FIELDS.some((field) => {
+    const nextTotal = next[field];
+    const previousTotal = previous[field];
+    // Without a scalable quantity pair there is nothing to derive the expected
+    // total from, so fall back to locking the value outright.
+    if (!canScale || typeof previousTotal !== "number") {
+      return numericChange(nextTotal, previousTotal);
+    }
+    if (nextTotal === undefined || nextTotal === null) {
+      return exact ? numericChange(nextTotal, previousTotal) : false;
+    }
+    const expectedTotal =
+      (previousTotal / (previousQuantity as number)) * (nextQuantity as number);
+    // Scale the tolerance with magnitude: a fixed 1e-6 is below the float noise
+    // floor once totals reach six figures.
+    const tolerance = Math.max(
+      SHIPPED_QUANTITY_TOLERANCE,
+      Math.abs(expectedTotal) * 1e-9,
+    );
+    return Math.abs(nextTotal - expectedTotal) > tolerance;
+  });
+}
+
+function hasShippedLinePricingChange(
+  next: Partial<ShippedLineComparable>,
+  previous: ShippedLineComparable,
+  nextQuantity: number | null | undefined,
+  exact: boolean,
+): boolean {
+  const numericChange = exact ? hasExactNumericChange : hasNumericChange;
+  return (
+    SHIPPED_LINE_NUMERIC_PRICING_FIELDS.some((field) =>
+      numericChange(next[field], previous[field]),
+    ) ||
+    hasShippedLineTotalChange(next, previous, nextQuantity, exact) ||
+    (exact
+      ? hasExactUnitChange(next.quantityUnit, previous.quantityUnit)
+      : hasUnitChange(next.quantityUnit, previous.quantityUnit))
+  );
+}
+
+async function assertShippedOrderLineChangeAllowed(
+  existingSnapshot: SalesLineSnapshot,
+  nextSnapshot: Partial<ShippedLineComparable> | null,
+  shippedQuantity: number,
+  exact: boolean,
+): Promise<void> {
+  if (shippedQuantity <= 0) return;
+
+  const nextQuantity = nextSnapshot
+    ? exact
+      ? nextSnapshot.quantity
+      : (nextSnapshot.quantity ?? existingSnapshot.quantity)
+    : 0;
+  const quantityInvalid =
+    nextQuantity === undefined ||
+    nextQuantity < shippedQuantity - SHIPPED_QUANTITY_TOLERANCE;
+  const pricingChanged =
+    nextSnapshot !== null &&
+    hasShippedLinePricingChange(
+      nextSnapshot,
+      existingSnapshot,
+      nextQuantity,
+      exact,
+    );
+  if (!quantityInvalid && !pricingChanged) return;
+
+  const { translate } = await resolveTranslations();
+  if (quantityInvalid) {
+    throw new CrudHttpError(409, {
+      error: translate(
+        "sales.documents.items.errorQuantityBelowShipped",
+        "You cannot lower the quantity below the {{shipped}} already shipped.",
+        { shipped: shippedQuantity },
+      ),
+    });
+  }
+  throw new CrudHttpError(409, {
+    error: translate(
+      "sales.documents.items.errorPriceShipped",
+      "You cannot change the price or unit of a line that has shipped items.",
+    ),
+  });
+}
+
 async function assertShippedOrderLineEditable(
   em: EntityManager,
   order: SalesOrder,
@@ -6657,32 +6859,38 @@ async function assertShippedOrderLineEditable(
     organizationId: order.organizationId,
   });
   const shippedQuantity = shippedByLine.get(lineId) ?? 0;
-  if (shippedQuantity <= 0) return;
+  await assertShippedOrderLineChangeAllowed(
+    existingSnapshot,
+    parsed,
+    shippedQuantity,
+    false,
+  );
+}
 
-  const { translate } = await resolveTranslations();
-  const nextQuantity = parsed.quantity ?? existingSnapshot.quantity;
-  if (nextQuantity < shippedQuantity - SHIPPED_QUANTITY_TOLERANCE) {
-    throw new CrudHttpError(409, {
-      error: translate(
-        "sales.documents.items.errorQuantityBelowShipped",
-        "You cannot lower the quantity below the {{shipped}} already shipped.",
-        { shipped: shippedQuantity },
-      ),
-    });
-  }
+async function assertShippedOrderGraphRestorable(
+  em: EntityManager,
+  order: SalesOrder,
+  existingLines: SalesOrderLine[],
+  snapshot: OrderGraphSnapshot,
+): Promise<void> {
+  const shippedByLine = await loadShippedQuantityByLine(em, order.id, {
+    tenantId: order.tenantId,
+    organizationId: order.organizationId,
+  });
+  if (shippedByLine.size === 0) return;
 
-  const pricingChanged =
-    hasNumericChange(parsed.unitPriceNet, existingSnapshot.unitPriceNet) ||
-    hasNumericChange(parsed.unitPriceGross, existingSnapshot.unitPriceGross) ||
-    hasNumericChange(parsed.taxRate, existingSnapshot.taxRate) ||
-    hasUnitChange(parsed.quantityUnit, existingSnapshot.quantityUnit);
-  if (pricingChanged) {
-    throw new CrudHttpError(409, {
-      error: translate(
-        "sales.documents.items.errorPriceShipped",
-        "You cannot change the price or unit of a line that has shipped items.",
-      ),
-    });
+  const snapshotLinesById = new Map(
+    snapshot.lines.flatMap((line) => (line.id ? [[line.id, line] as const] : [])),
+  );
+  for (const line of existingLines) {
+    const shippedQuantity = shippedByLine.get(line.id) ?? 0;
+    if (shippedQuantity <= 0) continue;
+    await assertShippedOrderLineChangeAllowed(
+      mapOrderLineEntityToSnapshot(line),
+      snapshotLinesById.get(line.id) ?? null,
+      shippedQuantity,
+      true,
+    );
   }
 }
 

package/src/modules/sales/data/validators.ts

@@ -717,6 +717,7 @@ export const orderCreateSchema = scoped.extend({
   paymentMethodSnapshot: jsonRecord.optional(),
   metadata,
   customFieldSetId: uuid().optional(),
+  customFields: z.record(z.string(), z.unknown()).optional(),
   lines: z
     .array(orderLineCreateSchema.omit({ organizationId: true, tenantId: true, orderId: true }), {
       error: SALES_ORDER_LINES_REQUIRED_MESSAGE_KEY,
@@ -761,6 +762,7 @@ export const quoteCreateSchema = scoped.extend({
   paymentMethodSnapshot: jsonRecord.optional(),
   metadata,
   customFieldSetId: uuid().optional(),
+  customFields: z.record(z.string(), z.unknown()).optional(),
   lines: z
     .array(quoteLineCreateSchema.omit({ organizationId: true, tenantId: true, quoteId: true }))
     .optional(),

package/src/modules/sales/workflows.ts

@@ -57,7 +57,7 @@ const orderApproval = defineWorkflow({
           config: {
             commandId: 'sales.orders.update',
             statusDictionary: 'sales.order_status',
-            input: { id: '{{context.id}}', statusValue: 'pending_approval' },
+            input: { id: '{{context.orderId}}', statusValue: 'pending_approval' },
           },
           retryPolicy: { maxAttempts: 3, initialIntervalMs: 1000, backoffCoefficient: 2, maxIntervalMs: 10000 },
         },
@@ -68,7 +68,7 @@ const orderApproval = defineWorkflow({
           async: true,
           config: {
             eventName: 'sales.order.approval.requested',
-            payload: { orderId: '{{context.id}}', workflowInstanceId: '{{workflow.instanceId}}' },
+            payload: { orderId: '{{context.orderId}}', workflowInstanceId: '{{workflow.instanceId}}' },
           },
         },
       ],
@@ -91,7 +91,7 @@ const orderApproval = defineWorkflow({
           config: {
             commandId: 'sales.orders.update',
             statusDictionary: 'sales.order_status',
-            input: { id: '{{context.id}}', statusValue: 'approved' },
+            input: { id: '{{context.orderId}}', statusValue: 'approved' },
           },
           retryPolicy: { maxAttempts: 3, initialIntervalMs: 1000, backoffCoefficient: 2, maxIntervalMs: 10000 },
         },
@@ -103,7 +103,7 @@ const orderApproval = defineWorkflow({
           config: {
             eventName: 'sales.order.approval.approved',
             payload: {
-              orderId: '{{context.id}}',
+              orderId: '{{context.orderId}}',
               workflowInstanceId: '{{workflow.instanceId}}',
               approvedBy: '{{context.completedBy}}',
               comments: '{{context.comments}}',
@@ -130,7 +130,7 @@ const orderApproval = defineWorkflow({
           config: {
             commandId: 'sales.orders.update',
             statusDictionary: 'sales.order_status',
-            input: { id: '{{context.id}}', statusValue: 'rejected' },
+            input: { id: '{{context.orderId}}', statusValue: 'rejected' },
           },
           retryPolicy: { maxAttempts: 3, initialIntervalMs: 1000, backoffCoefficient: 2, maxIntervalMs: 10000 },
         },
@@ -142,7 +142,7 @@ const orderApproval = defineWorkflow({
           config: {
             eventName: 'sales.order.approval.rejected',
             payload: {
-              orderId: '{{context.id}}',
+              orderId: '{{context.orderId}}',
               workflowInstanceId: '{{workflow.instanceId}}',
               rejectedBy: '{{context.completedBy}}',
               comments: '{{context.comments}}',
@@ -175,7 +175,10 @@ const orderApproval = defineWorkflow({
     name: 'Order Approval Trigger',
     description: 'Triggers when a new sales order is created',
     eventPattern: 'sales.order.created',
-    config: { entityType: 'SalesOrder' },
+    config: {
+      entityType: 'SalesOrder',
+      contextMapping: [{ targetKey: 'orderId', sourceExpression: 'id' }],
+    },
     enabled: true,
     priority: 0,
   }],

package/src/modules/workflows/i18n/de.json

@@ -935,6 +935,7 @@
   "workflows.orderApproval.decisionLabel": "Entscheidung",
   "workflows.orderApproval.groupDescription": "Bestellung prüfen und genehmigen oder ablehnen.",
   "workflows.orderApproval.groupLabel": "Bestellgenehmigung",
+  "workflows.orderApproval.missingOrderId": "Der Genehmigungsworkflow kann erst gestartet werden, wenn die Bestellung geladen ist.",
   "workflows.orderApproval.missingStatuses": "Fehlende Bestellstatus. Stellen Sie sicher, dass pending_approval, approved und rejected vorhanden sind.",
   "workflows.orderApproval.noWorkflowActive": "Kein Genehmigungsworkflow für diese Bestellung aktiv.",
   "workflows.orderApproval.pendingDescription": "Diese Bestellung erfordert eine Genehmigung.",

package/src/modules/workflows/i18n/en.json

@@ -935,6 +935,7 @@
   "workflows.orderApproval.decisionLabel": "Decision",
   "workflows.orderApproval.groupDescription": "Review and approve or reject this order.",
   "workflows.orderApproval.groupLabel": "Order Approval",
+  "workflows.orderApproval.missingOrderId": "Cannot start the approval workflow before the order has loaded.",
   "workflows.orderApproval.missingStatuses": "Missing order status entries. Please ensure pending_approval, approved, and rejected statuses exist.",
   "workflows.orderApproval.noWorkflowActive": "No approval workflow is active for this order.",
   "workflows.orderApproval.pendingDescription": "This order requires approval before processing.",

package/src/modules/workflows/i18n/es.json

@@ -935,6 +935,7 @@
   "workflows.orderApproval.decisionLabel": "Decisión",
   "workflows.orderApproval.groupDescription": "Revise y apruebe o rechace este pedido.",
   "workflows.orderApproval.groupLabel": "Aprobación de pedido",
+  "workflows.orderApproval.missingOrderId": "No se puede iniciar el flujo de aprobación antes de que el pedido se haya cargado.",
   "workflows.orderApproval.missingStatuses": "Faltan entradas de estado del pedido. Asegúrese de que existan los estados pending_approval, approved y rejected.",
   "workflows.orderApproval.noWorkflowActive": "No hay un flujo de aprobación activo para este pedido.",
   "workflows.orderApproval.pendingDescription": "Este pedido requiere aprobación antes de procesarse.",

package/src/modules/workflows/i18n/ko.json

@@ -935,6 +935,7 @@
   "workflows.orderApproval.decisionLabel": "결정",
   "workflows.orderApproval.groupDescription": "이 주문을 검토하여 승인하거나 반려하세요.",
   "workflows.orderApproval.groupLabel": "주문 승인",
+  "workflows.orderApproval.missingOrderId": "주문이 로드되기 전에는 승인 워크플로를 시작할 수 없습니다.",
   "workflows.orderApproval.missingStatuses": "주문 상태 항목이 누락되었습니다. pending_approval, approved, rejected 상태가 존재하는지 확인하세요.",
   "workflows.orderApproval.noWorkflowActive": "이 주문에 대해 활성화된 승인 워크플로우가 없습니다.",
   "workflows.orderApproval.pendingDescription": "이 주문은 처리 전에 승인이 필요합니다.",

package/src/modules/workflows/i18n/pl.json

@@ -935,6 +935,7 @@
   "workflows.orderApproval.decisionLabel": "Decyzja",
   "workflows.orderApproval.groupDescription": "Przejrzyj i zatwierdź lub odrzuć to zamówienie.",
   "workflows.orderApproval.groupLabel": "Zatwierdzanie zamówienia",
+  "workflows.orderApproval.missingOrderId": "Nie można rozpocząć procesu zatwierdzania, zanim zamówienie się nie wczyta.",
   "workflows.orderApproval.missingStatuses": "Brakuje wpisów statusów zamówienia. Upewnij się, że istnieją statusy pending_approval, approved i rejected.",
   "workflows.orderApproval.noWorkflowActive": "Brak aktywnego przepływu zatwierdzania dla tego zamówienia.",
   "workflows.orderApproval.pendingDescription": "To zamówienie wymaga zatwierdzenia przed realizacją.",

package/src/modules/workflows/lib/activity-executor.ts

@@ -603,6 +603,17 @@ export async function executeEmitEvent(
     throw new Error('EMIT_EVENT requires "eventName" field')
   }
 
+  // Emissions are fire-and-forget and no subscriber validates the payload shape,
+  // so an unresolved `{{context.x}}` here is even quieter than on the command
+  // path — it ships the literal template to every consumer. Fail loudly instead.
+  const unresolvedPayloadKeys = findUnresolvedTemplateKeys(payload)
+  if (unresolvedPayloadKeys.length > 0) {
+    throw new Error(
+      `EMIT_EVENT payload contains unresolved template variables for: ${unresolvedPayloadKeys.join(', ')}. ` +
+        `Check that the workflow context provides these keys.`
+    )
+  }
+
   // Get event bus from container
   const eventBus = container.resolve<{ emitEvent: (event: string, payload: unknown, options?: unknown) => Promise<unknown> | unknown }>('eventBus')
 
@@ -629,6 +640,23 @@ export async function executeEmitEvent(
   return { emitted: true, eventName, payload: enrichedPayload }
 }
 
+const UNRESOLVED_TEMPLATE_PATTERN = /\{\{[^}]+\}\}/
+
+function findUnresolvedTemplateKeys(value: unknown, path = ''): string[] {
+  if (typeof value === 'string') {
+    return UNRESOLVED_TEMPLATE_PATTERN.test(value) ? [path] : []
+  }
+  if (Array.isArray(value)) {
+    return value.flatMap((item, index) => findUnresolvedTemplateKeys(item, `${path}[${index}]`))
+  }
+  if (value && typeof value === 'object') {
+    return Object.entries(value).flatMap(([key, nested]) =>
+      findUnresolvedTemplateKeys(nested, path ? `${path}.${key}` : key)
+    )
+  }
+  return []
+}
+
 /**
  * UPDATE_ENTITY activity handler
  *
@@ -651,11 +679,14 @@ export async function executeEmitEvent(
  *   "commandId": "sales.orders.update",
  *   "statusDictionary": "sales.order_status",
  *   "input": {
- *     "id": "{{context.id}}",
+ *     "id": "{{context.orderId}}",
  *     "statusValue": "pending_approval"
  *   }
  * }
  * ```
+ *
+ * Every `{{...}}` reference in `input` must resolve against the workflow context —
+ * an unresolved reference is rejected rather than forwarded to the command bus.
  */
 export async function executeUpdateEntity(
   em: EntityManager,
@@ -701,6 +732,14 @@ export async function executeUpdateEntity(
     throw new Error('CommandBus not available in container')
   }
 
+  const unresolvedKeys = findUnresolvedTemplateKeys(input)
+  if (unresolvedKeys.length > 0) {
+    throw new Error(
+      `UPDATE_ENTITY input contains unresolved template variables for: ${unresolvedKeys.join(', ')}. ` +
+        `Check that the workflow context provides these keys.`
+    )
+  }
+
   // Prepare final input, resolving statusValue if provided
   let finalInput = { ...input }
 

package/src/modules/workflows/widgets/injection/order-approval/context-keys.ts

@@ -0,0 +1,18 @@
+/**
+ * The context keys the order-approval widget seeds when it starts the
+ * `sales.order-approval` workflow. The workflow definition interpolates
+ * `{{context.<key>}}` against exactly this set, and `interpolateVariables()`
+ * silently returns the original string when a key is missing — so the two must
+ * not drift. Both the widget and the contract test import this list, which is
+ * what makes the drift a type error rather than a runtime surprise (issue #4334).
+ */
+export const ORDER_APPROVAL_CONTEXT_KEYS = [
+  'orderId',
+  'pendingApprovalStatusId',
+  'approvedStatusId',
+  'rejectedStatusId',
+] as const
+
+export type OrderApprovalContextKey = (typeof ORDER_APPROVAL_CONTEXT_KEYS)[number]
+
+export type OrderApprovalInitialContext = Record<OrderApprovalContextKey, string>

package/src/modules/workflows/widgets/injection/order-approval/widget.client.tsx

@@ -11,6 +11,7 @@ import { Textarea } from '@open-mercato/ui/primitives/textarea'
 import { Badge } from '@open-mercato/ui/primitives/badge'
 import { emitSalesDocumentDataRefresh } from '@open-mercato/core/modules/sales/lib/frontend/documentDataEvents'
 import { fetchAllDictionaryEntries } from '@open-mercato/core/modules/dictionaries/lib/fetchAllEntries'
+import type { OrderApprovalInitialContext } from './context-keys'
 
 type OrderRecord = {
   id: string
@@ -199,20 +200,28 @@ export default function OrderApprovalWidget({ data }: InjectionWidgetComponentPr
       const approvedStatusId = findStatusId('approved')
       const rejectedStatusId = findStatusId('rejected')
 
+      if (!orderId) {
+        throw new Error(t('workflows.orderApproval.missingOrderId', 'Cannot start the approval workflow before the order has loaded.'))
+      }
+
       if (!pendingApprovalStatusId || !approvedStatusId || !rejectedStatusId) {
         throw new Error(t('workflows.orderApproval.missingStatuses', 'Missing order status entries. Please ensure pending_approval, approved, and rejected statuses exist in the sales.order_status dictionary.'))
       }
 
+      // Typed against the shared key list so a definition that references a new
+      // {{context.*}} key cannot compile until this seed provides it.
+      const initialContext: OrderApprovalInitialContext = {
+        orderId,
+        pendingApprovalStatusId,
+        approvedStatusId,
+        rejectedStatusId,
+      }
+
       const result = await apiCall<{ data: WorkflowInstance }>('/api/workflows/instances', {
         method: 'POST',
         body: JSON.stringify({
           workflowId: WORKFLOW_ID,
-          initialContext: {
-            orderId,
-            pendingApprovalStatusId,
-            approvedStatusId,
-            rejectedStatusId,
-          },
+          initialContext,
           metadata: {
             entityType: 'SalesOrder',
             entityId: orderId,