@open-mercato/core 0.6.6-develop.6366.1.fba69a7362 → 0.6.6-develop.6370.1.efeac59f8b

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

@@ -103,88 +103,88 @@
   "customer_accounts.admin.flash.deactivated": "User deactivated",
   "customer_accounts.admin.flash.deleted": "User deleted",
   "customer_accounts.admin.inactive": "Inactive",
-  "customer_accounts.admin.portalFeatures.addresses.manage": "Manage addresses",
-  "customer_accounts.admin.portalFeatures.addresses.view": "View addresses",
-  "customer_accounts.admin.portalFeatures.groups.addresses": "Addresses",
-  "customer_accounts.admin.portalFeatures.groups.invoices": "Invoices",
-  "customer_accounts.admin.portalFeatures.groups.orders": "Orders",
-  "customer_accounts.admin.portalFeatures.groups.profile": "Profile",
-  "customer_accounts.admin.portalFeatures.groups.quotes": "Quotes",
-  "customer_accounts.admin.portalFeatures.groups.users": "Users",
-  "customer_accounts.admin.portalFeatures.invoices.view": "View invoices",
-  "customer_accounts.admin.portalFeatures.orders.create": "Create orders",
-  "customer_accounts.admin.portalFeatures.orders.view": "View orders",
-  "customer_accounts.admin.portalFeatures.profile.edit": "Edit profile",
-  "customer_accounts.admin.portalFeatures.profile.view": "View profile",
-  "customer_accounts.admin.portalFeatures.quotes.request": "Request quotes",
-  "customer_accounts.admin.portalFeatures.quotes.view": "View quotes",
-  "customer_accounts.admin.portalFeatures.users.invite": "Invite team members",
-  "customer_accounts.admin.portalFeatures.users.manage": "Manage team members",
-  "customer_accounts.admin.portalFeatures.users.view": "View team members",
+  "customer_accounts.admin.portalFeatures.addresses.manage": "Adressen verwalten",
+  "customer_accounts.admin.portalFeatures.addresses.view": "Adressen anzeigen",
+  "customer_accounts.admin.portalFeatures.groups.addresses": "Adressen",
+  "customer_accounts.admin.portalFeatures.groups.invoices": "Rechnungen",
+  "customer_accounts.admin.portalFeatures.groups.orders": "Bestellungen",
+  "customer_accounts.admin.portalFeatures.groups.profile": "Profil",
+  "customer_accounts.admin.portalFeatures.groups.quotes": "Angebote",
+  "customer_accounts.admin.portalFeatures.groups.users": "Benutzer",
+  "customer_accounts.admin.portalFeatures.invoices.view": "Rechnungen anzeigen",
+  "customer_accounts.admin.portalFeatures.orders.create": "Bestellungen erstellen",
+  "customer_accounts.admin.portalFeatures.orders.view": "Bestellungen anzeigen",
+  "customer_accounts.admin.portalFeatures.profile.edit": "Profil bearbeiten",
+  "customer_accounts.admin.portalFeatures.profile.view": "Profil anzeigen",
+  "customer_accounts.admin.portalFeatures.quotes.request": "Angebote anfordern",
+  "customer_accounts.admin.portalFeatures.quotes.view": "Angebote anzeigen",
+  "customer_accounts.admin.portalFeatures.users.invite": "Teammitglieder einladen",
+  "customer_accounts.admin.portalFeatures.users.manage": "Teammitglieder verwalten",
+  "customer_accounts.admin.portalFeatures.users.view": "Teammitglieder anzeigen",
   "customer_accounts.admin.portalInfo.credentials": "Demo credentials: alice.johnson@example.com / Password123!",
   "customer_accounts.admin.portalInfo.description": "Manage customer portal accounts. Customers can self-register, log in, and access orders, quotes, and invoices through the portal.",
   "customer_accounts.admin.portalInfo.open": "Open Portal",
   "customer_accounts.admin.portalInfo.openConfiguration": "Open Configuration",
   "customer_accounts.admin.portalInfo.title": "Customer Portal",
   "customer_accounts.admin.portalInfo.url": "Portal URL: {url}",
