@open-mercato/core 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

package/src/modules/dashboards/services/widgetDataService.ts

@@ -5,6 +5,7 @@ import { decryptWithAesGcm } from '@open-mercato/shared/lib/encryption/aes'
 import { resolveTenantEncryptionService } from '@open-mercato/shared/lib/encryption/customFieldValues'
 import { resolveEntityIdFromMetadata } from '@open-mercato/shared/lib/encryption/entityIds'
 import { findWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+import { listEntityMetadata } from '@open-mercato/shared/lib/db/entityMetadata'
 import {
   type DateRangePreset,
   resolveDateRange,
@@ -13,17 +14,42 @@ import {
   determineChangeDirection,
   isValidDateRangePreset,
 } from '@open-mercato/ui/backend/date-range'
+import { parseDecryptedFieldValue } from '@open-mercato/shared/lib/encryption/tenantDataEncryptionService'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import type { TenantDek } from '@open-mercato/shared/lib/encryption/kms'
+import { isTenantDataEncryptionEnabled } from '@open-mercato/shared/lib/encryption/toggles'
 import {
   type AggregateFunction,
   type DateGranularity,
   buildAggregationQuery,
+  buildDistinctCurrencyQuery,
+  buildGroupSourceRowsQuery,
+  resolveGroupExpression,
 } from '../lib/aggregations'
+import {
+  type ExactDecimal,
+  EXACT_DECIMAL_ZERO,
+  addExactDecimal,
+  compareExactDecimal,
+  exactDecimalToNumber,
+  parseExactDecimal,
+} from '../lib/exactDecimal'
 import type { AnalyticsRegistry } from './analyticsRegistry'
+import type { BaseCurrencyResolver } from '../lib/optionalBaseCurrency'
+
+const logger = createLogger('dashboards').child({ component: 'widget-data-service' })
 
 const WIDGET_DATA_CACHE_TTL = 120_000
 const WIDGET_DATA_SEGMENT_TTL = 86_400_000
 const WIDGET_DATA_SEGMENT_KEY = 'widget-data:__segment__'
 
+/**
+ * Encrypted group sources cannot be grouped by the database, so the rows are scanned and
+ * aggregated in application code. The cap keeps that scan bounded; overflowing it fails loudly
+ * instead of charting a silently truncated result (#4622).
+ */
+const ENCRYPTED_GROUP_SCAN_LIMIT = 20_000
+
 const SAFE_IDENTIFIER_PATTERN = /^[a-zA-Z_][a-zA-Z0-9_]*$/
 
 export class WidgetDataValidationError extends Error {
@@ -33,12 +59,120 @@ export class WidgetDataValidationError extends Error {
   }
 }
 
+export class WidgetDataScanLimitError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WidgetDataScanLimitError'
+  }
+}
+
+/**
+ * Raised when encryption is configured but the group source cannot currently be resolved — an
+ * unhealthy KMS, an unreadable encryption map, or a missing tenant DEK. Grouping would either read
+ * ciphertext in SQL or silently collapse every encrypted row into "Unknown", so the request fails
+ * closed instead (#4622).
+ */
+export class WidgetDataEncryptionUnavailableError extends Error {
+  constructor(message: string) {
+    super(message)
+    this.name = 'WidgetDataEncryptionUnavailableError'
+  }
+}
+
+type EncryptedGroupSource = {
+  entityId: string
+  dbColumn: string
+  jsonPath: string | null
+}
+
 function assertSafeIdentifier(value: string, name: string): void {
   if (!SAFE_IDENTIFIER_PATTERN.test(value)) {
     throw new Error(`Invalid ${name}: ${value}`)
   }
 }
 
