@open-mercato/core 0.9.1-develop.7474.1.51db10479d → 0.9.1-develop.7475.1.28ca93ed97

package/src/modules/catalog/lib/omnibusTypes.ts

@@ -0,0 +1,202 @@
+import { z } from 'zod'
+
+export const PRICE_HISTORY_CHANGE_TYPES = ['create', 'update', 'delete', 'undo'] as const
+
+export const priceHistoryChangeTypeSchema = z.enum(PRICE_HISTORY_CHANGE_TYPES)
+
+export type PriceHistoryChangeType = z.infer<typeof priceHistoryChangeTypeSchema>
+
+export const PRICE_HISTORY_SOURCES = ['api', 'system'] as const
+
+export const priceHistorySourceSchema = z.enum(PRICE_HISTORY_SOURCES)
+
+export type PriceHistorySource = z.infer<typeof priceHistorySourceSchema>
+
+const numericString = z.string().regex(/^-?\d+(\.\d+)?$/)
+
+export const priceHistoryEntrySchema = z.object({
+  tenantId: z.string().uuid(),
+  organizationId: z.string().uuid(),
+  priceId: z.string().uuid(),
+  productId: z.string().uuid(),
+  variantId: z.string().uuid().nullable(),
+  offerId: z.string().uuid().nullable(),
+  channelId: z.string().uuid().nullable(),
+  priceKindId: z.string().uuid(),
+  priceKindCode: z.string().min(1),
+  currencyCode: z.string().length(3),
+  unitPriceNet: numericString.nullable(),
+  unitPriceGross: numericString.nullable(),
+  taxRate: numericString.nullable(),
+  taxAmount: numericString.nullable(),
+  minQuantity: z.number().int().nullable(),
+  maxQuantity: z.number().int().nullable(),
+  startsAt: z.date().nullable(),
+  endsAt: z.date().nullable(),
+  recordedAt: z.date(),
+  changeType: priceHistoryChangeTypeSchema,
+  source: priceHistorySourceSchema,
+  isAnnounced: z.boolean().nullable(),
+  idempotencyKey: z.string().min(1).nullable(),
+  metadata: z.record(z.string(), z.unknown()).nullable(),
+})
+
+export type PriceHistoryEntryInput = z.infer<typeof priceHistoryEntrySchema>
+
+export const OMNIBUS_CONFIG_MODULE_ID = 'catalog'
+
+export const OMNIBUS_CONFIG_NAME = 'omnibus'
+
+export const OMNIBUS_DEFAULT_LOOKBACK_DAYS = 30
+
+export const OMNIBUS_NO_CHANNEL_MODES = ['best_effort', 'require_channel'] as const
+
+export const omnibusNoChannelModeSchema = z.enum(OMNIBUS_NO_CHANNEL_MODES)
+
+export type OmnibusNoChannelMode = z.infer<typeof omnibusNoChannelModeSchema>
+
+export const OMNIBUS_MINIMIZATION_AXES = ['gross', 'net'] as const
+
+export const omnibusMinimizationAxisSchema = z.enum(OMNIBUS_MINIMIZATION_AXES)
+
+export type OmnibusMinimizationAxis = z.infer<typeof omnibusMinimizationAxisSchema>
+
+export const OMNIBUS_APPLICABILITY_REASONS = [
+  'no_history',
+  'not_in_eu_market',
+  'missing_channel_context',
+  'insufficient_history',
+  'announced_promotion',
+  'not_announced',
+  'progressive_reduction_frozen',
+  'perishable_exempt',
+  'perishable_last_price',
+  'new_arrival_reduced_window',
+] as const
+
+export const omnibusApplicabilityReasonSchema = z.enum(OMNIBUS_APPLICABILITY_REASONS)
+
+export type OmnibusApplicabilityReason = z.infer<typeof omnibusApplicabilityReasonSchema>
+
+export const omnibusCountryCodeSchema = z
+  .string()
+  .regex(/^[A-Z]{2}$/)
+  .refine((value) => value !== 'EU')
+
+export const omnibusLookbackDaysSchema = z.number().int().min(1).max(365)
+
+export const omnibusChannelConfigSchema = z.object({
+  presentedPriceKindId: z.string().uuid(),
+  countryCode: omnibusCountryCodeSchema.optional(),
+  lookbackDays: omnibusLookbackDaysSchema.optional(),
+  minimizationAxis: omnibusMinimizationAxisSchema.optional(),
+})
+
+export type OmnibusChannelConfig = z.infer<typeof omnibusChannelConfigSchema>
+
+export const omnibusBackfillCoverageSchema = z.object({
+  completedAt: z.string().datetime({ offset: true }),
+  lookbackDays: omnibusLookbackDaysSchema,
+})
+
+export const omnibusConfigSchema = z.object({
+  enabled: z.boolean().default(false),
+  enabledCountryCodes: z.array(omnibusCountryCodeSchema).default([]),
+  noChannelMode: omnibusNoChannelModeSchema.default('best_effort'),
+  lookbackDays: omnibusLookbackDaysSchema.default(OMNIBUS_DEFAULT_LOOKBACK_DAYS),
+  minimizationAxis: omnibusMinimizationAxisSchema.default('gross'),
+  defaultPresentedPriceKindId: z.string().uuid().optional(),
+  backfillCoverage: z.record(z.string(), omnibusBackfillCoverageSchema).default({}),
+  channels: z.record(z.string().uuid(), omnibusChannelConfigSchema).default({}),
+})
+
+export type OmnibusConfig = z.infer<typeof omnibusConfigSchema>
+
+export type OmnibusResolutionContext = {
+  tenantId: string
+  organizationId: string
+  productId?: string | null
+  variantId?: string | null
+  offerId?: string | null
+  channelId?: string | null
+  priceKindId?: string | null
+  currencyCode: string
+  isStorefront?: boolean
+  now?: Date
+}
+
+export type OmnibusPresentedEntry = {
+  priceId: string
+  changeType: PriceHistoryChangeType
+  recordedAt: Date | string
+  startsAt?: Date | string | null
+  offerId?: string | null
+  isAnnounced?: boolean | null
+}
+
+export type OmnibusResolutionRequest = {
+  context: OmnibusResolutionContext
+  presentedEntry?: OmnibusPresentedEntry | null
+  priceKindIsPromotion?: boolean
+}
+
+/** Undo of this command removes the price, so its history row is a tombstone, not a price observation. */
+export const OMNIBUS_PRICE_REMOVING_UNDO_COMMAND = 'catalog.prices.create'
+
+export type OmnibusHistoryRow = {
+  id: string
+  priceId: string
+  changeType: PriceHistoryChangeType
+  recordedAt: string
+  unitPriceNet: string | null
+  unitPriceGross: string | null
+  undoneCommand?: string | null
+}
+
+export type OmnibusLowestPriceResult = {
+  reason: OmnibusApplicabilityReason | null
+  presentedPriceKindId: string | null
+  lowestRow: OmnibusHistoryRow | null
+  previousRow: OmnibusHistoryRow | null
+  insufficientHistory: boolean
+  promotionAnchorAt: string | null
+  coverageStartAt: string | null
+  windowStart: string | null
+  windowEnd: string | null
+  lookbackDays: number
+  minimizationAxis: OmnibusMinimizationAxis
+}
+
+export type OmnibusBlock = {
+  presentedPriceKindId: string | null
+  lookbackDays: number
+  minimizationAxis: OmnibusMinimizationAxis
+  promotionAnchorAt: string | null
+  windowStart: string | null
+  windowEnd: string | null
+  coverageStartAt: string | null
+  lowestPriceNet: string | null
+  lowestPriceGross: string | null
+  previousPriceNet: string | null
+  previousPriceGross: string | null
+  currencyCode: string
+  applicable: boolean
+  applicabilityReason: OmnibusApplicabilityReason
+}
+
+export const omnibusBlockSchema = z.object({
+  presentedPriceKindId: z.string().uuid().nullable(),
+  lookbackDays: z.number().int(),
+  minimizationAxis: omnibusMinimizationAxisSchema,
+  promotionAnchorAt: z.string().nullable(),
+  windowStart: z.string().nullable(),
+  windowEnd: z.string().nullable(),
+  coverageStartAt: z.string().nullable(),
+  lowestPriceNet: z.string().nullable(),
+  lowestPriceGross: z.string().nullable(),
+  previousPriceNet: z.string().nullable(),
+  previousPriceGross: z.string().nullable(),
+  currencyCode: z.string(),
+  applicable: z.boolean(),
+  applicabilityReason: omnibusApplicabilityReasonSchema,
+}) satisfies z.ZodType<OmnibusBlock>