-  "customer_accounts.admin.roleCreate.actions.cancel": "Cancel",
-  "customer_accounts.admin.roleCreate.actions.create": "Create Role",
-  "customer_accounts.admin.roleCreate.actions.saving": "Creating...",
-  "customer_accounts.admin.roleCreate.error.nameRequired": "Name is required",
-  "customer_accounts.admin.roleCreate.error.required": "Name and slug are required",
-  "customer_accounts.admin.roleCreate.error.save": "Failed to create role",
-  "customer_accounts.admin.roleCreate.error.slugFormat": "Slug must contain only lowercase letters, numbers, hyphens, and underscores",
-  "customer_accounts.admin.roleCreate.error.slugRequired": "Slug is required",
-  "customer_accounts.admin.roleCreate.fields.customerAssignable": "Customers can self-assign",
-  "customer_accounts.admin.roleCreate.fields.description": "Description",
-  "customer_accounts.admin.roleCreate.fields.isDefault": "Default role (auto-assigned to new users)",
+  "customer_accounts.admin.roleCreate.actions.cancel": "Abbrechen",
+  "customer_accounts.admin.roleCreate.actions.create": "Rolle erstellen",
+  "customer_accounts.admin.roleCreate.actions.saving": "Erstellen...",
+  "customer_accounts.admin.roleCreate.error.nameRequired": "Name ist erforderlich",
+  "customer_accounts.admin.roleCreate.error.required": "Name und Slug sind erforderlich",
+  "customer_accounts.admin.roleCreate.error.save": "Rolle konnte nicht erstellt werden",
+  "customer_accounts.admin.roleCreate.error.slugFormat": "Slug darf nur Kleinbuchstaben, Zahlen, Bindestriche und Unterstriche enthalten",
+  "customer_accounts.admin.roleCreate.error.slugRequired": "Slug ist erforderlich",
+  "customer_accounts.admin.roleCreate.fields.customerAssignable": "Kunden können sich selbst zuweisen",
+  "customer_accounts.admin.roleCreate.fields.description": "Beschreibung",
+  "customer_accounts.admin.roleCreate.fields.isDefault": "Standardrolle (wird neuen Benutzern automatisch zugewiesen)",
   "customer_accounts.admin.roleCreate.fields.name": "Name",
-  "customer_accounts.admin.roleCreate.fields.namePlaceholder": "e.g. Buyer",
+  "customer_accounts.admin.roleCreate.fields.namePlaceholder": "z. B. Käufer",
   "customer_accounts.admin.roleCreate.fields.slug": "Slug",
