@open-mercato/core 0.8.1-develop.7296.1.2111d779db → 0.9.0

package/src/modules/customer_groups/migrations/Migration20260922095316_customer_groups.ts

@@ -0,0 +1,26 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260922095316_customer_groups extends Migration {
+
+  override name = 'Migration20260922095316';
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "customer_groups" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid null, "tenant_id" uuid not null, "code" text not null, "name" text not null, "description" text null, "kind" text not null, "parent_id" uuid null, "priority" int not null, "is_default" boolean not null default false, "is_active" boolean not null default true, "metadata" jsonb null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create unique index "customer_groups_tenant_default_unique" on "customer_groups" ("tenant_id") where "is_default" and "deleted_at" is null;`);
+    this.addSql(`create index "customer_groups_parent_idx" on "customer_groups" ("parent_id");`);
+    this.addSql(`create index "customer_groups_tenant_idx" on "customer_groups" ("tenant_id");`);
+    this.addSql(`alter table "customer_groups" add constraint "customer_groups_tenant_priority_unique" unique ("tenant_id", "priority");`);
+    this.addSql(`alter table "customer_groups" add constraint "customer_groups_tenant_code_unique" unique ("tenant_id", "code");`);
+
+    this.addSql(`create table "customer_group_memberships" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid null, "tenant_id" uuid not null, "group_id" uuid not null, "customer_id" uuid not null, "source" text not null default 'manual', "valid_from" timestamptz null, "valid_until" timestamptz null, "assigned_by_user_id" uuid null, "notes" text null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create unique index "customer_group_memberships_active_unique" on "customer_group_memberships" ("tenant_id", "group_id", "customer_id") where "deleted_at" is null;`);
+    this.addSql(`create index "customer_group_memberships_hot_path_idx" on "customer_group_memberships" ("tenant_id", "customer_id", "valid_from", "valid_until");`);
+    this.addSql(`create index "customer_group_memberships_tenant_idx" on "customer_group_memberships" ("tenant_id");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "customer_group_memberships" cascade;`);
+    this.addSql(`drop table if exists "customer_groups" cascade;`);
+  }
+
+}

package/src/modules/customer_groups/migrations/Migration20260922103033_customer_groups.ts

@@ -0,0 +1,22 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260922103033_customer_groups extends Migration {
+
+  override name = 'Migration20260922103033';
+
+  override up(): void | Promise<void> {
+    // The (tenant_id, priority) uniqueness was originally a plain table constraint,
+    // which does not exclude soft-deleted rows: a deleted group's priority stayed
+    // permanently reserved and could collide with a value the drag-reorder command
+    // (gaps of 10) later tried to assign to a live group. Replace it with a partial
+    // unique index scoped to deleted_at IS NULL, matching customer_groups_tenant_default_unique.
+    this.addSql(`alter table "customer_groups" drop constraint "customer_groups_tenant_priority_unique";`);
+    this.addSql(`create unique index "customer_groups_tenant_priority_unique" on "customer_groups" ("tenant_id", "priority") where "deleted_at" is null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index "customer_groups_tenant_priority_unique";`);
+    this.addSql(`alter table "customer_groups" add constraint "customer_groups_tenant_priority_unique" unique ("tenant_id", "priority");`);
+  }
+
+}

package/src/modules/customer_groups/migrations/Migration20260922105444_customer_groups.ts

@@ -0,0 +1,17 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260922105444_customer_groups extends Migration {
+
+  override name = 'Migration20260922105444';
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "customer_group_terms" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid null, "tenant_id" uuid not null, "group_id" uuid not null, "price_kind_id" uuid null, "payment_terms_days" int null, "allow_purchase_on_account" boolean not null default false, "default_credit_limit" numeric(16,2) null, "credit_currency_code" text null, "approval_required_above" numeric(16,2) null, "min_order_value" numeric(16,2) null, "metadata" jsonb null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create unique index "customer_group_terms_group_unique" on "customer_group_terms" ("group_id") where "deleted_at" is null;`);
+    this.addSql(`create index "customer_group_terms_tenant_idx" on "customer_group_terms" ("tenant_id");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "customer_group_terms" cascade;`);
+  }
+
+}

