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

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

@@ -0,0 +1,349 @@
+import { z } from "zod";
+import type { EntityManager } from "@mikro-orm/postgresql";
+import { raw } from "@mikro-orm/postgresql";
+import { buildCustomFieldFiltersFromQuery } from "@open-mercato/shared/lib/crud/custom-fields";
+import type { CrudCtx } from "@open-mercato/shared/lib/crud/factory";
+import { buildScopedWhere } from "@open-mercato/shared/lib/api/crud";
+import { parseBooleanFlag } from "@open-mercato/shared/lib/boolean";
+import { sanitizeSearchTerm } from "@open-mercato/shared/lib/query/sanitizeSearchTerm";
+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 { createLogger } from "@open-mercato/shared/lib/logger";
+import { fieldsetCodeRegex } from "@open-mercato/core/modules/entities/data/validators";
+import { E } from "#generated/entities.ids.generated";
+import {
+  CatalogOffer,
+  CatalogProduct,
+  CatalogProductCategory,
+  CatalogProductCategoryAssignment,
+  CatalogProductTagAssignment,
+} from "../data/entities";
+import { CATALOG_PRODUCT_TYPES } from "../data/types";
+import { PRODUCT_SEARCH_COLUMNS, PRODUCT_SEARCH_EXPRESSION_SQL } from "./productSearch";
+
+const logger = createLogger('catalog')
+
+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}$/;
+
+export const catalogProductFilterQuerySchema = 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();
+
+export type CatalogProductFilterQuery = z.infer<typeof catalogProductFilterQuerySchema>;
+
+export type BuildProductFiltersOptions = {
+  includeCategoryDescendants?: boolean;
+};
+
+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: CatalogProductFilterQuery,
+  ctx: CrudCtx,
+  options: BuildProductFiltersOptions = {},
+): 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 expandCategoryIds = async (): Promise<string[]> => {
+    if (!options.includeCategoryDescendants) return categoryFilterIds;
+    const categories = await findWithDecryption(
+      em,
+      CatalogProductCategory,
+      { id: { $in: categoryFilterIds }, deletedAt: null, ...scopeWhere },
+      { fields: ["id", "descendantIds"] },
+      scope,
+    );
+    const expanded = new Set(categoryFilterIds);
+    for (const category of categories) {
+      const descendants = Array.isArray(category.descendantIds) ? category.descendantIds : [];
+      for (const descendantId of descendants) {
+        if (typeof descendantId === "string" && descendantId.length > 0) {
+          expanded.add(descendantId);
+        }
+      }
+    }
+    return Array.from(expanded);
+  };
+
+  const categoryTask = async (): Promise<string[] | null> => {
+    if (!categoryFilterIds.length) return null;
+    const categoryIds = await expandCategoryIds();
+    const assignments = await findWithDecryption(
+      em,
+      CatalogProductCategoryAssignment,
+      { category: { $in: categoryIds }, ...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 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;
+}

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

@@ -0,0 +1,162 @@
+import { sql, type Kysely, type RawBuilder } from 'kysely'
+import type {
+  IndexDocEnricher,
+  IndexDocEnricherContext,
+  IndexDocEnricherRecord,
+  IndexDocEnrichment,
+} from '@open-mercato/core/modules/query_index/lib/doc-enrichers'
+
+/**
+ * Denormalized assortment keys on the `catalog:catalog_product` index document
+ * (Storefront Public API §3.3, decision D9).
+ *
+ * `scope_keys` is a sorted, de-duplicated jsonb string array:
+ * - `cat:<uuid>` for every assigned, non-deleted category AND each of its `ancestor_ids`
+ *   (so "a category includes its descendants" is a plain overlap test);
+ * - `tag:<uuid>` for every assigned tag.
+ *
+ * Ids only — never encrypted, never translated. A document whose `scope_keys` is `null`
+ * (enricher failure) or absent (not reindexed since the enricher shipped) is NOT indexed:
+ * consumers MUST fail closed on it, never read it as "no assignments" — see
+ * `isProductScopeIndexed`.
+ */
+export const PRODUCT_SCOPE_KEYS_ENTITY_TYPE = 'catalog:catalog_product'
+export const PRODUCT_SCOPE_KEYS_DOC_KEY = 'scope_keys'
+export const PRODUCT_SCOPE_KEYS_ENRICHER_ID = 'catalog.product_scope_keys'
+export const PRODUCT_SCOPE_CATEGORY_PREFIX = 'cat:'
+export const PRODUCT_SCOPE_TAG_PREFIX = 'tag:'
+
+export function compareCodeUnits(left: string, right: string): number {
+  if (left < right) return -1
+  if (left > right) return 1
+  return 0
+}
+
+export function categoryScopeKey(categoryId: string): string {
+  return `${PRODUCT_SCOPE_CATEGORY_PREFIX}${categoryId}`
+}
+
+export function tagScopeKey(tagId: string): string {
+  return `${PRODUCT_SCOPE_TAG_PREFIX}${tagId}`
+}
+
+export type ProductScopeKeyInput = {
+  categories: ReadonlyArray<{ categoryId: string; ancestorIds: readonly string[] }>
+  tagIds: readonly string[]
+}
+
+export function buildProductScopeKeys(input: ProductScopeKeyInput): string[] {
+  const keys = new Set<string>()
+  for (const category of input.categories) {
+    if (category.categoryId) keys.add(categoryScopeKey(category.categoryId))
+    for (const ancestorId of category.ancestorIds) {
+      if (ancestorId) keys.add(categoryScopeKey(ancestorId))
+    }
+  }
+  for (const tagId of input.tagIds) {
+    if (tagId) keys.add(tagScopeKey(tagId))
+  }
+  return Array.from(keys).sort(compareCodeUnits)
+}
+
+export function isProductScopeIndexed(doc: Readonly<Record<string, unknown>> | null | undefined): boolean {
+  if (!doc) return false
+  const keys = doc[PRODUCT_SCOPE_KEYS_DOC_KEY]
+  if (!Array.isArray(keys)) return false
+  return keys.every((entry) => typeof entry === 'string')
+}
+
+export function readJsonIdList(value: unknown): string[] {
+  let parsed: unknown = value
+  if (typeof value === 'string') {
+    try {
+      parsed = JSON.parse(value)
+    } catch {
+      return []
+    }
+  }
+  if (!Array.isArray(parsed)) return []
+  return parsed.filter((entry): entry is string => typeof entry === 'string' && entry.length > 0)
+}
+
+type ScopeFilter = { tenantId: string | null; organizationId: string | null }
+
+function scopeEquals(column: string, value: string | null): RawBuilder<boolean> {
+  return value === null
+    ? sql<boolean>`${sql.ref(column)} is null`
+    : sql<boolean>`${sql.ref(column)} = ${value}`
+}
+
+type CategoryAssignmentRow = { product_id: string; category_id: string; ancestor_ids: unknown }
+type TagAssignmentRow = { product_id: string; tag_id: string }
+
+/**
+ * Computes `scope_keys` for a batch of products in two queries (category assignments joined
+ * with their categories, then tag assignments). Every requested product gets an entry — a
+ * product without assignments maps to `[]`, which is "indexed, no keys", not "unknown".
+ */
+export async function computeProductScopeKeys(
+  db: Kysely<any>,
+  productIds: readonly string[],
+  scope: ScopeFilter,
+): Promise<Map<string, string[]>> {
+  const ids = Array.from(new Set(productIds.filter((id) => typeof id === 'string' && id.length > 0)))
+  const result = new Map<string, string[]>()
+  if (!ids.length) return result
+
+  const categoryRows = (await db
+    .selectFrom('catalog_product_category_assignments as a')
+    .innerJoin('catalog_product_categories as c', 'c.id', 'a.category_id')
+    .select(['a.product_id as product_id', 'a.category_id as category_id', 'c.ancestor_ids as ancestor_ids'])
+    .where('a.product_id', 'in', ids)
+    .where('c.deleted_at', 'is', null)
+    .where(scopeEquals('a.tenant_id', scope.tenantId))
+    .where(scopeEquals('a.organization_id', scope.organizationId))
+    .where(scopeEquals('c.tenant_id', scope.tenantId))
+    .where(scopeEquals('c.organization_id', scope.organizationId))
+    .execute()) as CategoryAssignmentRow[]
+
+  const tagRows = (await db
+    .selectFrom('catalog_product_tag_assignments as t')
+    .select(['t.product_id as product_id', 't.tag_id as tag_id'])
+    .where('t.product_id', 'in', ids)
+    .where(scopeEquals('t.tenant_id', scope.tenantId))
+    .where(scopeEquals('t.organization_id', scope.organizationId))
+    .execute()) as TagAssignmentRow[]
+
+  const inputs = new Map<string, { categories: Array<{ categoryId: string; ancestorIds: string[] }>; tagIds: string[] }>()
+  for (const id of ids) inputs.set(id, { categories: [], tagIds: [] })
+  for (const row of categoryRows) {
+    const entry = inputs.get(String(row.product_id))
+    if (!entry) continue
+    entry.categories.push({ categoryId: String(row.category_id), ancestorIds: readJsonIdList(row.ancestor_ids) })
+  }
+  for (const row of tagRows) {
+    const entry = inputs.get(String(row.product_id))
+    if (!entry) continue
+    entry.tagIds.push(String(row.tag_id))
+  }
+  for (const [id, input] of inputs) result.set(id, buildProductScopeKeys(input))
+  return result
+}
+
+export const catalogProductScopeKeysEnricher: IndexDocEnricher = {
+  id: PRODUCT_SCOPE_KEYS_ENRICHER_ID,
+  entityType: PRODUCT_SCOPE_KEYS_ENTITY_TYPE,
+  keys: [PRODUCT_SCOPE_KEYS_DOC_KEY],
+  async enrich(
+    records: readonly IndexDocEnricherRecord[],
+    ctx: IndexDocEnricherContext,
+  ): Promise<Map<string, IndexDocEnrichment>> {
+    const keysByProduct = await computeProductScopeKeys(
+      ctx.db,
+      records.map((record) => record.recordId),
+      { tenantId: ctx.tenantId, organizationId: ctx.organizationId },
+    )
+    const out = new Map<string, IndexDocEnrichment>()
+    for (const [productId, keys] of keysByProduct) {
+      out.set(productId, { [PRODUCT_SCOPE_KEYS_DOC_KEY]: keys })
+    }
+    return out
+  },
+}

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

@@ -0,0 +1,139 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { sql, type Kysely } from 'kysely'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { PRODUCT_SCOPE_KEYS_ENTITY_TYPE, readJsonIdList } from './productScopeKeys'
+
+const logger = createLogger('catalog').child({ component: 'product-scope-reindex' })
+
+/**
+ * Above this many affected products a category hierarchy change requests one scoped
+ * `query_index.reindex` job for `catalog:catalog_product` instead of per-record upserts.
+ */
+export const PRODUCT_SCOPE_REINDEX_UPSERT_LIMIT = 500
+
+export type CategoryScopeChangePayload = {
+  id?: unknown
+  tenantId?: unknown
+  organizationId?: unknown
+  hierarchyChanged?: unknown
+  previousDescendantIds?: unknown
+}
+
+export type ProductScopeReindexContext = {
+  resolve: <T = unknown>(name: string) => T
+}
+
+type EventBusLike = {
+  emitEvent: (event: string, payload: unknown, options?: Record<string, unknown>) => Promise<void>
+}
+
+type CategoryScopeTarget = {
+  categoryId: string
+  tenantId: string
+  organizationId: string
+  extraCategoryIds: string[]
+}
+
+export type ProductScopeReindexResult =
+  | { mode: 'skipped'; productCount: 0 }
+  | { mode: 'upsert'; productCount: number }
+  | { mode: 'reindex'; productCount: number }
+
+function readNonEmptyString(value: unknown): string | null {
+  return typeof value === 'string' && value.length > 0 ? value : null
+}
+
+export function parseCategoryScopeTarget(payload: CategoryScopeChangePayload | null | undefined): CategoryScopeTarget | null {
+  const categoryId = readNonEmptyString(payload?.id)
+  const tenantId = readNonEmptyString(payload?.tenantId)
+  const organizationId = readNonEmptyString(payload?.organizationId)
+  if (!categoryId || !tenantId || !organizationId) return null
+  return {
+    categoryId,
+    tenantId,
+    organizationId,
+    extraCategoryIds: readJsonIdList(payload?.previousDescendantIds),
+  }
+}
+
+export async function collectCategorySubtreeProductIds(
+  db: Kysely<any>,
+  target: CategoryScopeTarget,
+  limit: number,
+): Promise<string[]> {
+  const category = (await db
+    .selectFrom('catalog_product_categories')
+    .select(['id', 'descendant_ids'])
+    .where('id', '=', target.categoryId)
+    .where('tenant_id', '=', target.tenantId)
+    .where('organization_id', '=', target.organizationId)
+    .executeTakeFirst()) as { id: string; descendant_ids: unknown } | undefined
+
+  const categoryIds = Array.from(new Set([
+    target.categoryId,
+    ...readJsonIdList(category?.descendant_ids),
+    ...target.extraCategoryIds,
+  ]))
+
+  const rows = (await db
+    .selectFrom('catalog_product_category_assignments as a')
+    .innerJoin('catalog_products as p', 'p.id', 'a.product_id')
+    .select('a.product_id as product_id')
+    .distinct()
+    .where('a.category_id', 'in', categoryIds)
+    .where('a.tenant_id', '=', target.tenantId)
+    .where('a.organization_id', '=', target.organizationId)
+    .where(sql<boolean>`${sql.ref('p.deleted_at')} is null`)
+    .limit(limit + 1)
+    .execute()) as Array<{ product_id: string }>
+
+  return rows.map((row) => String(row.product_id))
+}
+
+/**
+ * Re-projects `scope_keys` for every product assigned anywhere in a category's subtree
+ * (Storefront Public API §3.3, R16). Runs from persistent `catalog.category.*` subscribers,
+ * i.e. in the events worker, never in the request that changed the hierarchy.
+ */
+export async function reindexProductsForCategorySubtree(
+  payload: CategoryScopeChangePayload | null | undefined,
+  ctx: ProductScopeReindexContext,
+  limit: number = PRODUCT_SCOPE_REINDEX_UPSERT_LIMIT,
+): Promise<ProductScopeReindexResult> {
+  const target = parseCategoryScopeTarget(payload)
+  if (!target) {
+    logger.warn('Category scope change without id/tenant/organization; product scope keys not refreshed', {
+      categoryId: readNonEmptyString(payload?.id),
+    })
+    return { mode: 'skipped', productCount: 0 }
+  }
+  const em = ctx.resolve<EntityManager>('em')
+  const db = em.getKysely() as Kysely<any>
+  const bus = ctx.resolve<EventBusLike>('eventBus')
+  const productIds = await collectCategorySubtreeProductIds(db, target, limit)
+  if (!productIds.length) return { mode: 'skipped', productCount: 0 }
+
+  if (productIds.length > limit) {
+    await bus.emitEvent(
+      'query_index.reindex',
+      {
+        entityType: PRODUCT_SCOPE_KEYS_ENTITY_TYPE,
+        tenantId: target.tenantId,
+        organizationId: target.organizationId,
+      },
+      { persistent: true, deliverInline: false },
+    )
+    return { mode: 'reindex', productCount: productIds.length }
+  }
+
+  for (const productId of productIds) {
+    await bus.emitEvent('query_index.upsert_one', {
+      entityType: PRODUCT_SCOPE_KEYS_ENTITY_TYPE,
+      recordId: productId,
+      tenantId: target.tenantId,
+      organizationId: target.organizationId,
+      crudAction: 'updated',
+    })
+  }
+  return { mode: 'upsert', productCount: productIds.length }
+}