@open-mercato/core 0.6.8-develop.6998.1.d2bc46c56c → 0.6.8-develop.7001.1.03608ab252

package/src/modules/warranty_claims/migrations/Migration20260703191537_warranty_claims.ts

@@ -0,0 +1,38 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260703191537_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "warranty_claims" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "claim_number" text not null, "claim_type" text not null, "status" text not null default 'draft', "channel" text not null default 'staff', "priority" text not null default 'normal', "customer_id" uuid null, "customer_name" text null, "vendor_name" text null, "vendor_ref" text null, "order_id" uuid null, "sales_return_id" uuid null, "replacement_order_id" uuid null, "source_claim_id" uuid null, "advance_replacement" boolean not null default false, "advance_shipped_at" timestamptz null, "reason_code" text null, "rejection_reason_code" text null, "resolution_summary" text null, "notes" text null, "currency_code" text null, "total_claimed_amount" numeric(18,4) null, "total_approved_amount" numeric(18,4) null, "total_recovered_amount" numeric(18,4) null, "sla_due_at" timestamptz null, "submitted_at" timestamptz null, "resolved_at" timestamptz null, "closed_at" timestamptz null, "assignee_user_id" uuid null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create index "warranty_claims_status_idx" on "warranty_claims" ("organization_id", "tenant_id", "status");`);
+    this.addSql(`create index "warranty_claims_order_idx" on "warranty_claims" ("order_id", "organization_id", "tenant_id");`);
+    this.addSql(`create index "warranty_claims_customer_idx" on "warranty_claims" ("customer_id", "organization_id", "tenant_id");`);
+    this.addSql(`alter table "warranty_claims" add constraint "warranty_claims_number_unique" unique ("tenant_id", "organization_id", "claim_number");`);
+
+    this.addSql(`create table "warranty_claim_events" ("id" uuid not null default gen_random_uuid(), "claim_id" uuid not null, "organization_id" uuid not null, "tenant_id" uuid not null, "kind" text not null, "visibility" text not null default 'internal', "body" text null, "payload" jsonb null, "actor_user_id" uuid null, "actor_customer_id" uuid null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "warranty_claim_events_claim_created_idx" on "warranty_claim_events" ("claim_id", "created_at");`);
+
+    this.addSql(`create table "warranty_claim_lines" ("id" uuid not null default gen_random_uuid(), "claim_id" uuid not null, "organization_id" uuid not null, "tenant_id" uuid not null, "line_no" int not null, "product_id" uuid null, "variant_id" uuid null, "sku" text null, "product_name" text null, "order_line_id" uuid null, "serial_number" text null, "lot_number" text null, "purchase_date" timestamptz null, "warranty_months" int null, "warranty_expires_at" timestamptz null, "warranty_status" text not null default 'unknown', "fault_code" text null, "fault_description" text null, "qty_claimed" numeric(18,4) not null default '1', "qty_approved" numeric(18,4) null, "qty_received" numeric(18,4) null, "condition_on_receipt" text null, "inspection_notes" text null, "disposition" text null, "line_status" text not null default 'pending', "credit_amount" numeric(18,4) null, "restocking_fee" numeric(18,4) null, "core_charge_amount" numeric(18,4) null, "core_credit_amount" numeric(18,4) null, "vendor_claim_line_id" uuid null, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create index "warranty_claim_lines_product_idx" on "warranty_claim_lines" ("product_id", "organization_id", "tenant_id");`);
+    this.addSql(`create index "warranty_claim_lines_order_line_idx" on "warranty_claim_lines" ("order_line_id", "organization_id", "tenant_id");`);
+    this.addSql(`create index "warranty_claim_lines_claim_idx" on "warranty_claim_lines" ("claim_id", "organization_id", "tenant_id");`);
+
+    this.addSql(`create table "warranty_claim_sequences" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "claim_type" text not null, "next_number" int not null default 1, "created_at" timestamptz not null, "updated_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`alter table "warranty_claim_sequences" add constraint "warranty_claim_sequences_type_unique" unique ("tenant_id", "organization_id", "claim_type");`);
+
+    this.addSql(`alter table "warranty_claim_events" add constraint "warranty_claim_events_claim_id_foreign" foreign key ("claim_id") references "warranty_claims" ("id");`);
+
+    this.addSql(`alter table "warranty_claim_lines" add constraint "warranty_claim_lines_claim_id_foreign" foreign key ("claim_id") references "warranty_claims" ("id");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claim_events" drop constraint if exists "warranty_claim_events_claim_id_foreign";`);
+    this.addSql(`alter table "warranty_claim_lines" drop constraint if exists "warranty_claim_lines_claim_id_foreign";`);
+
+    this.addSql(`drop table if exists "warranty_claim_sequences" cascade;`);
+    this.addSql(`drop table if exists "warranty_claim_lines" cascade;`);
+    this.addSql(`drop table if exists "warranty_claim_events" cascade;`);
+    this.addSql(`drop table if exists "warranty_claims" cascade;`);
+  }
+
+}

