@open-mercato/core 0.10.1-develop.7723.1.3b2ea82ea7 → 0.10.1-develop.7726.1.a447cc5525

package/src/modules/planner/lib/availabilityTimezone.ts

@@ -0,0 +1,242 @@
+import { createLogger } from '@open-mercato/shared/lib/logger'
+
+const logger = createLogger('planner').child({ component: 'availability' })
+
+const FALLBACK_TIME_ZONE = 'UTC'
+const DATE_KEY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+/**
+ * Availability rows store `timezone` as free-form `text`, so a malformed value
+ * must not turn a read or a write into a 500. Unknown zones degrade to UTC,
+ * which is already how the expander interprets every stored instant.
+ */
+export function resolveTimeZone(value: string | null | undefined): string {
+  if (!isResolvableTimeZone(value)) return FALLBACK_TIME_ZONE
+  return value.trim()
+}
+
+export function isResolvableTimeZone(value: string | null | undefined): value is string {
+  if (typeof value !== 'string' || !value.trim().length) return false
+  try {
+    new Intl.DateTimeFormat('en-US', { timeZone: value.trim() })
+    return true
+  } catch {
+    return false
+  }
+}
+
+/**
+ * The replace endpoints anchor `DTSTART` in the declared zone, so an
+ * unresolvable value is persisted as a UTC-anchored instant under a label
+ * nothing can resolve. Rejecting it with a 400 would narrow the replace
+ * schemas (a `data/validators.ts` contract surface), so for now the write is
+ * accepted and flagged; the 400 is announced in UPGRADE_NOTES.md.
+ */
+export function warnOnUnresolvableTimeZone(value: string, commandId: string): void {
+  if (isResolvableTimeZone(value)) return
+  logger.warn('[deprecated] Unresolvable availability timezone anchored to UTC; this will be rejected with 400 in a future minor release', {
+    commandId,
+    timezone: value,
+    fallback: FALLBACK_TIME_ZONE,
+  })
+}
+
+function parseTimeOfDay(value: string): { hours: number; minutes: number } | null {
+  const [hours, minutes] = String(value).split(':').map((part) => Number(part))
+  if (!Number.isFinite(hours) || !Number.isFinite(minutes)) return null
+  if (hours < 0 || hours > 23 || minutes < 0 || minutes > 59) return null
+  return { hours, minutes }
+}
+
+type WallClock = { year: number; month: number; day: number; hours: number; minutes: number; seconds: number }
+
+const MINUTE_MS = 60 * 1000
+const DAY_MS = 24 * 60 * MINUTE_MS
+const formatterCache = new Map<string, Intl.DateTimeFormat>()
+
+function zonedFormatter(timeZone: string): Intl.DateTimeFormat {
+  let formatter = formatterCache.get(timeZone)
+  if (!formatter) {
+    formatter = new Intl.DateTimeFormat('en-US', {
+      timeZone,
+      hourCycle: 'h23',
+      year: 'numeric',
+      month: '2-digit',
+      day: '2-digit',
+      hour: '2-digit',
+      minute: '2-digit',
+      second: '2-digit',
+    })
+    formatterCache.set(timeZone, formatter)
+  }
+  return formatter
+}
+
+/**
+ * Wall clock of an instant in `timeZone`, read through `Intl` only. `date-fns-tz`
+ * seeds its offset search with host-local getters, so around DST transitions
+ * the same input resolved differently depending on the serving machine's `TZ`.
+ */
+function zonedWallClock(epochMs: number, timeZone: string): WallClock {
+  const values: Record<string, number> = {}
+  for (const part of zonedFormatter(timeZone).formatToParts(new Date(epochMs))) {
+    if (part.type !== 'literal') values[part.type] = Number(part.value)
+  }
+  return {
+    year: values.year,
+    month: values.month,
+    day: values.day,
+    hours: values.hour,
+    minutes: values.minute,
+    seconds: values.second,
+  }
+}
+
+function wallClockAsUtc(clock: WallClock): number {
+  return Date.UTC(clock.year, clock.month - 1, clock.day, clock.hours, clock.minutes, clock.seconds)
+}
+
+function offsetAt(epochMs: number, timeZone: string): number {
+  const flooredToMinute = Math.floor(epochMs / MINUTE_MS) * MINUTE_MS
+  return wallClockAsUtc(zonedWallClock(flooredToMinute, timeZone)) - flooredToMinute
+}
+
+function parseDateKey(dateKey: string): { year: number; month: number; day: number } | null {
+  if (!DATE_KEY_PATTERN.test(String(dateKey))) return null
+  const [year, month, day] = dateKey.split('-').map((part) => Number(part))
+  const probe = new Date(Date.UTC(year, month - 1, day))
+  if (probe.getUTCMonth() !== month - 1 || probe.getUTCDate() !== day) return null
+  return { year, month, day }
+}
+
+function formatUtcDateKey(epochMs: number): string {
+  return new Date(epochMs).toISOString().slice(0, 10)
+}
+
+/**
+ * `2026-06-15` + `09:00` + `Europe/Warsaw` → the absolute instant that wall
+ * time denotes. Replaces `new Date(y, m, d, h, min)`, whose result depended on
+ * the host process's `TZ` rather than on the zone the caller declared (#5862).
+ *
+ * DST transitions follow the `compatible` disambiguation of RFC 5545 §3.3.5 and
+ * Temporal: a repeated wall time resolves to its EARLIER occurrence, and a
+ * skipped one moves forward by the length of the gap (`Africa/Cairo` has no
+ * 2026-04-24 00:00, so it becomes 01:00 — the first instant of that date).
+ */
+export function zonedWallTimeToInstant(dateKey: string, time: string, timeZone: string): Date | null {
+  const date = parseDateKey(dateKey)
+  const parsed = parseTimeOfDay(time)
+  if (!date || !parsed) return null
+  const wall = new Date(Date.UTC(date.year, date.month - 1, date.day, parsed.hours, parsed.minutes))
+  return zonedWallDateToInstant(wall, timeZone)
+}
+
+/** Resolve a UTC-encoded wall clock with compatible DST disambiguation. */
+export function zonedWallDateToInstant(wall: Date, timeZone: string): Date {
+  const zone = resolveTimeZone(timeZone)
+  const wallAsUtc = wall.getTime()
+  const offsetBefore = offsetAt(wallAsUtc - DAY_MS, zone)
+  const offsetAfter = offsetAt(wallAsUtc + DAY_MS, zone)
+  if (offsetBefore === offsetAfter) return new Date(wallAsUtc - offsetBefore)
+  const candidates = [wallAsUtc - offsetBefore, wallAsUtc - offsetAfter].sort((left, right) => left - right)
+  const matching = candidates.find((candidate) => candidate + offsetAt(candidate, zone) === wallAsUtc)
+  return new Date(matching ?? wallAsUtc - offsetBefore)
+}
+
+/**
+ * The span a full-day block covers: from the first instant of `dateKey` to the
+ * first instant of the following date, both in `timeZone`. That is 23 or 25
+ * hours on DST days, so the block neither bleeds into nor falls short of its
+ * neighbours.
+ */
+export function zonedDayBounds(dateKey: string, timeZone: string): { start: Date; end: Date } | null {
+  const date = parseDateKey(dateKey)
+  if (!date) return null
+  const nextDateKey = formatUtcDateKey(Date.UTC(date.year, date.month - 1, date.day) + DAY_MS)
+  const start = zonedWallTimeToInstant(dateKey, '00:00', timeZone)
+  const end = zonedWallTimeToInstant(nextDateKey, '00:00', timeZone)
+  if (!start || !end || end <= start) return null
+  return { start, end }
+}
+
+/**
+ * The calendar date an instant falls on, as seen from `timeZone`.
+ *
+ * Which day an existing rule belongs to has to be read in that rule's own zone,
+ * the same zone its `DTSTART` was anchored in. Derived from the host clock
+ * instead, replace-by-date selected a different set of rows — and the 403 gate
+ * in `api/availability-date-specific.ts` admitted or refused the same request —
+ * depending on which machine served it.
+ */
+export function zonedDateKey(instant: Date, timeZone: string): string {
+  const clock = zonedWallClock(instant.getTime(), resolveTimeZone(timeZone))
+  return formatUtcDateKey(Date.UTC(clock.year, clock.month - 1, clock.day))
+}
+
+/** `Date.getDay()` index (0 = Sunday) of an instant, as seen from `timeZone`. */
+export function zonedWeekday(instant: Date, timeZone: string): number {
+  const clock = zonedWallClock(instant.getTime(), resolveTimeZone(timeZone))
+  return new Date(Date.UTC(clock.year, clock.month - 1, clock.day)).getUTCDay()
+}
+
+/**
+ * The next occurrence of `weekday` (0 = Sunday) at or after `from`, as a
+ * calendar date key in `timeZone`. The zone matters: at 12:00 UTC on a Monday
+ * it is already Tuesday in `Pacific/Auckland`, which shifted the whole series
+ * by a week before this was zone-aware.
+ */
+export function nextWeekdayDateKey(weekday: number, timeZone: string, from: Date = new Date()): string {
+  const clock = zonedWallClock(from.getTime(), resolveTimeZone(timeZone))
+  const localMidnight = Date.UTC(clock.year, clock.month - 1, clock.day)
+  const diff = (weekday - new Date(localMidnight).getUTCDay() + 7) % 7
+  return formatUtcDateKey(localMidnight + diff * DAY_MS)
+}
+
+/**
+ * The start and end instants of the occurrence a weekly window is anchored on.
+ *
+ * The anchor's exact length becomes the rule's `DURATION`, which every reader
+ * applies to every week. An anchor that spans a DST transition (Europe/Warsaw
+ * Sunday 00:00–08:00 on 2026-10-25 lasts 9 hours) or starts in a gap would
+ * therefore misstate the window for all ordinary weeks, so the upcoming
+ * occurrence is used only when both local endpoints and its exact length match
+ * the request; otherwise the previous week's occurrence anchors the series. Taking
+ * the earlier week keeps the upcoming occurrence inside the series for readers
+ * that expand forward from `DTSTART`.
+ *
+ * `from` is threaded in rather than defaulted per call: resolving a window's
+ * start and end against two separate `new Date()` reads can straddle midnight
+ * in the declared zone, which lands the anchors seven days apart.
+ */
+export function zonedWeeklyAnchor(
+  weekday: number,
+  startTime: string,
+  endTime: string,
+  timeZone: string,
+  from: Date,
+): { start: Date; end: Date } | null {
+  const startClock = parseTimeOfDay(startTime)
+  const endClock = parseTimeOfDay(endTime)
+  if (!startClock || !endClock) return null
+  const zone = resolveTimeZone(timeZone)
+  const startMinutes = startClock.hours * 60 + startClock.minutes
+  const endMinutes = endClock.hours * 60 + endClock.minutes
+  const localLengthMs = (endMinutes - startMinutes) * MINUTE_MS
+  const upcoming = parseDateKey(nextWeekdayDateKey(weekday, timeZone, from))
+  if (!upcoming) return null
+  const upcomingMidnight = Date.UTC(upcoming.year, upcoming.month - 1, upcoming.day)
+  let fallback: { start: Date; end: Date } | null = null
+  for (const weekOffset of [0, -1]) {
+    const midnight = upcomingMidnight + weekOffset * 7 * DAY_MS
+    const dateKey = formatUtcDateKey(midnight)
+    const start = zonedWallTimeToInstant(dateKey, startTime, timeZone)
+    const end = zonedWallTimeToInstant(dateKey, endTime, timeZone)
+    if (!start || !end) return null
+    const startWall = wallClockAsUtc(zonedWallClock(start.getTime(), zone))
+    const endWall = wallClockAsUtc(zonedWallClock(end.getTime(), zone))
+    if (startWall !== midnight + startMinutes * MINUTE_MS || endWall !== midnight + endMinutes * MINUTE_MS) continue
+    if (end.getTime() - start.getTime() === localLengthMs) return { start, end }
+    fallback ??= { start, end }
+  }
+  return fallback
+}