package/src/modules/customer_groups/migrations/Migration20260923193330_customer_groups.ts

@@ -0,0 +1,20 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260923193330_customer_groups extends Migration {
+
+  override name = 'Migration20260923193330';
+
+  override up(): void | Promise<void> {
+    // Same soft-delete fix as Migration20260922103033 applied to (tenant_id, code): the
+    // plain table constraint kept a deleted group's code permanently reserved, so
+    // recreating a group with that code failed with a raw unique violation.
+    this.addSql(`alter table "customer_groups" drop constraint "customer_groups_tenant_code_unique";`);
+    this.addSql(`create unique index "customer_groups_tenant_code_unique" on "customer_groups" ("tenant_id", "code") where "deleted_at" is null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index "customer_groups_tenant_code_unique";`);
+    this.addSql(`alter table "customer_groups" add constraint "customer_groups_tenant_code_unique" unique ("tenant_id", "code");`);
+  }
+
+}

package/src/modules/customer_groups/migrations/Migration20260929083000_customer_groups.ts

@@ -0,0 +1,21 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260929083000_customer_groups extends Migration {
+
+  override name = 'Migration20260929083000';
+
+  override up(): void | Promise<void> {
+    // `allow_purchase_on_account` becomes nullable like every other terms field, so a
+    // group's terms row can leave it unset (`null`) and inherit it from the parent
+    // chain / tenant default. Existing values are kept as stored.
+    this.addSql(`alter table "customer_group_terms" alter column "allow_purchase_on_account" drop default;`);
+    this.addSql(`alter table "customer_group_terms" alter column "allow_purchase_on_account" drop not null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`update "customer_group_terms" set "allow_purchase_on_account" = false where "allow_purchase_on_account" is null;`);
+    this.addSql(`alter table "customer_group_terms" alter column "allow_purchase_on_account" set default false;`);
+    this.addSql(`alter table "customer_group_terms" alter column "allow_purchase_on_account" set not null;`);
+  }
+
+}

package/src/modules/customer_groups/services/customerGroupsService.ts

@@ -0,0 +1,358 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { unionScopes } from '@open-mercato/shared/lib/catalog-visibility'
+import type { AssortmentScope, EffectiveAssortmentScope } from '@open-mercato/shared/lib/catalog-visibility'
+import { CustomerGroup, CustomerGroupMembership, CustomerGroupTerms } from '../data/entities'
+import { CUSTOMER_GROUP_MAX_ANCESTOR_DEPTH } from '../data/validators'
+
+export type GroupResolution = {
+  groupIds: string[]
+  groups: Array<{ id: string; code: string; name: string; kind: string; priority: number }>
+}
+
+// The five scalar fields `resolveTerms` resolves per group, independently of one
+// another (spec §6.1). Kept as a `const` tuple (not a hardcoded literal union) so the
+// resolution loop and the `sources` map share a single source of truth for the field
+// list.
+const TERMS_FIELD_NAMES = [
+  'priceKindId',
+  'paymentTermsDays',
+  'allowPurchaseOnAccount',
+  'approvalRequiredAbove',
+  'minOrderValue',
+] as const
+type TermsFieldName = (typeof TERMS_FIELD_NAMES)[number]
+
+// Spec §6.1's illustrative type sketch shows a single shared `sourceGroupId` on
+// `ResolvedTerms`, but its own acceptance criteria (US-C2: "each resolved scalar
+// field... shows its value and the group it came from") require independent
+// per-field provenance — a customer can get `paymentTermsDays` from a grandparent
+// while `priceKindId` comes straight from its own group. Modeled as a `sources` map
+// keyed by field name (rather than five parallel `<field>SourceGroupId` fields) so
+// the resolution loop can write `result.sources[field] = groupId` generically instead
+// of a per-field switch, and so a future terms field only needs adding to
+// `TERMS_FIELD_NAMES` instead of a new parallel field everywhere.
+export type ResolvedTermsSources = Record<TermsFieldName, string | null>
+
+export type ResolvedTerms = {
+  priceKindId: string | null
+  paymentTermsDays: number | null
+  allowPurchaseOnAccount: boolean
+  approvalRequiredAbove: number | null
+  minOrderValue: number | null
+  sources: ResolvedTermsSources
+}
+
+// Ancestor-walk depth cap — the group hierarchy's own depth cap (spec §5.1, enforced at
+// create/update time by `findParentAssignmentIssue`), shared so the two cannot drift.
+// Defensive only: normal data can never produce a chain this long, but this stops a
+// corrupt/cyclic `parentId` graph from looping forever.
+const MAX_ANCESTOR_DEPTH = CUSTOMER_GROUP_MAX_ANCESTOR_DEPTH
+
+// `customer_groups` entities are tenant-scoped only (see the "Groups are
+// tenant-scoped, not organization-scoped" note in `data/entities.ts`), and this
+// codebase has no ambient/DI-resolved tenant context — `createRequestContainer()`
+// (packages/shared/src/lib/di/container.ts) builds the container before auth is
+// resolved, and every DB-querying DI service in this repo that needs tenant scope
+// takes it as an explicit caller-supplied argument (see
+// `warranty_claims/services/entitlementResolver.ts`'s `resolveEntitlement(input, scope, em)`).
+// The illustrative `resolveGroups(input: { customerId, at })` signature in
+// `.ai/specs/2026-08-14-customer-groups-and-b2b-terms.md` §6 omits `tenantId` for
+// brevity; `tenantId` is added here to the input so this service can never silently
+// query across tenants (root AGENTS.md § Never: "expose cross-tenant data or skip
+// tenant/organization scoping").
+export type ResolveGroupsInput = {
+  customerId: string | null
+  tenantId: string
+  at?: Date
+}
+
+// `groupIds` is optional and, when supplied by a caller who already resolved the
+// customer's groups, skips the membership-resolution query inside `resolveTerms` —
+// `resolveGroups`'s own DB round-trips (memberships + groups, or the tenant-default
+// lookup) are not repeated. Ancestor/terms rows are still fetched fresh regardless,
+// since `resolveGroups` never returns those.
+export type ResolveTermsInput = {
+  customerId: string | null
+  tenantId: string
+  at?: Date
+  groupIds?: string[]
+}
+
+// Same shape as `ResolveGroupsInput` — `resolveAssortmentScope` delegates straight to
+// `resolveGroups()` and adds no extra inputs of its own. Aliased rather than reused
+// directly so a future assortment-specific input (e.g. a channel id, once Phase 2 of
+// catalog-visibility composes channel scope too) doesn't ripple through `resolveGroups`'s
+// own signature.
+export type ResolveAssortmentScopeInput = ResolveGroupsInput
+
+export type ResolvedAssortmentScope = {
+  scope: EffectiveAssortmentScope
+  sourceGroupIds: string[]
+  // Always `null` in Phase 1 — `CustomerAssortmentOverride` (per-customer override table)
+  // is Phase 4 scope (spec §14 non-goals) and does not exist yet. Never read from anywhere;
+  // this is a fixed literal until that phase lands.
+  sourceCustomerOverrideId: string | null
+}
+
+export interface CustomerGroupsService {
+  resolveGroups(input: ResolveGroupsInput): Promise<GroupResolution>
+  resolveTerms(input: ResolveTermsInput): Promise<ResolvedTerms>
+  resolveAssortmentScope(input: ResolveAssortmentScopeInput): Promise<ResolvedAssortmentScope>
+}
+
+// Phase 1's `CustomerGroup` entity has no `assortment_scope`-shaped column yet — the spec's
+// full field list places it on `CustomerGroupTerms`, but that was deliberately withheld from
+// this PR's Step 2.1 entity (Phase 5 scope, spec §14 non-goals). Every matching group
+// therefore contributes an unrestricted (`null`) own-scope for now. Once a real column
+// exists, replace this stub's body with a read of it — `resolveAssortmentScope`'s
+// `unionScopes` composition below needs no changes to start returning real restrictions.
+function groupOwnAssortmentScope(_groupId: string): AssortmentScope | null {
+  return null
+}
+
+async function loadGroupCached(
+  em: EntityManager,
+  groupId: string,
+  tenantId: string,
+  cache: Map<string, CustomerGroup | null>,
+): Promise<CustomerGroup | null> {
+  if (cache.has(groupId)) return cache.get(groupId) ?? null
+  const group = await em.findOne(CustomerGroup, { id: groupId, tenantId, deletedAt: null })
+  cache.set(groupId, group)
+  return group
+}
+
+/**
+ * One group's ancestor chain — self first, then parent, grandparent, ... up to
+ * `MAX_ANCESTOR_DEPTH` — as loaded, non-deleted, active, same-tenant entities. The
+ * walk stops at the first id that does not resolve (soft-deleted, other tenant, or
+ * dangling `parentId`) or resolves to an inactive group (spec §5.1: inactive groups
+ * are excluded from resolution): such a group is never part of the chain, so neither
+ * its terms row nor anything above it can be inherited. Shared by `resolveTerms` and
+ * the explain-terms route so the resolved value and the explained ancestor path always
+ * come from the SAME chain. `cache` lets callers reuse group rows across several chains.
+ */
+export async function loadCustomerGroupAncestorChain(
+  em: EntityManager,
+  groupId: string,
+  tenantId: string,
+  cache: Map<string, CustomerGroup | null> = new Map(),
+): Promise<CustomerGroup[]> {
+  const chain: CustomerGroup[] = []
+  let currentId: string | null = groupId
+  while (currentId && chain.length < MAX_ANCESTOR_DEPTH) {
+    const group = await loadGroupCached(em, currentId, tenantId, cache)
+    if (!group || !group.isActive) break
+    chain.push(group)
+    currentId = group.parentId ?? null
+  }
+  return chain
+}
+
+function toGroupSummary(group: CustomerGroup): GroupResolution['groups'][number] {
+  return { id: group.id, code: group.code, name: group.name, kind: group.kind, priority: group.priority }
+}
+
+export function isMembershipValidAt(
+  membership: Pick<CustomerGroupMembership, 'validFrom' | 'validUntil'>,
+  at: Date,
+): boolean {
+  if (membership.validFrom && membership.validFrom.getTime() > at.getTime()) return false
+  // Inclusive upper bound: a membership expiring exactly at `at` is still valid
+  // AT that instant (spec-derived rule — see the module's di.ts contract task).
+  if (membership.validUntil && membership.validUntil.getTime() < at.getTime()) return false
+  return true
+}
+
+function tenantDefaultTerms(): ResolvedTerms {
+  return {
+    priceKindId: null,
+    paymentTermsDays: null,
+    allowPurchaseOnAccount: false,
+    approvalRequiredAbove: null,
+    minOrderValue: null,
+    sources: {
+      priceKindId: null,
+      paymentTermsDays: null,
+      allowPurchaseOnAccount: null,
+      approvalRequiredAbove: null,
+      minOrderValue: null,
+    },
+  }
+}
+
+function toNumberOrNull(value: string | null | undefined): number | null {
+  if (value == null) return null
+  const parsed = Number(value)
+  return Number.isNaN(parsed) ? null : parsed
+}
+
+// Every terms field is a nullable column: `null` means "not set on this group, keep
+// walking the ancestor chain", so a group can override a single field and inherit the
+// rest.
+function termsFieldIsSet(terms: CustomerGroupTerms, field: TermsFieldName): boolean {
+  switch (field) {
+    case 'priceKindId':
+      return terms.priceKindId != null
+    case 'paymentTermsDays':
+      return terms.paymentTermsDays != null
+    case 'allowPurchaseOnAccount':
+      return terms.allowPurchaseOnAccount != null
+    case 'approvalRequiredAbove':
+      return terms.approvalRequiredAbove != null
+    case 'minOrderValue':
+      return terms.minOrderValue != null
+  }
+}
+
+function applyTermsField(
+  result: ResolvedTerms,
+  field: TermsFieldName,
+  terms: CustomerGroupTerms,
+  sourceGroupId: string,
+): void {
+  switch (field) {
+    case 'priceKindId':
+      result.priceKindId = terms.priceKindId ?? null
+      break
+    case 'paymentTermsDays':
+      result.paymentTermsDays = terms.paymentTermsDays ?? null
+      break
+    case 'allowPurchaseOnAccount':
+      result.allowPurchaseOnAccount = terms.allowPurchaseOnAccount === true
+      break
+    case 'approvalRequiredAbove':
+      result.approvalRequiredAbove = toNumberOrNull(terms.approvalRequiredAbove)
+      break
+    case 'minOrderValue':
+      result.minOrderValue = toNumberOrNull(terms.minOrderValue)
+      break
+  }
+  result.sources[field] = sourceGroupId
+}
+
+export class DefaultCustomerGroupsService implements CustomerGroupsService {
+  constructor(private readonly em: EntityManager) {}
+
+  async resolveGroups(input: ResolveGroupsInput): Promise<GroupResolution> {
+    const at = input.at ?? new Date()
+
+    if (input.customerId == null) return this.resolveDefaultGroup(input.tenantId)
+
+    const memberships = await this.em.find(CustomerGroupMembership, {
+      tenantId: input.tenantId,
+      customerId: input.customerId,
+      deletedAt: null,
+    })
+
+    const validMemberships = memberships.filter((membership) => isMembershipValidAt(membership, at))
+    if (!validMemberships.length) return this.resolveDefaultGroup(input.tenantId)
+
+    // Precedence rule: when a customer has more than one membership row for the
+    // same group (e.g. re-added after a prior removal), the most recently created
+    // one is the one whose validity/attribution counts.
+    const latestMembershipByGroupId = new Map<string, CustomerGroupMembership>()
+    for (const membership of validMemberships) {
+      const existing = latestMembershipByGroupId.get(membership.groupId)
+      if (!existing || membership.createdAt.getTime() > existing.createdAt.getTime()) {
+        latestMembershipByGroupId.set(membership.groupId, membership)
+      }
+    }
+
+    const groupIds = Array.from(latestMembershipByGroupId.keys())
+    const groups = await this.em.find(CustomerGroup, {
+      id: { $in: groupIds },
+      tenantId: input.tenantId,
+      isActive: true,
+      deletedAt: null,
+    })
+
+    const sortedGroups = groups.slice().sort((a, b) => {
+      if (b.priority !== a.priority) return b.priority - a.priority
+      const membershipA = latestMembershipByGroupId.get(a.id)!
+      const membershipB = latestMembershipByGroupId.get(b.id)!
+      return membershipB.createdAt.getTime() - membershipA.createdAt.getTime()
+    })
+
+    if (!sortedGroups.length) return this.resolveDefaultGroup(input.tenantId)
+
+    return {
+      groupIds: sortedGroups.map((group) => group.id),
+      groups: sortedGroups.map(toGroupSummary),
+    }
+  }
+
+  private async resolveDefaultGroup(tenantId: string): Promise<GroupResolution> {
+    const defaultGroup = await this.em.findOne(CustomerGroup, {
+      tenantId,
+      isDefault: true,
+      isActive: true,
+      deletedAt: null,
+    })
+    if (!defaultGroup) return { groupIds: [], groups: [] }
+    return { groupIds: [defaultGroup.id], groups: [toGroupSummary(defaultGroup)] }
+  }
+
+  async resolveTerms(input: ResolveTermsInput): Promise<ResolvedTerms> {
+    const groupIds = input.groupIds
+      ?? (
+        await this.resolveGroups({ customerId: input.customerId, tenantId: input.tenantId, at: input.at })
+      ).groupIds
+
+    if (!groupIds.length) return tenantDefaultTerms()
+
+    // One ancestor chain per matching group, in the SAME priority order `groupIds`
+    // arrived in (self first, then parent, then grandparent, ... up to the depth
+    // cap). Computed once up front — the field loop below walks these same chains
+    // for every field, relying on `groupCache`/`termsCache` to avoid re-querying a
+    // group/terms row visited by an earlier chain or an earlier field.
+    const groupCache = new Map<string, CustomerGroup | null>()
+    const termsCache = new Map<string, CustomerGroupTerms | null>()
+    const chains: string[][] = []
+    for (const groupId of groupIds) {
+      const chain = await loadCustomerGroupAncestorChain(this.em, groupId, input.tenantId, groupCache)
+      chains.push(chain.map((group) => group.id))
+    }
+
+    const result = tenantDefaultTerms()
+
+    for (const field of TERMS_FIELD_NAMES) {
+      // "highest-priority group with a non-null value → its ancestors" is ONE
+      // resolution unit per priority-ordered group (spec §6.1): walk THIS group's
+      // full ancestor chain to completion before moving to the next-priority group,
+      // not "check every group's own row first, then every group's ancestors."
+      chainLoop: for (const chain of chains) {
+        for (const ancestorId of chain) {
+          const terms = await this.loadTerms(ancestorId, input.tenantId, termsCache)
+          if (!terms) continue
+          if (!termsFieldIsSet(terms, field)) continue
+          applyTermsField(result, field, terms, ancestorId)
+          break chainLoop
+        }
+      }
+    }
+
+    return result
+  }
+
+  async resolveAssortmentScope(input: ResolveAssortmentScopeInput): Promise<ResolvedAssortmentScope> {
+    const { groupIds } = await this.resolveGroups(input)
+    const scope = unionScopes(groupIds.map((groupId) => groupOwnAssortmentScope(groupId)))
+    return { scope, sourceGroupIds: groupIds, sourceCustomerOverrideId: null }
+  }
+
+  private async loadTerms(
+    groupId: string,
+    tenantId: string,
+    cache: Map<string, CustomerGroupTerms | null>,
+  ): Promise<CustomerGroupTerms | null> {
+    if (cache.has(groupId)) return cache.get(groupId) ?? null
+    const terms = await this.em.findOne(CustomerGroupTerms, { groupId, tenantId, deletedAt: null })
+    cache.set(groupId, terms)
+    return terms
+  }
+}
+
+export function createCustomerGroupsService(em: EntityManager): CustomerGroupsService {
+  return new DefaultCustomerGroupsService(em)
+}

package/src/modules/customer_groups/setup.ts

@@ -0,0 +1,11 @@
+import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
+
+export const setup: ModuleSetupConfig = {
+  defaultRoleFeatures: {
+    superadmin: ['customer_groups.*'],
+    admin: ['customer_groups.*'],
+    employee: ['customer_groups.groups.view', 'customer_groups.memberships.view', 'customer_groups.terms.view'],
+  },
+}
+
+export default setup

package/src/modules/customer_groups/widgets/injection/group-picker-field/widget.ts

@@ -0,0 +1,41 @@
+import { lazy } from 'react'
+import type { InjectionFieldWidget } from '@open-mercato/shared/modules/widgets/injection'
+
+// Step 1.11 — replaces the free-text `customerGroupId` UUID input on the
+// catalog price editor with a searchable picker sourced from
+// `/api/customer_groups/customer-groups`.
+//
+// This is a purely additive, optional injection: no `requires` entry is
+// declared anywhere, so `catalog` never gains a hard dependency on
+// `customer_groups`. When `customer_groups` is ejected/disabled, the widget
+// is never registered, `crud-form:<entityId>:fields` simply resolves empty,
+// and the host form falls back to its current plain free-text input with
+// no error — see `packages/core/src/modules/wms/widgets/injection/catalog-inventory-profile/widget.ts`
+// for the same pattern proven against `catalog.product`.
+const widget: InjectionFieldWidget = {
+  metadata: {
+    id: 'customer_groups.injection.group-picker-field',
+    priority: 100,
+    features: ['customer_groups.groups.view'],
+  },
+  fields: [
+    {
+      id: 'customerGroupId',
+      label: '',
+      labelKey: 'customer_groups.widgets.groupPicker.label',
+      type: 'custom',
+      // Targets the `scope` group on `catalog.catalog_product_price` (see
+      // `catalog/components/prices/priceFormFields.tsx`, read-only reference —
+      // this file is never edited by this module). Field ids collide by
+      // design: `CrudForm` resolves a field by id via a `Map` built from
+      // `[...fields, ...injectedFieldWidgets]`, so the later (injected) entry
+      // wins and replaces the host's plain-text `customerGroupId` input; its
+      // value is still submitted with the host payload. `label` stays empty
+      // because `GroupPickerField` renders its own translated label.
+      group: 'scope',
+      customComponent: lazy(() => import('../../../components/GroupPickerField')),
+    },
+  ],
+}
+
+export default widget