@open-mercato/core 0.9.1-develop.7473.1.de5b22888f → 0.9.1-develop.7475.1.28ca93ed97

package/src/modules/catalog/api/products/route.ts

@@ -1,12 +1,8 @@
 import { z } from "zod";
 import type { EntityManager } from "@mikro-orm/postgresql";
-import { raw } from "@mikro-orm/postgresql";
 import { makeCrudRoute } from "@open-mercato/shared/lib/crud/factory";
 import { CrudHttpError } from "@open-mercato/shared/lib/crud/errors";
-import {
-  buildCustomFieldFiltersFromQuery,
-  extractAllCustomFieldEntries,
-} from "@open-mercato/shared/lib/crud/custom-fields";
+import { extractAllCustomFieldEntries } from "@open-mercato/shared/lib/crud/custom-fields";
 import { resolveTranslations } from "@open-mercato/shared/lib/i18n/server";
 import {
   CatalogOffer,
@@ -18,7 +14,6 @@ import {
   CatalogProductVariant,
   CatalogProductTagAssignment,
 } from "../../data/entities";
-import { CATALOG_PRODUCT_TYPES } from "../../data/types";
 import type { CatalogProductType } from "../../data/types";
 import {
   productCreateSchema,
@@ -28,7 +23,7 @@ import { parseScopedCommandInput, resolveCrudRecordId } from "../utils";
 import { splitCustomFieldPayload } from "@open-mercato/shared/lib/crud/custom-fields";
 import { E } from "#generated/entities.ids.generated";
 import * as F from "#generated/entities/catalog_product";
-import { parseBooleanFlag, sanitizeSearchTerm } from "../helpers";
+import { sanitizeSearchTerm } from "../helpers";
 import type { CrudCtx } from "@open-mercato/shared/lib/crud/factory";
 import { buildScopedWhere } from "@open-mercato/shared/lib/api/crud";
 import {
@@ -40,7 +35,6 @@ import {
   type PriceRow,
 } from "../../lib/pricing";
 import type { CatalogPricingService } from "../../services/catalogPricingService";
-import { fieldsetCodeRegex } from "@open-mercato/core/modules/entities/data/validators";
 import { SalesChannel } from "@open-mercato/core/modules/sales/data/entities";
 import {
   createCatalogCrudOpenApi,
@@ -48,51 +42,28 @@ import {
   defaultOkResponseSchema,
 } from "../openapi";
 import { findWithDecryption } from "@open-mercato/shared/lib/encryption/find";
-import { warnOnEncryptedLikeFilter } from "@open-mercato/shared/lib/encryption/likeFilterWarning";
-import { buildAccentInsensitiveContainsPatternSql } from "@open-mercato/shared/lib/db/accentInsensitiveSearch";
-import {
-  PRODUCT_SEARCH_COLUMNS,
-  PRODUCT_SEARCH_EXPRESSION_SQL,
-} from "../../lib/productSearch";
 import { canonicalizeUnitCode, toUnitLookupKey } from "../../lib/unitCodes";
+import {
+  attachProductListOmnibusBlocks,
+  type OmnibusProductListEntry,
+} from "../../lib/omnibusProductListEnrichment";
+import { omnibusBlockSchema, type OmnibusBlock } from "../../lib/omnibusTypes";
+import {
+  buildProductFilters,
+  catalogProductFilterQuerySchema,
+  parseIdList,
+  scoreProductSearchRelevance,
+  type CatalogProductFilterQuery,
+} from "../../lib/productFilters";
 import { createLogger } from '@open-mercato/shared/lib/logger'
+import { getTelemetryRuntime } from '@open-mercato/shared/lib/telemetry/runtime'
 
 const logger = createLogger('catalog')
 const rawBodySchema = z.object({}).passthrough();
 
-const UUID_REGEX =
-  /^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$/;
-
-const listSchema = z
-  .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(),
-    status: z.string().optional(),
-    isActive: z.string().optional(),
-    configurable: z.string().optional(),
-    productType: z.enum(CATALOG_PRODUCT_TYPES).optional(),
-    channelIds: z.string().optional(),
-    channelId: z.string().uuid().optional(),
-    categoryIds: z.string().optional(),
-    tagIds: z.string().optional(),
-    offerId: z.string().uuid().optional(),
-    userId: z.string().uuid().optional(),
-    userGroupId: z.string().uuid().optional(),
-    customerId: z.string().uuid().optional(),
-    customerGroupId: z.string().uuid().optional(),
-    quantity: z.coerce.number().min(1).max(100000).optional(),
-    quantityUnit: z.string().trim().max(50).optional(),
-    priceDate: z.string().optional(),
-    sortField: z.string().optional(),
-    sortDir: z.enum(["asc", "desc"]).optional(),
-    withDeleted: z.coerce.boolean().optional(),
-    customFieldset: z.string().regex(fieldsetCodeRegex).optional(),
-  })
-  .passthrough();
+const listSchema = catalogProductFilterQuerySchema;
 
-type ProductsQuery = z.infer<typeof listSchema>;
+type ProductsQuery = CatalogProductFilterQuery;
 
 const routeMetadata = {
   GET: { requireAuth: true, requireFeatures: ["catalog.products.view"] },
@@ -103,252 +74,11 @@ const routeMetadata = {
 
 export const metadata = routeMetadata;
 
-export function parseIdList(raw?: string): string[] {
-  if (!raw) return [];
-  return raw
-    .split(",")
-    .map((value) => value.trim())
-    .filter((value) => UUID_REGEX.test(value));
-}
-
-export async function buildProductFilters(
-  query: ProductsQuery,
-  ctx: CrudCtx,
-): Promise<Record<string, unknown>> {
-  const filters: Record<string, unknown> = {};
-  const em = (ctx.container.resolve("em") as EntityManager).fork();
-  const restrictedProductIds: { value: Set<string> | null } = { value: null };
-
-  const intersectProductIds = (ids: string[]) => {
-    const normalized = ids.filter(
-      (id): id is string => typeof id === "string" && id.trim().length > 0,
-    );
-    const current = new Set(normalized);
-    if (!current.size) {
-      restrictedProductIds.value = new Set();
-      return;
-    }
-    if (!restrictedProductIds.value) {
-      restrictedProductIds.value = current;
-      return;
-    }
-    restrictedProductIds.value = new Set(
-      Array.from(restrictedProductIds.value).filter((id) => current.has(id)),
-    );
-  };
-
-  const applyRestrictedProducts = () => {
-    if (!restrictedProductIds.value) return;
-    if (restrictedProductIds.value.size === 0) {
-      filters.id = { $eq: "00000000-0000-0000-0000-000000000000" };
-      return;
-    }
-    const ids = Array.from(restrictedProductIds.value);
-    const existing = filters.id as Record<string, unknown> | undefined;
-    if (existing && typeof existing === "object") {
-      if (
-        "$eq" in existing &&
-        typeof (existing as { $eq?: unknown }).$eq === "string"
-      ) {
-        const target = (existing as { $eq: string }).$eq;
-        if (!restrictedProductIds.value.has(target)) {
-          filters.id = { $eq: "00000000-0000-0000-0000-000000000000" };
-        }
-        return;
-      }
-      if (
-        "$in" in existing &&
-        Array.isArray((existing as { $in?: unknown }).$in)
-      ) {
-        const subset = (existing as { $in: string[] }).$in.filter((id) =>
-          restrictedProductIds.value!.has(id),
-        );
-        filters.id = subset.length
-          ? { $in: subset }
-          : { $eq: "00000000-0000-0000-0000-000000000000" };
-        return;
-      }
-    }
-    filters.id = ids.length === 1 ? { $eq: ids[0] } : { $in: ids };
-  };
-  if (query.id) {
-    filters.id = { $eq: query.id };
-  }
-  if (query.status && query.status.trim()) {
-    filters.status_entry_id = { $eq: query.status.trim() };
-  }
-  const active = parseBooleanFlag(query.isActive);
-  if (active !== undefined) {
-    filters.is_active = active;
-  }
-  const configurable = parseBooleanFlag(query.configurable);
-  if (configurable !== undefined) {
-    filters.is_configurable = configurable;
-  }
-  if (query.productType) {
-    filters.product_type = { $eq: query.productType };
-  }
-  const scope = {
-    organizationId: ctx.selectedOrganizationId ?? ctx.auth?.orgId ?? null,
-    tenantId: ctx.auth?.tenantId ?? null,
-  };
-  const scopeWhere = buildScopedWhere(
-    {},
-    {
-      organizationId: scope.organizationId,
-      organizationIds: ctx.organizationIds ?? undefined,
-      tenantId: scope.tenantId,
-      orgField: ctx.organizationIds === null ? null : undefined,
-      softDeleteField: null,
-    },
-  );
-  const term = sanitizeSearchTerm(query.search);
-  const channelFilterIds = parseIdList(query.channelIds);
-  const categoryFilterIds = parseIdList(query.categoryIds);
-  const tagFilterIds = parseIdList(query.tagIds);
-  const customFieldset =
-    typeof query.customFieldset === "string" &&
-    query.customFieldset.trim().length
-      ? query.customFieldset.trim()
-      : null;
-  const tenantId = ctx.auth?.tenantId ?? null;
-
-  // These prequeries are independent — each only feeds the final product-id
-  // intersection, none depends on another's result — so dispatch them together
-  // instead of awaiting one after another (#3179). A task returns null when its
-  // filter is inactive (intersection skipped) or the matched product-id list
-  // (possibly empty) when active, preserving the "active filter with no matches
-  // => empty result" behavior.
-  const searchTask = async (): Promise<string[] | null> => {
-    if (!term) return null;
-    // The predicate hides behind a raw() symbol key, which the filter walker in
-    // findWithDecryption cannot see (Object.entries skips symbols), so the
-    // encrypted-ILIKE diagnostic is raised here with the field list instead.
-    // Without it, a tenant that encrypts one of these columns at rest gets an
-    // empty result indistinguishable from a genuine no-match (#5051). It runs
-    // alongside the query rather than before it: it is a development-only
-    // diagnostic and must not add a round trip to the request path.
-    const [searchMatches] = await Promise.all([
-      findWithDecryption(
-        em,
-        CatalogProduct,
-        {
-          ...scopeWhere,
-          ...(query.withDeleted ? {} : { deletedAt: null }),
-          [raw(PRODUCT_SEARCH_EXPRESSION_SQL)]: {
-            $ilike: raw(buildAccentInsensitiveContainsPatternSql(), [term]),
-          },
-        },
-        { fields: ["id"] },
-        scope,
-      ),
-      warnOnEncryptedLikeFilter({
-        em,
-        entityName: CatalogProduct,
-        likeFields: [...PRODUCT_SEARCH_COLUMNS],
-        tenantId: scope.tenantId,
-      }),
-    ]);
-    return searchMatches
-      .map((product) => product.id)
-      .filter((id): id is string => typeof id === "string" && id.length > 0);
-  };
-
-  const channelTask = async (): Promise<string[] | null> => {
-    if (!channelFilterIds.length) return null;
-    const offerRows = await findWithDecryption(
-      em,
-      CatalogOffer,
-      {
-        channelId: { $in: channelFilterIds },
-        deletedAt: null,
-        ...scopeWhere,
-      },
-      { fields: ["id", "product"] },
-      scope,
-    );
-    return offerRows
-      .map((offer) =>
-        typeof offer.product === "string"
-          ? offer.product
-          : (offer.product?.id ?? null),
-      )
-      .filter((id): id is string => !!id);
-  };
-
-  const categoryTask = async (): Promise<string[] | null> => {
-    if (!categoryFilterIds.length) return null;
-    const assignments = await findWithDecryption(
-      em,
-      CatalogProductCategoryAssignment,
-      { category: { $in: categoryFilterIds }, ...scopeWhere },
-      { fields: ["id", "product"] },
-      scope,
-    );
-    return assignments
-      .map((assignment) =>
-        typeof assignment.product === "string"
-          ? assignment.product
-          : (assignment.product?.id ?? null),
-      )
-      .filter((id): id is string => !!id);
-  };
-
-  const tagTask = async (): Promise<string[] | null> => {
-    if (!tagFilterIds.length) return null;
-    const assignments = await findWithDecryption(
-      em,
-      CatalogProductTagAssignment,
-      { tag: { $in: tagFilterIds }, ...scopeWhere },
-      { fields: ["id", "product"] },
-      scope,
-    );
-    return assignments
-      .map((assignment) =>
-        typeof assignment.product === "string"
-          ? assignment.product
-          : (assignment.product?.id ?? null),
-      )
-      .filter((id): id is string => !!id);
-  };
-
-  const customFieldTask = async (): Promise<Record<string, unknown>> => {
-    try {
-      const scopedEm = ctx.container.resolve("em") as EntityManager;
-      return await buildCustomFieldFiltersFromQuery({
-        entityIds: [E.catalog.catalog_product],
-        query,
-        em: scopedEm,
-        tenantId,
-        fieldset: customFieldset ?? undefined,
-      });
-    } catch (err) {
-      // Custom field filter parsing may fail for non-existent or misconfigured fields.
-      // Fall back to base filters to avoid blocking the product listing.
-      logger.debug('catalog.products custom field filter error', { err });
-      return {};
-    }
-  };
-
-  const [searchIds, channelIds, categoryIds, tagIds, cfFilters] =
-    await Promise.all([
-      searchTask(),
-      channelTask(),
-      categoryTask(),
-      tagTask(),
-      customFieldTask(),
-    ]);
-
-  // Apply intersections in the original order; intersection is commutative, so
-  // the result is identical to the previous sequential pass. An empty array is
-  // still intersected (active filter that matched nothing); null is skipped.
-  for (const productIds of [searchIds, channelIds, categoryIds, tagIds]) {
-    if (productIds) intersectProductIds(productIds);
-  }
-  Object.assign(filters, cfFilters);
-  applyRestrictedProducts();
-  return filters;
-}
+export {
+  buildProductFilters,
+  parseIdList,
+  scoreProductSearchRelevance,
+} from "../../lib/productFilters";
 
 export function buildPricingContext(
   query: ProductsQuery,
@@ -402,6 +132,7 @@ type ProductListItem = Record<string, unknown> & {
   categories?: Array<Record<string, unknown>>;
   categoryIds?: string[];
   tags?: string[];
+  omnibus?: OmnibusBlock;
 };
 
 async function decorateProductsAfterList(
@@ -753,10 +484,20 @@ async function decorateProductsAfterList(
     }
     const priceResults = await pricingService.resolvePriceMany(resolveInputs);
 
+    const omnibusEntries: OmnibusProductListEntry[] = [];
     for (let i = 0; i < resolveIndices.length; i++) {
       const item = items[resolveIndices[i]];
       const best = priceResults[i];
       if (best) {
+        if (typeof item.id === "string") {
+          omnibusEntries.push({
+            item,
+            productId: item.id,
+            candidates: resolveInputs[i].rows,
+            best,
+            context: resolveInputs[i].context,
+          });
+        }
         item.pricing = {
           kind: resolvePriceKindCode(best),
           price_kind_id:
@@ -785,6 +526,21 @@ async function decorateProductsAfterList(
         item.pricing = null;
       }
     }
+
+    try {
+      await attachProductListOmnibusBlocks({
+        em,
+        container: ctx.container,
+        tenantId: ctx.auth?.tenantId ?? null,
+        entries: omnibusEntries,
+      });
+    } catch (error) {
+      logger.error('decorateProductsAfterList failed to attach Omnibus blocks', { err: error });
+      getTelemetryRuntime()?.reportError(error, {
+        module: 'catalog',
+        code: 'catalog.omnibus_product_list_failed',
+      });
+    }
   } catch (error) {
     logger.error('decorateProductsAfterList Failed to load unit conversions', { err: error });
   }
@@ -801,22 +557,6 @@ async function decorateProductsAfterList(
   }
 }
 
-export function scoreProductSearchRelevance(
-  needle: string,
-  title: string | null | undefined,
-  sku: string | null | undefined,
-): number {
-  const t = (title ?? "").toLowerCase();
-  const s = (sku ?? "").toLowerCase();
-  if (t === needle) return 0;
-  if (s === needle) return 1;
-  if (t.startsWith(needle)) return 2;
-  if (s.startsWith(needle)) return 3;
-  if (t.includes(needle)) return 4;
-  if (s.includes(needle)) return 5;
-  return 6;
-}
-
 const crud = makeCrudRoute({
   metadata: routeMetadata,
   orm: {
@@ -1073,6 +813,11 @@ const productListItemSchema = z.object({
   categoryIds: z.array(z.string()).optional(),
   tags: z.array(z.string()).optional(),
   pricing: z.record(z.string(), z.unknown()).nullable().optional(),
+  omnibus: omnibusBlockSchema
+    .optional()
+    .describe(
+      "EU Omnibus reference-price block for the presented price. Present only when Omnibus is enabled for the tenant and the product has a resolved price.",
+    ),
 });
 
 export const openApi = createCatalogCrudOpenApi({

package/src/modules/catalog/api/tags/route.ts

@@ -10,6 +10,7 @@ import { CatalogProductTag } from '../../data/entities'
 import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
 import { createPagedListResponseSchema } from '../openapi'
 import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
+import { isIdsParamProvided, parseIdsParam } from '@open-mercato/shared/lib/crud/ids'
 
 const routeMetadata = {
   GET: { requireAuth: true, requireFeatures: ['catalog.products.view'] },
@@ -20,6 +21,7 @@ export const metadata = routeMetadata
 const querySchema = z
   .object({
     search: z.string().optional(),
+    ids: z.string().optional().describe('Comma-separated tag ids to return; malformed ids match nothing.'),
     page: z.coerce.number().min(1).default(1),
     pageSize: z.coerce.number().min(1).max(200).default(50),
   })
@@ -34,6 +36,7 @@ export async function GET(req: Request) {
   const url = new URL(req.url)
   const parsed = querySchema.safeParse({
     search: url.searchParams.get('search') ?? undefined,
+    ids: url.searchParams.get('ids') ?? undefined,
     page: url.searchParams.get('page') ?? undefined,
     pageSize: url.searchParams.get('pageSize') ?? undefined,
   })
@@ -68,6 +71,9 @@ export async function GET(req: Request) {
   if (search) {
     where.label = { $ilike: `%${escapeLikePattern(search)}%` }
   }
+  if (isIdsParamProvided(query.ids)) {
+    where.id = { $in: parseIdsParam(query.ids) }
+  }
 
   const limit = query.pageSize
   const offset = (query.page - 1) * query.pageSize

package/src/modules/catalog/backend/config/catalog/page.tsx

@@ -1,6 +1,7 @@
 import { Page, PageBody } from '@open-mercato/ui/backend/Page'
 import { PriceKindSettings } from '../../../components/PriceKindSettings'
 import { UnitPriceDisplaySettings } from '../../../components/UnitPriceDisplaySettings'
+import { OmnibusSettings } from '../../../components/OmnibusSettings'
 
 export default function CatalogConfigurationPage() {
   return (
@@ -8,6 +9,7 @@ export default function CatalogConfigurationPage() {
       <PageBody className="space-y-8">
         <PriceKindSettings />
         <UnitPriceDisplaySettings />
+        <OmnibusSettings />
       </PageBody>
     </Page>
   )

package/src/modules/catalog/cli.ts

@@ -1,6 +1,12 @@
 import type { ModuleCli } from '@open-mercato/shared/modules/registry'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
+import { runWithCacheTenant } from '@open-mercato/cache'
 import type { EntityManager } from '@mikro-orm/postgresql'
+import type { ModuleConfigService } from '@open-mercato/core/modules/configs/lib/module-config-service'
+import { parseBooleanToken } from '@open-mercato/shared/lib/boolean'
+import { runOmnibusBackfill, type OmnibusBackfillResult } from './lib/omnibusBackfill'
+import { resolveOmnibusCache } from './lib/omnibusCache'
+import { omnibusBackfillOptionsSchema } from './data/validators'
 import {
   installExampleCatalogData,
   seedCatalogExamplesForScope,
@@ -147,4 +153,81 @@ const installExamplesBundle: ModuleCli = {
   },
 }
 
-export default [seedUnitsCommand, seedPriceKindsCommand, seedExamplesCommand, installExamplesBundle]
+const OMNIBUS_BACKFILL_USAGE =
+  'Usage: mercato catalog omnibus:backfill --tenant <tenantId> [--org <organizationId>] [--channel-id <channelId> | --unscoped] [--batch-size N] [--dry-run]'
+
+function readFlag(rest: string[], name: string): boolean {
+  for (const part of rest) {
+    if (part === `--${name}`) return true
+    if (part.startsWith(`--${name}=`)) return parseBooleanToken(part.slice(name.length + 3)) === true
+  }
+  return false
+}
+
+export function parseOmnibusBackfillArgs(rest: string[]) {
+  const args = parseArgs(rest.filter((part) => part !== '--dry-run' && part !== '--unscoped'))
+  const rawBatchSize = args.batchSize ?? args['batch-size'] ?? args.batch
+  return omnibusBackfillOptionsSchema.safeParse({
+    tenantId: args.tenantId ?? args.tenant ?? '',
+    organizationId: args.organizationId ?? args.org ?? args.orgId ?? undefined,
+    channelId: args.channelId ?? args['channel-id'] ?? args.channel ?? undefined,
+    unscoped: readFlag(rest, 'unscoped'),
+    batchSize: rawBatchSize !== undefined ? Number(rawBatchSize) : undefined,
+    dryRun: readFlag(rest, 'dry-run'),
+  })
+}
+
+function printOmnibusBackfillResult(result: OmnibusBackfillResult) {
+  const label = result.dryRun ? '[omnibus:backfill] Dry run' : '[omnibus:backfill] Complete'
+  console.log(`${label} (tenant=${result.tenantId}, org=${result.organizationId ?? 'all'})`)
+  for (const target of result.targets) {
+    const key = target.coverageKey || '(unscoped)'
+    console.log(
+      `  ${key}: lookbackDays=${target.lookbackDays} recordedAt=${target.recordedAt} scanned=${target.scanned} alreadyCovered=${target.alreadyCovered} missing=${target.missing} created=${target.created} skippedIncomplete=${target.skippedIncomplete} skippedUntracked=${target.skippedUntracked}`,
+    )
+  }
+  if (!result.dryRun) {
+    console.log(`  Coverage recorded: ${result.coverageRecorded.map((key) => key || '(unscoped)').join(', ') || 'none'}`)
+  }
+  if (result.organizationId) {
+    console.log(
+      '  Coverage is tenant-wide and is recorded only by a run without --org; run the backfill without --org before enabling Omnibus.',
+    )
+  }
+}
+
+const omnibusBackfillCommand: ModuleCli = {
+  command: 'omnibus:backfill',
+  async run(rest) {
+    const parsed = parseOmnibusBackfillArgs(rest)
+    if (!parsed.success) {
+      console.error(OMNIBUS_BACKFILL_USAGE)
+      for (const issue of parsed.error.issues) {
+        console.error(`  ${issue.path.join('.') || 'options'}: ${issue.message}`)
+      }
+      process.exitCode = 2
+      return
+    }
+    const container = await createRequestContainer()
+    try {
+      const result = await runWithCacheTenant(parsed.data.tenantId, () =>
+        runOmnibusBackfill(
+          {
+            em: container.resolve<EntityManager>('em'),
+            moduleConfigService: container.resolve<ModuleConfigService>('moduleConfigService'),
+            cache: resolveOmnibusCache(container),
+          },
+          parsed.data,
+        ),
+      )
+      printOmnibusBackfillResult(result)
+    } finally {
+      const disposable = container as unknown as { dispose?: () => Promise<void> }
+      if (typeof disposable.dispose === 'function') {
+        await disposable.dispose()
+      }
+    }
+  },
+}
+
+export default [seedUnitsCommand, seedPriceKindsCommand, seedExamplesCommand, installExamplesBundle, omnibusBackfillCommand]

package/src/modules/catalog/commands/categories.ts

@@ -1,6 +1,13 @@
 import { registerCommand } from '@open-mercato/shared/lib/commands'
 import type { CommandHandler } from '@open-mercato/shared/lib/commands'
-import { buildChanges, requireId, parseWithCustomFields, setCustomFieldsIfAny, emitCrudSideEffects } from '@open-mercato/shared/lib/commands/helpers'
+import {
+  buildChanges,
+  requireId,
+  parseWithCustomFields,
+  setCustomFieldsIfAny,
+  emitCrudSideEffects,
+  emitCrudUndoSideEffects,
+} from '@open-mercato/shared/lib/commands/helpers'
 import { loadCustomFieldSnapshot, buildCustomFieldResetMap } from '@open-mercato/shared/lib/commands/customFieldSnapshots'
 import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
 import type { EntityManager } from '@mikro-orm/postgresql'
@@ -31,6 +38,23 @@ const categoryCrudEvents: CrudEventsConfig = {
   }),
 }
 
+function categoryHierarchyChangeEvents(previousDescendantIds: readonly string[]): CrudEventsConfig {
+  return {
+    ...categoryCrudEvents,
+    buildPayload: (ctx) => ({
+      id: ctx.identifiers.id,
+      organizationId: ctx.identifiers.organizationId,
+      tenantId: ctx.identifiers.tenantId,
+      hierarchyChanged: true,
+      previousDescendantIds: [...previousDescendantIds],
+    }),
+  }
+}
+
+function readDescendantIds(value: unknown): string[] {
+  return Array.isArray(value) ? value.filter((entry): entry is string => typeof entry === 'string') : []
+}
+
 type CategorySnapshot = {
   id: string
   organizationId: string
@@ -338,6 +362,9 @@ const updateCategoryCommand: CommandHandler<CategoryUpdateInput, { categoryId: s
       record.description = parsed.description?.trim()?.length ? parsed.description.trim() : null
     }
 
+    const previousParentId = record.parentId ?? null
+    const previousDescendantIds = readDescendantIds(record.descendantIds)
+
     if (parsed.parentId !== undefined) {
       const requestedParent = parsed.parentId ? String(parsed.parentId) : null
       const safeParent = requestedParent && requestedParent !== record.id ? requestedParent : null
@@ -367,6 +394,7 @@ const updateCategoryCommand: CommandHandler<CategoryUpdateInput, { categoryId: s
       values: custom,
     })
     const de = ctx.container.resolve('dataEngine') as DataEngine
+    const hierarchyChanged = (record.parentId ?? null) !== previousParentId
     await emitCrudSideEffects({
       dataEngine: de,
       action: 'updated',
@@ -376,7 +404,7 @@ const updateCategoryCommand: CommandHandler<CategoryUpdateInput, { categoryId: s
         organizationId: record.organizationId,
         tenantId: record.tenantId,
       },
-      events: categoryCrudEvents,
+      events: hierarchyChanged ? categoryHierarchyChangeEvents(previousDescendantIds) : categoryCrudEvents,
     })
     return { categoryId: record.id }
   },
@@ -466,6 +494,19 @@ const updateCategoryCommand: CommandHandler<CategoryUpdateInput, { categoryId: s
         values: resetValues,
       })
     }
+    if ((before.parentId ?? null) !== (payload?.after?.parentId ?? null)) {
+      await emitCrudUndoSideEffects({
+        dataEngine: ctx.container.resolve('dataEngine') as DataEngine,
+        action: 'updated',
+        entity: record,
+        identifiers: {
+          id: record.id,
+          organizationId: record.organizationId,
+          tenantId: record.tenantId,
+        },
+        events: categoryHierarchyChangeEvents(readDescendantIds(payload?.after?.descendantIds)),
+      })
+    }
   },
 }
 
@@ -608,6 +649,17 @@ const deleteCategoryCommand: CommandHandler<{ id?: string }, { categoryId: strin
         values: before.custom,
       })
     }
+    await emitCrudUndoSideEffects({
+      dataEngine: ctx.container.resolve('dataEngine') as DataEngine,
+      action: 'updated',
+      entity: record,
+      identifiers: {
+        id: record.id,
+        organizationId: record.organizationId,
+        tenantId: record.tenantId,
+      },
+      events: categoryHierarchyChangeEvents(readDescendantIds(before.descendantIds)),
+    })
   },
 }