package/src/modules/warranty_claims/migrations/Migration20260704115605_warranty_claims.ts

@@ -0,0 +1,17 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260704115605_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "warranty_claim_settings" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "sla_hours" int not null default 48, "sla_pause_on_info_requested" boolean not null default true, "sla_at_risk_threshold_pct" int not null default 75, "auto_approve_enabled" boolean not null default false, "auto_approve_max_amount" numeric(18,4) null, "auto_approve_currency_code" text null, "auto_approve_require_in_warranty" boolean not null default true, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`alter table "warranty_claim_settings" add constraint "warranty_claim_settings_scope_unique" unique ("organization_id", "tenant_id");`);
+
+    this.addSql(`alter table "warranty_claims" add "sla_paused_at" timestamptz null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claims" drop column "sla_paused_at";`);
+    this.addSql(`drop table if exists "warranty_claim_settings" cascade;`);
+  }
+
+}

package/src/modules/warranty_claims/migrations/Migration20260704230000_warranty_claims.ts

@@ -0,0 +1,17 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260704230000_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claims" add column "external_ref" text null, add column "contact_email" text null;`);
+    this.addSql(`create unique index "warranty_claims_external_ref_unique" on "warranty_claims" ("tenant_id", "organization_id", "external_ref") where "external_ref" is not null and "deleted_at" is null;`);
+    this.addSql(`alter table "warranty_claim_settings" add column "default_warranty_months" int null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index if exists "warranty_claims_external_ref_unique";`);
+    this.addSql(`alter table "warranty_claim_settings" drop column "default_warranty_months";`);
+    this.addSql(`alter table "warranty_claims" drop column "external_ref", drop column "contact_email";`);
+  }
+
+}

package/src/modules/warranty_claims/migrations/Migration20260705121601_warranty_claims.ts

