@open-mercato/core 0.6.2-develop.3467.1.2a1818709d → 0.6.2

package/src/modules/messages/components/inboxFilters.ts

@@ -0,0 +1,162 @@
+import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
+
+type Translator = (key: string, fallback?: string) => string
+
+export type SenderOption = {
+  value: string
+  label: string
+  description?: string | null
+}
+
+export type MessagesInboxFilterContext = {
+  t: Translator
+  typeOptions: { value: string; label: string }[]
+  senderOptions: SenderOption[]
+  loadSenderOptions: (query?: string) => Promise<SenderOption[]>
+}
+
+export function buildMessagesInboxFilters({
+  t,
+  typeOptions,
+  senderOptions,
+  loadSenderOptions,
+}: MessagesInboxFilterContext): FilterDef[] {
+  const senderLabel = (val: string): string => {
+    const match = senderOptions.find((opt) => opt.value === val)
+    return match?.label ?? val
+  }
+
+  return [
+    {
+      id: 'status',
+      label: t('messages.filters.status', 'Status'),
+      type: 'select',
+      options: [
+        { value: '', label: t('messages.filters.all', 'All') },
+        { value: 'unread', label: t('messages.status.unread', 'Unread') },
+        { value: 'read', label: t('messages.status.read', 'Read') },
+        { value: 'archived', label: t('messages.status.archived', 'Archived') },
+      ],
+    },
+    {
+      id: 'type',
+      label: t('messages.filters.type', 'Type'),
+      type: 'select',
+      options: [{ value: '', label: t('messages.filters.all', 'All') }, ...typeOptions],
+    },
+    {
+      id: 'hasObjects',
+      label: t('messages.filters.hasObjects', 'Has objects'),
+      type: 'select',
+      options: [
+        { value: '', label: t('messages.filters.all', 'All') },
+        { value: 'true', label: t('common.yes', 'Yes') },
+        { value: 'false', label: t('common.no', 'No') },
+      ],
+    },
+    {
+      id: 'hasAttachments',
+      label: t('messages.filters.hasAttachments', 'Has attachments'),
+      type: 'select',
+      options: [
+        { value: '', label: t('messages.filters.all', 'All') },
+        { value: 'true', label: t('common.yes', 'Yes') },
+        { value: 'false', label: t('common.no', 'No') },
+      ],
+    },
+    {
+      id: 'hasActions',
+      label: t('messages.filters.hasActions', 'Has actions'),
+      type: 'select',
+      options: [
+        { value: '', label: t('messages.filters.all', 'All') },
+        { value: 'true', label: t('common.yes', 'Yes') },
+        { value: 'false', label: t('common.no', 'No') },
+      ],
+    },
+    {
+      id: 'senderId',
+      label: t('messages.filters.sender', 'Sender'),
+      type: 'combobox',
+      placeholder: t('messages.filters.senderEmpty', 'Type to search users'),
+      options: senderOptions,
+      loadOptions: loadSenderOptions,
+      formatValue: senderLabel,
+      formatDescription: (val: string) =>
+        senderOptions.find((opt) => opt.value === val)?.description ?? null,
+    },
+    {
+      id: 'since',
+      label: t('messages.filters.since', 'Sent after'),
+      type: 'text',
+      placeholder: t('messages.filters.sincePlaceholder', 'YYYY-MM-DD'),
+    },
+  ]
+}
+
+const DATE_ONLY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+export function normalizeMessagesSinceValue(input: string): string | null {
+  const trimmed = input.trim()
+  if (!trimmed) return null
+  if (DATE_ONLY_PATTERN.test(trimmed)) {
+    const parsed = new Date(`${trimmed}T00:00:00.000Z`)
+    if (Number.isNaN(parsed.getTime())) return null
+    if (parsed.toISOString().slice(0, 10) !== trimmed) return null
+    return parsed.toISOString()
+  }
+  const parsed = new Date(trimmed)
+  if (Number.isNaN(parsed.getTime())) return null
+  return parsed.toISOString()
+}
+
+export type BuildMessagesListParamsOptions = {
+  folder: string
+  page: number
+  pageSize: number
+  search: string
+  filterValues: FilterValues
+}
+
+export function buildMessagesListParams({
+  folder,
+  page,
+  pageSize,
+  search,
+  filterValues,
+}: BuildMessagesListParamsOptions): URLSearchParams {
+  const params = new URLSearchParams()
+  params.set('folder', folder)
+  params.set('page', String(page))
+  params.set('pageSize', String(pageSize))
+
+  if (search.trim()) {
+    params.set('search', search.trim())
+  }
+
+  const stringValue = (id: string): string => {
+    const raw = filterValues[id]
+    return typeof raw === 'string' ? raw.trim() : ''
+  }
+
+  const status = stringValue('status')
+  const type = stringValue('type')
+  const hasObjects = stringValue('hasObjects')
+  const hasAttachments = stringValue('hasAttachments')
+  const hasActions = stringValue('hasActions')
+  const senderId = stringValue('senderId')
+  const sinceRaw = stringValue('since')
+
+  if (status) params.set('status', status)
+  if (type) params.set('type', type)
+  if (hasObjects) params.set('hasObjects', hasObjects)
+  if (hasAttachments) params.set('hasAttachments', hasAttachments)
+  if (hasActions) params.set('hasActions', hasActions)
+  if (senderId) params.set('senderId', senderId)
+  if (sinceRaw) {
+    const normalized = normalizeMessagesSinceValue(sinceRaw)
+    if (normalized) params.set('since', normalized)
+  }
+
+  return params
+}

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

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import { parseBooleanFlag } from '@open-mercato/shared/lib/boolean'
 
 function collectDuplicateRecipientIds(
   recipients: Array<{ userId: string }>,
@@ -178,14 +179,15 @@ export const updateDraftSchema = z.object({
   externalEmail: z.string().email().optional(),
   externalName: z.string().min(1).max(255).optional(),
   recipients: z.array(messageRecipientSchema).optional(),
-  subject: z.string().min(1).max(500).optional(),
-  body: z.string().min(1).max(50000).optional(),
+  subject: z.string().max(500).optional(),
+  body: z.string().max(50000).optional(),
   bodyFormat: z.enum(['text', 'markdown']).optional(),
   priority: z.enum(['low', 'normal', 'high', 'urgent']).optional(),
   objects: z.array(messageObjectSchema).optional(),
   attachmentIds: z.array(z.string().uuid()).optional(),
   actionData: messageActionDataSchema.optional(),
   sendViaEmail: z.boolean().optional(),
+  isDraft: z.literal(false).optional(),
 }).superRefine((value, ctx) => {
   if (value.recipients) {
     const duplicateRecipientIds = collectDuplicateRecipientIds(value.recipients)
@@ -209,9 +211,9 @@ export const listMessagesSchema = z.object({
   sourceEntityType: z.string().optional(),
   sourceEntityId: z.string().uuid().optional(),
   externalEmail: z.string().email().optional(),
-  hasObjects: z.coerce.boolean().optional(),
-  hasAttachments: z.coerce.boolean().optional(),
-  hasActions: z.coerce.boolean().optional(),
+  hasObjects: z.string().transform(parseBooleanFlag).optional(),
+  hasAttachments: z.string().transform(parseBooleanFlag).optional(),
+  hasActions: z.string().transform(parseBooleanFlag).optional(),
   senderId: z.string().uuid().optional(),
   search: z.string().max(200).optional(),
   since: z.string().datetime().optional(),

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

@@ -131,12 +131,13 @@
   "messages.externalName": "Externer Name",
   "messages.fields.type": "Nachrichtentyp",
   "messages.filters.all": "Alle",
-  "messages.filters.hasActions": "Aktionen",
-  "messages.filters.hasAttachments": "Anhänge",
-  "messages.filters.hasObjects": "Objekte",
+  "messages.filters.hasActions": "Hat Aktionen",
+  "messages.filters.hasAttachments": "Hat Anhänge",
+  "messages.filters.hasObjects": "Hat Objekte",
   "messages.filters.sender": "Absender",
+  "messages.filters.senderEmpty": "Tippe, um Benutzer zu suchen",
   "messages.filters.since": "Gesendet nach",
-  "messages.filters.sincePlaceholder": "YYYY-MM-DDTHH:mm:ssZ",
+  "messages.filters.sincePlaceholder": "YYYY-MM-DD",
   "messages.filters.status": "Status",
   "messages.filters.type": "Typ",
   "messages.flash.actionSuccess": "Aktion abgeschlossen.",

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

@@ -131,12 +131,13 @@
   "messages.externalName": "External name",
   "messages.fields.type": "Message type",
   "messages.filters.all": "All",
-  "messages.filters.hasActions": "Actions",
-  "messages.filters.hasAttachments": "Attachments",
-  "messages.filters.hasObjects": "Objects",
+  "messages.filters.hasActions": "Has actions",
+  "messages.filters.hasAttachments": "Has attachments",
+  "messages.filters.hasObjects": "Has objects",
   "messages.filters.sender": "Sender",
+  "messages.filters.senderEmpty": "Type to search users",
   "messages.filters.since": "Sent after",
-  "messages.filters.sincePlaceholder": "YYYY-MM-DDTHH:mm:ssZ",
+  "messages.filters.sincePlaceholder": "YYYY-MM-DD",
   "messages.filters.status": "Status",
   "messages.filters.type": "Type",
   "messages.flash.actionSuccess": "Action completed.",

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

@@ -131,12 +131,13 @@
   "messages.externalName": "Nombre externo",
   "messages.fields.type": "Tipo de mensaje",
   "messages.filters.all": "Todos",
-  "messages.filters.hasActions": "Acciones",
-  "messages.filters.hasAttachments": "Adjuntos",
-  "messages.filters.hasObjects": "Objetos",
+  "messages.filters.hasActions": "Tiene acciones",
+  "messages.filters.hasAttachments": "Tiene adjuntos",
+  "messages.filters.hasObjects": "Tiene objetos",
   "messages.filters.sender": "Remitente",
+  "messages.filters.senderEmpty": "Escribe para buscar usuarios",
   "messages.filters.since": "Enviado después de",
-  "messages.filters.sincePlaceholder": "YYYY-MM-DDTHH:mm:ssZ",
+  "messages.filters.sincePlaceholder": "YYYY-MM-DD",
   "messages.filters.status": "Estado",
   "messages.filters.type": "Tipo",
   "messages.flash.actionSuccess": "Acción completada.",

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

@@ -131,12 +131,13 @@
   "messages.externalName": "Nazwa zewnętrzna",
   "messages.fields.type": "Typ wiadomości",
   "messages.filters.all": "Wszystkie",
-  "messages.filters.hasActions": "Akcje",
-  "messages.filters.hasAttachments": "Załączniki",
-  "messages.filters.hasObjects": "Obiekty",
+  "messages.filters.hasActions": "Ma akcje",
+  "messages.filters.hasAttachments": "Ma załączniki",
+  "messages.filters.hasObjects": "Ma obiekty",
   "messages.filters.sender": "Nadawca",
+  "messages.filters.senderEmpty": "Wpisz, aby wyszukać użytkowników",
   "messages.filters.since": "Wysłane po",
-  "messages.filters.sincePlaceholder": "YYYY-MM-DDTHH:mm:ssZ",
+  "messages.filters.sincePlaceholder": "RRRR-MM-DD",
   "messages.filters.status": "Status",
   "messages.filters.type": "Typ",
   "messages.flash.actionSuccess": "Akcja wykonana.",

package/src/modules/progress/api/jobs/route.ts

@@ -138,27 +138,37 @@ export async function GET(req: Request) {
 }
 
 export async function POST(req: Request) {
-  const auth = await getAuthFromRequest(req)
-  if (!auth || !auth.tenantId) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-  }
-
-  const body = await req.json()
-  const parsed = createProgressJobSchema.safeParse(body)
-  if (!parsed.success) {
-    return NextResponse.json({ error: 'Invalid input', details: parsed.error.flatten() }, { status: 400 })
+  try {
+    const auth = await getAuthFromRequest(req)
+    if (!auth || !auth.tenantId) {
+      return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
+    }
+
+    const body = await req.json()
+    const parsed = createProgressJobSchema.safeParse(body)
+    if (!parsed.success) {
+      return NextResponse.json({ error: 'Invalid input', details: parsed.error.flatten() }, { status: 400 })
+    }
+
+    const container = await createRequestContainer()
+    const progressService = container.resolve('progressService') as import('../../lib/progressService').ProgressService
+
+    const job = await progressService.createJob(parsed.data, {
+      tenantId: auth.tenantId,
+      organizationId: auth.orgId,
+      userId: auth.sub,
+    })
+
+    return NextResponse.json({ id: job.id }, { status: 201 })
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error)
+    const stack = error instanceof Error ? error.stack : undefined
+    console.error('[progress.jobs.create] unhandled error', { message, stack })
+    return NextResponse.json(
+      { error: 'Failed to create progress job.', message, stack },
+      { status: 500 },
+    )
   }
-
-  const container = await createRequestContainer()
-  const progressService = container.resolve('progressService') as import('../../lib/progressService').ProgressService
-
-  const job = await progressService.createJob(parsed.data, {
-    tenantId: auth.tenantId,
-    organizationId: auth.orgId,
-    userId: auth.sub,
-  })
-
-  return NextResponse.json({ id: job.id }, { status: 201 })
 }
 
 const jobListItemSchema = z.object({

package/src/modules/query_index/di.ts

@@ -66,8 +66,8 @@ export function register(container: AppContainer) {
     const makeUpsertHandler = (entityType: string) => async (payload: any, ctx: any) => {
       try {
         const em = ctx.resolve('em')
-        let orgId = payload?.organizationId || payload?.orgId || null
-        let tenantId = payload?.tenantId || null
+        let orgId = payload?.organizationId || payload?.orgId || ctx?.organizationId || null
+        let tenantId = payload?.tenantId || ctx?.tenantId || null
         const id = String(payload?.id || payload?.recordId || '')
         if (!id) return
         if (!orgId || !tenantId) {
@@ -119,24 +119,26 @@ export function register(container: AppContainer) {
     const makeDeleteHandler = (entityType: string) => async (payload: any, ctx: any) => {
       try {
         const em = ctx.resolve('em')
-        let orgId = payload?.organizationId || payload?.orgId || null
+        let orgId = payload?.organizationId || payload?.orgId || ctx?.organizationId || null
+        let tenantId = payload?.tenantId || ctx?.tenantId || null
         const id = String(payload?.id || payload?.recordId || '')
         if (!id) return
-        if (!orgId) {
+        if (!orgId || !tenantId) {
           try {
             const db = (em as any).getKysely()
             const table = resolveEntityTableName(em, entityType)
             const row = await db
               .selectFrom(table as any)
-              .select(['organization_id' as any])
+              .select(['organization_id' as any, 'tenant_id' as any])
               .where('id' as any, '=', id)
-              .executeTakeFirst() as { organization_id: string | null } | undefined
+              .executeTakeFirst() as { organization_id: string | null; tenant_id: string | null } | undefined
             orgId = row?.organization_id ?? orgId
+            tenantId = row?.tenant_id ?? tenantId
           } catch {}
         }
         try {
           const bus = ctx.resolve('eventBus') as any
-          await bus.emitEvent('query_index.delete_one', { entityType, recordId: id, organizationId: orgId })
+          await bus.emitEvent('query_index.delete_one', { entityType, recordId: id, organizationId: orgId, tenantId })
         } catch {}
       } catch {}
     }

package/src/modules/query_index/lib/indexer.ts

@@ -158,7 +158,7 @@ function scopeEntityIndexes<QB extends { where: (...args: any[]) => QB }>(
 
 export async function upsertIndexRow(
   em: EntityManager,
-  args: { entityType: string; recordId: string; organizationId?: string | null; tenantId?: string | null }
+  args: { entityType: string; recordId: string; organizationId?: string | null; tenantId?: string | null; searchTokenDoc?: Record<string, unknown> | null }
 ): Promise<UpsertIndexResult> {
   const db = (em as any).getKysely()
 
@@ -234,21 +234,23 @@ export async function upsertIndexRow(
   const created = !existed
   const revived = existed && wasDeleted
   try {
-    const encryption = resolveTenantEncryptionService(em as any)
-    const dekKeyCache = new Map<string | null, string | null>()
-    const tokenDoc = await decryptIndexDocForSearch(
-      args.entityType,
-      doc,
-      { tenantId: args.tenantId ?? null, organizationId: args.organizationId ?? null },
-      encryption,
-      dekKeyCache,
-    )
+    const tokenDoc = args.searchTokenDoc ?? (() => {
+      const encryption = resolveTenantEncryptionService(em as any)
+      const dekKeyCache = new Map<string | null, string | null>()
+      return decryptIndexDocForSearch(
+        args.entityType,
+        doc,
+        { tenantId: args.tenantId ?? null, organizationId: args.organizationId ?? null },
+        encryption,
+        dekKeyCache,
+      )
+    })()
     await replaceSearchTokensForRecord(db, {
       entityType: args.entityType,
       recordId: args.recordId,
       organizationId: args.organizationId ?? null,
       tenantId: args.tenantId ?? null,
-      doc: tokenDoc,
+      doc: await tokenDoc,
     })
   } catch {}
   return { doc, existed, wasDeleted, created, revived }

package/src/modules/query_index/subscribers/upsert_one.ts

@@ -28,7 +28,15 @@ export default async function handle(payload: any, ctx: { resolve: <T=any>(name:
     organizationId = resolvedScope.organizationId
     tenantId = resolvedScope.tenantId
 
-    const result = await upsertIndexRow(em, { entityType, recordId, organizationId, tenantId })
+    const result = await upsertIndexRow(em, {
+      entityType,
+      recordId,
+      organizationId,
+      tenantId,
+      searchTokenDoc: typeof payload?.searchTokenDoc === 'object' && payload.searchTokenDoc && !Array.isArray(payload.searchTokenDoc)
+        ? payload.searchTokenDoc
+        : null,
+    })
     if (!suppressCoverage) {
       const doc = result.doc
       const isActive = !!doc && (doc.deleted_at == null || doc.deleted_at === null)

package/src/modules/sales/api/order-adjustments/route.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/core'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
@@ -85,7 +86,7 @@ const crud = makeCrudRoute({
       const filters: Record<string, unknown> = {}
       if (query.orderId) filters.order_id = { $eq: query.orderId }
       try {
-        const em = ctx.container.resolve('em')
+        const em = ctx.container.resolve<EntityManager>('em')
         const cfFilters = await buildCustomFieldFiltersFromQuery({
           entityId: E.sales.sales_order_adjustment,
           query,

package/src/modules/sales/api/quote-adjustments/route.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod'
+import type { EntityManager } from '@mikro-orm/core'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
@@ -82,7 +83,7 @@ const crud = makeCrudRoute({
       const filters: Record<string, unknown> = {}
       if (query.quoteId) filters.quote_id = { $eq: query.quoteId }
       try {
-        const em = ctx.container.resolve('em')
+        const em = ctx.container.resolve<EntityManager>('em')
         const cfFilters = await buildCustomFieldFiltersFromQuery({
           entityId: E.sales.sales_quote_adjustment,
           query,

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

@@ -67,6 +67,9 @@ import {
 } from "../../customers/data/entities";
 import {
   enforceAdjustmentSign,
+  validateReturnAdjustmentWithinRemaining,
+  RETURN_ADJUSTMENT_EXCEEDS_REMAINING_GROSS_MESSAGE,
+  RETURN_ADJUSTMENT_EXCEEDS_REMAINING_NET_MESSAGE,
   quoteCreateSchema,
   quoteLineCreateSchema,
   quoteAdjustmentCreateSchema,
@@ -7384,6 +7387,63 @@ const orderAdjustmentUpsertCommand: CommandHandler<
       shippingMethodCode: order.shippingMethodCode ?? null,
       paymentMethodCode: order.paymentMethodCode ?? null,
     });
+    const effectiveAdjustment = nextAdjustments.find(
+      (adj) => adj.id === adjustmentId,
+    );
+    if (effectiveAdjustment?.kind === "return") {
+      const baselineAdjustments = nextAdjustments.filter(
+        (adj) => adj.id !== adjustmentId,
+      );
+      const baselineCalculation =
+        await salesCalculationService.calculateDocumentTotals({
+          documentKind: "order",
+          lines: calcLines,
+          adjustments: baselineAdjustments,
+          context: calculationContext,
+          existingTotals: resolveExistingPaymentTotals(order),
+        });
+      const issues = validateReturnAdjustmentWithinRemaining({
+        kind: "return",
+        amountNet:
+          effectiveAdjustment.amountNet ?? effectiveAdjustment.amountGross ?? 0,
+        amountGross:
+          effectiveAdjustment.amountGross ?? effectiveAdjustment.amountNet ?? 0,
+        remainingNet: Number(
+          baselineCalculation.totals?.grandTotalNetAmount ?? 0,
+        ),
+        remainingGross: Number(
+          baselineCalculation.totals?.grandTotalGrossAmount ?? 0,
+        ),
+      });
+      if (issues.length > 0) {
+        const { translate } = await resolveTranslations();
+        const grossIssue = issues.find((issue) => issue.path === "amountGross");
+        const netIssue = issues.find((issue) => issue.path === "amountNet");
+        const fieldErrors: Record<string, string> = {};
+        if (grossIssue) {
+          fieldErrors.amountGross = translate(
+            "sales.adjustments.error.returnExceedsRemainingGrandTotalGross",
+            RETURN_ADJUSTMENT_EXCEEDS_REMAINING_GROSS_MESSAGE,
+          );
+        }
+        if (netIssue) {
+          fieldErrors.amountNet = translate(
+            "sales.adjustments.error.returnExceedsRemainingGrandTotalNet",
+            RETURN_ADJUSTMENT_EXCEEDS_REMAINING_NET_MESSAGE,
+          );
+        }
+        throw new CrudHttpError(400, {
+          error:
+            fieldErrors.amountGross ??
+            fieldErrors.amountNet ??
+            translate(
+              "sales.adjustments.error.returnExceedsRemainingGrandTotalGross",
+              RETURN_ADJUSTMENT_EXCEEDS_REMAINING_GROSS_MESSAGE,
+            ),
+          fieldErrors,
+        });
+      }
+    }
     const calculation = await salesCalculationService.calculateDocumentTotals({
       documentKind: "order",
       lines: calcLines,
@@ -7766,6 +7826,62 @@ const quoteAdjustmentUpsertCommand: CommandHandler<
       shippingMethodCode: quote.shippingMethodCode ?? null,
       paymentMethodCode: quote.paymentMethodCode ?? null,
     });
+    const effectiveAdjustment = nextAdjustments.find(
+      (adj) => adj.id === adjustmentId,
+    );
+    if (effectiveAdjustment?.kind === "return") {
+      const baselineAdjustments = nextAdjustments.filter(
+        (adj) => adj.id !== adjustmentId,
+      );
+      const baselineCalculation =
+        await salesCalculationService.calculateDocumentTotals({
+          documentKind: "quote",
+          lines: calcLines,
+          adjustments: baselineAdjustments,
+          context: calculationContext,
+        });
+      const issues = validateReturnAdjustmentWithinRemaining({
+        kind: "return",
+        amountNet:
+          effectiveAdjustment.amountNet ?? effectiveAdjustment.amountGross ?? 0,
+        amountGross:
+          effectiveAdjustment.amountGross ?? effectiveAdjustment.amountNet ?? 0,
+        remainingNet: Number(
+          baselineCalculation.totals?.grandTotalNetAmount ?? 0,
+        ),
+        remainingGross: Number(
+          baselineCalculation.totals?.grandTotalGrossAmount ?? 0,
+        ),
+      });
+      if (issues.length > 0) {
+        const { translate } = await resolveTranslations();
+        const grossIssue = issues.find((issue) => issue.path === "amountGross");
+        const netIssue = issues.find((issue) => issue.path === "amountNet");
+        const fieldErrors: Record<string, string> = {};
+        if (grossIssue) {
+          fieldErrors.amountGross = translate(
+            "sales.adjustments.error.returnExceedsRemainingGrandTotalGross",
+            RETURN_ADJUSTMENT_EXCEEDS_REMAINING_GROSS_MESSAGE,
+          );
+        }
+        if (netIssue) {
+          fieldErrors.amountNet = translate(
+            "sales.adjustments.error.returnExceedsRemainingGrandTotalNet",
+            RETURN_ADJUSTMENT_EXCEEDS_REMAINING_NET_MESSAGE,
+          );
+        }
+        throw new CrudHttpError(400, {
+          error:
+            fieldErrors.amountGross ??
+            fieldErrors.amountNet ??
+            translate(
+              "sales.adjustments.error.returnExceedsRemainingGrandTotalGross",
+              RETURN_ADJUSTMENT_EXCEEDS_REMAINING_GROSS_MESSAGE,
+            ),
+          fieldErrors,
+        });
+      }
+    }
     const calculation = await salesCalculationService.calculateDocumentTotals({
       documentKind: "quote",
       lines: calcLines,

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

@@ -523,6 +523,44 @@ export const enforceAdjustmentSign = (
  */
 export const enforceReturnAdjustmentSign = enforceAdjustmentSign
 
+export const RETURN_ADJUSTMENT_EXCEEDS_REMAINING_NET_MESSAGE =
+  'Return adjustment amountNet exceeds the remaining grand total. Reduce the amount or remove existing returns first.'
+export const RETURN_ADJUSTMENT_EXCEEDS_REMAINING_GROSS_MESSAGE =
+  'Return adjustment amountGross exceeds the remaining grand total. Reduce the amount or remove existing returns first.'
+
+export type ReturnAdjustmentRemainingCheck = {
+  kind?: string | null
+  amountNet?: number | null
+  amountGross?: number | null
+  remainingNet: number
+  remainingGross: number
+}
+
+export type ReturnAdjustmentRemainingIssue = {
+  path: 'amountNet' | 'amountGross'
+  message: string
+}
+
+// Inclusive: abs(amount) === remaining is allowed. Tiny epsilon absorbs
+// floating-point rounding from upstream tax/rate adjustments.
+const RETURN_REMAINING_EPSILON = 0.005
+
+export const validateReturnAdjustmentWithinRemaining = (
+  value: ReturnAdjustmentRemainingCheck
+): ReturnAdjustmentRemainingIssue[] => {
+  if (value.kind !== 'return') return []
+  const absNet = typeof value.amountNet === 'number' ? Math.abs(value.amountNet) : 0
+  const absGross = typeof value.amountGross === 'number' ? Math.abs(value.amountGross) : 0
+  const issues: ReturnAdjustmentRemainingIssue[] = []
+  if (absGross > value.remainingGross + RETURN_REMAINING_EPSILON) {
+    issues.push({ path: 'amountGross', message: RETURN_ADJUSTMENT_EXCEEDS_REMAINING_GROSS_MESSAGE })
+  }
+  if (absNet > value.remainingNet + RETURN_REMAINING_EPSILON) {
+    issues.push({ path: 'amountNet', message: RETURN_ADJUSTMENT_EXCEEDS_REMAINING_NET_MESSAGE })
+  }
+  return issues
+}
+
 export const orderAdjustmentCreateSchema = scoped.extend({
   orderId: uuid(),
   orderLineId: uuid().optional(),

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

@@ -4,6 +4,8 @@
   "audit_logs.resource_kind.sales.payment": "Zahlung",
   "audit_logs.resource_kind.sales.shipment": "Versand",
   "customers~sales.nav.group": "Vertrieb",
+  "sales.adjustments.error.returnExceedsRemainingGrandTotalGross": "Der Bruttobetrag der Rücksendeanpassung überschreitet den verbleibenden Gesamtbetrag. Bitte verringern Sie den Betrag oder entfernen Sie bestehende Rücksendungen.",
+  "sales.adjustments.error.returnExceedsRemainingGrandTotalNet": "Der Nettobetrag der Rücksendeanpassung überschreitet den verbleibenden Gesamtbetrag. Bitte verringern Sie den Betrag oder entfernen Sie bestehende Rücksendungen.",
   "sales.audit.channels.create": "Vertriebskanal erstellen",
   "sales.audit.channels.delete": "Vertriebskanal löschen",
   "sales.audit.channels.update": "Vertriebskanal aktualisieren",