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

package/src/modules/sales/components/documents/AdjustmentsSection.tsx

@@ -42,6 +42,8 @@ type SalesDocumentAdjustmentsSectionProps = {
   tenantId?: string | null
   onActionChange?: (action: SectionAction | null) => void
   onRowsChange?: (rows: AdjustmentRow[]) => void
+  /** Withdraws adjustment writes: on an external order they would all be refused. */
+  amountsReadOnly?: boolean
 }
 
 const FALLBACK_ADJUSTMENT_KIND_VALUES: SalesAdjustmentKind[] = [
@@ -76,6 +78,7 @@ export function SalesDocumentAdjustmentsSection({
   tenantId: tenantFromProps,
   onActionChange,
   onRowsChange,
+  amountsReadOnly = false,
 }: SalesDocumentAdjustmentsSectionProps) {
   const t = useT()
   const runDocumentMutation = useSalesDocumentMutation(kind, documentId)
@@ -281,10 +284,14 @@ export function SalesDocumentAdjustmentsSection({
     setDialogOpen(true)
   }, [])
 
-  const handleEdit = React.useCallback((row: AdjustmentRow) => {
-    setActiveAdjustment(row)
-    setDialogOpen(true)
-  }, [])
+  const handleEdit = React.useCallback(
+    (row: AdjustmentRow) => {
+      if (amountsReadOnly) return
+      setActiveAdjustment(row)
+      setDialogOpen(true)
+    },
+    [amountsReadOnly]
+  )
 
   const handleCloseDialog = React.useCallback(() => {
     setDialogOpen(false)
@@ -296,10 +303,10 @@ export function SalesDocumentAdjustmentsSection({
     onActionChange({
       label: t('sales.documents.adjustments.add', 'Add adjustment'),
       onClick: handleOpenCreate,
-      disabled: false,
+      disabled: amountsReadOnly,
     })
     return () => onActionChange(null)
-  }, [handleOpenCreate, onActionChange, t])
+  }, [amountsReadOnly, handleOpenCreate, onActionChange, t])
 
   const handleFormSubmit = React.useCallback(
     async (values: AdjustmentSubmitPayload) => {
@@ -451,24 +458,25 @@ export function SalesDocumentAdjustmentsSection({
   const showLoadingState = loading && rows.length === 0
 
   const renderRowActions = React.useCallback(
-    (row: AdjustmentRow) => (
-      <RowActions
-        items={[
-          {
-            id: 'edit',
-            label: t('ui.actions.edit', 'Edit'),
-            onSelect: () => handleEdit(row),
-          },
-          {
-            id: 'delete',
-            label: t('ui.actions.delete', 'Delete'),
-            destructive: true,
-            onSelect: () => handleDelete(row),
-          },
-        ]}
-      />
-    ),
-    [handleDelete, handleEdit, t]
+    (row: AdjustmentRow) =>
+      amountsReadOnly ? null : (
+        <RowActions
+          items={[
+            {
+              id: 'edit',
+              label: t('ui.actions.edit', 'Edit'),
+              onSelect: () => handleEdit(row),
+            },
+            {
+              id: 'delete',
+              label: t('ui.actions.delete', 'Delete'),
+              destructive: true,
+              onSelect: () => handleDelete(row),
+            },
+          ]}
+        />
+      ),
+    [amountsReadOnly, handleDelete, handleEdit, t]
   )
 
   return (
@@ -487,7 +495,7 @@ export function SalesDocumentAdjustmentsSection({
           columns={columns}
           isLoading={loading && rows.length > 0}
           embedded
-          onRowClick={handleEdit}
+          onRowClick={amountsReadOnly ? undefined : handleEdit}
           rowActions={renderRowActions}
           emptyState={
             <TabEmptyState
@@ -495,6 +503,7 @@ export function SalesDocumentAdjustmentsSection({
               description={t('sales.documents.empty.adjustments.description', 'Add discounts, fees, or taxes to refine totals.')}
               actionLabel={t('sales.documents.adjustments.add', 'Add adjustment')}
               onAction={handleOpenCreate}
+              disabled={amountsReadOnly}
             />
           }
         />

package/src/modules/sales/components/documents/DocumentTotals.tsx

@@ -17,9 +17,20 @@ type DocumentTotalsProps = {
   currency: string | null | undefined
   items: DocumentTotalItem[]
   className?: string
+  /** Marks the header as caller-asserted, e.g. "Amounts from source". */
+  sourceBadge?: { label: string; hint?: string } | null
+  /** Rendered under the table — the explicit action that leaves the source-owned mode. */
+  footerAction?: React.ReactNode
 }
 
-export function DocumentTotals({ title, currency, items, className }: DocumentTotalsProps) {
+export function DocumentTotals({
+  title,
+  currency,
+  items,
+  className,
+  sourceBadge,
+  footerAction,
+}: DocumentTotalsProps) {
   const t = useT()
   const emphasizedRows = items.filter((item) => item.emphasize)
   const heading = title ?? t('sales.documents.detail.totals.title')
@@ -56,7 +67,17 @@ export function DocumentTotals({ title, currency, items, className }: DocumentTo
     <div className={cn('space-y-3', className)}>
       <div className="overflow-hidden rounded-xl border bg-card shadow-sm">
         <div className="flex items-center justify-between border-b bg-muted/50 px-4 py-3">
-          <span className="text-xs font-semibold uppercase tracking-wide text-muted-foreground">{heading}</span>
+          <span className="flex items-center gap-2 text-xs font-semibold uppercase tracking-wide text-muted-foreground">
+            {heading}
+            {sourceBadge ? (
+              <span
+                title={sourceBadge.hint}
+                className="rounded-full bg-status-info-bg px-2 py-0.5 text-xs font-semibold normal-case tracking-normal text-status-info-text"
+              >
+                {sourceBadge.label}
+              </span>
+            ) : null}
+          </span>
           {currency ? (
             <span className="rounded-full border border-border/70 bg-background/80 px-3 py-1 text-xs font-semibold tracking-wide text-foreground">
               {currency}
@@ -113,6 +134,9 @@ export function DocumentTotals({ title, currency, items, className }: DocumentTo
             </button>
           </div>
         ) : null}
+        {footerAction ? (
+          <div className="flex items-center justify-end border-t bg-muted/30 px-4 py-3">{footerAction}</div>
+        ) : null}
       </div>
     </div>
   )

package/src/modules/sales/components/documents/ItemsSection.tsx

@@ -16,6 +16,7 @@ import {
   createDictionaryMap,
   normalizeDictionaryEntries,
 } from "@open-mercato/core/modules/dictionaries/components/dictionaryAppearance";
+import { cn } from "@open-mercato/shared/lib/utils";
 import { useT, useLocale } from "@open-mercato/shared/lib/i18n/context";
 import { useOrganizationScopeDetail } from "@open-mercato/shared/lib/frontend/useOrganizationScope";
 import { useConfirmDialog } from "@open-mercato/ui/backend/confirm-dialog";
@@ -151,6 +152,8 @@ type SalesDocumentItemsSectionProps = {
   tenantId?: string | null;
   onActionChange?: (action: SectionAction | null) => void;
   onItemsChange?: (items: SalesLineRecord[]) => void;
+  /** Disables line writes: on an external order they would all be rejected. */
+  amountsReadOnly?: boolean;
 };
 
 export function SalesDocumentItemsSection({
@@ -162,6 +165,7 @@ export function SalesDocumentItemsSection({
   tenantId: tenantFromProps,
   onActionChange,
   onItemsChange,
+  amountsReadOnly = false,
 }: SalesDocumentItemsSectionProps) {
   const t = useT();
   const runDocumentMutation = useSalesDocumentMutation(kind, documentId);
@@ -535,15 +539,19 @@ export function SalesDocumentItemsSection({
     onActionChange({
       label: t("sales.documents.items.add", "Add item"),
       onClick: openCreate,
-      disabled: false,
+      disabled: amountsReadOnly,
     });
     return () => onActionChange(null);
-  }, [onActionChange, openCreate, t]);
+  }, [amountsReadOnly, onActionChange, openCreate, t]);
 
-  const handleEdit = React.useCallback((line: SalesLineRecord) => {
-    setLineForEdit(line);
-    setDialogOpen(true);
-  }, []);
+  const handleEdit = React.useCallback(
+    (line: SalesLineRecord) => {
+      if (amountsReadOnly) return;
+      setLineForEdit(line);
+      setDialogOpen(true);
+    },
+    [amountsReadOnly],
+  );
 
   const resolveVariantInfo = React.useCallback((record: SalesLineRecord) => {
     const meta =
@@ -728,10 +736,11 @@ export function SalesDocumentItemsSection({
           action={{
             label: t("sales.documents.items.add", "Add item"),
             onClick: openCreate,
+            disabled: amountsReadOnly,
           }}
         />
       ) : (
-        <div className="overflow-hidden rounded border">
+        <div className="relative overflow-x-auto rounded border">
           <table className="w-full text-sm">
             <thead className="bg-muted">
               <tr className="text-left">
@@ -810,7 +819,10 @@ export function SalesDocumentItemsSection({
                 return (
                   <tr
                     key={item.id}
-                    className="border-t hover:bg-muted/50 cursor-pointer transition-colors"
+                    className={cn(
+                      "border-t transition-colors",
+                      amountsReadOnly ? "" : "cursor-pointer hover:bg-muted/50",
+                    )}
                     onClick={() => handleEdit(item)}
                   >
                     <td className="px-3 py-3">
@@ -995,6 +1007,7 @@ export function SalesDocumentItemsSection({
                           variant="ghost"
                           className="h-8 w-8"
                           aria-label={t('ui.actions.edit', 'Edit')}
+                          disabled={amountsReadOnly}
                           onClick={(event) => {
                             event.stopPropagation();
                             handleEdit(item);
@@ -1003,16 +1016,18 @@ export function SalesDocumentItemsSection({
                           <Pencil className="h-4 w-4" />
                         </Button>
                         <span
-                          title={kind === 'order' && items.length === 1
-                            ? t('sales.documents.items.errorDeleteLast', 'An order must contain at least one line item.')
-                            : undefined}
+                          title={amountsReadOnly
+                            ? t('sales.documents.amountsExternalHint', 'Totals on this document come from an external system and are stored as supplied.')
+                            : kind === 'order' && items.length === 1
+                              ? t('sales.documents.items.errorDeleteLast', 'An order must contain at least one line item.')
+                              : undefined}
                         >
                           <Button
                             size="icon"
                             variant="ghost"
                             className="h-8 w-8 text-destructive"
                             aria-label={t('ui.actions.delete', 'Delete')}
-                            disabled={kind === 'order' && items.length === 1}
+                            disabled={amountsReadOnly || (kind === 'order' && items.length === 1)}
                             onClick={(event) => {
                               event.stopPropagation();
                               void handleDelete(item);

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

@@ -8,6 +8,7 @@ export type SalesDocumentKind = 'order' | 'quote' | 'invoice' | 'credit_memo'
 export type SalesLineKind = 'product' | 'service' | 'shipping' | 'discount' | 'adjustment'
 export const DEFAULT_SALES_ADJUSTMENT_KINDS = ['discount', 'tax', 'shipping', 'surcharge', 'return', 'custom'] as const
 export type SalesAdjustmentKind = (typeof DEFAULT_SALES_ADJUSTMENT_KINDS)[number] | string
+export type SalesAmountsMode = 'computed' | 'external'
 
 @Entity({ tableName: 'sales_channels' })
 @Index({ name: 'sales_channels_org_tenant_idx', properties: ['organizationId', 'tenantId'] })
@@ -331,6 +332,9 @@ export class SalesTaxRate {
 @Index({ name: 'sales_orders_payment_status_idx', properties: ['organizationId', 'tenantId', 'paymentStatus'] })
 @Unique({ name: 'sales_orders_number_unique', properties: ['organizationId', 'tenantId', 'orderNumber'] })
 export class SalesOrder {
+  // Optional so existing `em.create(SalesOrder, ...)` callers keep compiling.
+  [OptionalProps]?: 'totalsMode'
+
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
 
@@ -466,6 +470,10 @@ export class SalesOrder {
   @Property({ name: 'outstanding_amount', type: 'numeric', precision: 18, scale: 4, default: '0' })
   outstandingAmount: string = '0'
 
+  /** `external`: the header totals are the caller's and never rebuilt; payment totals stay core-owned. */
+  @Property({ name: 'totals_mode', type: 'text', default: 'computed' })
+  totalsMode: SalesAmountsMode = 'computed'
+
   @Property({ name: 'line_item_count', type: 'integer', default: 0 })
   lineItemCount: number = 0
 
@@ -553,6 +561,8 @@ export class SalesOrder {
   properties: ['organizationId', 'tenantId', 'normalizedUnit', 'normalizedQuantity'],
 })
 export class SalesOrderLine {
+  [OptionalProps]?: 'amountsMode'
+
   @PrimaryKey({ type: 'uuid', defaultRaw: 'gen_random_uuid()' })
   id!: string
 
@@ -649,6 +659,10 @@ export class SalesOrderLine {
   @Property({ name: 'total_gross_amount', type: 'numeric', precision: 18, scale: 4, default: '0' })
   totalGrossAmount: string = '0'
 
+  /** `external`: amounts are the caller's; `discount_amount` is then signed. Matches the order's `totals_mode`. */
+  @Property({ name: 'amounts_mode', type: 'text', default: 'computed' })
+  amountsMode: SalesAmountsMode = 'computed'
+
   @Property({ name: 'configuration', type: 'jsonb', nullable: true })
   configuration?: Record<string, unknown> | null
 

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

@@ -329,6 +329,8 @@ const lineKindSchema = z.enum(['product', 'service', 'shipping', 'discount', 'ad
 
 const adjustmentKindSchema = z.string().trim().min(1).max(150)
 
+export const amountsModeSchema = z.enum(['computed', 'external'])
+
 const linePricingSchema = z.object({
   quantity: decimal({ min: 0, max: MAX_QUANTITY, message: 'Quantity is too large.' }),
   quantityUnit: z.string().trim().max(25).optional(),
@@ -348,6 +350,9 @@ const linePricingSchema = z.object({
   taxAmount: decimal({ min: 0 }).optional(),
   totalNetAmount: decimal({ min: 0 }).optional(),
   totalGrossAmount: decimal({ min: 0 }).optional(),
+  // Omitted inherits the document's mode; defaulting to `computed` would make an
+  // external order mixed. Order lines only — quote commands reject it.
+  amountsMode: amountsModeSchema.optional(),
 })
 
 const uomSnapshotSchema = z.object({
@@ -672,6 +677,10 @@ const orderTotalsSchema = z.object({
   lineItemCount: z.coerce.number().int().min(0).optional(),
 })
 
+// `lineItemCount` is core's count of the rows it persisted, not one of the amounts
+// a caller owns; asserting it could make a document disagree with its own lines.
+export const orderHeaderTotalsSchema = orderTotalsSchema.omit({ lineItemCount: true })
+
 const quoteTotalsSchema = z.object({
   subtotalNetAmount: decimal({ min: 0 }).optional(),
   subtotalGrossAmount: decimal({ min: 0 }).optional(),
@@ -728,6 +737,7 @@ export const orderCreateSchema = scoped.extend({
     .min(1, SALES_ORDER_LINES_REQUIRED_MESSAGE_KEY),
   adjustments: z.array(orderAdjustmentCreateSchema.omit({ organizationId: true, tenantId: true, orderId: true })).optional(),
   tags: z.array(uuid()).optional(),
+  totalsMode: amountsModeSchema.optional(),
   ...orderTotalsSchema.shape,
   ...orderPaymentLedgerShape,
 })

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

@@ -497,6 +497,13 @@
   "sales.documents.adjustments.title": "Anpassungen",
   "sales.documents.adjustments.untitled": "Ohne Titel",
   "sales.documents.adjustments.updated": "Anpassung aktualisiert.",
+  "sales.documents.amountsExternal": "Beträge aus Quellsystem",
+  "sales.documents.amountsExternalHint": "Die Summen dieses Belegs stammen aus einem externen System und werden unverändert gespeichert.",
+  "sales.documents.amountsExternalMethodNote": "Die Methode wird gespeichert, aber es wird keine Gebühr berechnet — die Summen dieses Auftrags stammen aus dem Quellsystem.",
+  "sales.documents.amountsSwitchConfirm": "Die Beträge dieses Auftrags aus seinen Positionen neu berechnen? Die vom Quellsystem gelieferten Summen werden ersetzt und lassen sich von hier aus nicht wiederherstellen.",
+  "sales.documents.amountsSwitchDone": "Die Beträge werden jetzt aus den Positionen berechnet.",
+  "sales.documents.amountsSwitchFailed": "Umstellung auf berechnete Beträge fehlgeschlagen.",
+  "sales.documents.amountsSwitchToComputed": "Auf berechnete Beträge umstellen",
   "sales.documents.create.title": "Verkaufsdokument erstellen",
   "sales.documents.detail.addresses.add": "Adresse hinzufügen",
   "sales.documents.detail.addresses.additional": "Weitere Adressen",
@@ -1240,6 +1247,11 @@
   "sales.documents.status.documentPlaceholder": "Neuen Bestell-/Angebotsstatus auswählen",
   "sales.documents.status.linePlaceholder": "Positionsstatus auswählen",
   "sales.documents.status.sectionTitle": "Statusänderungen",
+  "sales.errors.externalAdjustmentRefused": "Dieser Auftrag führt Beträge aus einem externen System, daher können keine Anpassungen hinzugefügt oder entfernt werden. Stellen Sie ihn zuerst auf berechnete Beträge um.",
+  "sales.errors.externalAmountsIncomplete": "Position {{line}} hat externe Beträge, aber es fehlen: {{fields}}. Eine unvollständige Angabe ist kein Modus.",
+  "sales.errors.externalModeMixed": "Ein Auftrag und alle seine Positionen müssen denselben Betragsmodus verwenden.",
+  "sales.errors.externalModeUnsupportedOnQuote": "Angebote können keinen Betragsmodus führen; sie verwenden immer berechnete Beträge.",
+  "sales.errors.externalTotalsRequired": "Ein Auftrag mit externen Beträgen muss eigene Belegsummen angeben: {{fields}}.",
   "sales.errors.invalid_query": "Ungültige Abfrageparameter",
   "sales.errors.organization_required": "Organisationskontext ist erforderlich",
   "sales.errors.tag_invalid": "Ungültiges Tag-Format.",

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

@@ -497,6 +497,13 @@
   "sales.documents.adjustments.title": "Adjustments",
   "sales.documents.adjustments.untitled": "Untitled",
   "sales.documents.adjustments.updated": "Adjustment updated.",
+  "sales.documents.amountsExternal": "Amounts from source",
+  "sales.documents.amountsExternalHint": "Totals on this document come from an external system and are stored as supplied.",
+  "sales.documents.amountsExternalMethodNote": "The method is recorded, but no charge is added — this order’s totals come from the source system.",
+  "sales.documents.amountsSwitchConfirm": "Recompute this order’s amounts from its lines? The totals supplied by the source system will be replaced and cannot be restored from here.",
+  "sales.documents.amountsSwitchDone": "Amounts are now computed from the lines.",
+  "sales.documents.amountsSwitchFailed": "Could not switch to computed amounts.",
+  "sales.documents.amountsSwitchToComputed": "Switch to computed amounts",
   "sales.documents.create.title": "Create sales document",
   "sales.documents.detail.addresses.add": "Add address",
   "sales.documents.detail.addresses.additional": "Additional addresses",
@@ -1240,6 +1247,11 @@
   "sales.documents.status.documentPlaceholder": "Select new order/quote status",
   "sales.documents.status.linePlaceholder": "Select item status",
   "sales.documents.status.sectionTitle": "Status changes",
+  "sales.errors.externalAdjustmentRefused": "This order carries amounts from an external system, so adjustments cannot be added or removed. Switch it to computed amounts first.",
+  "sales.errors.externalAmountsIncomplete": "Line {{line}} has external amounts but is missing: {{fields}}. Partial specification is not a mode.",
+  "sales.errors.externalModeMixed": "An order and all of its lines must share the same amounts mode.",
+  "sales.errors.externalModeUnsupportedOnQuote": "Quotes cannot carry an amounts mode; they always use computed amounts.",
+  "sales.errors.externalTotalsRequired": "An order with external amounts must supply its own document totals: {{fields}}.",
   "sales.errors.invalid_query": "Invalid query parameters",
   "sales.errors.organization_required": "Organization context is required",
   "sales.errors.tag_invalid": "Invalid tag format.",

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

@@ -497,6 +497,13 @@
   "sales.documents.adjustments.title": "Ajustes",
   "sales.documents.adjustments.untitled": "Sin título",
   "sales.documents.adjustments.updated": "Ajuste actualizado.",
+  "sales.documents.amountsExternal": "Importes del origen",
+  "sales.documents.amountsExternalHint": "Los totales de este documento provienen de un sistema externo y se guardan tal cual.",
+  "sales.documents.amountsExternalMethodNote": "El método se guarda, pero no añade ningún cargo: los totales de este pedido provienen del sistema de origen.",
+  "sales.documents.amountsSwitchConfirm": "¿Recalcular los importes de este pedido a partir de sus líneas? Los totales aportados por el sistema de origen se reemplazarán y no se podrán restaurar desde aquí.",
+  "sales.documents.amountsSwitchDone": "Los importes ahora se calculan a partir de las líneas.",
+  "sales.documents.amountsSwitchFailed": "No se pudo cambiar a importes calculados.",
+  "sales.documents.amountsSwitchToComputed": "Cambiar a importes calculados",
   "sales.documents.create.title": "Crear documento de ventas",
   "sales.documents.detail.addresses.add": "Agregar dirección",
   "sales.documents.detail.addresses.additional": "Direcciones adicionales",
@@ -1240,6 +1247,11 @@
   "sales.documents.status.documentPlaceholder": "Seleccionar nuevo estado de pedido/cotización",
   "sales.documents.status.linePlaceholder": "Seleccionar estado del artículo",
   "sales.documents.status.sectionTitle": "Cambios de estado",
+  "sales.errors.externalAdjustmentRefused": "Este pedido lleva importes de un sistema externo, por lo que no se pueden añadir ni eliminar ajustes. Cámbialo primero a importes calculados.",
+  "sales.errors.externalAmountsIncomplete": "La línea {{line}} tiene importes externos, pero faltan: {{fields}}. Una especificación parcial no es un modo.",
+  "sales.errors.externalModeMixed": "Un pedido y todas sus líneas deben compartir el mismo modo de importes.",
+  "sales.errors.externalModeUnsupportedOnQuote": "Los presupuestos no pueden llevar un modo de importes; siempre usan importes calculados.",
+  "sales.errors.externalTotalsRequired": "Un pedido con importes externos debe aportar sus propios totales de documento: {{fields}}.",
   "sales.errors.invalid_query": "Parámetros de consulta inválidos",
   "sales.errors.organization_required": "Se requiere el contexto de la organización",
   "sales.errors.tag_invalid": "Formato de etiqueta no válido.",

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

@@ -497,6 +497,13 @@
   "sales.documents.adjustments.title": "조정 항목",
   "sales.documents.adjustments.untitled": "제목 없음",
   "sales.documents.adjustments.updated": "조정 항목이 수정되었습니다.",
+  "sales.documents.amountsExternal": "원본 시스템 금액",
+  "sales.documents.amountsExternalHint": "이 문서의 합계는 외부 시스템에서 제공된 값 그대로 저장됩니다.",
+  "sales.documents.amountsExternalMethodNote": "수단은 저장되지만 요금은 추가되지 않습니다. 이 주문의 합계는 원본 시스템에서 옵니다.",
+  "sales.documents.amountsSwitchConfirm": "이 주문의 금액을 품목에서 다시 계산할까요? 원본 시스템이 제공한 합계는 대체되며 여기서는 복원할 수 없습니다.",
+  "sales.documents.amountsSwitchDone": "이제 금액이 품목에서 계산됩니다.",
+  "sales.documents.amountsSwitchFailed": "계산 금액으로 전환하지 못했습니다.",
+  "sales.documents.amountsSwitchToComputed": "계산 금액으로 전환",
   "sales.documents.create.title": "판매 문서 생성",
   "sales.documents.detail.addresses.add": "주소 추가",
   "sales.documents.detail.addresses.additional": "추가 주소",
@@ -1240,6 +1247,11 @@
   "sales.documents.status.documentPlaceholder": "새 주문/견적 상태 선택",
   "sales.documents.status.linePlaceholder": "항목 상태 선택",
   "sales.documents.status.sectionTitle": "상태 변경",
+  "sales.errors.externalAdjustmentRefused": "이 주문의 금액은 외부 시스템에서 온 것이므로 조정을 추가하거나 삭제할 수 없습니다. 먼저 계산 금액으로 전환하세요.",
+  "sales.errors.externalAmountsIncomplete": "{{line}}번 품목에 외부 금액이 있지만 누락된 항목이 있습니다: {{fields}}. 부분 지정은 모드가 아닙니다.",
+  "sales.errors.externalModeMixed": "주문과 모든 품목은 동일한 금액 모드를 사용해야 합니다.",
+  "sales.errors.externalModeUnsupportedOnQuote": "견적에는 금액 모드를 지정할 수 없습니다. 견적은 항상 계산 금액을 사용합니다.",
+  "sales.errors.externalTotalsRequired": "외부 금액을 사용하는 주문은 문서 합계를 직접 제공해야 합니다: {{fields}}.",
   "sales.errors.invalid_query": "잘못된 조회 파라미터입니다",
   "sales.errors.organization_required": "조직 컨텍스트가 필요합니다",
   "sales.errors.tag_invalid": "잘못된 태그 형식입니다.",

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

@@ -497,6 +497,13 @@
   "sales.documents.adjustments.title": "Korekty",
   "sales.documents.adjustments.untitled": "Bez tytułu",
   "sales.documents.adjustments.updated": "Korekta zaktualizowana.",
+  "sales.documents.amountsExternal": "Kwoty ze źródła",
+  "sales.documents.amountsExternalHint": "Sumy tego dokumentu pochodzą z systemu zewnętrznego i są zapisane w podanej postaci.",
+  "sales.documents.amountsExternalMethodNote": "Metoda zostanie zapisana, ale nie doliczy opłaty — sumy tego zamówienia pochodzą z systemu źródłowego.",
+  "sales.documents.amountsSwitchConfirm": "Przeliczyć kwoty tego zamówienia z pozycji? Sumy podane przez system źródłowy zostaną zastąpione i nie da się ich stąd przywrócić.",
+  "sales.documents.amountsSwitchDone": "Kwoty są teraz wyliczane z pozycji.",
+  "sales.documents.amountsSwitchFailed": "Nie udało się przełączyć na kwoty wyliczane.",
+  "sales.documents.amountsSwitchToComputed": "Przełącz na kwoty wyliczane",
   "sales.documents.create.title": "Utwórz dokument sprzedaży",
   "sales.documents.detail.addresses.add": "Dodaj adres",
   "sales.documents.detail.addresses.additional": "Dodatkowe adresy",
@@ -1240,6 +1247,11 @@
   "sales.documents.status.documentPlaceholder": "Wybierz nowy status zamówienia/oferty",
   "sales.documents.status.linePlaceholder": "Wybierz status pozycji",
   "sales.documents.status.sectionTitle": "Zmiany statusu",
+  "sales.errors.externalAdjustmentRefused": "To zamówienie ma kwoty z systemu zewnętrznego, więc nie można dodawać ani usuwać korekt. Najpierw przełącz je na kwoty wyliczane.",
+  "sales.errors.externalAmountsIncomplete": "Pozycja {{line}} ma kwoty zewnętrzne, ale brakuje: {{fields}}. Częściowa specyfikacja nie jest trybem.",
+  "sales.errors.externalModeMixed": "Zamówienie i wszystkie jego pozycje muszą mieć ten sam tryb kwot.",
+  "sales.errors.externalModeUnsupportedOnQuote": "Oferty nie mogą mieć trybu kwot; zawsze używają kwot wyliczanych.",
+  "sales.errors.externalTotalsRequired": "Zamówienie z kwotami zewnętrznymi musi podać własne sumy dokumentu: {{fields}}.",
   "sales.errors.invalid_query": "Nieprawidłowe parametry zapytania",
   "sales.errors.organization_required": "Wymagany jest kontekst organizacji",
   "sales.errors.tag_invalid": "Nieprawidłowy format tagu.",

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

@@ -1,6 +1,8 @@
 import { createLogger } from '@open-mercato/shared/lib/logger'
 import {
   type SalesAdjustmentDraft,
+  type SalesAmountsMode,
+  type SalesDocumentAmounts,
   type SalesCalculationContext,
   type CalculateDocumentOptions,
   type CalculateLineOptions,
@@ -115,7 +117,49 @@ function resolveLineDiscountTotal(
   return line.discountAmountBasis === 'line' ? amount : amount * quantity
 }
 
+/** The header fields a caller owns under `external`; the rest stay core-derived. */
+export const EXTERNAL_HEADER_FIELDS = [
+  'subtotalNetAmount',
+  'subtotalGrossAmount',
+  'discountTotalAmount',
+  'taxTotalAmount',
+  'shippingNetAmount',
+  'shippingGrossAmount',
+  'surchargeTotalAmount',
+  'grandTotalNetAmount',
+  'grandTotalGrossAmount',
+] as const
+
+export function isExternalAmountsMode(mode: SalesAmountsMode | null | undefined): boolean {
+  return mode === 'external'
+}
+
+function resolveSuppliedTotals(
+  supplied: Partial<SalesDocumentAmounts> | null | undefined
+): Pick<SalesDocumentAmounts, (typeof EXTERNAL_HEADER_FIELDS)[number]> {
+  const resolved = {} as Record<(typeof EXTERNAL_HEADER_FIELDS)[number], number>
+  for (const field of EXTERNAL_HEADER_FIELDS) {
+    resolved[field] = round(toNumber(supplied?.[field], 0))
+  }
+  return resolved
+}
+
+// The derived discount is signed and unclamped: a markup is a negative discount.
+function buildExternalLineResult(line: SalesLineSnapshot): SalesLineCalculationResult {
+  const quantity = Math.max(toNumber(line.quantity, 0), 0)
+  const netAmount = round(toNumber(line.totalNetAmount, 0))
+  return {
+    line,
+    netAmount,
+    grossAmount: round(toNumber(line.totalGrossAmount, 0)),
+    taxAmount: round(toNumber(line.taxAmount, 0)),
+    discountAmount: round(toNumber(line.unitPriceNet, 0) * quantity - netAmount),
+    adjustments: [],
+  }
+}
+
 function buildBaseLineResult(line: SalesLineSnapshot): SalesLineCalculationResult {
+  if (isExternalAmountsMode(line.amountsMode)) return buildExternalLineResult(line)
   const quantity = Math.max(toNumber(line.quantity, 0), 0)
   const taxRate = toNumber(line.taxRate, 0) / 100
   const unitNet =
@@ -195,6 +239,8 @@ function buildBaseDocumentResult(params: {
   adjustments: SalesAdjustmentDraft[]
   currencyCode: string
   existingTotals?: { paidTotalAmount?: number | null; refundedTotalAmount?: number | null }
+  totalsMode?: SalesAmountsMode | null
+  suppliedTotals?: Partial<SalesDocumentAmounts> | null
 }): SalesDocumentCalculationResult {
   const { documentKind, lines, adjustments, currencyCode } = params
   const orderedAdjustments = [...(adjustments ?? [])].sort(
@@ -313,6 +359,25 @@ function buildBaseDocumentResult(params: {
   const refundedTotalAmount = Math.max(toNumber(params.existingTotals?.refundedTotalAmount, 0), 0)
   const outstandingAmount = Math.max(grandTotalGross - paidTotalAmount + refundedTotalAmount, 0)
 
+  if (isExternalAmountsMode(params.totalsMode)) {
+    const suppliedTotals = resolveSuppliedTotals(params.suppliedTotals)
+    return {
+      kind: documentKind,
+      currencyCode,
+      lines,
+      adjustments: resolvedAdjustments,
+      metadata: {},
+      totals: {
+        ...suppliedTotals,
+        paidTotalAmount,
+        refundedTotalAmount,
+        outstandingAmount: round(
+          Math.max(suppliedTotals.grandTotalGrossAmount - paidTotalAmount + refundedTotalAmount, 0)
+        ),
+      },
+    }
+  }
+
   return {
     kind: documentKind,
     currencyCode,
@@ -389,11 +454,32 @@ class SalesCalculationRegistry {
       })
     }
 
+    // Re-applied after the registry and events, which may otherwise overwrite it.
+    if (isExternalAmountsMode(line.amountsMode)) {
+      const supplied = buildExternalLineResult(line)
+      current = {
+        ...current,
+        netAmount: supplied.netAmount,
+        grossAmount: supplied.grossAmount,
+        taxAmount: supplied.taxAmount,
+        discountAmount: supplied.discountAmount,
+      }
+    }
+
     return current
   }
 
   async calculateDocument(opts: CalculateDocumentOptions): Promise<SalesDocumentCalculationResult> {
-    const { documentKind, lines, adjustments = [], context, eventBus, existingTotals } = opts
+    const {
+      documentKind,
+      lines,
+      adjustments = [],
+      context,
+      eventBus,
+      existingTotals,
+      totalsMode,
+      suppliedTotals,
+    } = opts
     const resolvedLines: SalesLineCalculationResult[] = []
 
     for (const line of lines) {
@@ -407,6 +493,8 @@ class SalesCalculationRegistry {
       adjustments,
       currencyCode: context.currencyCode,
       existingTotals,
+      totalsMode,
+      suppliedTotals,
     })
 
     if (eventBus) {
@@ -430,6 +518,7 @@ class SalesCalculationRegistry {
         context,
         current,
         eventBus,
+        totalsMode,
       })
       if (next) current = next
     }
@@ -453,9 +542,15 @@ class SalesCalculationRegistry {
     // outstanding back to the full grand total), producing a stale paid/
     // outstanding display after a payment. Re-apply the input totals last and
     // recompute outstanding against the post-calculation grand total.
-    if (existingTotals) {
-      const paidTotalAmount = Math.max(toNumber(existingTotals.paidTotalAmount, 0), 0)
-      const refundedTotalAmount = Math.max(toNumber(existingTotals.refundedTotalAmount, 0), 0)
+    // Totals calculators rebuild the header from the lines, and core registers one
+    // itself by module side effect (lib/providers/index.ts) — so this always runs.
+    if (isExternalAmountsMode(totalsMode)) {
+      current.totals = { ...current.totals, ...resolveSuppliedTotals(suppliedTotals) }
+    }
+
+    if (existingTotals || isExternalAmountsMode(totalsMode)) {
+      const paidTotalAmount = Math.max(toNumber(existingTotals?.paidTotalAmount, 0), 0)
+      const refundedTotalAmount = Math.max(toNumber(existingTotals?.refundedTotalAmount, 0), 0)
       current.totals = {
         ...current.totals,
         paidTotalAmount,