@@ -0,0 +1,37 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260705121601_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "warranty_claim_registrations" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "serial_number" text null, "product_id" uuid null, "variant_id" uuid null, "sku" text null, "product_name" text null, "customer_id" uuid null, "order_id" uuid null, "purchase_date" timestamptz null, "warranty_months" int null, "warranty_expires_at" timestamptz null, "coverage_type" text null, "source" text null, "proof_attachment_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 index "warranty_claim_registrations_customer_idx" on "warranty_claim_registrations" ("tenant_id", "organization_id", "customer_id");`);
+    this.addSql(`create index "warranty_claim_registrations_serial_idx" on "warranty_claim_registrations" ("tenant_id", "organization_id", "serial_number");`);
+
+    this.addSql(`create table "warranty_claim_troubleshooting_guides" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "claim_type" text null, "reason_code" text null, "title" text not null, "steps" jsonb null, "is_active" boolean not null default true, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create index "warranty_claim_troubleshooting_guides_lookup_idx" on "warranty_claim_troubleshooting_guides" ("tenant_id", "organization_id", "claim_type", "reason_code");`);
+
+    this.addSql(`create table "warranty_claim_vendor_policies" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "vendor_name" text not null, "vendor_ref" text null, "coverage_months" int null, "claimable_reason_codes" jsonb null, "recovery_rate_pct" numeric(5,2) null, "contact_email" text null, "auto_generate_recovery" boolean not null default false, "is_active" boolean not null default true, "created_at" timestamptz not null, "updated_at" timestamptz not null, "deleted_at" timestamptz null, primary key ("id"));`);
+    this.addSql(`create index "warranty_claim_vendor_policies_vendor_idx" on "warranty_claim_vendor_policies" ("tenant_id", "organization_id", "vendor_name");`);
+
+    this.addSql(`alter table "warranty_claims" add "return_label_url" text null, add "return_tracking_number" text null, add "return_carrier" text null, add "escalation_level" int not null default 0, add "escalated_at" timestamptz null, add "intake_message_ref" text null, add "entitlement_source" text null;`);
+    this.addSql(`create unique index "warranty_claims_intake_message_ref_unique" on "warranty_claims" ("tenant_id", "organization_id", "intake_message_ref") where "intake_message_ref" is not null and "deleted_at" is null;`);
+
+    this.addSql(`alter table "warranty_claim_lines" add "condition_grade" text null, add "quarantine_status" text not null default 'none', add "assessment_payload" jsonb null, add "vendor_name" text null;`);
+
+    this.addSql(`alter table "warranty_claim_settings" add "business_hours" jsonb null, add "escalation_tiers" jsonb null, add "adjudication_use_rules" boolean not null default false, add "quarantine_grades" jsonb null, add "return_label_provider" text null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop table if exists "warranty_claim_vendor_policies" cascade;`);
+    this.addSql(`drop table if exists "warranty_claim_troubleshooting_guides" cascade;`);
+    this.addSql(`drop table if exists "warranty_claim_registrations" cascade;`);
+
+    this.addSql(`alter table "warranty_claim_lines" drop column "condition_grade", drop column "quarantine_status", drop column "assessment_payload", drop column "vendor_name";`);
+
+    this.addSql(`alter table "warranty_claim_settings" drop column "business_hours", drop column "escalation_tiers", drop column "adjudication_use_rules", drop column "quarantine_grades", drop column "return_label_provider";`);
+
+    this.addSql(`drop index if exists "warranty_claims_intake_message_ref_unique";`);
+    this.addSql(`alter table "warranty_claims" drop column "return_label_url", drop column "return_tracking_number", drop column "return_carrier", drop column "escalation_level", drop column "escalated_at", drop column "intake_message_ref", drop column "entitlement_source";`);
+  }
+
+}

package/src/modules/warranty_claims/migrations/Migration20260709120000_warranty_claims.ts

@@ -0,0 +1,25 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260709120000_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claims" add "order_number" text null, add "awaiting_staff_reply" boolean not null default false;`);
+    this.addSql(`
+      do $$ begin
+        if to_regclass('sales_orders') is not null then
+          update "warranty_claims" wc
+          set "order_number" = so."order_number"
+          from "sales_orders" so
+          where wc."order_id" = so."id"
+            and wc."order_number" is null
+            and so."order_number" is not null;
+        end if;
+      end $$;
+    `);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claims" drop column "order_number", drop column "awaiting_staff_reply";`);
+  }
+
+}

package/src/modules/warranty_claims/migrations/Migration20260710023607_warranty_claims.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260710023607_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claims" add "sla_at_risk_notified_at" timestamptz null, add "sla_breached_notified_at" timestamptz null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claims" drop column "sla_at_risk_notified_at", drop column "sla_breached_notified_at";`);
+  }
+
+}

package/src/modules/warranty_claims/migrations/Migration20260716203936_warranty_claims.ts

@@ -0,0 +1,15 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260716203936_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claim_settings" add column "return_window_days" int null;`);
+    this.addSql(`create index "warranty_claims_return_tracking_idx" on "warranty_claims" ("tenant_id", "organization_id", "return_tracking_number") where "return_tracking_number" is not null and "deleted_at" is null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index "warranty_claims_return_tracking_idx";`);
+    this.addSql(`alter table "warranty_claim_settings" drop column "return_window_days";`);
+  }
+
+}

