@open-mercato/core 0.10.1-develop.7722.1.901c72b9e9 → 0.10.1-develop.7724.1.95e4e7d38e

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

@@ -84,7 +84,9 @@ import {
   orderCreateSchema,
   ORDER_PAYMENT_LEDGER_WARNING_CODE,
   resolveSuppliedOrderPaymentLedgerFields,
+  amountsModeSchema,
   orderLineCreateSchema,
+  orderHeaderTotalsSchema,
   orderAdjustmentCreateSchema,
   invoiceCreateSchema,
   invoiceUpdateSchema,
@@ -130,9 +132,11 @@ import type {
   ShippingMethodContext,
 } from "../lib/providers";
 import {
+  type SalesAmountsMode,
   type SalesLineSnapshot,
   type SalesLineUomSnapshot,
   type SalesAdjustmentDraft,
+  type SalesDocumentAmounts,
   type SalesLineCalculationResult,
   type SalesDocumentCalculationResult,
 } from "../lib/types";
@@ -143,6 +147,18 @@ import {
   resolveUpsertTotalsOrigin,
   resolveUpsertCalculatedAmounts,
 } from "../lib/lineSnapshots";
+import {
+  assertAmountsModeUnsupportedOnQuote,
+  assertExternalHeaderComplete,
+  assertExternalLineComplete,
+  assertUniformAmountsMode,
+  buildExternalHeaderTotals,
+  hasAnySuppliedHeaderTotal,
+  readPersistedHeaderTotals,
+  refuseOnExternalOrder,
+  requireOrderTotalsForExternalWrite,
+} from "../lib/externalAmounts";
+import { isExternalAmountsMode } from "../lib/calculations";
 import { loadShippedQuantityByLine } from "../lib/shipments/snapshots";
 import { resolveDictionaryEntryValue, resolveCachedDictionaryEntryValue } from "../lib/dictionaries";
 import { assertOrderCanBeCancelled, isCancelledOrderStatus } from "../lib/orderCancellationGuard";
@@ -390,6 +406,7 @@ type OrderGraphSnapshot = {
     outstandingAmount: string;
     totalsSnapshot: Record<string, unknown> | null;
     lineItemCount: number;
+    totalsMode: SalesAmountsMode;
   };
   lines: OrderLineSnapshot[];
   adjustments: OrderAdjustmentSnapshot[];
@@ -430,6 +447,7 @@ type OrderLineSnapshot = {
   taxAmount: string;
   totalNetAmount: string;
   totalGrossAmount: string;
+  amountsMode: SalesAmountsMode;
   configuration: Record<string, unknown> | null;
   promotionCode: string | null;
   promotionSnapshot: Record<string, unknown> | null;
@@ -604,7 +622,7 @@ const addressSnapshotSchema = z
 // is 0 — and would turn a clear into a written zero.
 const exchangeRateSchema = z.coerce.number().min(0);
 
-export const documentUpdateSchema = z
+const documentUpdateFieldsSchema = z
   .object({
     id: z.string().uuid(),
     customerEntityId: z.string().uuid().nullable().optional(),
@@ -652,43 +670,63 @@ export const documentUpdateSchema = z
     tags: z.array(z.string().uuid()).optional(),
     customFields: z.record(z.string(), z.unknown()).optional(),
     customFieldSetId: z.string().uuid().nullable().optional(),
-  })
-  .refine(
-    (input) =>
-      typeof input.currencyCode === "string" ||
-      input.placedAt !== undefined ||
-      input.expectedDeliveryAt !== undefined ||
-      input.channelId !== undefined ||
-      input.statusEntryId !== undefined ||
-      input.exchangeRate !== undefined ||
-      input.paymentStatusEntryId !== undefined ||
-      input.fulfillmentStatusEntryId !== undefined ||
-      input.shippingAddressId !== undefined ||
-      input.billingAddressId !== undefined ||
-      input.customerEntityId !== undefined ||
-      input.customerContactId !== undefined ||
-      input.customerSnapshot !== undefined ||
-      input.metadata !== undefined ||
-      input.customerReference !== undefined ||
-      input.externalReference !== undefined ||
-      input.comment !== undefined ||
-      input.comments !== undefined ||
-      input.internalNotes !== undefined ||
-      input.orderNumber !== undefined ||
-      input.quoteNumber !== undefined ||
-      input.shippingAddressSnapshot !== undefined ||
-      input.billingAddressSnapshot !== undefined ||
-      input.shippingMethodId !== undefined ||
-      input.shippingMethodCode !== undefined ||
-      input.shippingMethodSnapshot !== undefined ||
-      input.paymentMethodId !== undefined ||
-      input.paymentMethodCode !== undefined ||
-      input.paymentMethodSnapshot !== undefined ||
-      input.tags !== undefined ||
-      input.customFields !== undefined ||
-      input.customFieldSetId !== undefined,
-    { message: "update_payload_empty" },
+    totalsMode: amountsModeSchema.optional(),
+    ...orderHeaderTotalsSchema.shape,
+  });
+
+type DocumentUpdateFields = z.infer<typeof documentUpdateFieldsSchema>;
+
+function carriesDocumentEdit(input: DocumentUpdateFields): boolean {
+  return (
+    typeof input.currencyCode === "string" ||
+    input.placedAt !== undefined ||
+    input.expectedDeliveryAt !== undefined ||
+    input.channelId !== undefined ||
+    input.statusEntryId !== undefined ||
+    input.exchangeRate !== undefined ||
+    input.paymentStatusEntryId !== undefined ||
+    input.fulfillmentStatusEntryId !== undefined ||
+    input.shippingAddressId !== undefined ||
+    input.billingAddressId !== undefined ||
+    input.customerEntityId !== undefined ||
+    input.customerContactId !== undefined ||
+    input.customerSnapshot !== undefined ||
+    input.metadata !== undefined ||
+    input.customerReference !== undefined ||
+    input.externalReference !== undefined ||
+    input.comment !== undefined ||
+    input.comments !== undefined ||
+    input.internalNotes !== undefined ||
+    input.orderNumber !== undefined ||
+    input.quoteNumber !== undefined ||
+    input.shippingAddressSnapshot !== undefined ||
+    input.billingAddressSnapshot !== undefined ||
+    input.shippingMethodId !== undefined ||
+    input.shippingMethodCode !== undefined ||
+    input.shippingMethodSnapshot !== undefined ||
+    input.paymentMethodId !== undefined ||
+    input.paymentMethodCode !== undefined ||
+    input.paymentMethodSnapshot !== undefined ||
+    input.tags !== undefined ||
+    input.customFields !== undefined ||
+    input.customFieldSetId !== undefined
   );
+}
+
+// The route cannot see an order's persisted mode, so it lets header totals count
+// as an edit; each command re-applies `documentEditSchema` once it can. An empty
+// update must not reach a quote: execution reverts a `sent` quote to draft.
+export const documentUpdateSchema = documentUpdateFieldsSchema.refine(
+  (input) =>
+    carriesDocumentEdit(input) ||
+    input.totalsMode !== undefined ||
+    hasAnySuppliedHeaderTotal(input),
+  { message: "update_payload_empty" },
+);
+
+const documentEditSchema = documentUpdateFieldsSchema.refine(carriesDocumentEdit, {
+  message: "update_payload_empty",
+});
 
 export type DocumentUpdateInput = z.infer<typeof documentUpdateSchema>;
 
@@ -2049,6 +2087,7 @@ async function loadOrderSnapshot(
         ? cloneJson(order.totalsSnapshot)
         : null,
       lineItemCount: order.lineItemCount,
+      totalsMode: order.totalsMode ?? "computed",
     },
     lines: lines.map((line) => ({
       id: line.id,
@@ -2082,6 +2121,7 @@ async function loadOrderSnapshot(
       taxAmount: line.taxAmount,
       totalNetAmount: line.totalNetAmount,
       totalGrossAmount: line.totalGrossAmount,
+      amountsMode: line.amountsMode ?? "computed",
       configuration: line.configuration ? cloneJson(line.configuration) : null,
       promotionCode: line.promotionCode ?? null,
       promotionSnapshot: line.promotionSnapshot
@@ -3124,6 +3164,7 @@ function createLineSnapshotFromInput(
       "customFields" in line && line.customFields
         ? cloneJson((line as any).customFields)
         : null,
+    amountsMode: (line as { amountsMode?: SalesAmountsMode | null }).amountsMode ?? null,
   };
 }
 
@@ -3163,7 +3204,12 @@ function convertLineCalculationToEntityInput(
   index: number,
 ) {
   const line = lineResult.line;
-  return reconcileLinePersistedTotals({
+  // The gross-derived net repair heals core-owned rows; on an external line a
+  // zero net is the caller's figure, not a defect to correct.
+  const persistTotals = isExternalAmountsMode(line.amountsMode)
+    ? <T,>(payload: T): T => payload
+    : reconcileLinePersistedTotals;
+  return persistTotals({
     lineNumber: line.lineNumber ?? index + 1,
     kind: line.kind ?? "product",
     statusEntryId: sourceLine.statusEntryId ?? null,
@@ -3201,6 +3247,8 @@ function convertLineCalculationToEntityInput(
     taxAmount: toNumericString(lineResult.taxAmount) ?? "0",
     totalNetAmount: toNumericString(lineResult.netAmount) ?? "0",
     totalGrossAmount: toNumericString(lineResult.grossAmount) ?? "0",
+    // Conditional: this converter also serves quote lines, which have no column.
+    ...(line.amountsMode ? { amountsMode: line.amountsMode } : {}),
     configuration: line.configuration ? cloneJson(line.configuration) : null,
     promotionCode: line.promotionCode ?? null,
     promotionSnapshot: sourceLine.promotionSnapshot
@@ -3695,6 +3743,25 @@ function applyOrderTotals(
   order.lineItemCount = lineCount;
 }
 
+function applyOrderLineAmountsFromCalculation(params: {
+  em: EntityManager;
+  lines: SalesOrderLine[];
+  calculation: SalesDocumentCalculationResult;
+  amountsMode: SalesAmountsMode;
+}): void {
+  const { em, lines, calculation, amountsMode } = params;
+  lines.forEach((line, index) => {
+    const result = calculation.lines[index];
+    if (!result) return;
+    line.amountsMode = amountsMode;
+    line.discountAmount = toNumericString(result.discountAmount) ?? "0";
+    line.taxAmount = toNumericString(result.taxAmount) ?? "0";
+    line.totalNetAmount = toNumericString(result.netAmount) ?? "0";
+    line.totalGrossAmount = toNumericString(result.grossAmount) ?? "0";
+    em.persist(line);
+  });
+}
+
 function normalizePaymentTotal(value: unknown): number {
   if (typeof value === "number" && Number.isFinite(value))
     return Math.max(value, 0);
@@ -4069,6 +4136,9 @@ function applyOrderSnapshot(
     ? cloneJson(snapshot.totalsSnapshot)
     : null;
   order.lineItemCount = snapshot.lineItemCount;
+  // Restored with the amounts, never separately: the lines come back with their
+  // own mode, so omitting this leaves a mixed document the next write recomputes.
+  order.totalsMode = snapshot.totalsMode ?? "computed";
 }
 
 async function assertQuoteGraphUndoCurrent(
@@ -4744,6 +4814,7 @@ async function restoreOrderGraph(
         ? cloneJson(snapshot.order.totalsSnapshot)
         : null,
       lineItemCount: snapshot.order.lineItemCount,
+      totalsMode: snapshot.order.totalsMode ?? "computed",
       createdAt: new Date(),
       updatedAt: new Date(),
     });
@@ -4854,10 +4925,14 @@ async function restoreOrderGraph(
       discountPercent: line.discountPercent,
       taxRate: line.taxRate,
       taxAmount: line.taxAmount,
-      totalNetAmount: toNumericString(
-        deriveLineNetFromGross(line.totalNetAmount, line.totalGrossAmount, line.taxRate),
-      ),
+      // Not repaired from gross: an external line's net is the caller's figure.
+      totalNetAmount: isExternalAmountsMode(line.amountsMode)
+        ? line.totalNetAmount
+        : toNumericString(
+            deriveLineNetFromGross(line.totalNetAmount, line.totalGrossAmount, line.taxRate),
+          ),
       totalGrossAmount: line.totalGrossAmount,
+      amountsMode: line.amountsMode ?? "computed",
       configuration: line.configuration ? cloneJson(line.configuration) : null,
       promotionCode: line.promotionCode ?? null,
       promotionSnapshot: line.promotionSnapshot
@@ -5157,6 +5232,7 @@ const createQuoteCommand: CommandHandler<
       updatedAt: new Date(),
     });
 
+    await assertAmountsModeUnsupportedOnQuote(parsed.lines ?? []);
     const lineInputs = (parsed.lines ?? []).map((line, index) =>
       quoteLineCreateSchema.parse({
         ...line,
@@ -5539,6 +5615,8 @@ const updateQuoteCommand: CommandHandler<
   },
   async execute(rawInput, ctx) {
     const parsed = documentUpdateSchema.parse(rawInput ?? {});
+    await assertAmountsModeUnsupportedOnQuote([parsed]);
+    documentEditSchema.parse(rawInput ?? {});
     const em = (ctx.container.resolve("em") as EntityManager).fork();
     const quote = await findOneWithDecryption(em, SalesQuote, {
       id: parsed.id,
@@ -5836,6 +5914,17 @@ const updateOrderCommand: CommandHandler<
     if (!order)
       throw notFound("Sales order not found");
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
+    const currentTotalsMode: SalesAmountsMode = order.totalsMode ?? "computed";
+    const nextTotalsMode: SalesAmountsMode = parsed.totalsMode ?? currentTotalsMode;
+    const totalsModeChanged = nextTotalsMode !== currentTotalsMode;
+    const externalHeaderSupplied =
+      isExternalAmountsMode(nextTotalsMode) && hasAnySuppliedHeaderTotal(parsed);
+    if (!totalsModeChanged && !externalHeaderSupplied) {
+      documentEditSchema.parse(rawInput ?? {});
+    }
+    if (isExternalAmountsMode(nextTotalsMode) && (totalsModeChanged || externalHeaderSupplied)) {
+      await requireOrderTotalsForExternalWrite(parsed);
+    }
     await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
     const previousStatus = normalizeStatusValue(order.status);
     if (parsed.statusEntryId && !isCancelledOrderStatus(previousStatus)) {
@@ -5849,6 +5938,13 @@ const updateOrderCommand: CommandHandler<
       }
     }
     let statusChangeNote: SalesNote | null = null;
+    const suppliedTotals: Partial<SalesDocumentAmounts> | null = isExternalAmountsMode(
+      nextTotalsMode,
+    )
+      ? externalHeaderSupplied
+        ? buildExternalHeaderTotals(parsed)
+        : readPersistedHeaderTotals(order)
+      : null;
     const shouldRecalculateTotals =
       parsed.shippingMethodId !== undefined ||
       parsed.shippingMethodSnapshot !== undefined ||
@@ -5856,7 +5952,9 @@ const updateOrderCommand: CommandHandler<
       parsed.paymentMethodId !== undefined ||
       parsed.paymentMethodSnapshot !== undefined ||
       parsed.paymentMethodCode !== undefined ||
-      parsed.currencyCode !== undefined;
+      parsed.currencyCode !== undefined ||
+      totalsModeChanged ||
+      externalHeaderSupplied;
     // Apply the scalar update, totals recalc, and status-change note atomically.
     // applyDocumentUpdate/replace*/setRecordCustomFields flush mid-build, so
     // without a transaction a later failure would leave a half-updated order
@@ -5893,10 +5991,17 @@ const updateOrderCommand: CommandHandler<
               ),
             ]);
             const lineSnapshots = existingLines.map(mapOrderLineEntityToSnapshot);
+            // Leaving external: the stored tax and gross are the source's figures,
+            // and the computed path honours both verbatim while it re-derives net,
+            // so they must be re-derived too or net + tax ≠ gross (#7925).
+            const leavingExternal =
+              totalsModeChanged && !isExternalAmountsMode(nextTotalsMode);
             const calcLines = lineSnapshots.map((line, index) =>
               createLineSnapshotFromInput(
                 {
                   ...line,
+                  ...(leavingExternal ? { taxAmount: null, totalGrossAmount: null } : {}),
+                  amountsMode: nextTotalsMode,
                   organizationId: order.organizationId,
                   tenantId: order.tenantId,
                   orderId: order.id,
@@ -5931,6 +6036,8 @@ const updateOrderCommand: CommandHandler<
                 adjustments: adjustmentDrafts,
                 context: calculationContext,
                 existingTotals: resolveExistingPaymentTotals(order),
+                totalsMode: nextTotalsMode,
+                suppliedTotals,
               });
             const adjustmentInputs = adjustmentDrafts.map((adj, index) => ({
               organizationId: order.organizationId,
@@ -5955,6 +6062,15 @@ const updateOrderCommand: CommandHandler<
               calculation,
               adjustmentInputs,
             );
+            if (totalsModeChanged) {
+              applyOrderLineAmountsFromCalculation({
+                em,
+                lines: existingLines,
+                calculation,
+                amountsMode: nextTotalsMode,
+              });
+              order.totalsMode = nextTotalsMode;
+            }
             applyOrderTotals(order, calculation.totals, calculation.lines.length);
             let eventBus: EventBus | null = null;
             try {
@@ -6306,7 +6422,23 @@ const createOrderCommand: CommandHandler<
         )
       : null;
 
-    const lineSnapshots: SalesLineSnapshot[] = normalizedLineInputs.map(
+    const totalsMode: SalesAmountsMode = parsed.totalsMode ?? "computed";
+    await assertUniformAmountsMode(totalsMode, normalizedLineInputs);
+    const modedLineInputs = normalizedLineInputs.map((line) => ({
+      ...line,
+      amountsMode: totalsMode,
+    }));
+    if (isExternalAmountsMode(totalsMode)) {
+      await assertExternalHeaderComplete(parsed);
+      for (const [index, line] of modedLineInputs.entries()) {
+        await assertExternalLineComplete(line, line.lineNumber ?? index + 1);
+      }
+    }
+    order.totalsMode = totalsMode;
+    const suppliedTotals: Partial<SalesDocumentAmounts> | null = isExternalAmountsMode(totalsMode)
+      ? buildExternalHeaderTotals(parsed)
+      : null;
+    const lineSnapshots: SalesLineSnapshot[] = modedLineInputs.map(
       (line, index) =>
         createLineSnapshotFromInput(line, line.lineNumber ?? index + 1),
     );
@@ -6333,6 +6465,8 @@ const createOrderCommand: CommandHandler<
       adjustments: adjustmentDrafts,
       context: calculationContext,
       existingTotals: resolveExistingPaymentTotals(order),
+      totalsMode,
+      suppliedTotals,
     });
 
     let eventBus: EventBus | null = null;
@@ -6349,7 +6483,7 @@ const createOrderCommand: CommandHandler<
       [
         async () => {
           em.persist(order);
-          await replaceOrderLines(em, order, calculation, normalizedLineInputs);
+          await replaceOrderLines(em, order, calculation, modedLineInputs);
           await replaceOrderAdjustments(
             em,
             order,
@@ -7188,13 +7322,17 @@ const convertQuoteToOrderCommand: CommandHandler<
   },
 };
 
+// Nested rather than spread flat: a line payload already has a `totalNetAmount`
+// that means the line's, not the document's.
 const orderLineUpsertSchema = orderLineCreateSchema.extend({
   id: z.string().uuid().optional(),
+  orderTotals: orderHeaderTotalsSchema.optional(),
 });
 
 const orderLineDeleteSchema = z.object({
   id: z.string().uuid(),
   orderId: z.string().uuid(),
+  orderTotals: orderHeaderTotalsSchema.optional(),
 });
 
 const quoteLineUpsertSchema = quoteLineCreateSchema.extend({
@@ -7511,6 +7649,14 @@ const orderLineUpsertCommand: CommandHandler<
     const existingSnapshot = parsed.id
       ? (lineSnapshots.find((line) => line.id === parsed.id) ?? null)
       : null;
+    const totalsMode: SalesAmountsMode = order.totalsMode ?? "computed";
+    await assertUniformAmountsMode(totalsMode, [parsed]);
+    if (isExternalAmountsMode(totalsMode)) {
+      await requireOrderTotalsForExternalWrite(parsed.orderTotals);
+    }
+    const suppliedTotals: Partial<SalesDocumentAmounts> | null = isExternalAmountsMode(totalsMode)
+      ? buildExternalHeaderTotals(parsed.orderTotals)
+      : null;
     await assertOrderAcceptsNewLine(order, existingSnapshot);
     await assertShippedOrderLineEditable(em, order, existingSnapshot, parsed);
     const priceMode =
@@ -7524,6 +7670,7 @@ const orderLineUpsertCommand: CommandHandler<
     let unitPriceGross =
       parsed.unitPriceGross ?? existingSnapshot?.unitPriceGross ?? null;
     let taxRate = parsed.taxRate ?? existingSnapshot?.taxRate ?? null;
+    const unitPriceSupplied = unitPriceNet !== null || unitPriceGross !== null;
     if (priceMode && (unitPriceNet === null || unitPriceGross === null)) {
       let taxService: TaxCalculationService | null = null;
       try {
@@ -7659,11 +7806,25 @@ const orderLineUpsertCommand: CommandHandler<
         parsed.customFields && typeof parsed.customFields === "object"
           ? cloneJson(parsed.customFields)
           : ((existingSnapshot as any)?.customFields ?? null),
+      amountsMode: totalsMode,
     };
     Object.assign(
       updatedSnapshot,
       resolveUpsertCalculatedAmounts(parsed, updatedSnapshot, existingSnapshot),
     );
+    // After the line above, never before: tax and gross only exist once it runs,
+    // and it nulls them when pricing changed, which an external line must restate.
+    // The unit price is checked as resolved, not as defaulted to zero above,
+    // and a price the tax service derived from no source price counts as absent.
+    if (isExternalAmountsMode(totalsMode)) {
+      await assertExternalLineComplete(
+        {
+          ...(updatedSnapshot as Record<string, unknown>),
+          unitPriceNet: unitPriceSupplied ? unitPriceNet : null,
+        },
+        updatedSnapshot.lineNumber ?? 1,
+      );
+    }
     (updatedSnapshot as any).statusEntryId = statusEntryId;
     (updatedSnapshot as any).catalogSnapshot =
       parsed.catalogSnapshot ??
@@ -7716,6 +7877,8 @@ const orderLineUpsertCommand: CommandHandler<
       adjustments: adjustmentDrafts,
       context: calculationContext,
       existingTotals: resolveExistingPaymentTotals(order),
+      totalsMode,
+      suppliedTotals,
     });
     let eventBus: EventBus | null = null;
     try {
@@ -7858,6 +8021,13 @@ const orderLineDeleteCommand: CommandHandler<
         ),
       });
     }
+    const totalsMode: SalesAmountsMode = order.totalsMode ?? "computed";
+    if (isExternalAmountsMode(totalsMode)) {
+      await requireOrderTotalsForExternalWrite(parsed.orderTotals);
+    }
+    const suppliedTotals: Partial<SalesDocumentAmounts> | null = isExternalAmountsMode(totalsMode)
+      ? buildExternalHeaderTotals(parsed.orderTotals)
+      : null;
     const sourceInputs = filtered.map((line, index) => ({
       ...mapOrderLineEntityToSnapshot(line),
       statusEntryId: line.statusEntryId ?? null,
@@ -7895,6 +8065,8 @@ const orderLineDeleteCommand: CommandHandler<
       adjustments: adjustmentDrafts,
       context: calculationContext,
       existingTotals: resolveExistingPaymentTotals(order),
+      totalsMode,
+      suppliedTotals,
     });
     let eventBus: EventBus | null = null;
     try {
@@ -7986,6 +8158,7 @@ const quoteLineUpsertCommand: CommandHandler<
   async execute(input, ctx) {
     const rawBody = (input?.body as Record<string, unknown> | undefined) ?? {};
     const parsed = quoteLineUpsertSchema.parse(rawBody);
+    await assertAmountsModeUnsupportedOnQuote([parsed]);
     const em = (ctx.container.resolve("em") as EntityManager).fork();
     const quote = await findOneWithDecryption(em, SalesQuote, {
       id: parsed.quoteId,
@@ -8460,6 +8633,7 @@ const orderAdjustmentUpsertCommand: CommandHandler<
       throw notFound("Sales order not found");
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
     await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
+    if (isExternalAmountsMode(order.totalsMode ?? "computed")) await refuseOnExternalOrder();
     if (parsed.scope === "line") {
       throw new CrudHttpError(400, {
         error: "Line-scoped adjustments are not supported yet.",
@@ -8752,6 +8926,7 @@ const orderAdjustmentDeleteCommand: CommandHandler<
     ensureOrderScope(ctx, order.organizationId, order.tenantId);
     await enforceSalesDocumentOptimisticLock(ctx, order, SALES_RESOURCE_KIND_ORDER);
 
+    if (isExternalAmountsMode(order.totalsMode ?? "computed")) await refuseOnExternalOrder();
     const [existingLines, adjustments] = await Promise.all([
       em.find(SalesOrderLine, { order }, { orderBy: { lineNumber: "asc" } }),
       em.find(

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

@@ -13,6 +13,8 @@ import { findOneWithDecryption, findWithDecryption } from '@open-mercato/shared/
 import { SalesDocumentNumberGenerator } from '../services/salesDocumentNumberGenerator'
 import type { SalesCalculationService } from '../services/salesCalculationService'
 import type { SalesAdjustmentDraft, SalesLineSnapshot, SalesDocumentCalculationResult } from '../lib/types'
+import { isExternalAmountsMode } from '../lib/calculations'
+import { readPersistedHeaderTotals } from '../lib/externalAmounts'
 import { cloneJson, deriveLineNetFromGross, ensureOrganizationScope, ensureSameScope, ensureTenantScope, extractUndoPayload, toNumericString, enforceSalesDocumentOptimisticLock, SALES_RESOURCE_KIND_ORDER, SALES_RESOURCE_KIND_RETURN } from './shared'
 import { resolveRedoSnapshot } from '@open-mercato/shared/lib/commands/redo'
 import { SalesOrder, SalesOrderAdjustment, SalesOrderLine, SalesReturn, SalesReturnLine } from '../data/entities'
@@ -135,6 +137,24 @@ function applyOrderTotals(order: SalesOrder, totals: SalesDocumentCalculationRes
   order.lineItemCount = lineCount
 }
 
+// Deliberate, not an omission: an external order's header belongs to the source
+// system, which issues its own credit document. The return itself is still recorded.
+function applyOrderTotalsUnlessExternal(
+  order: SalesOrder,
+  calculation: SalesDocumentCalculationResult,
+): void {
+  if (isExternalAmountsMode(order.totalsMode ?? 'computed')) return
+  applyOrderTotals(order, calculation.totals, calculation.lines.length)
+}
+
+function resolveOrderCalculationMode(order: SalesOrder) {
+  const totalsMode = order.totalsMode ?? 'computed'
+  return {
+    totalsMode,
+    suppliedTotals: isExternalAmountsMode(totalsMode) ? readPersistedHeaderTotals(order) : null,
+  }
+}
+
 function mapOrderAdjustmentToDraft(adjustment: SalesOrderAdjustment): SalesAdjustmentDraft {
   return {
     id: adjustment.id,
@@ -206,6 +226,7 @@ export async function recalculateOrderTotalsForDisplay(
     adjustments: adjustmentDrafts,
     context: buildCalculationContext(order),
     existingTotals: resolveExistingPaymentTotals(order),
+    ...resolveOrderCalculationMode(order),
   })
   return calculation.totals
 }
@@ -391,8 +412,9 @@ async function reverseReturnEffects(
           adjustments: adjustmentDrafts,
           context: buildCalculationContext(order),
           existingTotals: resolveExistingPaymentTotals(order),
+          ...resolveOrderCalculationMode(order),
         })
-        applyOrderTotals(order, calculation.totals, calculation.lines.length)
+        applyOrderTotalsUnlessExternal(order, calculation)
         order.updatedAt = new Date()
         em.persist(order)
       },
@@ -577,8 +599,9 @@ async function restoreReturnEffects(
           adjustments: adjustmentDrafts,
           context: buildCalculationContext(order),
           existingTotals: resolveExistingPaymentTotals(order),
+          ...resolveOrderCalculationMode(order),
         })
-        applyOrderTotals(order, calculation.totals, calculation.lines.length)
+        applyOrderTotalsUnlessExternal(order, calculation)
         order.updatedAt = new Date()
         em.persist(order)
       },
@@ -763,8 +786,9 @@ const createReturnCommand: CommandHandler<ReturnCreateInput, { returnId: string
         adjustments: adjustmentDrafts,
         context: buildCalculationContext(order),
         existingTotals: resolveExistingPaymentTotals(order),
+        ...resolveOrderCalculationMode(order),
       })
-      applyOrderTotals(order, calculation.totals, calculation.lines.length)
+      applyOrderTotalsUnlessExternal(order, calculation)
       order.updatedAt = new Date()
       tx.persist(order)