-  "customer_accounts.admin.roleCreate.fields.slugHint": "Lowercase letters, numbers, hyphens, and underscores only.",
-  "customer_accounts.admin.roleCreate.fields.slugPlaceholder": "e.g. buyer",
-  "customer_accounts.admin.roleCreate.flash.created": "Role created",
-  "customer_accounts.admin.roleCreate.sections.details": "Role Details",
-  "customer_accounts.admin.roleCreate.sections.options": "Options",
-  "customer_accounts.admin.roleCreate.title": "Create Customer Role",
-  "customer_accounts.admin.roleDetail.actions.backToList": "Back to roles",
-  "customer_accounts.admin.roleDetail.actions.cancel": "Cancel",
-  "customer_accounts.admin.roleDetail.actions.delete": "Delete",
-  "customer_accounts.admin.roleDetail.actions.save": "Save Changes",
-  "customer_accounts.admin.roleDetail.actions.saving": "Saving...",
-  "customer_accounts.admin.roleDetail.error.load": "Failed to load role",
-  "customer_accounts.admin.roleDetail.error.notFound": "Role not found",
-  "customer_accounts.admin.roleDetail.error.save": "Failed to save role",
-  "customer_accounts.admin.roleDetail.error.saveAcl": "Failed to save permissions",
-  "customer_accounts.admin.roleDetail.fields.customerAssignable": "Customers can self-assign",
-  "customer_accounts.admin.roleDetail.fields.description": "Description",
-  "customer_accounts.admin.roleDetail.fields.isDefault": "Default role (auto-assigned to new users)",
+  "customer_accounts.admin.roleCreate.fields.slugHint": "Nur Kleinbuchstaben, Zahlen, Bindestriche und Unterstriche.",
+  "customer_accounts.admin.roleCreate.fields.slugPlaceholder": "z. B. kaeufer",
+  "customer_accounts.admin.roleCreate.flash.created": "Rolle erstellt",
+  "customer_accounts.admin.roleCreate.sections.details": "Rollendetails",
+  "customer_accounts.admin.roleCreate.sections.options": "Optionen",
+  "customer_accounts.admin.roleCreate.title": "Kundenrolle erstellen",
+  "customer_accounts.admin.roleDetail.actions.backToList": "Zurück zu Rollen",
+  "customer_accounts.admin.roleDetail.actions.cancel": "Abbrechen",
+  "customer_accounts.admin.roleDetail.actions.delete": "Löschen",
+  "customer_accounts.admin.roleDetail.actions.save": "Änderungen speichern",
+  "customer_accounts.admin.roleDetail.actions.saving": "Speichern...",
+  "customer_accounts.admin.roleDetail.error.load": "Rolle konnte nicht geladen werden",
+  "customer_accounts.admin.roleDetail.error.notFound": "Rolle nicht gefunden",
+  "customer_accounts.admin.roleDetail.error.save": "Rolle konnte nicht gespeichert werden",
+  "customer_accounts.admin.roleDetail.error.saveAcl": "Berechtigungen konnten nicht gespeichert werden",
+  "customer_accounts.admin.roleDetail.fields.customerAssignable": "Kunden können sich selbst zuweisen",
+  "customer_accounts.admin.roleDetail.fields.description": "Beschreibung",
+  "customer_accounts.admin.roleDetail.fields.isDefault": "Standardrolle (wird neuen Benutzern automatisch zugewiesen)",
   "customer_accounts.admin.roleDetail.fields.name": "Name",
-  "customer_accounts.admin.roleDetail.flash.saved": "Role updated",
-  "customer_accounts.admin.roleDetail.loading": "Loading role...",
-  "customer_accounts.admin.roleDetail.sections.details": "Role Details",
-  "customer_accounts.admin.roleDetail.sections.options": "Options",
-  "customer_accounts.admin.roleDetail.sections.permissions": "Portal Permissions",
-  "customer_accounts.admin.roleDetail.selectAll": "Select all",
-  "customer_accounts.admin.roles": "Roles",
-  "customer_accounts.admin.roles.actions.create": "Create Role",
-  "customer_accounts.admin.roles.actions.delete": "Delete",
-  "customer_accounts.admin.roles.actions.edit": "Edit",
-  "customer_accounts.admin.roles.assignable": "Yes",
-  "customer_accounts.admin.roles.columns.customerAssignable": "Self-assignable",
-  "customer_accounts.admin.roles.columns.description": "Description",
-  "customer_accounts.admin.roles.columns.isDefault": "Default",
+  "customer_accounts.admin.roleDetail.flash.saved": "Rolle aktualisiert",
+  "customer_accounts.admin.roleDetail.loading": "Rolle wird geladen...",
+  "customer_accounts.admin.roleDetail.sections.details": "Rollendetails",
+  "customer_accounts.admin.roleDetail.sections.options": "Optionen",
+  "customer_accounts.admin.roleDetail.sections.permissions": "Portal-Berechtigungen",
+  "customer_accounts.admin.roleDetail.selectAll": "Alle auswählen",
+  "customer_accounts.admin.roles": "Rollen",
+  "customer_accounts.admin.roles.actions.create": "Rolle erstellen",
+  "customer_accounts.admin.roles.actions.delete": "Löschen",
+  "customer_accounts.admin.roles.actions.edit": "Bearbeiten",
+  "customer_accounts.admin.roles.assignable": "Ja",
+  "customer_accounts.admin.roles.columns.customerAssignable": "Selbst zuweisbar",
+  "customer_accounts.admin.roles.columns.description": "Beschreibung",
+  "customer_accounts.admin.roles.columns.isDefault": "Standard",
   "customer_accounts.admin.roles.columns.isSystem": "System",
   "customer_accounts.admin.roles.columns.name": "Name",
   "customer_accounts.admin.roles.columns.slug": "Slug",