package/src/modules/catalog/lib/optionSchemaTranslations.ts

@@ -0,0 +1,55 @@
+import type { TranslatableFieldExpansion } from '@open-mercato/shared/lib/localization/translatable-fields'
+
+export const OPTION_SCHEMA_TEMPLATE_ENTITY_TYPE = 'catalog:catalog_option_schema_template'
+
+export function optionLabelTranslationField(optionCode: string): string {
+  return `options.${optionCode}.label`
+}
+
+export function optionChoiceLabelTranslationField(optionCode: string, choiceCode: string): string {
+  return `options.${optionCode}.choices.${choiceCode}.label`
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length > 0 ? value.trim() : null
+}
+
+export function expandOptionSchemaTranslationFields(record: Record<string, unknown>): TranslatableFieldExpansion[] {
+  const schema = isRecord(record.schema) ? record.schema : null
+  const options = schema && Array.isArray(schema.options) ? schema.options : []
+  const expansions: TranslatableFieldExpansion[] = []
+  const seen = new Set<string>()
+  const push = (expansion: TranslatableFieldExpansion) => {
+    if (seen.has(expansion.key)) return
+    seen.add(expansion.key)
+    expansions.push(expansion)
+  }
+  for (const option of options) {
+    if (!isRecord(option)) continue
+    const optionCode = nonEmptyText(option.code)
+    if (!optionCode) continue
+    const optionLabel = nonEmptyText(option.label) ?? optionCode
+    push({
+      key: optionLabelTranslationField(optionCode),
+      label: optionLabel,
+      baseValue: nonEmptyText(option.label) ?? '',
+    })
+    const choices = Array.isArray(option.choices) ? option.choices : []
+    for (const choice of choices) {
+      if (!isRecord(choice)) continue
+      const choiceCode = nonEmptyText(choice.code)
+      if (!choiceCode) continue
+      const choiceLabel = nonEmptyText(choice.label)
+      push({
+        key: optionChoiceLabelTranslationField(optionCode, choiceCode),
+        label: `${optionLabel} › ${choiceLabel ?? choiceCode}`,
+        baseValue: choiceLabel ?? '',
+      })
+    }
+  }
+  return expansions
+}

