@open-mercato/core 0.6.4-develop.4382.1.6b4f656b77 → 0.6.4

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ę",
@@ -91,6 +94,7 @@
   "sales.channels.form.updateSubmit": "Zapisz zmiany",
   "sales.channels.form.websiteUrl": "Adres URL strony",
   "sales.channels.nav.title": "Kanały sprzedaży",
+  "sales.channels.offers.actions.backToList": "Powrót do ofert",
   "sales.channels.offers.actions.create": "Dodaj ofertę",
   "sales.channels.offers.actions.delete": "Usuń",
   "sales.channels.offers.actions.edit": "Edytuj",

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

@@ -94,14 +94,23 @@ function buildBaseLineResult(line: SalesLineSnapshot): SalesLineCalculationResul
   const netSubtotalBeforeDiscount = toNumber(unitNet, 0) * quantity
   const discountTotal = Math.min(Math.max(discountPerUnit * quantity, 0), netSubtotalBeforeDiscount)
   const netSubtotal = Math.max(netSubtotalBeforeDiscount - discountTotal, 0)
-  const taxAmount =
-    line.taxAmount !== null && line.taxAmount !== undefined
-      ? toNumber(line.taxAmount, 0)
-      : round(netSubtotal * Math.max(taxRate, 0))
+  const explicitTaxAmount = line.taxAmount !== null && line.taxAmount !== undefined
+  let taxAmount = explicitTaxAmount
+    ? toNumber(line.taxAmount, 0)
+    : round(netSubtotal * Math.max(taxRate, 0))
   const grossSubtotal =
     line.totalGrossAmount !== null && line.totalGrossAmount !== undefined
       ? toNumber(line.totalGrossAmount, 0)
       : round(netSubtotal + taxAmount)
+  // When tax was not supplied explicitly and the rate-derived tax is zero but
+  // the gross total already embeds tax (gross > net) — e.g. a tax-class-priced
+  // line whose resolved rate was not persisted — derive the tax from the
+  // net/gross delta so the document-level tax total is not silently zeroed
+  // while per-line net/gross stay correct (#2457).
+  if (!explicitTaxAmount && taxAmount <= 0) {
+    const grossNetDelta = round(grossSubtotal - netSubtotal)
+    if (grossNetDelta > 0) taxAmount = grossNetDelta
+  }
 
   return {
     line,
@@ -356,6 +365,25 @@ class SalesCalculationRegistry {
       })
     }
 
+    // Payment totals (paid/refunded) are authoritative inputs, not derived from
+    // lines or adjustments. Totals calculators rebuild the document result from
+    // lines+adjustments and would otherwise reset paid/refunded to 0 (and
+    // outstanding back to the full grand total), producing a stale paid/
+    // outstanding display after a payment. Re-apply the input totals last and
+    // recompute outstanding against the post-calculation grand total.
+    if (existingTotals) {
+      const paidTotalAmount = Math.max(toNumber(existingTotals.paidTotalAmount, 0), 0)
+      const refundedTotalAmount = Math.max(toNumber(existingTotals.refundedTotalAmount, 0), 0)
+      current.totals = {
+        ...current.totals,
+        paidTotalAmount,
+        refundedTotalAmount,
+        outstandingAmount: round(
+          Math.max(current.totals.grandTotalGrossAmount - paidTotalAmount + refundedTotalAmount, 0)
+        ),
+      }
+    }
+
     return current
   }
 }

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