-  "customer_accounts.admin.roles.confirm.delete": "Delete role \"{{name}}\"?",
-  "customer_accounts.admin.roles.default": "Default",
-  "customer_accounts.admin.roles.error.delete": "Failed to delete role",
-  "customer_accounts.admin.roles.error.deleteSystem": "System roles cannot be deleted",
-  "customer_accounts.admin.roles.error.load": "Failed to load roles",
-  "customer_accounts.admin.roles.flash.deleted": "Role deleted",
-  "customer_accounts.admin.roles.notAssignable": "No",
-  "customer_accounts.admin.roles.searchPlaceholder": "Search roles...",
+  "customer_accounts.admin.roles.confirm.delete": "Rolle \"{{name}}\" löschen?",
+  "customer_accounts.admin.roles.default": "Standard",
+  "customer_accounts.admin.roles.error.delete": "Rolle konnte nicht gelöscht werden",
+  "customer_accounts.admin.roles.error.deleteSystem": "Systemrollen können nicht gelöscht werden",
+  "customer_accounts.admin.roles.error.load": "Rollen konnten nicht geladen werden",
+  "customer_accounts.admin.roles.flash.deleted": "Rolle gelöscht",
+  "customer_accounts.admin.roles.notAssignable": "Nein",
+  "customer_accounts.admin.roles.searchPlaceholder": "Rollen suchen...",
   "customer_accounts.admin.roles.system": "System",
   "customer_accounts.admin.roles.title": "Rollen",
   "customer_accounts.admin.searchPlaceholder": "Search by name or email...",
@@ -263,8 +263,8 @@
   "customer_accounts.domainMapping.tls.retryButton": "Retry SSL",
   "customer_accounts.domainMapping.verifyNow": "Check Now",
   "customer_accounts.nav.group": "Customers",
-  "customer_accounts.nav.role_create": "Create Role",
-  "customer_accounts.nav.role_detail": "Role Detail",
+  "customer_accounts.nav.role_create": "Rolle erstellen",
+  "customer_accounts.nav.role_detail": "Rollendetails",
   "customer_accounts.nav.roles": "Kundenrollen",
   "customer_accounts.nav.user_detail": "User Detail",
   "customer_accounts.nav.users": "Kundenbenutzer",

package/src/modules/customers/api/companies/[id]/route.ts

@@ -50,6 +50,13 @@ import {
 } from '../../../lib/personCompanyLinkTable'
 import { normalizeCustomerDetailCustomFields } from '../../detailCustomFields'
 import { isOrganizationReadAccessAllowed } from '@open-mercato/core/modules/directory/utils/organizationScopeGuard'