package/src/modules/catalog/lib/priceHistoryQuery.ts

@@ -0,0 +1,155 @@
+import { z } from 'zod'
+import type { FilterQuery } from '@mikro-orm/postgresql'
+import type { CatalogPriceHistoryEntry } from '../data/entities'
+import type { PriceHistoryQuery } from '../data/validators'
+import type { PriceHistoryChangeType, PriceHistorySource } from './omnibusTypes'
+
+export type PriceHistoryCursor = {
+  recordedAt: string
+  id: string
+}
+
+const cursorSchema = z.object({
+  recordedAt: z.string().datetime({ offset: true }),
+  id: z.string().uuid(),
+})
+
+export function encodePriceHistoryCursor(cursor: PriceHistoryCursor): string {
+  return Buffer.from(JSON.stringify(cursor), 'utf8').toString('base64')
+}
+
+export function decodePriceHistoryCursor(value: string | null | undefined): PriceHistoryCursor | null {
+  if (typeof value !== 'string' || value.trim().length === 0) return null
+  try {
+    const decoded = Buffer.from(value.trim(), 'base64').toString('utf8')
+    const parsed = cursorSchema.safeParse(JSON.parse(decoded))
+    if (!parsed.success) return null
+    return { recordedAt: new Date(parsed.data.recordedAt).toISOString(), id: parsed.data.id }
+  } catch {
+    return null
+  }
+}
+
+export type PriceHistoryScope = {
+  tenantId: string
+  organizationIds: string[] | null
+}
+
+export type PriceHistoryOrganizationScopeInput = {
+  selectedId: string | null
+  filterIds: string[] | null
+  allowedIds: string[] | null
+}
+
+export function resolvePriceHistoryOrganizationIds(
+  scope: PriceHistoryOrganizationScopeInput,
+  authOrganizationId: string | null | undefined,
+): string[] | null {
+  if (scope.selectedId) return [scope.selectedId]
+  if (Array.isArray(scope.filterIds) && scope.filterIds.length > 0) return Array.from(new Set(scope.filterIds))
+  if (scope.filterIds === null && scope.allowedIds === null) return null
+  return authOrganizationId ? [authOrganizationId] : []
+}
+
+export function buildPriceHistoryWhere(
+  scope: PriceHistoryScope,
+  query: PriceHistoryQuery,
+): FilterQuery<CatalogPriceHistoryEntry> {
+  const where: Record<string, unknown> = { tenantId: scope.tenantId }
+  if (scope.organizationIds) where.organizationId = { $in: scope.organizationIds }
+  if (query.productId) where.productId = query.productId
+  if (query.variantId) where.variantId = query.variantId
+  if (query.priceKindId) where.priceKindId = query.priceKindId
+  if (query.channelId) where.channelId = query.channelId
+  if (query.currencyCode) where.currencyCode = query.currencyCode
+  const recordedAt: Record<string, Date> = {}
+  if (query.from) recordedAt.$gte = new Date(query.from)
+  if (query.to) recordedAt.$lte = new Date(query.to)
+  if (Object.keys(recordedAt).length > 0) where.recordedAt = recordedAt
+  return where as FilterQuery<CatalogPriceHistoryEntry>
+}
+
+export function applyPriceHistoryCursor(
+  where: FilterQuery<CatalogPriceHistoryEntry>,
+  cursor: PriceHistoryCursor | null,
+): FilterQuery<CatalogPriceHistoryEntry> {
+  if (!cursor) return where
+  const recordedAt = new Date(cursor.recordedAt)
+  return {
+    $and: [
+      where,
+      {
+        $or: [
+          { recordedAt: { $lt: recordedAt } },
+          { recordedAt, id: { $lt: cursor.id } },
+        ],
+      },
+    ],
+  } as FilterQuery<CatalogPriceHistoryEntry>
+}
+
+export function formatFixedDecimal4(value: string | number | null | undefined): string | null {
+  if (value === null || value === undefined) return null
+  const raw = typeof value === 'number' ? value.toFixed(4) : value.trim()
+  const match = /^(-?)(\d+)(?:\.(\d*))?$/.exec(raw)
+  if (!match) return raw
+  const [, sign, whole, fraction = ''] = match
+  const normalizedFraction = fraction.length >= 4 ? fraction.slice(0, 4) : fraction.padEnd(4, '0')
+  return `${sign}${whole}.${normalizedFraction}`
+}
+
+function toIsoOrNull(value: Date | string | null | undefined): string | null {
+  if (!value) return null
+  const date = value instanceof Date ? value : new Date(value)
+  return Number.isNaN(date.getTime()) ? null : date.toISOString()
+}
+
+export type PriceHistoryItem = {
+  id: string
+  priceId: string
+  productId: string
+  variantId: string | null
+  offerId: string | null
+  channelId: string | null
+  priceKindId: string
+  priceKindCode: string
+  currencyCode: string
+  unitPriceNet: string | null
+  unitPriceGross: string | null
+  taxRate: string | null
+  taxAmount: string | null
+  minQuantity: number | null
+  maxQuantity: number | null
+  startsAt: string | null
+  endsAt: string | null
+  recordedAt: string
+  changeType: PriceHistoryChangeType
+  source: PriceHistorySource
+  isAnnounced: boolean
+}
+
+export function serializePriceHistoryEntry(entry: CatalogPriceHistoryEntry): PriceHistoryItem {
+  return {
+    id: entry.id,
+    priceId: entry.priceId,
+    productId: entry.productId,
+    variantId: entry.variantId ?? null,
+    offerId: entry.offerId ?? null,
+    channelId: entry.channelId ?? null,
+    priceKindId: entry.priceKindId,
+    priceKindCode: entry.priceKindCode,
+    currencyCode: entry.currencyCode,
+    unitPriceNet: formatFixedDecimal4(entry.unitPriceNet),
+    unitPriceGross: formatFixedDecimal4(entry.unitPriceGross),
+    taxRate: formatFixedDecimal4(entry.taxRate),
+    taxAmount: formatFixedDecimal4(entry.taxAmount),
+    minQuantity: entry.minQuantity ?? null,
+    maxQuantity: entry.maxQuantity ?? null,
+    startsAt: toIsoOrNull(entry.startsAt),
+    endsAt: toIsoOrNull(entry.endsAt),
+    recordedAt: toIsoOrNull(entry.recordedAt) ?? new Date(0).toISOString(),
+    changeType: entry.changeType,
+    source: entry.source,
+    isAnnounced: entry.isAnnounced === true,
+  }
+}

