@open-mercato/core 0.6.5-develop.4516.1.88e6ab71a9 → 0.6.5-develop.4544.1.71c003c861

package/src/modules/sales/di.ts

@@ -2,6 +2,8 @@ import { asFunction, asValue } from 'awilix'
 import type { EntityManager } from '@mikro-orm/postgresql'
 import type { EventBus } from '@open-mercato/events'
 import type { AppContainer } from '@open-mercato/shared/lib/di/container'
+import type { OptimisticLockCurrentReader } from '@open-mercato/shared/lib/crud/optimistic-lock'
+import { registerOptimisticLockReaders } from '@open-mercato/shared/lib/crud/optimistic-lock-store'
 import { DefaultSalesCalculationService } from './services/salesCalculationService'
 import { DefaultTaxCalculationService } from './services/taxCalculationService'
 import { SalesDocumentNumberGenerator } from './services/salesDocumentNumberGenerator'
@@ -38,6 +40,34 @@ type AppCradle = AppContainer['cradle'] & {
   eventBus?: EventBus | null
 }
 
+const RESOURCE_KIND_ORDER = 'sales.order'
+
+const readSalesOrderUpdatedAt: OptimisticLockCurrentReader = async (
+  em: EntityManager,
+  { resourceId, tenantId, organizationId },
+) => {
+  const row = await em.findOne(
+    SalesOrder,
+    {
+      id: resourceId,
+      tenantId,
+      ...(organizationId ? { organizationId } : {}),
+      deletedAt: null,
+    },
+    { fields: ['updatedAt'] as const },
+  )
+  return row?.updatedAt instanceof Date ? row.updatedAt.toISOString() : null
+}
+
+// Hand-wired sales.order reader registered at module-load time so the
+// `customer_entities`-style polymorphic-table override pattern stays
+// observable for downstream modules. Functionally identical to the
+// auto-registered generic reader; kept here as a reference example. The
+// guard's mode check short-circuits when `OM_OPTIMISTIC_LOCK=off`.
+registerOptimisticLockReaders({
+  [RESOURCE_KIND_ORDER]: readSalesOrderUpdatedAt,
+})
+
 export function register(container: AppContainer) {
   container.register({
     salesCalculationService: asFunction(({ eventBus }: AppCradle) => {
@@ -81,4 +111,9 @@ export function register(container: AppContainer) {
     SalesPaymentMethod: asValue(SalesPaymentMethod),
     SalesTaxRate: asValue(SalesTaxRate),
   })
+
+  // `crudMutationGuardService` is registered platform-wide in the shared
+  // DI bootstrap (`packages/shared/src/lib/di/container.ts`). The
+  // hand-wired sales.order reader above already lives in the global store,
+  // so this module no longer needs its own DI binding.
 }

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

@@ -15,6 +15,9 @@
   "sales.audit.delivery-windows.create": "Create delivery window",
   "sales.audit.delivery-windows.delete": "Delete delivery window",
   "sales.audit.delivery-windows.update": "Update delivery window",
+  "sales.audit.document_addresses.create": "Dokumentadresse hinzufügen",
+  "sales.audit.document_addresses.delete": "Dokumentadresse entfernen",
+  "sales.audit.document_addresses.update": "Dokumentadresse aktualisieren",
   "sales.audit.invoices.create": "Rechnung erstellen",
   "sales.audit.invoices.delete": "Rechnung löschen",
   "sales.audit.invoices.update": "Rechnung aktualisieren",

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

@@ -15,6 +15,9 @@
   "sales.audit.delivery-windows.create": "Create delivery window",
   "sales.audit.delivery-windows.delete": "Delete delivery window",
   "sales.audit.delivery-windows.update": "Update delivery window",
+  "sales.audit.document_addresses.create": "Add document address",
+  "sales.audit.document_addresses.delete": "Remove document address",
+  "sales.audit.document_addresses.update": "Update document address",
   "sales.audit.invoices.create": "Create invoice",
   "sales.audit.invoices.delete": "Delete invoice",
   "sales.audit.invoices.update": "Update invoice",

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

@@ -15,6 +15,9 @@
   "sales.audit.delivery-windows.create": "Create delivery window",
   "sales.audit.delivery-windows.delete": "Delete delivery window",
   "sales.audit.delivery-windows.update": "Update delivery window",
+  "sales.audit.document_addresses.create": "Agregar dirección del documento",
+  "sales.audit.document_addresses.delete": "Eliminar dirección del documento",
+  "sales.audit.document_addresses.update": "Actualizar dirección del documento",
   "sales.audit.invoices.create": "Crear factura",
   "sales.audit.invoices.delete": "Eliminar factura",
   "sales.audit.invoices.update": "Actualizar factura",

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

@@ -15,6 +15,9 @@
   "sales.audit.delivery-windows.create": "Create delivery window",
   "sales.audit.delivery-windows.delete": "Delete delivery window",
   "sales.audit.delivery-windows.update": "Update delivery window",
+  "sales.audit.document_addresses.create": "Dodaj adres dokumentu",
+  "sales.audit.document_addresses.delete": "Usuń adres dokumentu",
+  "sales.audit.document_addresses.update": "Zaktualizuj adres dokumentu",
   "sales.audit.invoices.create": "Utwórz fakturę",
   "sales.audit.invoices.delete": "Usuń fakturę",
   "sales.audit.invoices.update": "Zaktualizuj fakturę",

package/src/modules/shipping_carriers/api/cancel/route.ts

@@ -3,7 +3,7 @@ import { getAuthFromRequest } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { readJsonSafe } from '@open-mercato/shared/lib/http/readJsonSafe'
 import type { ShippingCarrierService } from '../../lib/shipping-service'
-import { ShipmentCancelNotAllowedError } from '../../lib/status-sync'
+import { isShipmentCancelNotAllowedError } from '../../lib/status-sync'
 import { cancelShipmentSchema } from '../../data/validators'
 import { shippingCarriersTag } from '../openapi'
 
@@ -32,7 +32,7 @@ export async function POST(req: Request) {
     })
     return NextResponse.json(result)
   } catch (error: unknown) {
-    if (error instanceof ShipmentCancelNotAllowedError) {
+    if (isShipmentCancelNotAllowedError(error)) {
       return NextResponse.json({ error: error.message }, { status: 422 })
     }
     const message = error instanceof Error ? error.message : 'Failed to cancel shipment'

package/src/modules/shipping_carriers/lib/status-sync.ts

@@ -2,13 +2,32 @@ import type { UnifiedShipmentStatus } from './adapter'
 import type { CarrierShipment } from '../data/entities'
 import type { ShippingEventId } from '../events'
 
+// Use Symbol.for so the marker survives module duplication across bundle
+// boundaries — production builds can split this class into separate chunks,
+// which breaks `instanceof` (see isCrudHttpError in
+// @open-mercato/shared/lib/crud/errors for the same pattern).
+const SHIPMENT_CANCEL_NOT_ALLOWED_MARKER = Symbol.for('@open-mercato/shipping_carriers/ShipmentCancelNotAllowedError')
+
 export class ShipmentCancelNotAllowedError extends Error {
+  readonly [SHIPMENT_CANCEL_NOT_ALLOWED_MARKER] = true
+
   constructor(status: string) {
     super(`Shipment cannot be cancelled in its current status: ${status}`)
     this.name = 'ShipmentCancelNotAllowedError'
   }
 }
 
+/**
+ * Type-safe check that works across module/bundle boundaries. Prefer this over
+ * `instanceof ShipmentCancelNotAllowedError` in route handlers, where the thrown
+ * error may originate from a different bundle than the one performing the check.
+ */
+export function isShipmentCancelNotAllowedError(error: unknown): error is ShipmentCancelNotAllowedError {
+  return !!error
+    && typeof error === 'object'
+    && (error as Record<symbol, unknown>)[SHIPMENT_CANCEL_NOT_ALLOWED_MARKER] === true
+}
+
 const VALID_SHIPPING_TRANSITIONS: Record<string, UnifiedShipmentStatus[]> = {
   label_created: ['picked_up', 'in_transit', 'cancelled'],
   picked_up: ['in_transit', 'cancelled'],

package/src/modules/staff/api/job-histories.ts

@@ -4,6 +4,7 @@ import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { resolveCrudRecordId, parseScopedCommandInput } from '@open-mercato/shared/lib/api/scoped'
 import { StaffTeamMemberJobHistory } from '../data/entities'
 import {
+  optimisticUpdatedAtSchema,
   staffTeamMemberJobHistoryCreateSchema,
   staffTeamMemberJobHistoryUpdateSchema,
 } from '../data/validators'
@@ -12,6 +13,11 @@ import { E } from '#generated/entities.ids.generated'
 
 const rawBodySchema = z.object({}).passthrough()
 
+const optimisticDeleteSchema = z.object({
+  id: z.string().uuid(),
+  updatedAt: optimisticUpdatedAtSchema.optional(),
+})
+
 const listSchema = z
   .object({
     page: z.coerce.number().min(1).default(1),
@@ -94,7 +100,11 @@ const crud = makeCrudRoute({
       mapInput: async ({ parsed, ctx }) => {
         const { translate } = await resolveTranslations()
         const id = resolveCrudRecordId(parsed, ctx, translate)
-        return { id }
+        const parsedBody = (parsed as { body?: Record<string, unknown> })?.body
+        return {
+          id,
+          updatedAt: typeof parsedBody?.updatedAt === 'string' ? parsedBody.updatedAt : undefined,
+        }
       },
       response: () => ({ ok: true }),
     },
@@ -137,7 +147,7 @@ export const openApi = createStaffCrudOpenApi({
     description: 'Updates a team member job history entry.',
   },
   del: {
-    schema: z.object({ id: z.string().uuid() }),
+    schema: optimisticDeleteSchema,
     responseSchema: defaultOkResponseSchema,
     description: 'Deletes a team member job history entry.',
   },

package/src/modules/staff/api/timesheets/time-entries/route.ts

@@ -37,13 +37,25 @@ export const metadata = routeMetadata
 
 const rawBodySchema = z.object({}).passthrough()
 
+const isParseableDateFilter = (value: string): boolean => {
+  const trimmed = value.trim()
+  if (trimmed.length === 0) return true
+  if (!/^\d{4}-\d{2}-\d{2}([T ].*)?$/.test(trimmed)) return false
+  return !Number.isNaN(new Date(trimmed).getTime())
+}
+
+const dateFilterSchema = z
+  .string()
+  .refine(isParseableDateFilter, { message: 'Invalid date' })
+  .optional()
+
 const listSchema = z
   .object({
     page: z.coerce.number().min(1).default(1),
     pageSize: z.coerce.number().min(1).max(100).default(50),
     staffMemberId: z.string().uuid().optional(),
-    from: z.string().optional(),
-    to: z.string().optional(),
+    from: dateFilterSchema,
+    to: dateFilterSchema,
     projectId: z.string().uuid().optional(),
     ids: z.string().optional(),
     sortField: z.string().optional(),
@@ -102,10 +114,10 @@ const crud = makeCrudRoute({
       if (typeof query.staffMemberId === 'string' && query.staffMemberId.length > 0) {
         filters[F.staff_member_id] = query.staffMemberId
       }
-      if (typeof query.from === 'string' && query.from.length > 0) {
+      if (typeof query.from === 'string' && query.from.length > 0 && isParseableDateFilter(query.from)) {
         filters[F.date] = { ...((filters[F.date] as Record<string, unknown>) ?? {}), $gte: query.from }
       }
-      if (typeof query.to === 'string' && query.to.length > 0) {
+      if (typeof query.to === 'string' && query.to.length > 0 && isParseableDateFilter(query.to)) {
         filters[F.date] = { ...((filters[F.date] as Record<string, unknown>) ?? {}), $lte: query.to }
       }
       if (typeof query.projectId === 'string' && query.projectId.length > 0) {

package/src/modules/staff/backend/staff/leave-requests/[id]/page.tsx

@@ -8,7 +8,8 @@ import { Button } from '@open-mercato/ui/primitives/button'
 import { Textarea } from '@open-mercato/ui/primitives/textarea'
 import { LoadingMessage, ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
 import { SendObjectMessageDialog } from '@open-mercato/ui/backend/messages'
-import { apiCallOrThrow, readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { apiCallOrThrow, readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { updateCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
@@ -89,6 +90,7 @@ export default function StaffLeaveRequestDetailPage({ params }: { params?: { id?
     unavailabilityReasonEntryId: record?.unavailabilityReasonEntryId ?? null,
     unavailabilityReasonValue: record?.unavailabilityReasonValue ?? null,
     note: record?.note ?? null,
+    updatedAt: record?.updatedAt ?? null,
   }), [record, memberLabel])
 
 const handleSubmit = React.useCallback(async (values: LeaveRequestFormValues) => {
@@ -104,11 +106,14 @@ const handleSubmit = React.useCallback(async (values: LeaveRequestFormValues) =>
   const handleDecision = React.useCallback(async (action: 'accept' | 'reject') => {
     if (!record?.id) return
     const endpoint = action === 'accept' ? '/api/staff/leave-requests/accept' : '/api/staff/leave-requests/reject'
-    await apiCallOrThrow(endpoint, {
-      method: 'POST',
-      headers: { 'content-type': 'application/json' },
-      body: JSON.stringify({ id: record.id, decisionComment: decisionComment || null }),
-    })
+    await withScopedApiRequestHeaders(
+      buildOptimisticLockHeader(record.updatedAt),
+      () => apiCallOrThrow(endpoint, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ id: record.id, decisionComment: decisionComment || null }),
+      }),
+    )
     flash(
       action === 'accept'
         ? t('staff.leaveRequests.messages.accepted', 'Leave request approved.')
@@ -116,7 +121,7 @@ const handleSubmit = React.useCallback(async (values: LeaveRequestFormValues) =>
       'success',
     )
     router.refresh()
-  }, [decisionComment, record?.id, router, t])
+  }, [decisionComment, record?.id, record?.updatedAt, router, t])
 
   if (isLoading) {
     return (

package/src/modules/staff/backend/staff/my-leave-requests/[id]/page.tsx

@@ -74,6 +74,7 @@ export default function StaffMyLeaveRequestDetailPage({ params }: { params?: { i
 
   const status = record?.status ?? 'pending'
   const memberLabel = record?.member?.displayName ?? null
+  // optimistic-lock: LeaveRequestForm forwards optimisticLockUpdatedAt from initialValues.updatedAt (wrapper auto-derives the header on save).
   const initialValues = React.useMemo<LeaveRequestFormValues>(() => ({
     id: record?.id,
     memberId: record?.memberId ?? null,
@@ -84,6 +85,7 @@ export default function StaffMyLeaveRequestDetailPage({ params }: { params?: { i
     unavailabilityReasonEntryId: record?.unavailabilityReasonEntryId ?? null,
     unavailabilityReasonValue: record?.unavailabilityReasonValue ?? null,
     note: record?.note ?? null,
+    updatedAt: record?.updatedAt ?? null,
   }), [record, memberLabel])
   const dateSummary = formatDateRange(record?.startDate, record?.endDate)
 const handleSubmit = React.useCallback(async (values: LeaveRequestFormValues) => {

package/src/modules/staff/backend/staff/team-members/[id]/page.tsx

@@ -5,9 +5,10 @@ import Link from 'next/link'
 import { useRouter, useSearchParams } from 'next/navigation'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { Button } from '@open-mercato/ui/primitives/button'
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { extractCustomFieldEntries } from '@open-mercato/shared/lib/crud/custom-fields-client'
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 import { createTranslatorWithFallback } from '@open-mercato/shared/lib/i18n/translate'
@@ -54,6 +55,8 @@ type TeamMemberRecord = {
   is_active?: boolean
   availabilityRuleSetId?: string | null
   availability_rule_set_id?: string | null
+  updatedAt?: string | null
+  updated_at?: string | null
   user?: { id?: string; email?: string | null } | null
   team?: { id?: string; name?: string | null } | null
   customFields?: Record<string, unknown> | null
@@ -226,6 +229,11 @@ export default function StaffTeamMemberDetailPage({ params }: { params?: { id?:
             roleIds: normalizedRoleIds,
             tags: normalizeStringList(record.tags),
             isActive: record.isActive ?? record.is_active ?? true,
+            updatedAt: typeof record.updatedAt === 'string'
+              ? record.updatedAt
+              : typeof record.updated_at === 'string'
+                ? record.updated_at
+                : null,
             ...customFields,
           })
           setMemberRecord(record)
@@ -289,12 +297,15 @@ export default function StaffTeamMemberDetailPage({ params }: { params?: { id?:
 
   const handleRulesetChange = React.useCallback(async (nextId: string | null) => {
     if (!memberId) return
-    await updateCrud('staff/team-members', { id: memberId, availabilityRuleSetId: nextId }, {
-      errorMessage: t('staff.teamMembers.availability.ruleset.updateError', 'Failed to update schedule.'),
-    })
+    const headers = buildOptimisticLockHeader(initialValues?.updatedAt)
+    await withScopedApiRequestHeaders(headers, () => (
+      updateCrud('staff/team-members', { id: memberId, availabilityRuleSetId: nextId }, {
+        errorMessage: t('staff.teamMembers.availability.ruleset.updateError', 'Failed to update schedule.'),
+      })
+    ))
     setAvailabilityRuleSetId(nextId)
     flash(t('staff.teamMembers.availability.ruleset.updateSuccess', 'Schedule updated.'), 'success')
-  }, [memberId, t])
+  }, [initialValues?.updatedAt, memberId, t])
 
   const panelTabs = React.useMemo(() => ([
     { id: 'details' as const, label: t('staff.teamMembers.detail.tabs.details', 'Details') },

package/src/modules/staff/backend/staff/team-members/page.tsx

@@ -9,8 +9,9 @@ import { DataTable, withDataTableNamespaces } from '@open-mercato/ui/backend/Dat
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { BooleanIcon } from '@open-mercato/ui/backend/ValueIcons'
-import { readApiResultOrThrow, apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
@@ -391,7 +392,10 @@ export default function StaffTeamMembersPage() {
     })
     if (!confirmed) return
     try {
-      await deleteCrud('staff/team-members', entry.id, { errorMessage: labels.errors.delete })
+      const headers = buildOptimisticLockHeader(entry.updatedAt)
+      await withScopedApiRequestHeaders(headers, () => (
+        deleteCrud('staff/team-members', entry.id, { errorMessage: labels.errors.delete })
+      ))
       flash(labels.messages.deleted, 'success')
       handleRefresh()
     } catch (error) {

package/src/modules/staff/backend/staff/team-roles/[id]/edit/page.tsx

@@ -23,6 +23,8 @@ type TeamRoleRecord = {
   appearanceColor?: string | null
   appearance_icon?: string | null
   appearance_color?: string | null
+  updatedAt?: string | null
+  updated_at?: string | null
 } & Record<string, unknown>
 
 type TeamRoleResponse = {
@@ -38,6 +40,7 @@ export default function StaffTeamRoleEditPage({ params }: { params?: { id?: stri
   const t = useT()
   const router = useRouter()
   const scopeVersion = useOrganizationScopeVersion()
+  // optimistic-lock: TeamRoleForm forwards optimisticLockUpdatedAt from initialValues.updatedAt (wrapper auto-derives the header on save + delete).
   const [initialValues, setInitialValues] = React.useState<TeamRoleFormValues | null>(null)
   const [error, setError] = React.useState<string | null>(null)
   const [isNotFound, setIsNotFound] = React.useState(false)
@@ -86,6 +89,11 @@ export default function StaffTeamRoleEditPage({ params }: { params?: { id?: stri
             name: record.name ?? '',
             description: record.description ?? '',
             appearance: { icon: appearanceIcon, color: appearanceColor },
+            updatedAt: typeof record.updatedAt === 'string'
+              ? record.updatedAt
+              : typeof record.updated_at === 'string'
+                ? record.updated_at
+                : null,
             ...customFields,
           })
         }

package/src/modules/staff/backend/staff/team-roles/page.tsx

@@ -9,8 +9,9 @@ import { DataTable, withDataTableNamespaces } from '@open-mercato/ui/backend/Dat
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { MarkdownPreview } from '@open-mercato/ui/backend/markdown/MarkdownContent'
 import { Button } from '@open-mercato/ui/primitives/button'
-import { readApiResultOrThrow, apiCall } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
 import { Pencil, Users } from 'lucide-react'
@@ -277,7 +278,10 @@ export default function StaffTeamRolesPage() {
     })
     if (!confirmed) return
     try {
-      await deleteCrud('staff/team-roles', entry.id, { errorMessage: labels.errors.delete })
+      const headers = buildOptimisticLockHeader(entry.updatedAt)
+      await withScopedApiRequestHeaders(headers, () => (
+        deleteCrud('staff/team-roles', entry.id, { errorMessage: labels.errors.delete })
+      ))
       flash(labels.messages.deleted, 'success')
       handleRefresh()
     } catch (error) {

package/src/modules/staff/backend/staff/teams/[id]/edit/page.tsx

@@ -6,8 +6,9 @@ import { useRouter, useSearchParams } from 'next/navigation'
 import type { ColumnDef, SortingState } from '@tanstack/react-table'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { ErrorMessage, RecordNotFoundState } from '@open-mercato/ui/backend/detail'
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
 import { updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
 import { DataTable, withDataTableNamespaces } from '@open-mercato/ui/backend/DataTable'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { Button } from '@open-mercato/ui/primitives/button'
@@ -29,6 +30,8 @@ type TeamRecord = {
   description?: string | null
   isActive?: boolean
   is_active?: boolean
+  updatedAt?: string | null
+  updated_at?: string | null
 } & Record<string, unknown>
 
 type TeamResponse = {
@@ -199,6 +202,11 @@ export default function StaffTeamEditPage({ params }: { params?: { id?: string }
             name: record.name ?? '',
             description: record.description ?? '',
             isActive,
+            updatedAt: typeof record.updatedAt === 'string'
+              ? record.updatedAt
+              : typeof record.updated_at === 'string'
+                ? record.updated_at
+                : null,
             ...customFields,
           })
         }
@@ -278,7 +286,10 @@ export default function StaffTeamEditPage({ params }: { params?: { id?: string }
   const handleUnassignMember = React.useCallback(async (entry: TeamMemberRow) => {
     if (!teamId || entry.teamId !== teamId) return
     try {
-      await updateCrud('staff/team-members', { id: entry.id, teamId: null }, { errorMessage: memberLabels.errors.unassign })
+      const headers = buildOptimisticLockHeader(entry.updatedAt)
+      await withScopedApiRequestHeaders(headers, () => (
+        updateCrud('staff/team-members', { id: entry.id, teamId: null }, { errorMessage: memberLabels.errors.unassign })
+      ))
       flash(memberLabels.messages.unassigned, 'success')
       handleMemberRefresh()
     } catch (error) {
@@ -468,4 +479,3 @@ function mapApiTeamMember(item: Record<string, unknown>): TeamMemberRow {
     teamId,
   }, item)
 }
-

package/src/modules/staff/backend/staff/teams/page.tsx

@@ -10,7 +10,9 @@ import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { MarkdownPreview } from '@open-mercato/ui/backend/markdown/MarkdownContent'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { BooleanIcon } from '@open-mercato/ui/backend/ValueIcons'
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
@@ -207,14 +209,18 @@ export default function StaffTeamsPage() {
     })
     if (!confirmed) return
     try {
-      await deleteCrud('staff/teams', entry.id, { errorMessage: labels.errors.delete })
+      await withScopedApiRequestHeaders(
+        buildOptimisticLockHeader(entry.updatedAt),
+        () => deleteCrud('staff/teams', entry.id, { errorMessage: labels.errors.delete }),
+      )
       flash(labels.messages.deleted, 'success')
       handleRefresh()
     } catch (error) {
+      if (surfaceRecordConflict(error, t)) { handleRefresh(); return }
       console.error('staff.teams.delete', error)
       flash(labels.errors.delete, 'error')
     }
-  }, [confirm, handleRefresh, labels.actions.deleteConfirm, labels.actions.delete, labels.errors.delete, labels.errors.deleteAssigned, labels.messages.deleted])
+  }, [confirm, handleRefresh, labels.actions.deleteConfirm, labels.actions.delete, labels.errors.delete, labels.errors.deleteAssigned, labels.messages.deleted, t])
 
   return (
     <Page>

package/src/modules/staff/backend/staff/timesheets/page.tsx

@@ -290,6 +290,10 @@ export default function MyTimesheetsPage() {
           .filter((id) => id.length > 0),
       )
 
+      const entriesParams = new URLSearchParams({ pageSize: '100', staffMemberId: memberId })
+      if (dateRange.from) entriesParams.set('from', dateRange.from)
+      if (dateRange.to) entriesParams.set('to', dateRange.to)
+
       const [projectsRes, entriesRes] = await Promise.all([
         assignedProjectIds.length > 0
           ? readApiResultOrThrow<{ items?: Array<Record<string, unknown>> }>(
@@ -299,7 +303,7 @@ export default function MyTimesheetsPage() {
             )
           : Promise.resolve({ items: [] as Array<Record<string, unknown>> }),
         readApiResultOrThrow<{ items?: Array<Record<string, unknown>> }>(
-          `/api/staff/timesheets/time-entries?pageSize=100&staffMemberId=${memberId}&from=${dateRange.from}&to=${dateRange.to}`,
+          `/api/staff/timesheets/time-entries?${entriesParams.toString()}`,
           undefined,
           { errorMessage: t('staff.timesheets.my.errors.load', 'Failed to load timesheets.'), fallback: { items: [] } },
         ),
@@ -530,6 +534,11 @@ export default function MyTimesheetsPage() {
   // --- Add row handler ---
   const visibleProjectIds = React.useMemo(() => new Set(projects.map((p) => p.id)), [projects])
 
+  // optimistic-lock-exempt: the my-projects PATCH calls below only toggle the
+  // caller's own `showInGrid` preference on the staff.timesheets.time_project_member
+  // junction (a per-user membership flag). There is no shared, multi-user-editable
+  // state to lose, so version-locking the toggle would surface false 409s without
+  // protecting any data.
   const handleAddProject = React.useCallback(async (project: ProjectRow) => {
     try {
       const payload = { showInGrid: true }

package/src/modules/staff/backend/staff/timesheets/projects/[id]/page.tsx

@@ -210,6 +210,10 @@ export default function TimesheetProjectDetailPage({ params }: { params?: { id?:
     })
   }, [])
 
+  // optimistic-lock-exempt: the employee add/remove calls below mutate the
+  // time-project ↔ staff-member assignment junction (createCrud/deleteCrud of a
+  // membership row), not a shared editable aggregate. Junction add/remove is exempt
+  // from OSS optimistic locking per the data-integrity contract.
   // --- Remove employee ---
   const handleRemoveEmployee = React.useCallback(async (emp: EmployeeAssignment) => {
     const confirmed = await confirm({

package/src/modules/staff/backend/staff/timesheets/projects/page.tsx

@@ -9,7 +9,9 @@ import { DataTable, withDataTableNamespaces } from '@open-mercato/ui/backend/Dat
 import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterOverlay'
 import { RowActions } from '@open-mercato/ui/backend/RowActions'
 import { Button } from '@open-mercato/ui/primitives/button'
-import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
+import { readApiResultOrThrow, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
 import { deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { flash } from '@open-mercato/ui/backend/FlashMessages'
 import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
@@ -467,15 +469,19 @@ export default function TimesheetProjectsPage() {
       })
       if (!confirmed) return
       try {
-        await deleteCrud('staff/timesheets/time-projects', entry.id, { errorMessage: labels.errors.delete })
+        await withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(entry.updatedAt),
+          () => deleteCrud('staff/timesheets/time-projects', entry.id, { errorMessage: labels.errors.delete }),
+        )
         flash(labels.messages.deleted, 'success')
         handleRefresh()
       } catch (error) {
+        if (surfaceRecordConflict(error, t)) { handleRefresh(); return }
         console.error('staff.timesheets.projects.delete', error)
         flash(labels.errors.delete, 'error')
       }
     },
-    [confirm, handleRefresh, labels.actions.deleteConfirm, labels.actions.delete, labels.errors.delete, labels.messages.deleted],
+    [confirm, handleRefresh, t, labels.actions.deleteConfirm, labels.actions.delete, labels.errors.delete, labels.messages.deleted],
   )
 
   const columns = React.useMemo<ColumnDef<ProjectRow>[]>(