@open-mercato/core 0.10.1-develop.7723.1.3b2ea82ea7 → 0.10.1-develop.7724.1.95e4e7d38e

package/src/modules/sales/lib/externalAmounts.ts

@@ -0,0 +1,174 @@
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+import type { SalesAmountsMode } from '../data/entities'
+import { EXTERNAL_HEADER_FIELDS } from './calculations'
+import type { SalesDocumentAmounts } from './types'
+
+export type ExternalHeaderField = (typeof EXTERNAL_HEADER_FIELDS)[number]
+
+// A mirrored document that charges no shipping or surcharge has nothing to say
+// about them, so they default to zero instead of being required.
+const OPTIONAL_EXTERNAL_HEADER_FIELDS: ReadonlySet<ExternalHeaderField> = new Set([
+  'shippingNetAmount',
+  'shippingGrossAmount',
+  'surchargeTotalAmount',
+])
+
+export const REQUIRED_EXTERNAL_HEADER_FIELDS: readonly ExternalHeaderField[] =
+  EXTERNAL_HEADER_FIELDS.filter((field) => !OPTIONAL_EXTERNAL_HEADER_FIELDS.has(field))
+
+/**
+ * `unitPriceNet` is required because the derived discount consumes it: without it
+ * the line's whole net would be stored as a discount, indistinguishable from a markup.
+ */
+export const REQUIRED_EXTERNAL_LINE_FIELDS = [
+  'unitPriceNet',
+  'totalNetAmount',
+  'totalGrossAmount',
+  'taxAmount',
+] as const
+
+export type ExternalLineField = (typeof REQUIRED_EXTERNAL_LINE_FIELDS)[number]
+
+function toFiniteNumber(value: unknown): number | null {
+  if (typeof value === 'number' && Number.isFinite(value)) return value
+  if (typeof value === 'string' && value.trim() !== '') {
+    const parsed = Number(value)
+    return Number.isFinite(parsed) ? parsed : null
+  }
+  return null
+}
+
+type HeaderSource = Record<string, unknown> | null | undefined
+
+export function collectSuppliedHeaderTotals(source: HeaderSource): Partial<SalesDocumentAmounts> {
+  const totals: Partial<SalesDocumentAmounts> = {}
+  if (!source) return totals
+  for (const field of EXTERNAL_HEADER_FIELDS) {
+    const value = toFiniteNumber(source[field])
+    if (value !== null) totals[field] = value
+  }
+  return totals
+}
+
+export function hasAnySuppliedHeaderTotal(source: HeaderSource): boolean {
+  if (!source) return false
+  return EXTERNAL_HEADER_FIELDS.some((field) => toFiniteNumber(source[field]) !== null)
+}
+
+function missingHeaderFields(source: HeaderSource): ExternalHeaderField[] {
+  return REQUIRED_EXTERNAL_HEADER_FIELDS.filter(
+    (field) => toFiniteNumber(source?.[field]) === null,
+  )
+}
+
+function missingLineFields(line: Record<string, unknown>): ExternalLineField[] {
+  return REQUIRED_EXTERNAL_LINE_FIELDS.filter((field) => toFiniteNumber(line[field]) === null)
+}
+
+/** The supplied header with its optional fields defaulted to zero. */
+export function buildExternalHeaderTotals(source: HeaderSource): Partial<SalesDocumentAmounts> {
+  const supplied = collectSuppliedHeaderTotals(source)
+  for (const field of OPTIONAL_EXTERNAL_HEADER_FIELDS) {
+    supplied[field] ??= 0
+  }
+  return supplied
+}
+
+export async function assertExternalHeaderComplete(source: HeaderSource): Promise<void> {
+  const missing = missingHeaderFields(source)
+  if (!missing.length) return
+  const { translate } = await resolveTranslations()
+  throw new CrudHttpError(400, {
+    error: translate(
+      'sales.errors.externalTotalsRequired',
+      'An order with external amounts must supply its own document totals: {{fields}}.',
+      { fields: missing.join(', ') },
+    ),
+  })
+}
+
+export async function assertExternalLineComplete(
+  line: Record<string, unknown>,
+  lineNumber: number,
+): Promise<void> {
+  const missing = missingLineFields(line)
+  if (!missing.length) return
+  const { translate } = await resolveTranslations()
+  throw new CrudHttpError(400, {
+    error: translate(
+      'sales.errors.externalAmountsIncomplete',
+      'Line {{line}} has external amounts but is missing: {{fields}}. Partial specification is not a mode.',
+      { line: String(lineNumber), fields: missing.join(', ') },
+    ),
+  })
+}
+
+export async function assertUniformAmountsMode(
+  documentMode: SalesAmountsMode,
+  lines: Array<{ amountsMode?: SalesAmountsMode | null }>,
+): Promise<void> {
+  const conflicting = lines.some(
+    (line) => line.amountsMode != null && line.amountsMode !== documentMode,
+  )
+  if (!conflicting) return
+  const { translate } = await resolveTranslations()
+  throw new CrudHttpError(400, {
+    error: translate(
+      'sales.errors.externalModeMixed',
+      'An order and all of its lines must share the same amounts mode.',
+      { mode: documentMode },
+    ),
+  })
+}
+
+export async function refuseOnExternalOrder(): Promise<never> {
+  const { translate } = await resolveTranslations()
+  throw new CrudHttpError(409, {
+    error: translate(
+      'sales.errors.externalAdjustmentRefused',
+      'This order carries amounts from an external system, so adjustments cannot be added or removed. Switch it to computed amounts first.',
+    ),
+  })
+}
+
+export async function requireOrderTotalsForExternalWrite(source: HeaderSource): Promise<void> {
+  if (!hasAnySuppliedHeaderTotal(source)) {
+    const { translate } = await resolveTranslations()
+    throw new CrudHttpError(400, {
+      error: translate(
+        'sales.errors.externalTotalsRequired',
+        'An order with external amounts must supply its own document totals: {{fields}}.',
+        { fields: REQUIRED_EXTERNAL_HEADER_FIELDS.join(', ') },
+      ),
+    })
+  }
+  await assertExternalHeaderComplete(source)
+}
+
+export function readPersistedHeaderTotals(
+  order: Record<ExternalHeaderField, string | number | null | undefined>,
+): Partial<SalesDocumentAmounts> {
+  const totals: Partial<SalesDocumentAmounts> = {}
+  for (const field of EXTERNAL_HEADER_FIELDS) {
+    totals[field] = toFiniteNumber(order[field]) ?? 0
+  }
+  return totals
+}
+
+export async function assertAmountsModeUnsupportedOnQuote(
+  payloads:
+    | Array<{ amountsMode?: SalesAmountsMode | null; totalsMode?: SalesAmountsMode | null }>
+    | null
+    | undefined,
+): Promise<void> {
+  // Both reach quote commands, through schemas shared with orders.
+  if (!payloads?.some((payload) => payload.amountsMode != null || payload.totalsMode != null)) return
+  const { translate } = await resolveTranslations()
+  throw new CrudHttpError(400, {
+    error: translate(
+      'sales.errors.externalModeUnsupportedOnQuote',
+      'Quotes cannot carry an amounts mode; they always use computed amounts.',
+    ),
+  })
+}

