@open-mercato/core 0.6.7 → 0.6.8-develop.6875.1.871a4afc94

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

@@ -76,6 +76,8 @@ import {
   quoteLineCreateSchema,
   quoteAdjustmentCreateSchema,
   orderCreateSchema,
+  ORDER_PAYMENT_LEDGER_WARNING_CODE,
+  resolveSuppliedOrderPaymentLedgerFields,
   orderLineCreateSchema,
   orderAdjustmentCreateSchema,
   invoiceCreateSchema,
@@ -87,6 +89,7 @@ import {
   type QuoteLineCreateInput,
   type QuoteAdjustmentCreateInput,
   type OrderCreateInput,
+  type OrderPaymentLedgerWarning,
   type OrderLineCreateInput,
   type OrderAdjustmentCreateInput,
   type InvoiceCreateInput,
@@ -143,6 +146,7 @@ import type { TranslateWithFallbackFn } from "@open-mercato/shared/lib/i18n/tran
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('sales')
+let warnedDeprecatedOrderPaymentLedgerInput = false
 
 // CRUD events configuration for workflow triggers
 const orderCrudEvents: CrudEventsConfig<SalesOrder> = {
@@ -661,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,
@@ -4182,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,
@@ -4266,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 },
@@ -4778,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 },
@@ -5505,14 +5560,22 @@ const updateOrderCommand: CommandHandler<
 
 const createOrderCommand: CommandHandler<
   OrderCreateInput,
-  { orderId: string }
+  { orderId: string; warnings?: OrderPaymentLedgerWarning[] }
 > = {
   id: "sales.orders.create",
   async execute(rawInput, ctx) {
     const generator = ctx.container.resolve(
       "salesDocumentNumberGenerator",
     ) as SalesDocumentNumberGenerator;
+    const deprecatedPaymentLedgerFields = resolveSuppliedOrderPaymentLedgerFields(rawInput)
     const initial = orderCreateSchema.parse(rawInput ?? {});
+    if (deprecatedPaymentLedgerFields.length && !warnedDeprecatedOrderPaymentLedgerInput) {
+      warnedDeprecatedOrderPaymentLedgerInput = true
+      logger.warn("sales.orders.create ignored deprecated payment ledger input", {
+        code: ORDER_PAYMENT_LEDGER_WARNING_CODE,
+        fields: deprecatedPaymentLedgerFields,
+      })
+    }
     const orderNumber =
       typeof initial.orderNumber === "string" &&
       initial.orderNumber.trim().length
@@ -5792,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 },
@@ -5871,7 +5941,19 @@ const createOrderCommand: CommandHandler<
       previousStatus: null,
     });
 
-    return { orderId: order.id };
+    return {
+      orderId: order.id,
+      ...(deprecatedPaymentLedgerFields.length
+        ? {
+            warnings: [
+              {
+                code: ORDER_PAYMENT_LEDGER_WARNING_CODE,
+                fields: deprecatedPaymentLedgerFields,
+              },
+            ],
+          }
+        : {}),
+    };
   },
   captureAfter: async (_input, result, ctx) => {
     const em = (ctx.container.resolve("em") as EntityManager).fork();
@@ -6601,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,
@@ -6610,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,
@@ -6620,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,
@@ -6633,35 +6859,67 @@ 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,
+    );
   }
 }
 
+const FULFILLED_ORDER_STATUS = "fulfilled";
+
+const isFulfilledOrder = (order: SalesOrder): boolean => {
+  const normalize = (value: string | null | undefined): string =>
+    (value ?? "").trim().toLowerCase();
+  return (
+    normalize(order.status) === FULFILLED_ORDER_STATUS ||
+    normalize(order.fulfillmentStatus) === FULFILLED_ORDER_STATUS
+  );
+};
+
+async function assertOrderAcceptsNewLine(
+  order: SalesOrder,
+  existingSnapshot: SalesLineSnapshot | null,
+): Promise<void> {
+  if (existingSnapshot) return;
+  if (!isFulfilledOrder(order)) return;
+  const { translate } = await resolveTranslations();
+  throw new CrudHttpError(409, {
+    error: translate(
+      "sales.documents.items.errorAddToFulfilled",
+      "You cannot add a new item to a fulfilled order. Change the order status first.",
+    ),
+  });
+}
+
 const orderLineUpsertCommand: CommandHandler<
   { body?: Record<string, unknown>; query?: Record<string, unknown> },
   { orderId: string; lineId: string }
@@ -6706,6 +6964,7 @@ const orderLineUpsertCommand: CommandHandler<
     const existingSnapshot = parsed.id
       ? (lineSnapshots.find((line) => line.id === parsed.id) ?? null)
       : null;
+    await assertOrderAcceptsNewLine(order, existingSnapshot);
     await assertShippedOrderLineEditable(em, order, existingSnapshot, parsed);
     const priceMode =
       parsed.priceMode === "gross"
@@ -7042,6 +7301,14 @@ const orderLineDeleteCommand: CommandHandler<
           "Document not found or inaccessible.",
         ));
     }