package/src/modules/catalog/lib/pricing.ts

@@ -20,6 +20,15 @@ export type PricingContext = {
   customerGroupIds?: string[]
   /** When set, only rows in this currency match. Omitted (the default): no currency filtering, unchanged legacy behavior. */
   currencyCode?: string | null
+  /**
+   * When set, only rows of this price kind (by `CatalogPriceKind` id) match, plus rows of any promotional
+   * kind (`CatalogPriceKind.isPromotion === true`) as an overlay (pricing-engine amendment D2a). Promotion
+   * status is read from a populated `priceKind`; a row carrying only a kind id string is admitted solely when
+   * that id equals this one. Unset or `null`: kind is not filtered, unchanged legacy behavior.
+   */
+  priceKindId?: string | null
+  /** The buyer's customer entities, person first, then company. A row's `customerId` matches when it appears in this list. Falls back to `customerId` (above) when omitted. */
+  customerIds?: string[]
   quantity: number
   date: Date
 }
@@ -47,6 +56,23 @@ export function resolvePriceChannelId(row: PriceRow): string | null {
   return row.channelId ?? row.offer.channelId ?? null
 }
 
+export function resolvePriceKindId(row: PriceRow): string | null {
+  if (!row.priceKind) return null
+  return typeof row.priceKind === 'string' ? row.priceKind : row.priceKind.id ?? null
+}
+
+function resolveContextCustomerIds(ctx: PricingContext): string[] {
+  return ctx.customerIds ?? (ctx.customerId ? [ctx.customerId] : [])
+}
+
+function isPromotionalPriceKindRow(row: PriceRow): boolean {
+  return Boolean(row.priceKind && typeof row.priceKind !== 'string' && row.priceKind.isPromotion === true)
+}
+
+function matchesPriceKind(row: PriceRow, priceKindId: string): boolean {
+  return resolvePriceKindId(row) === priceKindId || isPromotionalPriceKindRow(row)
+}
+
 export function resolvePriceKindCode(row: PriceRow): string {
   if (row.priceKind) {
     if (typeof row.priceKind === 'string') return row.priceKind
@@ -68,12 +94,13 @@ function matchesContext(row: PriceRow, ctx: PricingContext): boolean {
   }
   if (row.userId && ctx.userId !== row.userId) return false
   if (row.userGroupId && ctx.userGroupId !== row.userGroupId) return false
-  if (row.customerId && ctx.customerId !== row.customerId) return false
+  if (row.customerId && !resolveContextCustomerIds(ctx).includes(row.customerId)) return false
   if (row.customerGroupId) {
     const candidateGroupIds = ctx.customerGroupIds ?? (ctx.customerGroupId ? [ctx.customerGroupId] : [])
     if (!candidateGroupIds.includes(row.customerGroupId)) return false
   }
   if (ctx.currencyCode && row.currencyCode !== ctx.currencyCode) return false
+  if (ctx.priceKindId && !matchesPriceKind(row, ctx.priceKindId)) return false
   if (ctx.offerId && resolvePriceOfferId(row) && resolvePriceOfferId(row) !== ctx.offerId) return false
   return true
 }
@@ -86,7 +113,8 @@ function matchesContext(row: PriceRow, ctx: PricingContext): boolean {
  * `.ai/specs/2026-08-21-pricing-engine.md` § Row narrowing).
  *
  * Covers only the dimensions that are plain column comparisons: customer,
- * customer-group, user, user-group, channel, currency. Quantity bounds,
+ * customer-group, user, user-group, channel, currency, price kind (the resolved
+ * kind or any promotional kind, via a `priceKind.isPromotion` relation clause). Quantity bounds,
  * validity windows, and offer-derived channel resolution stay in
  * `matchesContext` — they are cheap over an already-narrowed set and are not
  * expressible as one column predicate (offer's own `channelId` lives on a
@@ -101,10 +129,11 @@ function matchesContext(row: PriceRow, ctx: PricingContext): boolean {
  */
 export function buildPriceRowFilter(ctx: PricingContext): FilterQuery<CatalogProductPrice> {
   const customerGroupIds = ctx.customerGroupIds ?? (ctx.customerGroupId ? [ctx.customerGroupId] : [])
+  const customerIds = resolveContextCustomerIds(ctx)
 
   const clauses: FilterQuery<CatalogProductPrice>[] = [
-    ctx.customerId
-      ? { $or: [{ customerId: null }, { customerId: ctx.customerId }] }
+    customerIds.length
+      ? { $or: [{ customerId: null }, { customerId: { $in: customerIds } }] }
       : { customerId: null },
     customerGroupIds.length
       ? { $or: [{ customerGroupId: null }, { customerGroupId: { $in: customerGroupIds } }] }
@@ -124,6 +153,10 @@ export function buildPriceRowFilter(ctx: PricingContext): FilterQuery<CatalogPro
     clauses.push({ currencyCode: ctx.currencyCode })
   }
 
+  if (ctx.priceKindId) {
+    clauses.push({ $or: [{ priceKind: ctx.priceKindId }, { priceKind: { isPromotion: true } }] })
+  }
+
   return { $and: clauses } as FilterQuery<CatalogProductPrice>
 }
 
@@ -148,9 +181,14 @@ function scorePrice(row: PriceRow): number {
 export function selectBestPrice(rows: PriceRow[], ctx: PricingContext): PriceRow | null {
   const candidates = rows.filter((row) => matchesContext(row, ctx))
   if (!candidates.length) return null
+  const customerIds = resolveContextCustomerIds(ctx)
+  const customerRank = (row: PriceRow): number => (row.customerId ? customerIds.indexOf(row.customerId) : -1)
   candidates.sort((a, b) => {
     const scoreDiff = scorePrice(b) - scorePrice(a)
     if (scoreDiff !== 0) return scoreDiff
+    const rankA = customerRank(a)
+    const rankB = customerRank(b)
+    if (rankA >= 0 && rankB >= 0 && rankA !== rankB) return rankA - rankB
     const startA = a.startsAt ? a.startsAt.getTime() : 0
     const startB = b.startsAt ? b.startsAt.getTime() : 0
     if (startA !== startB) return startB - startA