package/src/modules/sales/lib/lineSnapshots.ts

@@ -80,7 +80,12 @@ function mapPersistedLine(line: SalesOrderLine | SalesQuoteLine): SalesPersisted
  * the return flows kept the discount defect after the order flows were fixed.
  */
 export function mapOrderLineEntityToSnapshot(line: SalesOrderLine): SalesPersistedLineSnapshot {
-  return mapPersistedLine(line)
+  return {
+    ...mapPersistedLine(line),
+    // Who owns the amounts, not where they came from — never conflate it with the
+    // origin flags above. Order-only: quote lines have no such column.
+    amountsMode: line.amountsMode ?? 'computed',
+  }
 }
 
 export function mapQuoteLineEntityToSnapshot(line: SalesQuoteLine): SalesPersistedLineSnapshot {

package/src/modules/sales/lib/makeSalesLineRoute.ts

@@ -28,6 +28,8 @@ interface SalesLineRouteConfig {
   parentFkColumn: string
   parentFkParam: string
   createSchema: z.ZodObject<z.ZodRawShape>
+  /** Extra fields accepted by the write payloads on top of `createSchema`. */
+  writeExtensionShape?: z.ZodRawShape
   features: { view: string; manage: string }
   commandPrefix: string
   openApi: {
@@ -110,6 +112,7 @@ export function makeSalesLineRoute(config: SalesLineRouteConfig) {
     parentFkColumn,
     parentFkParam,
     createSchema,
+    writeExtensionShape,
     features,
     commandPrefix,
   } = config
@@ -127,11 +130,13 @@ export function makeSalesLineRoute(config: SalesLineRouteConfig) {
 
   const upsertSchema = createSchema.extend({
     id: z.string().uuid().optional(),
+    ...(writeExtensionShape ?? {}),
   })
 
   const deleteSchema = z.object({
     id: z.string().uuid(),
     [parentFkParam]: z.string().uuid(),
+    ...(writeExtensionShape ?? {}),
   })
 
   const routeMetadata = {
@@ -199,6 +204,8 @@ export function makeSalesLineRoute(config: SalesLineRouteConfig) {
         ]
         const returnedQuantity = F['returned_quantity']
         if (typeof returnedQuantity === 'string') fields.push(returnedQuantity)
+        const amountsMode = F['amounts_mode']
+        if (typeof amountsMode === 'string') fields.push(amountsMode)
         return fields
       })(),
       sortFieldMap: {
@@ -321,6 +328,7 @@ export function makeSalesLineRoute(config: SalesLineRouteConfig) {
     promotion_snapshot: z.record(z.string(), z.unknown()).nullable().optional(),
     metadata: z.record(z.string(), z.unknown()).nullable().optional(),
     custom_field_set_id: z.string().uuid().nullable().optional(),
+    amounts_mode: z.enum(['computed', 'external']).optional(),
     created_at: z.string(),
     updated_at: z.string(),
   })

package/src/modules/sales/lib/providers/totals.ts

@@ -1,4 +1,4 @@
-import { registerSalesTotalsCalculator, rebuildDocumentResult } from '../calculations'
+import { isExternalAmountsMode, registerSalesTotalsCalculator, rebuildDocumentResult } from '../calculations'
 import type { SalesAdjustmentDraft, SalesDocumentCalculationResult } from '../types'
 import {
   getPaymentProvider,
@@ -180,7 +180,10 @@ export function ensureProviderTotalsCalculator() {
   if (totalsRegistered) return
   totalsRegistered = true
 
-  registerSalesTotalsCalculator(async ({ documentKind, lines, context, current, eventBus }) => {
+  registerSalesTotalsCalculator(async ({ documentKind, lines, context, current, eventBus, totalsMode }) => {
+    // A provider charge here could not move the caller's header, so it would show
+    // in the breakdown and be absent from the total.
+    if (isExternalAmountsMode(totalsMode)) return current
     const metadata = (context.metadata ?? {}) as Record<string, unknown>
     const shippingMethod = (metadata.shippingMethod ?? null) as ShippingMethodContext | null
     const paymentMethod = (metadata.paymentMethod ?? null) as PaymentMethodContext | null

package/src/modules/sales/lib/types.ts

@@ -1,8 +1,17 @@
 import type { EventBus } from '@open-mercato/events'
 import type { ReferenceUnitCode } from '@open-mercato/shared/lib/units/unitCodes'
-import type { SalesAdjustmentKind, SalesDocumentKind, SalesLineKind } from '../data/entities'
+import type {
+  SalesAdjustmentKind,
+  SalesAmountsMode,
+  SalesDocumentKind,
+  SalesLineKind,
+} from '../data/entities'
 
-export type { SalesAdjustmentKind, SalesDocumentKind, SalesLineKind }
+/**
+ * `SalesAmountsMode`: `computed` means core derives the amounts; `external` means
+ * they are the caller's, mirrored from another system, and are never recomputed.
+ */
+export type { SalesAdjustmentKind, SalesAmountsMode, SalesDocumentKind, SalesLineKind }
 
 export type NumericLike = number | string
 
@@ -89,6 +98,8 @@ export type SalesLineSnapshot = {
   metadata?: Record<string, unknown> | null
   customFieldSetId?: string | null
   customFields?: Record<string, unknown> | null
+  /** `external`: net, gross and tax are returned verbatim, never derived. Omitted means `computed`. */
+  amountsMode?: SalesAmountsMode | null
 }
 
 export type SalesAdjustmentDraft = {
@@ -155,6 +166,8 @@ export type SalesTotalsCalculationHook = (params: {
   context: SalesCalculationContext
   current: SalesDocumentCalculationResult
   eventBus?: EventBus | null
+  /** `external`: the supplied header is re-applied after every calculator, so none can move it. */
+  totalsMode?: SalesAmountsMode | null
 }) => SalesDocumentCalculationResult | Promise<SalesDocumentCalculationResult>
 
 export type SalesCalculationContext = {
@@ -182,4 +195,8 @@ export type CalculateDocumentOptions = {
     refundedTotalAmount?: number | null
   }
   eventBus?: EventBus | null
+  /** `external` makes {@link CalculateDocumentOptions.suppliedTotals} authoritative for the header. */
+  totalsMode?: SalesAmountsMode | null
+  /** The caller-asserted header, honoured verbatim when `totalsMode` is `external`. */
+  suppliedTotals?: Partial<SalesDocumentAmounts> | null
 }

package/src/modules/sales/migrations/.snapshot-open-mercato.json

@@ -4222,6 +4222,22 @@
       "name": "sales_order_lines",
       "schema": "public",
       "columns": {
+        "amounts_mode": {
+          "name": "amounts_mode",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "'computed'",
+          "comment": null,
+          "enumItems": [],
+          "mappedType": "text"
+        },
         "catalog_snapshot": {
           "name": "catalog_snapshot",
           "type": "jsonb",
@@ -5892,6 +5908,22 @@
           "enumItems": [],
           "mappedType": "uuid"
         },
+        "totals_mode": {
+          "name": "totals_mode",
+          "type": "text",
+          "unsigned": false,
+          "autoincrement": false,
+          "primary": false,
+          "nullable": false,
+          "unique": false,
+          "length": null,
+          "precision": null,
+          "scale": null,
+          "default": "'computed'",
+          "comment": null,
+          "enumItems": [],
+          "mappedType": "text"
+        },
         "totals_snapshot": {
           "name": "totals_snapshot",
           "type": "jsonb",
@@ -10943,4 +10975,4 @@
   ],
   "views": [],
   "nativeEnums": {}
-}
+}

package/src/modules/sales/migrations/Migration20260910120000_sales_external_amounts_mode.ts

@@ -0,0 +1,25 @@
+import { Migration } from '@mikro-orm/migrations';
+
+// Opt-in `external` amounts mode for sales orders: the row-level statement that
+// the stored amounts are a caller's assertion mirrored from an external book of
+// record, not something core derived. Two defaulted columns, no backfill — every
+// existing row takes 'computed', which is exactly today's behaviour, so the
+// change is observably inert until a caller sets the mode.
+//
+// PostgreSQL has not rewritten a table for a defaulted column add since 11, so
+// both statements are metadata-only regardless of table size.
+export class Migration20260910120000_sales_external_amounts_mode extends Migration {
+  override async up(): Promise<void> {
+    this.addSql(
+      `alter table "sales_orders" add column if not exists "totals_mode" text not null default 'computed';`,
+    );
+    this.addSql(
+      `alter table "sales_order_lines" add column if not exists "amounts_mode" text not null default 'computed';`,
+    );
+  }
+
+  override async down(): Promise<void> {
+    this.addSql(`alter table "sales_order_lines" drop column if exists "amounts_mode";`);
+    this.addSql(`alter table "sales_orders" drop column if exists "totals_mode";`);
+  }
+}