@@ -113,10 +113,11 @@ export async function ensureSalesDictionary(params: {
 
 export async function resolveDictionaryEntryValue(
   em: EntityManager,
-  entryId: string | null | undefined
+  entryId: string | null | undefined,
+  scope: { tenantId: string }
 ): Promise<string | null> {
   if (!entryId) return null
-  const entry = await em.findOne(DictionaryEntry, entryId)
+  const entry = await em.findOne(DictionaryEntry, { id: entryId, tenantId: scope.tenantId })
   if (!entry) return null
   return entry.value?.trim() || null
 }

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

@@ -96,6 +96,7 @@ export function makeStatusDictionaryRoute(config: StatusDictionaryRouteConfig) {
     .object({
       page: z.coerce.number().min(1).default(1),
       pageSize: z.coerce.number().min(1).max(100).default(50),
+      id: z.string().uuid().optional(),
       search: z.string().optional(),
       sortField: z.string().optional(),
       sortDir: z.enum(['asc', 'desc']).optional(),
@@ -212,6 +213,7 @@ export function makeStatusDictionaryRoute(config: StatusDictionaryRouteConfig) {
         const filters: Record<string, unknown> = {
           dictionary_id: dictionaryId,
         }
+        if (query.id) filters.id = { $eq: query.id }
         const searchFilter = buildAggregateSearchFilter(query.search)
         if (searchFilter) Object.assign(filters, searchFilter)
         return filters

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/leave-requests/page.tsx

@@ -6,6 +6,7 @@ import { useRouter } from 'next/navigation'
 import type { ColumnDef, SortingState } from '@tanstack/react-table'
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { DataTable, withDataTableNamespaces } from '@open-mercato/ui/backend/DataTable'
+import { ListEmptyState } from '@open-mercato/ui/backend/filters/ListEmptyState'
 import { Badge } from '@open-mercato/ui/primitives/badge'
 import { Button } from '@open-mercato/ui/primitives/button'
 import { readApiResultOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
@@ -150,7 +151,13 @@ export default function StaffLeaveRequestsPage() {
           searchValue={search}
           onSearchChange={handleSearchChange}
           searchPlaceholder={labels.table.search}
-          emptyState={<p className="py-8 text-center text-sm text-muted-foreground">{labels.table.empty}</p>}
+          emptyState={(
+            <ListEmptyState
+              entityName={labels.title}
+              createHref="/backend/staff/leave-requests/create"
+              createLabel={labels.actions.add}
+            />
+          )}
           actions={(
             <Button asChild size="sm">
               <Link href="/backend/staff/leave-requests/create">{labels.actions.add}</Link>

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/profile/create/page.tsx

@@ -53,7 +53,7 @@ export default function StaffProfileCreatePage() {
 
   const fields = React.useMemo<CrudField[]>(() => ([
     { id: 'displayName', label: t('staff.teamMembers.form.fields.displayName', 'Display name'), type: 'text', required: true },
-    { id: 'description', label: t('staff.teamMembers.form.fields.description', 'Description'), type: 'richtext', editor: 'html' },
+    { id: 'description', label: t('staff.teamMembers.form.fields.description', 'Description'), type: 'richtext', editor: 'uiw' },
   ]), [t])
 
   const handleSubmit = React.useCallback(async (values: SelfProfileValues) => {

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,14 +9,17 @@ 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 { markdownToPlainText } from '@open-mercato/ui/backend/markdown/markdownToPlainText'
+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'
+import { ListEmptyState } from '@open-mercato/ui/backend/filters/ListEmptyState'
 import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
-import { Pencil } from 'lucide-react'
+import { Pencil, Users } from 'lucide-react'
 import { formatDateTime } from '@open-mercato/shared/lib/time'
 
 const PAGE_SIZE = 50
@@ -150,7 +153,7 @@ export default function StaffTeamMembersPage() {
           ? (
             <div className="flex items-center justify-between gap-3">
               <div className="flex items-center gap-2">
-                {row.original.teamId ? <TeamsIcon className="h-4 w-4 text-muted-foreground" /> : null}
+                {row.original.teamId ? <Users className="h-4 w-4 text-muted-foreground" /> : null}
                 <span className="font-semibold">{row.original.displayName}</span>
               </div>
               {row.original.teamId ? (
@@ -173,7 +176,7 @@ export default function StaffTeamMembersPage() {
             <div className="flex flex-col">
               <span className="font-medium pl-6">{row.original.displayName}</span>
               {row.original.description ? (
-                <span className="text-xs text-muted-foreground line-clamp-2 pl-6">{row.original.description}</span>
+                <span className="text-xs text-muted-foreground line-clamp-2 pl-6">{markdownToPlainText(row.original.description)}</span>
               ) : null}
             </div>
           )
@@ -391,7 +394,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) {
@@ -415,7 +421,13 @@ export default function StaffTeamMembersPage() {
           filterValues={filterValues}
           onFiltersApply={handleFiltersApply}
           onFiltersClear={handleFiltersClear}
-          emptyState={<p className="py-8 text-center text-sm text-muted-foreground">{labels.table.empty}</p>}
+          emptyState={(
+            <ListEmptyState
+              entityName={labels.title}
+              createHref="/backend/staff/team-members/create"
+              createLabel={labels.actions.add}
+            />
+          )}
           actions={(
             <Button asChild size="sm">
               <Link href="/backend/staff/team-members/create">
@@ -627,22 +639,3 @@ function renderLabelPills(values: string[]): React.ReactNode {
   )
 }
 
-function TeamsIcon({ className }: { className?: string }) {
-  return (
-    <svg
-      width="16"
-      height="16"
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth="2"
-      className={className}
-      aria-hidden="true"
-    >
-      <circle cx="8" cy="8" r="3" />
-      <circle cx="16" cy="8" r="3" />
-      <path d="M3 20c0-3 3-5 5-5" />
-      <path d="M21 20c0-3-3-5-5-5" />
-    </svg>
-  )
-}

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

@@ -23,6 +23,9 @@ type TeamRoleRecord = {
   appearanceColor?: string | null
   appearance_icon?: string | null
   appearance_color?: string | null
+  updatedAt?: string | null
+  updated_at?: string | null
+  team?: { id?: string | null; name?: string | null } | null
 } & Record<string, unknown>
 
 type TeamRoleResponse = {
@@ -38,10 +41,14 @@ 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)
   const [teams, setTeams] = React.useState<TeamRoleOption[]>([])
+  const selectedTeamId = typeof initialValues?.teamId === 'string' && initialValues.teamId.trim().length
+    ? initialValues.teamId.trim()
+    : null
 
   React.useEffect(() => {
     if (!roleId) return
@@ -76,16 +83,29 @@ export default function StaffTeamRoleEditPage({ params }: { params?: { id?: stri
             ? record.appearance_color
             : null
         if (!cancelled) {
+          const teamId = typeof record.teamId === 'string'
+            ? record.teamId
+            : typeof record.team_id === 'string'
+              ? record.team_id
+              : null
+          const teamName = typeof record.team?.name === 'string' ? record.team.name : null
+          if (teamId && teamName) {
+            setTeams((previous) => {
+              if (previous.some((team) => team.id === teamId)) return previous
+              return [{ id: teamId, name: teamName }, ...previous]
+            })
+          }
           setInitialValues({
             id: record.id,
-            teamId: typeof record.teamId === 'string'
-              ? record.teamId
-              : typeof record.team_id === 'string'
-                ? record.team_id
-                : null,
+            teamId,
             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,
           })
         }
@@ -119,7 +139,14 @@ export default function StaffTeamRoleEditPage({ params }: { params?: { id?: stri
             return { id, name }
           })
           .filter((entry): entry is TeamRoleOption => entry !== null)
-        if (!cancelled) setTeams(options)
+        if (!cancelled) {
+          setTeams((previous) => {
+            if (!previous.length) return options
+            const seen = new Set(options.map((team) => team.id))
+            const preservedSelected = previous.filter((team) => !seen.has(team.id))
+            return [...preservedSelected, ...options]
+          })
+        }
       } catch {
         if (!cancelled) setTeams([])
       }
@@ -128,6 +155,34 @@ export default function StaffTeamRoleEditPage({ params }: { params?: { id?: stri
     return () => { cancelled = true }
   }, [scopeVersion])
 
+  React.useEffect(() => {
+    if (!selectedTeamId) return
+    if (teams.some((team) => team.id === selectedTeamId)) return
+    const lookupId = selectedTeamId
+    let cancelled = false
+    async function loadSelectedTeam() {
+      try {
+        const call = await apiCall<TeamsResponse>(
+          `/api/staff/teams?ids=${encodeURIComponent(lookupId)}&pageSize=1`,
+        )
+        const entry = Array.isArray(call.result?.items) ? call.result.items[0] : null
+        const id = typeof entry?.id === 'string' ? entry.id : null
+        const name = typeof entry?.name === 'string' ? entry.name : null
+        if (!id || !name) return
+        if (!cancelled) {
+          setTeams((previous) => {
+            if (previous.some((team) => team.id === id)) return previous
+            return [{ id, name }, ...previous]
+          })
+        }
+      } catch {
+        if (!cancelled) setTeams((previous) => previous)
+      }
+    }
+    loadSelectedTeam()
+    return () => { cancelled = true }
+  }, [selectedTeamId, teams])
+
   const handleSubmit = React.useCallback(async (values: TeamRoleFormValues) => {
     if (!roleId) return
     const payload = buildTeamRolePayload(values, { id: roleId })