package/src/modules/sales/api/documents/factory.ts

@@ -424,6 +424,7 @@ export function buildDocumentCrudOptions(binding: DocumentBinding) {
 
   const orderOnlyFields = [
     'expected_delivery_at',
+    'totals_mode',
     'shipping_net_amount',
     'shipping_gross_amount',
     'surcharge_total_amount',
@@ -535,6 +536,7 @@ export function buildDocumentCrudOptions(binding: DocumentBinding) {
           paidTotalAmount: toNumber(item.paid_total_amount),
           refundedTotalAmount: toNumber(item.refunded_total_amount),
           outstandingAmount: toNumber(item.outstanding_amount),
+          ...(binding.kind === 'order' ? { totalsMode: item.totals_mode ?? 'computed' } : {}),
           customerSnapshot: normalizeJsonRecord(item.customer_snapshot),
           billingAddressSnapshot: normalizeJsonRecord(item.billing_address_snapshot),
           shippingAddressSnapshot: normalizeJsonRecord(item.shipping_address_snapshot),
@@ -665,6 +667,7 @@ export function buildDocumentOpenApi(binding: DocumentBinding) {
     paidTotalAmount: z.number().nullable().optional(),
     refundedTotalAmount: z.number().nullable().optional(),
     outstandingAmount: z.number().nullable().optional(),
+    totalsMode: z.enum(['computed', 'external']).optional(),
     createdAt: z.string(),
     updatedAt: z.string(),
     customFields: z.record(z.string(), z.unknown()).optional(),

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

@@ -1,5 +1,5 @@
 import { SalesOrderLine } from "../../data/entities";
-import { orderLineCreateSchema } from "../../data/validators";
+import { orderHeaderTotalsSchema, orderLineCreateSchema } from "../../data/validators";
 import { E } from "#generated/entities.ids.generated";
 import * as F from "#generated/entities/sales_order_line";
 import { makeSalesLineRoute } from "../../lib/makeSalesLineRoute";
@@ -11,6 +11,7 @@ const route = makeSalesLineRoute({
   parentFkColumn: "order_id",
   parentFkParam: "orderId",
   createSchema: orderLineCreateSchema,
+  writeExtensionShape: { orderTotals: orderHeaderTotalsSchema.optional() },
   features: { view: "sales.orders.view", manage: "sales.orders.manage" },
   commandPrefix: "sales.orders.lines",
   openApi: {

package/src/modules/sales/backend/sales/documents/[id]/page.tsx

@@ -77,6 +77,7 @@ import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuarde
 import { buildRecordInjectionContext, useSetCurrentRecordInjectionContext } from '@open-mercato/ui/backend/injection/recordContext'
 import { useSalesChannelsEnabled } from '@open-mercato/core/modules/sales/components/useSalesChannelsEnabled'
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
 
 const logger = createLogger('sales')
 
@@ -899,6 +900,7 @@ type DocumentRecord = {
   paidTotalAmount?: number | null
   refundedTotalAmount?: number | null
   outstandingAmount?: number | null
+  totalsMode?: 'computed' | 'external' | null
   createdAt?: string
   updatedAt?: string
   metadata?: Record<string, unknown> | null
@@ -1478,6 +1480,7 @@ function MethodInlineEditor({
   emptyResultsLabel,
   selectedHint,
   icon,
+  note,
   allowClear = true,
 }: {
   label: string
@@ -1494,6 +1497,7 @@ function MethodInlineEditor({
   emptyResultsLabel: string
   selectedHint: (id: string) => string
   icon: React.ReactNode
+  note?: string | null
   allowClear?: boolean
 }) {
   const t = useT()
@@ -1607,6 +1611,7 @@ function MethodInlineEditor({
       <div className="flex items-start justify-between gap-2">
         <div className="flex-1 min-w-0">
           <p className="text-xs uppercase tracking-wide text-muted-foreground">{label}</p>
+          {note ? <p className="mt-1 text-xs text-muted-foreground">{note}</p> : null}
           {editing ? (
             <div
               className="mt-2 space-y-2"
@@ -1937,6 +1942,7 @@ export default function SalesDocumentDetailPage({
   const [generating, setGenerating] = React.useState(false)
   const [converting, setConverting] = React.useState(false)
   const [deleting, setDeleting] = React.useState(false)
+  const [switchingToComputedAmounts, setSwitchingToComputedAmounts] = React.useState(false)
   const [sending, setSending] = React.useState(false)
   const [sendOpen, setSendOpen] = React.useState(false)
   const [validForDays, setValidForDays] = React.useState(DEFAULT_QUOTE_VALID_FOR_DAYS)
@@ -2844,6 +2850,8 @@ export default function SalesDocumentDetailPage({
     },
     [t]
   )
+  const amountsAreExternal = kind === 'order' && record?.totalsMode === 'external'
+
   const totalsItems = React.useMemo(() => {
     if (!record) return []
     const items: { key: string; label: string; amount: number | null | undefined; emphasize?: boolean }[] = [
@@ -3791,6 +3799,48 @@ export default function SalesDocumentDetailPage({
     }
   }, [fetchDocumentByKind, kind, record, runMutationWithContext, t, validForDays])
 
+  const handleSwitchToComputedAmounts = React.useCallback(async () => {
+    if (!record || kind !== 'order') return
+    const ok = await confirm({
+      title: t(
+        'sales.documents.amountsSwitchConfirm',
+        'Recompute this order\u2019s amounts from its lines? The totals supplied by the source system will be replaced and cannot be restored from here.',
+      ),
+      variant: 'default',
+    })
+    if (!ok) return
+    setSwitchingToComputedAmounts(true)
+    try {
+      await runMutationWithContext(async () => {
+        await withScopedApiRequestHeaders(buildOptimisticLockHeader(record.updatedAt), () =>
+          apiCallOrThrow('/api/sales/orders', {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({ id: record.id, totalsMode: 'computed' }),
+          }),
+        )
+      }, { id: record.id, totalsMode: 'computed' })
+      flash(t('sales.documents.amountsSwitchDone', 'Amounts are now computed from the lines.'), 'success')
+      await refreshDocumentTotals()
+    } catch (err) {
+      logger.error('sales.documents.amounts.switchToComputed', { err })
+      try {
+        getTelemetryRuntime()?.reportError(err, {
+          module: 'sales',
+          code: 'sales.amounts_switch_to_computed_failed',
+          attributes: { orderId: record.id },
+        })
+      } catch (reportFailure) {
+        logger.warn('sales.documents.amounts.switchToComputed.reportFailed', { err: reportFailure })
+      }
+      if (!handleDocumentMutationError(err, t, () => setReloadKey((prev) => prev + 1))) {
+        flash(t('sales.documents.amountsSwitchFailed', 'Could not switch to computed amounts.'), 'error')
+      }
+    } finally {
+      setSwitchingToComputedAmounts(false)
+    }
+  }, [confirm, kind, record, refreshDocumentTotals, runMutationWithContext, t])
+
   const handleDelete = React.useCallback(async () => {
     if (!record) return
     const ok = await confirm({
@@ -3851,6 +3901,14 @@ export default function SalesDocumentDetailPage({
               t('sales.documents.detail.shippingMethod.selected', 'Selected shipping method: {{id}}', { id })
             }
             icon={<Truck className="h-5 w-5 text-muted-foreground" />}
+            note={
+              amountsAreExternal
+                ? t(
+                    'sales.documents.amountsExternalMethodNote',
+                    'The method is recorded, but no charge is added \u2014 this order\u2019s totals come from the source system.',
+                  )
+                : null
+            }
           />
         ),
       },
@@ -3877,6 +3935,14 @@ export default function SalesDocumentDetailPage({
               t('sales.documents.detail.paymentMethod.selected', 'Selected payment method: {{id}}', { id })
             }
             icon={<CreditCard className="h-5 w-5 text-muted-foreground" />}
+            note={
+              amountsAreExternal
+                ? t(
+                    'sales.documents.amountsExternalMethodNote',
+                    'The method is recorded, but no charge is added \u2014 this order\u2019s totals come from the source system.',
+                  )
+                : null
+            }
           />
         ),
       },
@@ -3949,6 +4015,7 @@ export default function SalesDocumentDetailPage({
     )
     return fields
   }, [
+    amountsAreExternal,
     handleUpdateComment,
     handleUpdateCustomerReference,
     handleUpdateExpectedDeliveryAt,
@@ -4266,6 +4333,9 @@ export default function SalesDocumentDetailPage({
     if (activeTab === 'items') {
       return (
         <SalesDocumentItemsSection
+          // Remount on a mode flip: the switch rewrites every line server-side, and the
+          // section loads its lines only once per `documentId`, which does not change.
+          key={`items:${amountsAreExternal ? 'external' : 'computed'}`}
           documentId={record.id}
           kind={kind}
           currencyCode={record.currencyCode ?? null}
@@ -4274,6 +4344,7 @@ export default function SalesDocumentDetailPage({
           tenantId={(record as any)?.tenantId ?? (record as any)?.tenant_id ?? null}
           onActionChange={handleSectionActionChange}
           onItemsChange={(items) => setHasItems(items.length > 0)}
+          amountsReadOnly={amountsAreExternal}
         />
       )
     }
@@ -4332,6 +4403,7 @@ export default function SalesDocumentDetailPage({
           tenantId={(record as any)?.tenantId ?? (record as any)?.tenant_id ?? null}
           onActionChange={handleSectionActionChange}
           onRowsChange={setAdjustmentRows}
+          amountsReadOnly={amountsAreExternal}
         />
       )
     }
@@ -4914,6 +4986,30 @@ export default function SalesDocumentDetailPage({
           title={t('sales.documents.detail.totals.title', 'Totals')}
           currency={record.currencyCode ?? null}
           items={totalsItems}
+          sourceBadge={
+            amountsAreExternal
+              ? {
+                  label: t('sales.documents.amountsExternal', 'Amounts from source'),
+                  hint: t(
+                    'sales.documents.amountsExternalHint',
+                    'Totals on this document come from an external system and are stored as supplied.',
+                  ),
+                }
+              : null
+          }
+          footerAction={
+            amountsAreExternal ? (
+              <Button
+                type="button"
+                variant="outline"
+                size="sm"
+                disabled={switchingToComputedAmounts}
+                onClick={handleSwitchToComputedAmounts}
+              >
+                {t('sales.documents.amountsSwitchToComputed', 'Switch to computed amounts')}
+              </Button>
+            ) : null
+          }
         />
 
         <div className="space-y-4" ref={detailSectionRef}>