+import { runWithCacheTenant } from '@open-mercato/cache'
+import {
+  buildCollectionTags,
+  canonicalizeResourceTag,
+  isCrudCacheEnabled,
+  resolveCrudCache,
+} from '@open-mercato/shared/lib/crud/cache'
 
 export const metadata = {
   GET: { requireAuth: true, requireFeatures: ['customers.companies.view'] },
@@ -59,6 +66,66 @@ const paramsSchema = z.object({
   id: z.string().uuid(),
 })
 
+const COMPANY_DETAIL_CACHE_TTL_MS = 60_000
+
+// The customers write commands already invalidate these resource collections via
+// invalidateCrudCache using these exact resourceKind strings. Reusing them as
+// cache tags means the cached detail is flushed by those existing commands with
+// no new wiring (#3664, mirroring #3143). Canonicalize each kind the same way
+// invalidateCrudCache does (camelCase split + lowercase) so the tag shapes match.
+const COMPANY_DETAIL_CACHE_RESOURCE_KINDS = [
+  'customers.company',
+  'customers.address',
+  'customers.tagAssignment',
+  'customers.labelAssignment',
+  'customers.personCompanyLink',
+  'customers.interaction',
+  'customers.activity',
+] as const
+
+function buildCompanyDetailCacheTags(tenantId: string | null, organizationId: string | null): string[] {
+  const tags = new Set<string>()
+  for (const resourceKind of COMPANY_DETAIL_CACHE_RESOURCE_KINDS) {
+    const resource = canonicalizeResourceTag(resourceKind) ?? resourceKind
+    for (const tag of buildCollectionTags(resource, tenantId, [organizationId])) {
+      tags.add(tag)
+    }
+  }
+  return Array.from(tags)
+}
+
+function buildCompanyDetailCacheKey(parts: {
+  tenantId: string | null
+  organizationId: string | null
+  companyId: string
+  selectedOrganizationId: string | null
+  filterIds: string[] | null
+  allowedIds: string[] | null
+  isSuperAdmin: boolean
+  viewerUserId: string | null
+  interactionMode: string
+  includeTokens: string[]
+}): string {
+  const sortKeys = (values: string[]): string[] =>
+    [...values].sort((a, b) => (a < b ? -1 : a > b ? 1 : 0))
+  const filterIds = parts.filterIds ? sortKeys(parts.filterIds).join(',') : 'all'
+  const allowedIds = parts.allowedIds ? sortKeys(parts.allowedIds).join(',') : 'all'
+  const includeTokens = sortKeys(parts.includeTokens).join(',')
+  return [
+    'customers:companies:detail',
+    `tenant:${parts.tenantId ?? 'null'}`,
+    `org:${parts.organizationId ?? 'null'}`,
+    `company:${parts.companyId}`,
+    `selected:${parts.selectedOrganizationId ?? 'null'}`,
+    `filter:${filterIds}`,
+    `allowed:${allowedIds}`,
+    `super:${parts.isSuperAdmin ? '1' : '0'}`,
+    `viewer:${parts.viewerUserId ?? 'null'}`,
+    `mode:${parts.interactionMode}`,
+    `include:${includeTokens}`,
+  ].join('|')
+}
+
 function parseIncludeParams(request: Request): Set<string> {
   const url = new URL(request.url)
   const raw = url.searchParams.getAll('include')
@@ -414,6 +481,31 @@ export async function GET(_req: Request, ctx: { params?: { id?: string } }) {
     userFeatures: undefined,
   })
 
+  // Opt-in cache (#3664): the company existence + org read-access checks above
+  // always run, so authorization is never served from cache. Only the expensive
+  // detail sweeps below are cached. Key on tenant/org/company + the RBAC scope,
+  // viewer (email privacy), interaction mode, and the requested include set.
+  const cacheTenantId = companyScope.tenantId
+  const cache = isCrudCacheEnabled() ? resolveCrudCache(container) : null
+  const cacheKey = cache
+    ? buildCompanyDetailCacheKey({
+        tenantId: cacheTenantId,
+        organizationId: companyScope.organizationId,
+        companyId: company.id,
+        selectedOrganizationId: scope?.selectedId ?? auth.orgId ?? null,
+        filterIds: scope?.filterIds ?? null,
+        allowedIds: scope?.allowedIds ?? null,
+        isSuperAdmin: auth.isSuperAdmin === true,
+        viewerUserId,
+        interactionMode,
+        includeTokens: Array.from(includeTokens),
+      })
+    : null
+  if (cache && cacheKey) {
+    const cached = await runWithCacheTenant(cacheTenantId, () => cache.get(cacheKey))
+    if (cached) return NextResponse.json(cached)
+  }
+
   const shouldLoadCanonicalInteractions = includeInteractions || includeActivities || includeTodos
 
   // These reads only depend on the resolved company + scope + email visibility
@@ -961,7 +1053,7 @@ export async function GET(_req: Request, ctx: { params?: { id?: string } }) {
     addresses: addressesCount,
   }
 
-  return NextResponse.json({
+  const payload = {
     interactionMode,
     company: {
       id: company.id,
@@ -1170,7 +1262,22 @@ export async function GET(_req: Request, ctx: { params?: { id?: string } }) {
       name: viewerUserId ? userMap.get(viewerUserId)?.name ?? null : null,
       email: viewerUserId ? userMap.get(viewerUserId)?.email ?? auth.email ?? null : auth.email ?? null,
     },
-  })
+  }
+
+  if (cache && cacheKey) {
+    try {
+      await runWithCacheTenant(cacheTenantId, () =>
+        cache.set(cacheKey, payload, {
+          ttl: COMPANY_DETAIL_CACHE_TTL_MS,
+          tags: buildCompanyDetailCacheTags(cacheTenantId, companyScope.organizationId),
+        }),
+      )
+    } catch (err) {
+      console.warn('[customers:companies] Failed to set company detail cache', err)
+    }
+  }
+
+  return NextResponse.json(payload)
 }
 
 const companyDetailQuerySchema = z.object({

package/src/modules/customers/api/deals/[id]/route.ts

@@ -24,6 +24,15 @@ import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
 import { isOrganizationReadAccessAllowed } from '@open-mercato/core/modules/directory/utils/organizationScopeGuard'
 import { decryptEntitiesWithFallbackScope } from '@open-mercato/shared/lib/encryption/subscriber'
+import { runWithCacheTenant } from '@open-mercato/cache'
+import {
+  buildCollectionTags,
+  debugCrudCache,
+  expandResourceAliases,
+  isCrudCacheEnabled,
+  resolveCrudCache,
+} from '@open-mercato/shared/lib/crud/cache'
+import type { OrganizationScope } from '@open-mercato/core/modules/directory/utils/organizationScope'
 import { isMissingDealStageTransitionTable, warnMissingDealStageTransitionTable } from '../../../lib/dealStageTransitionTable'
 
 export const metadata = {
@@ -324,6 +333,72 @@ async function resolveEffectivePipelineStage(
   return null
 }
 
+const DEAL_DETAIL_CACHE_RESOURCE = 'customers.deal'
+// Every entity the detail payload reads, expressed with the same resourceKind
+// strings the customers commands declare. `expandResourceAliases` canonicalizes
+// them exactly the way `invalidateCrudCache` does on the write side (camelCase is
+// split, `_`/`-` become `.`), so `customers.pipelineStage` resolves to
+// `customers.pipeline.stage` and `customers.dictionary_entry` to
+// `customers.dictionary.entry`. That guarantees the collection tags stored here
+// match the ones the deal/pipeline/stage/dictionary commands flush.
+const DEAL_DETAIL_CACHE_TAG_RESOURCES = [
+  'customers.pipeline',
+  'customers.pipelineStage',
+  'customers.dictionary_entry',
+]
+const DEAL_DETAIL_CACHE_TTL_MS = 60_000
+
+type DealDetailCacheAuth = {
+  isSuperAdmin?: boolean | null
+  orgId?: string | null
+}
+
+// Capture every input `isOrganizationReadAccessAllowed` consults, so two requests
+// that share a signature also share an authorization outcome for the same deal.
+// The lookup runs after the access check, so this is defense in depth plus the
+// per-scope cache partitioning the issue asks for.
+function buildDealDetailScopeSignature(
+  auth: DealDetailCacheAuth,
+  scope: Pick<OrganizationScope, 'allowedIds' | 'filterIds'> | null | undefined,
+): string {
+  if (auth?.isSuperAdmin === true) return 'super'
+  if (scope?.allowedIds === null) return 'all'
+  const filterIds = Array.isArray(scope?.filterIds)
+    ? scope!.filterIds.filter((id): id is string => typeof id === 'string' && id.trim().length > 0)
+    : []
+  if (filterIds.length) return `filter:${[...filterIds].sort((left, right) => (left < right ? -1 : left > right ? 1 : 0)).join(',')}`
+  return `home:${auth?.orgId ?? 'null'}`
+}
+
+function buildDealDetailCacheKey(params: {
+  tenantId: string | null
+  organizationId: string | null
+  dealId: string
+  scopeSignature: string
+  view: 'full' | 'lite'
+  includeKey: string
+}): string {
+  return [
+    'customers:deal:detail',
+    `tenant=${params.tenantId ?? 'null'}`,
+    `org=${params.organizationId ?? 'null'}`,
+    `deal=${params.dealId}`,
+    `scope=${params.scopeSignature}`,
+    `view=${params.view}`,
+    `include=${params.includeKey}`,
+  ].join(':')
+}
+
+function buildDealDetailCacheTags(tenantId: string | null, organizationId: string | null): string[] {
+  const tags = new Set<string>()
+  for (const key of expandResourceAliases(DEAL_DETAIL_CACHE_RESOURCE, DEAL_DETAIL_CACHE_TAG_RESOURCES)) {
+    for (const tag of buildCollectionTags(key, tenantId, [organizationId])) {
+      tags.add(tag)
+    }
+  }
+  return Array.from(tags)
+}
+
 export async function GET(request: Request, context: { params?: Record<string, unknown> }) {
   const parsedParams = paramsSchema.safeParse(context.params)
   if (!parsedParams.success) {
@@ -386,6 +461,69 @@ export async function GET(request: Request, context: { params?: Record<string, u
     tenantId: deal.tenantId ?? auth.tenantId ?? null,
     organizationId: deal.organizationId ?? auth.orgId ?? null,
   }
+
+  const viewerUserId = auth.isApiKey ? null : auth.sub ?? null
+  const resolveViewer = async (): Promise<{ name: string | null; email: string | null }> => {
+    if (!viewerUserId) {
+      return { name: null, email: auth.email ?? null }
+    }
+    const viewer = await findOneWithDecryption(
+      em,
+      User,
+      { id: viewerUserId, tenantId: auth.tenantId ?? null },
+      {},
+      { tenantId: auth.tenantId ?? null, organizationId: auth.orgId ?? null },
+    )
+    return {
+      name: viewer?.name ?? null,
+      email: viewer?.email ?? auth.email ?? null,
+    }
+  }
+
+  // Opt-in detail cache (ENABLE_CRUD_API_CACHE). The lookup runs after the deal is
+  // resolved and the tenant + organization read-access checks pass, so the cache
+  // only ever memoizes a payload this caller is already authorized to see; it then
+  // skips the heavy association / custom-field / pipeline-stage / dictionary /
+  // audit-fallback sweeps below. The viewer block is request-specific, so it is
+  // excluded from the cached value and always resolved fresh.
+  const cacheTenantId = deal.tenantId ?? auth.tenantId ?? null
+  const cacheOrganizationId = deal.organizationId ?? null
+  const detailCache = isCrudCacheEnabled() ? resolveCrudCache(container) : null
+  const includeKey = includeFlags.size ? Array.from(includeFlags).sort((left, right) => (left < right ? -1 : left > right ? 1 : 0)).join(',') : 'none'
+  const detailCacheKey = detailCache
+    ? buildDealDetailCacheKey({
+        tenantId: cacheTenantId,
+        organizationId: cacheOrganizationId,
+        dealId: deal.id,
+        scopeSignature: buildDealDetailScopeSignature(auth, scope),
+        view: viewMode,
+        includeKey,
+      })
+    : null
+
+  if (detailCache && detailCacheKey) {
+    try {
+      const cached = await runWithCacheTenant(cacheTenantId, () => detailCache.get(detailCacheKey))
+      if (cached && typeof cached === 'object') {
+        const viewerInfo = await resolveViewer()
+        return NextResponse.json({
+          ...(cached as Record<string, unknown>),
+          viewer: {
+            userId: viewerUserId,
+            name: viewerInfo.name,
+            email: viewerInfo.email,
+          },
+        })
+      }
+    } catch (err) {
+      // A cache-backend read error must degrade to a fresh DB read, never a 500.
+      debugCrudCache('get', {
+        resource: DEAL_DETAIL_CACHE_RESOURCE,
+        key: detailCacheKey,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
   // Issue #3175: the reads below only depend on the already-resolved deal +
   // organization scope + decryption scope, so they are grouped into Promise.all
   // batches instead of being awaited one after another. True dependencies stay
@@ -535,24 +673,6 @@ export async function GET(request: Request, context: { params?: Record<string, u
     }
   }
 
-  const viewerUserId = auth.isApiKey ? null : auth.sub ?? null
-  const resolveViewer = async (): Promise<{ name: string | null; email: string | null }> => {
-    if (!viewerUserId) {
-      return { name: null, email: auth.email ?? null }
-    }
-    const viewer = await findOneWithDecryption(
-      em,
-      User,
-      { id: viewerUserId, tenantId: auth.tenantId ?? null },
-      {},
-      { tenantId: auth.tenantId ?? null, organizationId: auth.orgId ?? null },
-    )
-    return {
-      name: viewer?.name ?? null,
-      email: viewer?.email ?? auth.email ?? null,
-    }
-  }
-
   const resolveOwner = async () =>
     deal.ownerUserId
       ? await findOneWithDecryption(
@@ -682,7 +802,15 @@ export async function GET(request: Request, context: { params?: Record<string, u
     fallbackTimestamp: deal.createdAt.toISOString(),
   })
 
-  return NextResponse.json({
+  const viewer = {
+    userId: viewerUserId,
+    name: viewerName,
+    email: viewerEmail,
+  }
+
+  // Everything except the request-specific viewer block is shareable across
+  // authorized callers, so it is what gets cached.
+  const cacheableBody = {
     deal: {
       id: deal.id,
       title: deal.title,
@@ -714,11 +842,6 @@ export async function GET(request: Request, context: { params?: Record<string, u
       companies: linkedCompanyIds.length,
     },
     customFields,
-    viewer: {
-      userId: viewerUserId,
-      name: viewerName,
-      email: viewerEmail,
-    },
     pipelineStages: pipelineStages.map((stage) => {
       const appearance = pipelineStageAppearanceMap.get(stage.label.trim().toLowerCase())
       return {
@@ -732,7 +855,28 @@ export async function GET(request: Request, context: { params?: Record<string, u
     pipelineName: pipeline?.name ?? null,
     stageTransitions: stageTransitionPayload,
     owner: ownerPayload,
-  })
+  }
+
+  if (detailCache && detailCacheKey) {
+    try {
+      await runWithCacheTenant(cacheTenantId, () =>
+        detailCache.set(detailCacheKey, cacheableBody, {
+          ttl: DEAL_DETAIL_CACHE_TTL_MS,
+          tags: buildDealDetailCacheTags(cacheTenantId, cacheOrganizationId),
+        }),
+      )
+    } catch (err) {
+      // A cache write must never break the request; log it for observability
+      // instead of failing the response (matches the CRUD factory).
+      debugCrudCache('store', {
+        resource: DEAL_DETAIL_CACHE_RESOURCE,
+        key: detailCacheKey,
+        error: err instanceof Error ? err.message : String(err),
+      })
+    }
+  }
+
+  return NextResponse.json({ ...cacheableBody, viewer })
 }
 
 const dealDetailQuerySchema = z.object({