+/**
+ * Encryption maps may register a field in either casing (`findKey` in the encryption service
+ * accepts both), so match the analytics column tolerantly rather than by exact snake_case.
+ */
+function matchesColumn(fieldName: string, dbColumn: string): boolean {
+  const normalize = (value: string) => value.replace(/_/g, '').toLowerCase()
+  return normalize(fieldName) === normalize(dbColumn)
+}
+
+function readJsonPath(value: unknown, path: string): unknown {
+  let current = value
+  for (const part of path.split('.')) {
+    if (current === null || typeof current !== 'object') return null
+    current = (current as Record<string, unknown>)[part]
+  }
+  return current
+}
+
+/**
+ * Running aggregate state for one group. Values are folded in as they are scanned — the bucket
+ * never holds the row set — so the scan cost stays linear and independent of the row cap.
+ */
+type GroupBucket = {
+  /** Rows with a non-null metric column, mirroring SQL `COUNT(column)`. */
+  count: number
+  /** Rows whose metric parsed as a decimal, mirroring the row set SQL aggregates operate on. */
+  numericCount: number
+  /** Exact running sum, so money never accumulates in binary floating point. */
+  sum: ExactDecimal
+  min: ExactDecimal | null
+  max: ExactDecimal | null
+}
+
+function createGroupBucket(): GroupBucket {
+  return { count: 0, numericCount: 0, sum: EXACT_DECIMAL_ZERO, min: null, max: null }
+}
+
+function foldMetricValue(bucket: GroupBucket, value: ExactDecimal): void {
+  bucket.numericCount += 1
+  bucket.sum = addExactDecimal(bucket.sum, value)
+  if (bucket.min === null || compareExactDecimal(value, bucket.min) < 0) bucket.min = value
+  if (bucket.max === null || compareExactDecimal(value, bucket.max) > 0) bucket.max = value
+}
+
+/**
+ * Mirrors the SQL semantics of `buildAggregateExpression` for application-side aggregation. That
+ * expression wraps `SUM`/`AVG` in `COALESCE(..., 0)`, so an empty value set aggregates to `0` on
+ * both paths, while the uncoalesced `MIN`/`MAX` keep PostgreSQL's `NULL`. An encrypted group source
+ * must not report a different value than the same data would report in plaintext (#4622).
+ */
+function aggregateBucket(aggregate: AggregateFunction, bucket: GroupBucket): number | null {
+  switch (aggregate) {
+    case 'count':
+      return bucket.count
+    case 'sum':
+      return bucket.numericCount === 0 ? 0 : exactDecimalToNumber(bucket.sum)
+    case 'avg':
+      return bucket.numericCount === 0 ? 0 : exactDecimalToNumber(bucket.sum) / bucket.numericCount
+    case 'min':
+      return bucket.min === null ? null : exactDecimalToNumber(bucket.min)
+    case 'max':
+      return bucket.max === null ? null : exactDecimalToNumber(bucket.max)
+    default:
+      return bucket.count
+  }
+}
+
+/**
+ * Mirrors the SQL path's `ORDER BY value DESC NULLS LAST`. PostgreSQL defaults DESC to NULLS FIRST,
+ * which would let empty buckets displace real ones under a group limit, so both paths state the
+ * policy explicitly: highest value first, buckets without a value last.
+ */
+function compareWidgetDataItemsByValueDesc(
+  left: { value: number | null },
+  right: { value: number | null },
+): number {
+  if (left.value === null && right.value === null) return 0
+  if (left.value === null) return 1
+  if (right.value === null) return -1
+  return right.value - left.value
+}
+
 export type WidgetDataRequest = {
   entityType: string
   metric: {
@@ -82,6 +216,7 @@ export type WidgetDataResponse = {
   metadata: {
     fetchedAt: string
     recordCount: number
+    currency?: string | null
   }
 }
 
@@ -95,6 +230,7 @@ export type WidgetDataServiceOptions = {
   scope: WidgetDataScope
   registry: AnalyticsRegistry
   cache?: CacheStrategy
+  baseCurrencyResolver?: BaseCurrencyResolver
 }
 
 export class WidgetDataService {
@@ -102,12 +238,15 @@ export class WidgetDataService {
   private scope: WidgetDataScope
   private registry: AnalyticsRegistry
   private cache?: CacheStrategy
+  private baseCurrencyResolver?: BaseCurrencyResolver
+  private baseCurrencyPromise?: Promise<string | null>
 
   constructor(options: WidgetDataServiceOptions) {
     this.em = options.em
     this.scope = options.scope
     this.registry = options.registry
     this.cache = options.cache
+    this.baseCurrencyResolver = options.baseCurrencyResolver
   }
 
   private buildCacheKey(request: WidgetDataRequest): string {
@@ -147,11 +286,15 @@ export class WidgetDataService {
 
     const shouldFetchComparison = Boolean(comparisonRange && request.dateRange)
 
-    const [mainResult, comparisonResult] = await Promise.all([
+    const aggregatedRanges =
+      shouldFetchComparison && comparisonRange ? [dateRangeResolved, comparisonRange] : [dateRangeResolved]
+
+    const [mainResult, comparisonResult, currency] = await Promise.all([
       this.executeQuery(request, dateRangeResolved),
       shouldFetchComparison && comparisonRange
         ? this.executeQuery(request, comparisonRange)
         : Promise.resolve<{ value: number | null; data: WidgetDataItem[] } | undefined>(undefined),
+      this.resolveCurrencyLabel(request, aggregatedRanges),
     ])
 
     const response: WidgetDataResponse = {
@@ -160,6 +303,7 @@ export class WidgetDataService {
       metadata: {
         fetchedAt: now.toISOString(),
         recordCount: mainResult.data.length || (mainResult.value !== null ? 1 : 0),
+        currency,
       },
     }
 
@@ -188,6 +332,99 @@ export class WidgetDataService {
     return response
   }
 
+  /**
+   * Resolves the currency the response may be labelled with. The base currency of the
+   * scope is only half the answer: it describes how the organizations are configured, not
+   * what the aggregated rows are actually denominated in. A PLN-based organization holding
+   * both PLN and EUR orders would otherwise sum them and present the total as PLN (#4676),
+   * so the base currency survives only when every aggregated row carries exactly that code.
+   *
+   * The check is deliberately conservative — anything it cannot prove resolves to `null`
+   * and the widgets render an explicitly unlabelled number, which is recoverable, while a
+   * confident wrong label is not.
+   */
+  private async resolveCurrencyLabel(
+    request: WidgetDataRequest,
+    aggregatedRanges: Array<{ start: Date; end: Date } | undefined>,
+  ): Promise<string | null> {
+    const baseCurrency = await this.resolveBaseCurrency()
+    if (!baseCurrency) return null
+
+    try {
+      for (const range of aggregatedRanges) {
+        const uniform = await this.rowsShareCurrency(request, range, baseCurrency)
+        if (!uniform) return null
+      }
+      return baseCurrency
+    } catch (err) {
+      logger.warn('Row-currency uniformity check failed; leaving the amount unlabelled', {
+        err,
+        entityType: request.entityType,
+      })
+      return null
+    }
+  }
+
+  /**
+   * Reads the distinct per-row currencies of the rows one aggregation range would sum.
+   * Entities that declare no `currencyField` carry no per-row currency to contradict the
+   * base one, so they pass. An empty range has nothing to mislabel and also passes.
+   *
+   * A missing currency cannot prove the row uses the scope's base currency, so it fails
+   * closed just like a conflicting code. An empty range has no row to mislabel and passes.
+   */
+  private async rowsShareCurrency(
+    request: WidgetDataRequest,
+    dateRange: { start: Date; end: Date } | undefined,
+    expectedCode: string,
+  ): Promise<boolean> {
+    const query = buildDistinctCurrencyQuery({
+      entityType: request.entityType,
+      dateRange: dateRange && request.dateRange ? { field: request.dateRange.field, ...dateRange } : undefined,
+      filters: request.filters,
+      scope: this.scope,
+      registry: this.registry,
+    })
+
+    if (!query) return true
+
+    const rows = await this.em.getConnection().execute(query.sql, query.params)
+    const resultRows = (Array.isArray(rows) ? rows : []) as Array<Record<string, unknown>>
+
+    const recordedCodes = new Set<string>()
+    for (const row of resultRows) {
+      const code = typeof row.code === 'string' ? row.code.trim().toUpperCase() : ''
+      if (!code) return false
+      recordedCodes.add(code)
+    }
+
+    if (recordedCodes.size === 0) return true
+    if (recordedCodes.size > 1) return false
+    return recordedCodes.has(expectedCode)
+  }
+
+  /**
+   * Resolves the base currency of the current scope so money widgets can label amounts
+   * with the tenant's own currency instead of a hard-coded default (#4620). The lookup
+   * is soft: a scope spanning organizations with different base currencies, a missing
+   * base currency, or an unavailable currencies module all resolve to `null`, and the
+   * widgets then render unlabelled numbers rather than a wrong currency.
+   */
+  private resolveBaseCurrency(): Promise<string | null> {
+    if (!this.baseCurrencyPromise) {
+      const organizationIds = [...new Set(this.scope.organizationIds ?? [])]
+      if (!this.baseCurrencyResolver || organizationIds.length === 0) {
+        this.baseCurrencyPromise = Promise.resolve(null)
+      } else {
+        this.baseCurrencyPromise = this.baseCurrencyResolver
+          .resolveBaseCurrency({ tenantId: this.scope.tenantId, organizationIds })
+          .then((result) => result.status === 'resolved' ? result.code : null)
+          .catch(() => null)
+      }
+    }
+    return this.baseCurrencyPromise
+  }
+
   private validateRequest(request: WidgetDataRequest): void {
     if (!this.registry.isValidEntityType(request.entityType)) {
       throw new WidgetDataValidationError(`Invalid entity type: ${request.entityType}`)
@@ -229,6 +466,13 @@ export class WidgetDataService {
     request: WidgetDataRequest,
     dateRange?: { start: Date; end: Date },
   ): Promise<{ value: number | null; data: WidgetDataItem[] }> {
+    if (request.groupBy) {
+      const encryptedSource = await this.resolveEncryptedGroupSource(request.entityType, request.groupBy)
+      if (encryptedSource) {
+        return this.executeEncryptedGroupQuery(request, encryptedSource, dateRange)
+      }
+    }
+
     const query = buildAggregationQuery({
       entityType: request.entityType,
       metric: request.metric,
@@ -264,6 +508,193 @@ export class WidgetDataService {
     return { value: singleValue, data: [] }
   }
 
+  /**
+   * Reports the encrypted column a groupBy field reads from, or null when the source is stored in
+   * plaintext and can be grouped by the database. Grouping over an encrypted column in SQL buckets
+   * ciphertext and renders it to the user (#4622).
+   */
+  private async resolveEncryptedGroupSource(
+    entityType: string,
+    groupBy: NonNullable<WidgetDataRequest['groupBy']>,
+  ): Promise<EncryptedGroupSource | null> {
+    // Encryption is not configured for this deployment, so no column can hold ciphertext and the
+    // database may group the source directly.
+    if (!isTenantDataEncryptionEnabled()) return null
+
+    const resolved = resolveGroupExpression(this.registry, entityType, groupBy)
+    if (!resolved) return null
+
+    const tableName = this.registry.getEntityTypeConfig(entityType)?.tableName
+    if (!tableName) return null
+
+    // Without an encryption entity id the table is outside the encryption map entirely, which is
+    // the same state the encrypting subscriber sees when it skips the row.
+    const entityId = this.resolveEncryptionEntityId(tableName)
+    if (!entityId) return null
+
+    const encryptionService = resolveTenantEncryptionService(this.em)
+    if (!encryptionService) {
+      throw new WidgetDataEncryptionUnavailableError(
+        `Cannot determine whether ${groupBy.field} is encrypted: encryption service unavailable`,
+      )
+    }
+
+    const organizationId = this.resolveOrganizationId()
+    let encryptedFields: string[]
+    try {
+      // Deliberately independent of KMS health: the map describes how the rows were written, and
+      // an unhealthy KMS must not be read as "this column is plaintext" (#4622).
+      encryptedFields = await encryptionService.getEncryptedFieldNames(
+        entityId,
+        this.scope.tenantId,
+        organizationId,
+        { ignoreRuntimeHealth: true },
+      )
+    } catch (err) {
+      logger.error('Failed to resolve encrypted fields for widget grouping', { err, entityId, entityType })
+      throw new WidgetDataEncryptionUnavailableError(
+        `Cannot determine whether ${groupBy.field} is encrypted: encryption map lookup failed`,
+      )
+    }
+
+    if (!encryptedFields.some((field) => matchesColumn(field, resolved.dbColumn))) return null
+
+    if (resolved.jsonPath === null && groupBy.granularity) {
+      throw new WidgetDataValidationError(
+        `Cannot group encrypted field by granularity: ${groupBy.field}`,
+      )
+    }
+
+    return { entityId, dbColumn: resolved.dbColumn, jsonPath: resolved.jsonPath }
+  }
+
+  /**
+   * Aggregates an encrypted group source in application code: rows are scanned, the group column is
+   * decrypted, and only the resulting plaintext keys are grouped. Values that cannot be decrypted
+   * collapse into the null ("Unknown") bucket so ciphertext never reaches the response.
+   */
+  private async executeEncryptedGroupQuery(
+    request: WidgetDataRequest,
+    source: EncryptedGroupSource,
+    dateRange?: { start: Date; end: Date },
+  ): Promise<{ value: number | null; data: WidgetDataItem[] }> {
+    const query = buildGroupSourceRowsQuery({
+      entityType: request.entityType,
+      metric: request.metric,
+      dateRange: dateRange && request.dateRange ? { field: request.dateRange.field, ...dateRange } : undefined,
+      filters: request.filters,
+      scope: this.scope,
+      registry: this.registry,
+      groupColumn: source.dbColumn,
+      rowLimit: ENCRYPTED_GROUP_SCAN_LIMIT,
+    })
+
+    if (!query) {
+      throw new Error('Failed to build aggregation query')
+    }
+
+    const rows = await this.em.getConnection().execute(query.sql, query.params)
+    const results = Array.isArray(rows) ? rows : []
+
+    if (results.length > ENCRYPTED_GROUP_SCAN_LIMIT) {
+      throw new WidgetDataScanLimitError(
+        `Too many rows to group encrypted field ${request.groupBy?.field} (limit ${ENCRYPTED_GROUP_SCAN_LIMIT})`,
+      )
+    }
+
+    const encryptionService = resolveTenantEncryptionService(this.em)
+    let dek: TenantDek | null = null
+    try {
+      dek = encryptionService ? await encryptionService.getDek(this.scope.tenantId) : null
+    } catch (err) {
+      logger.error('Failed to resolve the tenant DEK for widget grouping', { err, entityId: source.entityId })
+      dek = null
+    }
+
+    const buckets = new Map<string | null, GroupBucket>()
+    let undecryptableRows = 0
+
+    for (const row of results as Array<Record<string, unknown>>) {
+      const resolvedKey = this.resolveDecryptedGroupKey(row.group_source, source, dek?.key ?? null)
+      // An undecryptable source joins the null ("Unknown") bucket rather than being dropped, so the
+      // widget total still matches the underlying rows.
+      if (resolvedKey === undefined) undecryptableRows += 1
+      const groupKey = resolvedKey === undefined ? null : resolvedKey
+
+      let bucket = buckets.get(groupKey)
+      if (!bucket) {
+        bucket = createGroupBucket()
+        buckets.set(groupKey, bucket)
+      }
+
+      const metricValue = row.metric_value
+      if (metricValue === null || metricValue === undefined) continue
+      bucket.count += 1
+      const numeric = parseExactDecimal(metricValue)
+      if (numeric) foldMetricValue(bucket, numeric)
+    }
+
+    if (undecryptableRows > 0) {
+      // No DEK at all means every ciphertext row would collapse into "Unknown" and the widget would
+      // report a confidently wrong distribution, so fail closed rather than chart it (#4622).
+      if (!dek) {
+        throw new WidgetDataEncryptionUnavailableError(
+          `Cannot group encrypted field ${request.groupBy?.field}: tenant encryption key is unavailable`,
+        )
+      }
+      logger.warn('Grouped rows with an undecryptable group source as unknown', {
+        entityId: source.entityId,
+        column: source.dbColumn,
+        rows: undecryptableRows,
+      })
+    }
+
+    let data: WidgetDataItem[] = Array.from(buckets.entries())
+      .map(([groupKey, bucket]) => ({ groupKey, value: aggregateBucket(request.metric.aggregate, bucket) }))
+      .sort(compareWidgetDataItemsByValueDesc)
+
+    if (request.groupBy?.limit && request.groupBy.limit > 0) {
+      data = data.slice(0, Math.min(request.groupBy.limit, 100))
+    }
+
+    if (request.groupBy?.resolveLabels) {
+      data = await this.resolveGroupLabels(data, request.entityType, request.groupBy.field)
+    }
+
+    const totalValue = data.reduce((sum: number, item: WidgetDataItem) => sum + (item.value ?? 0), 0)
+    return { value: totalValue, data }
+  }
+
+  /**
+   * Returns the plaintext group key for a scanned row, `null` for an empty/absent value, or
+   * `undefined` when the source is ciphertext that could not be decrypted.
+   */
+  private resolveDecryptedGroupKey(
+    rawValue: unknown,
+    source: EncryptedGroupSource,
+    dek: string | null,
+  ): string | null | undefined {
+    if (rawValue === null || rawValue === undefined) return null
+
+    let value: unknown = rawValue
+    if (typeof value === 'string' && this.isEncryptedPayload(value)) {
+      if (!dek) return undefined
+      const decrypted = this.decryptWithDek(value, dek)
+      if (decrypted === null) return undefined
+      value = parseDecryptedFieldValue(decrypted)
+    }
+
+    if (source.jsonPath !== null) {
+      value = readJsonPath(value, source.jsonPath)
+    }
+
+    if (value === null || value === undefined || value === '') return null
+    if (typeof value === 'object') return null
+    const key = String(value)
+    // Defense in depth: a nested value that is itself ciphertext must never reach the response.
+    return this.isEncryptedPayload(key) ? undefined : key
+  }
+
   private async resolveGroupLabels(
     data: WidgetDataItem[],
     entityType: string,
@@ -272,10 +703,13 @@ export class WidgetDataService {
     const config = this.registry.getLabelResolverConfig(entityType, groupByField)
 
     if (!config) {
-      return data.map((item) => ({
-        ...item,
-        groupLabel: item.groupKey != null && item.groupKey !== '' ? String(item.groupKey) : undefined,
-      }))
+      return data.map((item) => {
+        if (item.groupKey == null || item.groupKey === '') return { ...item, groupLabel: undefined }
+        const label = String(item.groupKey)
+        // A ciphertext group key has no meaningful label; echoing it would render encrypted data
+        // into the chart legend (#4622).
+        return { ...item, groupLabel: this.isEncryptedPayload(label) ? undefined : label }
+      })
     }
 
     const ids = data
@@ -432,12 +866,8 @@ export class WidgetDataService {
   }
 
   private resolveEntityMetadata(tableName: string): Record<string, any> | null {
-    const registry = (this.em as any)?.getMetadata?.()
-    if (!registry) return null
-    const entries =
-      (typeof registry.getAll === 'function' && registry.getAll()) ||
-      (Array.isArray(registry.metadata) ? registry.metadata : Object.values(registry.metadata ?? {}))
-    const metas = Array.isArray(entries) ? entries : Object.values(entries ?? {})
+    const metas = listEntityMetadata(this.em)
+    if (!metas.length) return null
     const match = metas.find((meta: any) => {
       const table = meta?.tableName ?? meta?.collection
       if (typeof table !== 'string') return false
@@ -468,6 +898,16 @@ export class WidgetDataService {
     }
   }
 
+  /**
+   * Resolves the encryption entity id for an analytics table. A request-scoped `EntityManager` fork
+   * frequently reports an empty metadata registry, which used to make every group source look
+   * unencrypted and send the request back to the ciphertext-grouping SQL path (#4622). The table
+   * name alone is enough for the entity-id lookup, so it is the fallback.
+   */
+  private resolveEncryptionEntityId(tableName: string): string | null {
+    return this.resolveEntityId(this.resolveEntityMetadata(tableName)) ?? this.resolveEntityId({ tableName })
+  }
+
   private isEncryptedPayload(value: string): boolean {
     const parts = value.split(':')
     return parts.length === 4 && parts[3] === 'v1'
@@ -486,6 +926,7 @@ export function createWidgetDataService(
   scope: WidgetDataScope,
   registry: AnalyticsRegistry,
   cache?: CacheStrategy,
+  baseCurrencyResolver?: BaseCurrencyResolver,
 ): WidgetDataService {
-  return new WidgetDataService({ em, scope, registry, cache })
+  return new WidgetDataService({ em, scope, registry, cache, baseCurrencyResolver })
 }

package/src/modules/dashboards/subscribers/invalidateWidgetDataCache.ts

@@ -0,0 +1,32 @@
+import { runWithCacheTenant } from '@open-mercato/cache'
+
+type CacheService = {
+  deleteByTags(tags: string[]): Promise<number>
+}
+
+export const metadata = {
+  event: 'currencies.currency.*',
+  persistent: false,
+  id: 'dashboards:invalidate-widget-data-on-currency-change',
+}
+
+export default async function handle(
+  payload: unknown,
+  context: { resolve: <T = unknown>(name: string) => T },
+): Promise<void> {
+  const data = (payload ?? {}) as Record<string, unknown>
+  const tenantId = typeof data.tenantId === 'string' ? data.tenantId : null
+  if (!tenantId) return
+
+  let cache: CacheService
+  try {
+    cache = context.resolve<CacheService>('cache')
+  } catch {
+    return
+  }
+
+  try {
+    await runWithCacheTenant(tenantId, () => cache.deleteByTags(['widget-data']))
+  } catch {
+  }
+}

package/src/modules/dashboards/widgets/dashboard/aov-kpi/widget.client.tsx

@@ -3,7 +3,7 @@
 import * as React from 'react'
 import type { DashboardWidgetComponentProps } from '@open-mercato/shared/modules/dashboard/widgets'
 import { useWidgetData, type WidgetDataFetcher } from '@open-mercato/ui/backend/dashboard/widgetData'
-import { useT } from '@open-mercato/shared/lib/i18n/context'
+import { useLocale, useT } from '@open-mercato/shared/lib/i18n/context'
 import { KpiCard, type KpiTrend } from '@open-mercato/ui/backend/charts'
 import {
   DateRangeSelect,
@@ -13,7 +13,8 @@ import {
 } from '@open-mercato/ui/backend/date-range'
 import { DEFAULT_SETTINGS, hydrateSettings, type AovKpiSettings } from './config'
 import type { WidgetDataResponse } from '../../../services/widgetDataService'
-import { formatCurrencyWithDecimals } from '../../../lib/formatters'
+import { createCurrencyFormatters } from '../../../lib/formatters'
+import { UnlabelledAmountNotice } from '../../../components/UnlabelledAmountNotice'
 import { createLogger } from '@open-mercato/shared/lib/logger'
 
 const logger = createLogger('dashboards').child({ component: 'aov-kpi' })
@@ -43,11 +44,14 @@ const AovKpiWidget: React.FC<DashboardWidgetComponentProps<AovKpiSettings>> = ({
   onRefreshStateChange,
 }) => {
   const t = useT()
+  const locale = useLocale()
   const hydrated = React.useMemo(() => hydrateSettings(settings), [settings])
   const [value, setValue] = React.useState<number | null>(null)
   const [trend, setTrend] = React.useState<KpiTrend | undefined>(undefined)
+  const [currency, setCurrency] = React.useState<string | null>(null)
   const [loading, setLoading] = React.useState(true)
   const [error, setError] = React.useState<string | null>(null)
+  const money = React.useMemo(() => createCurrencyFormatters(currency, '--', locale), [currency, locale])
 
   const fetchWidgetData = useWidgetData()
   const refresh = React.useCallback(async () => {
@@ -57,6 +61,7 @@ const AovKpiWidget: React.FC<DashboardWidgetComponentProps<AovKpiSettings>> = ({
     try {
       const data = await fetchAovData(hydrated, fetchWidgetData)
       setValue(data.value)
+      setCurrency(data.metadata?.currency ?? null)
       if (data.comparison) {
         setTrend({
           value: data.comparison.change,
@@ -114,7 +119,8 @@ const AovKpiWidget: React.FC<DashboardWidgetComponentProps<AovKpiSettings>> = ({
       comparisonLabel={comparisonLabel}
       loading={loading}
       error={error}
-      formatValue={formatCurrencyWithDecimals}
+      formatValue={money.formatWithDecimals}
+      footer={<UnlabelledAmountNotice currency={currency} loading={loading} error={error} />}
       headerAction={
         <InlineDateRangeSelect
           value={hydrated.dateRange}