+    if (filtered.length === 0) {
+      throw new CrudHttpError(409, {
+        error: translate(
+          "sales.documents.items.errorDeleteLast",
+          "An order must contain at least one line item.",
+        ),
+      });
+    }
     const sourceInputs = filtered.map((line, index) => ({
       ...mapOrderLineEntityToSnapshot(line),
       statusEntryId: line.statusEntryId ?? null,

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

@@ -1,6 +1,7 @@
 "use client";
 
 import * as React from "react";
+import { extensionPoints } from "@open-mercato/core/modules/sales/extension-points";
 import { apiCall, withScopedApiRequestHeaders } from "@open-mercato/ui/backend/utils/apiCall";
 import { buildOptimisticLockHeader } from "@open-mercato/ui/backend/utils/optimisticLock";
 import { deleteCrud } from "@open-mercato/ui/backend/utils/crud";
@@ -165,7 +166,7 @@ export function SalesDocumentItemsSection({
   );
 
   const { widgets: allColumnWidgets } = useInjectionDataWidgets(
-    "data-table:sales.order.items:columns",
+    extensionPoints.hosts.orderItemColumns.spotId,
   );
   const columnWidgets = kind === "order" ? allColumnWidgets : [];
   const injectedColumns = React.useMemo<InjectionColumnDefinition[]>(() => {
@@ -238,6 +239,10 @@ export function SalesDocumentItemsSection({
                     typeof (item.catalog_snapshot as Record<string, unknown>).name === "string"
                   ? (item.catalog_snapshot as Record<string, unknown>).name as string
                   : null;
+            const description =
+              typeof item.description === "string" && item.description.trim()
+                ? item.description
+                : null;
             const quantity = normalizeNumber(item.quantity, 0);
             const uomFields = getUomFields(item);
             const quantityUnit = canonicalizeUnitCode(uomFields.quantityUnit);
@@ -302,6 +307,7 @@ export function SalesDocumentItemsSection({
             const record: SalesLineRecord = {
               id,
               name,
+              description,
               productId:
                 typeof item.product_id === "string" ? item.product_id : null,
               productVariantId:
@@ -724,6 +730,14 @@ export function SalesDocumentItemsSection({
                               {showProductSku}
                             </div>
                           ) : null}
+                          {item.description ? (
+                            <div
+                              className="text-xs text-muted-foreground line-clamp-2"
+                              title={item.description}
+                            >
+                              {item.description}
+                            </div>
+                          ) : null}
                         </div>
                       </div>
                     </td>
@@ -833,6 +847,7 @@ export function SalesDocumentItemsSection({
                           size="icon"
                           variant="ghost"
                           className="h-8 w-8"
+                          aria-label={t('ui.actions.edit', 'Edit')}
                           onClick={(event) => {
                             event.stopPropagation();
                             handleEdit(item);
@@ -840,17 +855,25 @@ export function SalesDocumentItemsSection({
                         >
                           <Pencil className="h-4 w-4" />
                         </Button>
-                        <Button
-                          size="icon"
-                          variant="ghost"
-                          className="h-8 w-8 text-destructive"
-                          onClick={(event) => {
-                            event.stopPropagation();
-                            void handleDelete(item);
-                          }}
+                        <span
+                          title={kind === 'order' && items.length === 1
+                            ? t('sales.documents.items.errorDeleteLast', 'An order must contain at least one line item.')
+                            : undefined}
                         >
-                          <Trash2 className="h-4 w-4" />
-                        </Button>
+                          <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}
+                            onClick={(event) => {
+                              event.stopPropagation();
+                              void handleDelete(item);
+                            }}
+                          >
+                            <Trash2 className="h-4 w-4" />
+                          </Button>
+                        </span>
                       </div>
                     </td>
                   </tr>

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

@@ -272,7 +272,7 @@ type SnapshotEntity = {
 type SalesLineDialogProps = {
   open: boolean;
   kind: "order" | "quote";
-  documentId: string;
+  documentId?: string;
   currencyCode: string | null | undefined;
   documentUpdatedAt?: string | null;
   organizationId: string | null;
@@ -281,6 +281,7 @@ type SalesLineDialogProps = {
   shippedQuantity?: number;
   onOpenChange: (open: boolean) => void;
   onSaved?: () => Promise<void> | void;
+  onDraftSaved?: (payload: Record<string, unknown>, lineId: string | null) => Promise<void> | void;
 };
 
 const defaultForm = (currencyCode?: string | null): LineFormState => ({
@@ -476,6 +477,7 @@ export function LineItemDialog({
   shippedQuantity = 0,
   onOpenChange,
   onSaved,
+  onDraftSaved,
 }: SalesLineDialogProps) {
   const t = useT();
   const scope = useOrganizationScopeDetail();
@@ -1273,7 +1275,7 @@ export function LineItemDialog({
       const resolvedOrg = resolvedOrganizationId;
       const resolvedTenant = resolvedTenantId;
 
-      if (!resolvedOrg || !resolvedTenant || !resolvedDocumentId) {
+      if (!onDraftSaved && (!resolvedOrg || !resolvedTenant || !resolvedDocumentId)) {
         throw createCrudFormError(
           t(
             "sales.documents.items.errorScope",
@@ -1466,9 +1468,9 @@ export function LineItemDialog({
       };
 
       const payload: Record<string, unknown> = {
-        [documentKey]: String(resolvedDocumentId),
-        organizationId: String(resolvedOrg),
-        tenantId: String(resolvedTenant),
+        ...(resolvedDocumentId ? { [documentKey]: resolvedDocumentId } : {}),
+        ...(resolvedOrg ? { organizationId: resolvedOrg } : {}),
+        ...(resolvedTenant ? { tenantId: resolvedTenant } : {}),
         productId: isCustomLine
           ? undefined
           : values.productId
@@ -1508,6 +1510,11 @@ export function LineItemDialog({
       if (resolvedName) payload.name = resolvedName;
 
       try {
+        if (onDraftSaved) {
+          await onDraftSaved(payload, editingId);
+          closeDialog();
+          return;
+        }
         const action = editingId ? updateCrud : createCrud;
         const result = await withScopedApiRequestHeaders(
           buildOptimisticLockHeader(documentUpdatedAt),
@@ -1545,6 +1552,7 @@ export function LineItemDialog({
       documentKey,
       documentUpdatedAt,
       editingId,
+      onDraftSaved,
       priceOptions,
       productOption,
       resourcePath,