package/src/modules/warranty_claims/migrations/Migration20260717150000_warranty_claims.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260717150000_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claims" add column "credit_memo_id" uuid null;`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`alter table "warranty_claims" drop column "credit_memo_id";`);
+  }
+
+}

package/src/modules/warranty_claims/migrations/Migration20260719120000_warranty_claims.ts

@@ -0,0 +1,13 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260719120000_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create index "warranty_claim_lines_serial_idx" on "warranty_claim_lines" ("tenant_id", "organization_id", "serial_number");`);
+  }
+
+  override down(): void | Promise<void> {
+    this.addSql(`drop index "warranty_claim_lines_serial_idx";`);
+  }
+
+}

package/src/modules/warranty_claims/migrations/Migration20260813103053_warranty_claims.ts

@@ -0,0 +1,11 @@
+import { Migration } from '@mikro-orm/migrations';
+
+export class Migration20260813103053_warranty_claims extends Migration {
+
+  override up(): void | Promise<void> {
+    this.addSql(`create table "warranty_claim_sla_signals" ("id" uuid not null default gen_random_uuid(), "organization_id" uuid not null, "tenant_id" uuid not null, "claim_id" uuid not null, "event_id" text not null, "cycle_key" text not null, "payload" jsonb not null, "lease_token" uuid null, "lease_expires_at" timestamptz null, "published_at" timestamptz null, "created_at" timestamptz not null, primary key ("id"));`);
+    this.addSql(`create index "warranty_claim_sla_signals_pending_scope_idx" on "warranty_claim_sla_signals" ("tenant_id", "organization_id", "published_at", "created_at");`);
+    this.addSql(`alter table "warranty_claim_sla_signals" add constraint "warranty_claim_sla_signals_claim_event_cycle_unique" unique ("tenant_id", "organization_id", "claim_id", "event_id", "cycle_key");`);
+  }
+
+}

package/src/modules/warranty_claims/notifications.client.ts

@@ -0,0 +1,78 @@
+'use client'
+
+import type {
+  NotificationTypeAction,
+  NotificationTypeDefinition,
+} from '@open-mercato/shared/modules/notifications/types'
+import { WarrantyClaimNotificationRenderer } from './widgets/notifications/WarrantyClaimNotificationRenderer'
+
+const CLAIM_DETAIL_HREF = '/backend/warranty_claims/{sourceEntityId}'
+
+function viewClaimAction(): NotificationTypeAction {
+  return {
+    id: 'view',
+    labelKey: 'common.view',
+    variant: 'outline',
+    href: CLAIM_DETAIL_HREF,
+    icon: 'external-link',
+  }
+}
+
+function claimNotificationType(
+  type: string,
+  titleKey: string,
+  bodyKey: string,
+  icon: string,
+  severity: NotificationTypeDefinition['severity'] = 'info',
+): NotificationTypeDefinition {
+  return {
+    type,
+    module: 'warranty_claims',
+    titleKey,
+    bodyKey,
+    icon,
+    severity,
+    actions: [viewClaimAction()],
+    linkHref: CLAIM_DETAIL_HREF,
+    Renderer: WarrantyClaimNotificationRenderer,
+    expiresAfterHours: 168,
+  }
+}
+
+export const warrantyClaimsNotificationTypes: NotificationTypeDefinition[] = [
+  claimNotificationType(
+    'warranty_claims.claim.submitted',
+    'warranty_claims.notifications.submitted.title',
+    'warranty_claims.notifications.submitted.body',
+    'clipboard-check',
+  ),
+  claimNotificationType(
+    'warranty_claims.claim.assigned',
+    'warranty_claims.notifications.assigned.title',
+    'warranty_claims.notifications.assigned.body',
+    'user-check',
+  ),
+  claimNotificationType(
+    'warranty_claims.claim.status_changed',
+    'warranty_claims.notifications.statusChanged.title',
+    'warranty_claims.notifications.statusChanged.body',
+    'refresh-cw',
+  ),
+  claimNotificationType(
+    'warranty_claims.claim.escalated',
+    'warranty_claims.notifications.escalated.title',
+    'warranty_claims.notifications.escalated.body',
+    'alarm-clock',
+    'warning',
+  ),
+  claimNotificationType(
+    'warranty_claims.claim.customer_replied',
+    'warranty_claims.notifications.customerReplied.title',
+    'warranty_claims.notifications.customerReplied.body',
+    'message-square-reply',
+  ),
+]
+
+export const notificationTypes = warrantyClaimsNotificationTypes
+
+export default warrantyClaimsNotificationTypes

package/src/modules/warranty_claims/notifications.ts

@@ -0,0 +1,101 @@
+import type { NotificationTypeDefinition } from '@open-mercato/shared/modules/notifications/types'
+
+export const notificationTypes: NotificationTypeDefinition[] = [
+  {
+    type: 'warranty_claims.claim.submitted',
+    module: 'warranty_claims',
+    titleKey: 'warranty_claims.notifications.submitted.title',
+    bodyKey: 'warranty_claims.notifications.submitted.body',
+    icon: 'clipboard-check',
+    severity: 'info',
+    actions: [
+      {
+        id: 'view',
+        labelKey: 'common.view',
+        variant: 'outline',
+        href: '/backend/warranty_claims/{sourceEntityId}',
+        icon: 'external-link',
+      },
+    ],
+    linkHref: '/backend/warranty_claims/{sourceEntityId}',
+    expiresAfterHours: 168,
+  },
+  {
+    type: 'warranty_claims.claim.assigned',
+    module: 'warranty_claims',
+    titleKey: 'warranty_claims.notifications.assigned.title',
+    bodyKey: 'warranty_claims.notifications.assigned.body',
+    icon: 'user-check',
+    severity: 'info',
+    actions: [
+      {
+        id: 'view',
+        labelKey: 'common.view',
+        variant: 'outline',
+        href: '/backend/warranty_claims/{sourceEntityId}',
+        icon: 'external-link',
+      },
+    ],
+    linkHref: '/backend/warranty_claims/{sourceEntityId}',
+    expiresAfterHours: 168,
+  },
+  {
+    type: 'warranty_claims.claim.status_changed',
+    module: 'warranty_claims',
+    titleKey: 'warranty_claims.notifications.statusChanged.title',
+    bodyKey: 'warranty_claims.notifications.statusChanged.body',
+    icon: 'refresh-cw',
+    severity: 'info',
+    actions: [
+      {
+        id: 'view',
+        labelKey: 'common.view',
+        variant: 'outline',
+        href: '/backend/warranty_claims/{sourceEntityId}',
+        icon: 'external-link',
+      },
+    ],
+    linkHref: '/backend/warranty_claims/{sourceEntityId}',
+    expiresAfterHours: 168,
+  },
+  {
+    type: 'warranty_claims.claim.escalated',
+    module: 'warranty_claims',
+    titleKey: 'warranty_claims.notifications.escalated.title',
+    bodyKey: 'warranty_claims.notifications.escalated.body',
+    icon: 'alarm-clock',
+    severity: 'warning',
+    actions: [
+      {
+        id: 'view',
+        labelKey: 'common.view',
+        variant: 'outline',
+        href: '/backend/warranty_claims/{sourceEntityId}',
+        icon: 'external-link',
+      },
+    ],
+    linkHref: '/backend/warranty_claims/{sourceEntityId}',
+    expiresAfterHours: 168,
+  },
+  {
+    type: 'warranty_claims.claim.customer_replied',
+    module: 'warranty_claims',
+    titleKey: 'warranty_claims.notifications.customerReplied.title',
+    bodyKey: 'warranty_claims.notifications.customerReplied.body',
+    icon: 'message-square-reply',
+    severity: 'info',
+    actions: [
+      {
+        id: 'view',
+        labelKey: 'common.view',
+        variant: 'outline',
+        href: '/backend/warranty_claims/{sourceEntityId}',
+        icon: 'external-link',
+      },
+    ],
+    linkHref: '/backend/warranty_claims/{sourceEntityId}',
+    expiresAfterHours: 168,
+  },
+]
+
+export default notificationTypes

package/src/modules/warranty_claims/search.ts

@@ -0,0 +1,199 @@
+import { SortDir, type QueryEngine } from '@open-mercato/shared/lib/query/types'
+import type {
+  SearchBuildContext,
+  SearchIndexSource,
+  SearchModuleConfig,
+  SearchResultLink,
+  SearchResultPresenter,
+} from '@open-mercato/shared/modules/search'
+import { E } from '#generated/entities.ids.generated'
+import { createLogger } from '@open-mercato/shared/lib/logger'
+import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
+
+const logger = createLogger('warranty_claims')
+
+type SearchContext = SearchBuildContext & {
+  tenantId: string
+  queryEngine?: QueryEngine
+}
+
+function assertTenantContext(ctx: SearchBuildContext): asserts ctx is SearchContext {
+  if (typeof ctx.tenantId !== 'string' || ctx.tenantId.length === 0) {
+    throw new Error('[internal] [search.warranty_claims] Missing tenantId in search build context')
+  }
+}
+
+function readString(record: Record<string, unknown>, snakeKey: string, camelKey?: string): string | null {
+  const value = record[snakeKey] ?? (camelKey ? record[camelKey] : undefined)
+  if (typeof value !== 'string') return null
+  const trimmed = value.trim()
+  return trimmed.length ? trimmed : null
+}
+
+function appendLine(lines: string[], label: string, value: unknown): void {
+  if (typeof value !== 'string') return
+  const trimmed = value.trim()
+  if (!trimmed.length) return
+  lines.push(`${label}: ${trimmed}`)
+}
+
+function resolveClaimId(record: Record<string, unknown>): string | null {
+  return readString(record, 'id', 'id')
+}
+
+function resolvePresenter(record: Record<string, unknown>): SearchResultPresenter {
+  const claimNumber = readString(record, 'claim_number', 'claimNumber') ?? 'Warranty claim'
+  const customerName = readString(record, 'customer_name', 'customerName')
+  const claimType = readString(record, 'claim_type', 'claimType')
+  const status = readString(record, 'status', 'status')
+  const subtitle = [customerName, claimType].filter((value): value is string => Boolean(value)).join(' — ')
+  return {
+    title: claimNumber,
+    subtitle: subtitle || undefined,
+    icon: 'shield-check',
+    badge: status ?? undefined,
+  }
+}
+
+async function loadClaimLineRows(ctx: SearchContext, claimId: string): Promise<Array<Record<string, unknown>>> {
+  if (!ctx.queryEngine) return []
+  try {
+    const rows: Array<Record<string, unknown>> = []
+    const pageSize = 100
+    for (let page = 1; ; page += 1) {
+      const result = await ctx.queryEngine.query<Record<string, unknown>>(E.warranty_claims.warranty_claim_line, {
+        tenantId: ctx.tenantId,
+        organizationId: ctx.organizationId ?? undefined,
+        filters: { claim_id: { $eq: claimId } },
+        fields: [
+          'id',
+          'line_no',
+          'sku',
+          'product_name',
+          'serial_number',
+          'lot_number',
+          'fault_code',
+          'warranty_status',
+          'disposition',
+          'line_status',
+        ],
+        page: { page, pageSize },
+        sort: [
+          { field: 'line_no', dir: SortDir.Asc },
+          { field: 'id', dir: SortDir.Asc },
+        ],
+      })
+      rows.push(...result.items)
+      if (result.items.length < pageSize || rows.length >= result.total) break
+    }
+    return rows
+  } catch (err) {
+    logger.warn('[search.warranty_claims] Failed to load claim lines', {
+      claimId,
+      error: err instanceof Error ? err.message : err,
+    })
+    return []
+  }
+}
+
+function appendLineRows(lines: string[], lineRows: Array<Record<string, unknown>>): void {
+  for (const row of lineRows) {
+    appendLine(lines, 'Line SKU', readString(row, 'sku', 'sku') ?? '')
+    appendLine(lines, 'Line product', readString(row, 'product_name', 'productName') ?? '')
+    appendLine(lines, 'Serial number', readString(row, 'serial_number', 'serialNumber') ?? '')
+    appendLine(lines, 'Lot number', readString(row, 'lot_number', 'lotNumber') ?? '')
+    appendLine(lines, 'Fault code', readString(row, 'fault_code', 'faultCode') ?? '')
+    appendLine(lines, 'Warranty status', readString(row, 'warranty_status', 'warrantyStatus') ?? '')
+    appendLine(lines, 'Disposition', readString(row, 'disposition', 'disposition') ?? '')
+    appendLine(lines, 'Line status', readString(row, 'line_status', 'lineStatus') ?? '')
+  }
+}
+
+function buildClaimUrl(record: Record<string, unknown>): string | null {
+  const claimId = resolveClaimId(record)
+  return claimId ? `/backend/warranty_claims/${claimId}` : null
+}
+
+export const searchConfig: SearchModuleConfig = {
+  entities: [
+    {
+      entityId: E.warranty_claims.warranty_claim,
+      enabled: true,
+      priority: 20,
+
+      buildSource: async (ctx: SearchBuildContext): Promise<SearchIndexSource | null> => {
+        assertTenantContext(ctx)
+        const record = ctx.record
+        const lines: string[] = []
+        appendLine(lines, 'Claim number', readString(record, 'claim_number', 'claimNumber') ?? '')
+        appendLine(lines, 'Customer', readString(record, 'customer_name', 'customerName') ?? '')
+        appendLine(lines, 'Order number', readString(record, 'order_number', 'orderNumber') ?? '')
+        appendLine(lines, 'Claim type', readString(record, 'claim_type', 'claimType') ?? '')
+        appendLine(lines, 'Status', readString(record, 'status', 'status') ?? '')
+        appendLine(lines, 'Vendor', readString(record, 'vendor_name', 'vendorName') ?? '')
+        appendLine(lines, 'Vendor reference', readString(record, 'vendor_ref', 'vendorRef') ?? '')
+
+        const claimId = resolveClaimId(record)
+        const lineRows = claimId ? await loadClaimLineRows(ctx, claimId) : []
+        appendLineRows(lines, lineRows)
+        if (!lines.length) return null
+
+        const presenter = resolvePresenter(record)
+        const url = buildClaimUrl(record)
+        const links: SearchResultLink[] = url ? [{ href: url, label: presenter.title, kind: 'primary' }] : []
+        return {
+          text: lines,
+          presenter,
+          links,
+          checksumSource: {
+            record,
+            customFields: ctx.customFields,
+            lineRows,
+          },
+        }
+      },
+
+      formatResult: (ctx: SearchBuildContext): SearchResultPresenter | null => {
+        assertTenantContext(ctx)
+        return resolvePresenter(ctx.record)
+      },
+
+      resolveUrl: (ctx: SearchBuildContext): string | null => buildClaimUrl(ctx.record),
+
+      resolveLinks: async (ctx: SearchBuildContext): Promise<SearchResultLink[] | null> => {
+        const url = buildClaimUrl(ctx.record)
+        if (!url) return null
+        const { t } = await resolveTranslations()
+        return [{ href: url, label: t('warranty_claims.search.openClaim', 'Open claim'), kind: 'secondary' }]
+      },
+
+      fieldPolicy: {
+        searchable: [
+          'claim_number',
+          'claim_type',
+          'status',
+          'priority',
+          'customer_name',
+          'vendor_name',
+          'vendor_ref',
+        ],
+        hashOnly: ['customer_id', 'order_id', 'sales_return_id', 'replacement_order_id', 'source_claim_id'],
+        excluded: [
+          'tenant_id',
+          'organization_id',
+          'assignee_user_id',
+          'deleted_at',
+          'notes',
+          'resolution_summary',
+          'contact_email',
+          'fault_description',
+          'inspection_notes',
+          'rejection_reason_code',
+        ],
+      },
+      aclFeatures: ['warranty_claims.claim.view'],
+    },
+  ],
+}
+
+export default searchConfig