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

package/src/modules/warranty_claims/lib/businessHoursForm.ts

@@ -0,0 +1,206 @@
+import type { BusinessWeekday } from './businessHours'
+
+export type BusinessHoursIntervalRow = {
+  key: string
+  start: string
+  end: string
+}
+
+export type BusinessHoursDayRow = {
+  weekday: BusinessWeekday
+  enabled: boolean
+  intervals: BusinessHoursIntervalRow[]
+}
+
+export type BusinessHoursHolidayRow = {
+  key: string
+  date: string
+}
+
+export type BusinessHoursFormValue = {
+  timezone: string
+  days: BusinessHoursDayRow[]
+  holidays: BusinessHoursHolidayRow[]
+  extras: Record<string, unknown>
+  raw: string
+  rawDirty: boolean
+}
+
+export type BusinessHoursValidationMessages = {
+  error: {
+    window: string
+    holiday: string
+  }
+}
+
+export type BusinessHoursValidation =
+  | { ok: true; value: Record<string, unknown> | null }
+  | { ok: false; reason: 'json' }
+  | { ok: false; reason: 'rows'; rowErrors: Record<string, string> }
+
+const BUSINESS_HOURS_WEEKDAYS: readonly BusinessWeekday[] = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun']
+const BUSINESS_HOURS_DAY_MINUTES = 24 * 60
+const BUSINESS_HOURS_DEFAULT_START = '09:00'
+const BUSINESS_HOURS_DEFAULT_END = '17:00'
+const BUSINESS_HOURS_HOLIDAY_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+export function stringifyJsonValue(value: Record<string, unknown> | unknown[] | null): string {
+  if (value === null) return ''
+  const serialized = JSON.stringify(value, null, 2)
+  return typeof serialized === 'string' ? serialized : ''
+}
+
+let businessHoursRowSeq = 0
+
+export function nextBusinessHoursRowKey(): string {
+  businessHoursRowSeq += 1
+  return `business-hours-${businessHoursRowSeq}`
+}
+
+export function businessHoursTimeToMinutes(value: string): number | null {
+  const match = /^(\d{1,2}):(\d{2})(?::(\d{2}))?$/.exec(value.trim())
+  if (!match) return null
+  const hour = Number(match[1])
+  const minute = Number(match[2])
+  const second = match[3] ? Number(match[3]) : 0
+  if (minute > 59 || second !== 0) return null
+  if (hour === 24 && minute === 0) return BUSINESS_HOURS_DAY_MINUTES
+  if (hour > 23) return null
+  return hour * 60 + minute
+}
+
+export function formatBusinessHoursTime(minutes: number): string {
+  if (minutes === BUSINESS_HOURS_DAY_MINUTES) return '24:00'
+  const hour = Math.floor(minutes / 60)
+  const minute = minutes % 60
+  return `${String(hour).padStart(2, '0')}:${String(minute).padStart(2, '0')}`
+}
+
+export function businessHoursEndTimeToMinutes(value: string): number | null {
+  const minutes = businessHoursTimeToMinutes(value)
+  if (minutes === 0) return BUSINESS_HOURS_DAY_MINUTES
+  return minutes
+}
+
+export function formatBusinessHoursEndTimeForInput(minutes: number): string {
+  if (minutes === BUSINESS_HOURS_DAY_MINUTES) return '00:00'
+  return formatBusinessHoursTime(minutes)
+}
+
+export function normalizeBusinessHoursEndTime(value: string): string {
+  return businessHoursEndTimeToMinutes(value) === BUSINESS_HOURS_DAY_MINUTES ? '24:00' : value
+}
+
+export function createBusinessHoursIntervalRow(
+  start = BUSINESS_HOURS_DEFAULT_START,
+  end = BUSINESS_HOURS_DEFAULT_END,
+): BusinessHoursIntervalRow {
+  return { key: nextBusinessHoursRowKey(), start, end }
+}
+
+export function parseBusinessHoursIntervalRows(value: unknown): BusinessHoursIntervalRow[] {
+  if (!Array.isArray(value)) return []
+  const intervals: Array<{ startMinutes: number; endMinutes: number }> = []
+  for (const rawInterval of value) {
+    if (!isRecord(rawInterval)) continue
+    const startMinutes = typeof rawInterval.start === 'string' ? businessHoursTimeToMinutes(rawInterval.start) : null
+    const endMinutes = typeof rawInterval.end === 'string' ? businessHoursEndTimeToMinutes(rawInterval.end) : null
+    if (startMinutes === null || endMinutes === null || endMinutes <= startMinutes) continue
+    intervals.push({ startMinutes, endMinutes })
+  }
+  return intervals
+    .sort((left, right) => left.startMinutes - right.startMinutes)
+    .map((interval) => createBusinessHoursIntervalRow(
+      formatBusinessHoursTime(interval.startMinutes),
+      formatBusinessHoursEndTimeForInput(interval.endMinutes),
+    ))
+}
+
+export function buildBusinessHoursFormValue(record: Record<string, unknown> | null): BusinessHoursFormValue {
+  const source = isRecord(record) ? record : null
+  const rawWeek = source && isRecord(source.week) ? source.week : null
+  const days = BUSINESS_HOURS_WEEKDAYS.map((weekday) => {
+    const intervals = rawWeek ? parseBusinessHoursIntervalRows(rawWeek[weekday]) : []
+    return {
+      weekday,
+      enabled: intervals.length > 0,
+      intervals: intervals.length ? intervals : [createBusinessHoursIntervalRow()],
+    }
+  })
+  const holidays = Array.isArray(source?.holidays)
+    ? source.holidays
+        .filter((item): item is string => typeof item === 'string' && BUSINESS_HOURS_HOLIDAY_PATTERN.test(item))
+        .map((date) => ({ key: nextBusinessHoursRowKey(), date }))
+    : []
+  const extras: Record<string, unknown> = {}
+  if (source) {
+    for (const [key, entry] of Object.entries(source)) {
+      if (key === 'timezone' || key === 'week' || key === 'holidays') continue
+      extras[key] = entry
+    }
+  }
+  return {
+    timezone: typeof source?.timezone === 'string' ? source.timezone.trim() : '',
+    days,
+    holidays,
+    extras,
+    raw: stringifyJsonValue(source),
+    rawDirty: false,
+  }
+}
+
+export function serializeBusinessHoursRecord(value: BusinessHoursFormValue): Record<string, unknown> | null {
+  const result: Record<string, unknown> = { ...value.extras }
+  const timezone = value.timezone.trim()
+  if (timezone) result.timezone = timezone
+  const week: Partial<Record<BusinessWeekday, Array<{ start: string; end: string }>>> = {}
+  for (const day of value.days) {
+    if (!day.enabled) continue
+    const intervals = day.intervals
+      .map((interval) => ({ start: interval.start.trim(), end: normalizeBusinessHoursEndTime(interval.end.trim()) }))
+      .filter((interval) => interval.start.length > 0 || interval.end.length > 0)
+    if (intervals.length) week[day.weekday] = intervals
+  }
+  if (Object.keys(week).length) result.week = week
+  const holidays = Array.from(new Set(
+    value.holidays
+      .map((row) => row.date.trim())
+      .filter((date) => BUSINESS_HOURS_HOLIDAY_PATTERN.test(date)),
+  ))
+  if (holidays.length) result.holidays = holidays
+  return Object.keys(result).length ? result : null
+}
+
+export function validateBusinessHoursValue(
+  value: BusinessHoursFormValue,
+  translations: BusinessHoursValidationMessages,
+): BusinessHoursValidation {
+  if (value.rawDirty) return { ok: false, reason: 'json' }
+  const rowErrors: Record<string, string> = {}
+  for (const day of value.days) {
+    if (!day.enabled) continue
+    for (const interval of day.intervals) {
+      const startMinutes = businessHoursTimeToMinutes(interval.start)
+      const endMinutes = businessHoursEndTimeToMinutes(interval.end)
+      if (
+        startMinutes === null ||
+        endMinutes === null ||
+        startMinutes >= BUSINESS_HOURS_DAY_MINUTES ||
+        endMinutes <= startMinutes
+      ) {
+        rowErrors[interval.key] = translations.error.window
+      }
+    }
+  }
+  for (const holiday of value.holidays) {
+    if (!BUSINESS_HOURS_HOLIDAY_PATTERN.test(holiday.date.trim())) {
+      rowErrors[holiday.key] = translations.error.holiday
+    }
+  }
+  if (Object.keys(rowErrors).length) return { ok: false, reason: 'rows', rowErrors }
+  return { ok: true, value: serializeBusinessHoursRecord(value) }
+}

package/src/modules/warranty_claims/lib/claimTypeConfig.ts

@@ -0,0 +1,49 @@
+import { CrudHttpError } from '@open-mercato/shared/lib/crud/errors'
+import type { WarrantyClaimType } from '../data/validators'
+
+export type ClaimTypeUiConfig = {
+  lineHeaderKey: string
+  allowedDispositions: string[]
+}
+
+export const CLAIM_TYPE_UI_CONFIG: Record<WarrantyClaimType, ClaimTypeUiConfig> = {
+  warranty: {
+    lineHeaderKey: 'warranty_claims.form.lineHeader.warranty',
+    allowedDispositions: ['repair', 'replace', 'credit', 'refund', 'return_to_vendor', 'scrap', 'field_destroy', 'restock', 'deny'],
+  },
+  return: {
+    lineHeaderKey: 'warranty_claims.form.lineHeader.return',
+    allowedDispositions: ['restock', 'refund', 'replace', 'credit', 'deny'],
+  },
+  core_return: {
+    lineHeaderKey: 'warranty_claims.form.lineHeader.core_return',
+    allowedDispositions: ['credit', 'refund', 'restock', 'return_to_vendor', 'scrap', 'deny'],
+  },
+  vendor_recovery: {
+    lineHeaderKey: 'warranty_claims.form.lineHeader.vendor_recovery',
+    allowedDispositions: ['return_to_vendor', 'credit', 'replace', 'deny'],
+  },
+}
+
+export function resolveClaimTypeUiConfig(claimType: string | null | undefined): ClaimTypeUiConfig {
+  return (CLAIM_TYPE_UI_CONFIG as Record<string, ClaimTypeUiConfig>)[claimType ?? 'warranty'] ?? CLAIM_TYPE_UI_CONFIG.warranty
+}
+
+// Restocking fees and core charge/credit only apply to return and core-return claims. Warranty
+// and vendor-recovery claims settle on the credit amount alone, so these adjustment fields must
+// neither be edited nor rolled into the header totals for those types (LINE-05).
+const FINANCIAL_ADJUSTMENT_CLAIM_TYPES = new Set<WarrantyClaimType>(['return', 'core_return'])
+
+export function claimTypeAllowsLineFinancialAdjustments(claimType: string | null | undefined): boolean {
+  return FINANCIAL_ADJUSTMENT_CLAIM_TYPES.has((claimType ?? 'warranty') as WarrantyClaimType)
+}
+
+export function assertDispositionAllowedForType(
+  claimType: string | null | undefined,
+  disposition: string | null | undefined,
+): void {
+  if (!disposition) return
+  if (!resolveClaimTypeUiConfig(claimType).allowedDispositions.includes(disposition)) {
+    throw new CrudHttpError(400, { error: 'warranty_claims.errors.dispositionTypeConflict' })
+  }
+}

package/src/modules/warranty_claims/lib/decryptionSafety.ts

@@ -0,0 +1,19 @@
+const BASE64_PART = /^[A-Za-z0-9+/]+={0,2}$/
+
+export function isPotentialEncryptedPayload(value: unknown): boolean {
+  if (typeof value !== 'string') return false
+  const parts = value.split(':')
+  if (parts.length !== 4 || parts[3] !== 'v1') return false
+  const [iv, ciphertext, tag] = parts
+  return iv.length === 16
+    && ciphertext.length > 0
+    && tag.length === 24
+    && BASE64_PART.test(iv)
+    && BASE64_PART.test(ciphertext)
+    && BASE64_PART.test(tag)
+}
+
+export function readSafeDecryptedString(value: unknown): string | null {
+  if (typeof value !== 'string' || !value.trim().length || isPotentialEncryptedPayload(value)) return null
+  return value.trim()
+}

package/src/modules/warranty_claims/lib/deskFilters.ts

@@ -0,0 +1,131 @@
+import { sql, type SelectQueryBuilder } from 'kysely'
+import type { EntityManager } from '@mikro-orm/postgresql'
+import type { Where } from '@open-mercato/shared/lib/query/types'
+import { mergeIdFilter } from '@open-mercato/shared/lib/crud/ids'
+
+export const SLA_EXCLUDED_STATUSES = ['resolved', 'closed', 'rejected', 'cancelled', 'draft'] as const
+export const SLA_AT_RISK_EXCLUDED_STATUSES = SLA_EXCLUDED_STATUSES
+export const SLA_AT_RISK_MATCH_LIMIT = 500
+export const SLA_AT_RISK_DEFAULT_THRESHOLD_PCT = 75
+
+export const ISO_DATE_PATTERN = /^\d{4}-\d{2}-\d{2}$/
+
+const CLAIM_ID_NO_MATCH_FILTER = { $eq: '00000000-0000-0000-0000-000000000000' }
+
+export type WarrantyClaimsSlaTable = {
+  id: string
+  tenant_id: string
+  organization_id: string
+  status: string
+  deleted_at: Date | null
+  sla_due_at: Date | null
+  sla_paused_at: Date | null
+  submitted_at: Date | null
+}
+
+export type WarrantyClaimsSlaDb = {
+  warranty_claims: WarrantyClaimsSlaTable
+}
+
+export type SlaAtRiskLookupScope = {
+  tenantId: string
+  selectedOrganizationId: string | null
+  visibleOrganizationIds: string[] | null
+}
+
+export function normalizeSlaAtRiskThresholdPct(value: unknown): number {
+  const parsed = typeof value === 'number' ? value : Number(value)
+  if (!Number.isFinite(parsed)) return SLA_AT_RISK_DEFAULT_THRESHOLD_PCT
+  return Math.min(Math.max(parsed, 0), 100)
+}
+
+export function applySlaAtRiskConditions<O>(
+  query: SelectQueryBuilder<WarrantyClaimsSlaDb, 'warranty_claims', O>,
+  thresholdPct: number,
+  now: Date,
+): SelectQueryBuilder<WarrantyClaimsSlaDb, 'warranty_claims', O> {
+  const pct = normalizeSlaAtRiskThresholdPct(thresholdPct)
+  return query
+    .where('sla_due_at', '>', now)
+    .where('sla_paused_at', 'is', null)
+    .where('status', 'not in', [...SLA_EXCLUDED_STATUSES])
+    .where('submitted_at', 'is not', null)
+    .where(sql<boolean>`sla_due_at > submitted_at`)
+    .where(sql<boolean>`extract(epoch from (${now}::timestamptz - submitted_at)) * 100 >= extract(epoch from (sla_due_at - submitted_at)) * ${pct}`)
+}
+
+export async function findSlaAtRiskClaimIds(
+  em: EntityManager,
+  scope: SlaAtRiskLookupScope,
+  thresholdPct: number,
+  now: Date = new Date(),
+): Promise<string[]> {
+  const db = em.getKysely<WarrantyClaimsSlaDb>()
+  let query = applySlaAtRiskConditions(
+    db
+      .selectFrom('warranty_claims')
+      .select('id')
+      .where('tenant_id', '=', scope.tenantId)
+      .where('deleted_at', 'is', null),
+    thresholdPct,
+    now,
+  )
+  if (scope.selectedOrganizationId) {
+    query = query.where('organization_id', '=', scope.selectedOrganizationId)
+  } else if (scope.visibleOrganizationIds && scope.visibleOrganizationIds.length) {
+    query = query.where('organization_id', 'in', scope.visibleOrganizationIds)
+  }
+  const rows = await query.limit(SLA_AT_RISK_MATCH_LIMIT).execute()
+  return rows.map((row) => row.id)
+}
+
+export function narrowFiltersToClaimIds(filters: Record<string, unknown>, claimIds: string[]): void {
+  if (!claimIds.length) {
+    filters.id = { ...CLAIM_ID_NO_MATCH_FILTER }
+    return
+  }
+  const merged = mergeIdFilter(filters as Where<Record<string, unknown>>, claimIds) as Record<string, unknown>
+  const mergedId = merged.id
+  const mergedIn = mergedId && typeof mergedId === 'object' && !Array.isArray(mergedId)
+    ? (mergedId as Record<string, unknown>).$in
+    : undefined
+  if (Array.isArray(mergedIn) && mergedIn.length === 0) {
+    filters.id = { ...CLAIM_ID_NO_MATCH_FILTER }
+    return
+  }
+  filters.id = mergedId ?? { $in: claimIds }
+}
+
+export function buildAttentionFilter(atRiskClaimIds: string[], now: Date = new Date()): Record<string, unknown> {
+  const branches: Record<string, unknown>[] = [
+    { awaiting_staff_reply: { $eq: true } },
+    {
+      sla_due_at: { $lt: now },
+      sla_paused_at: { $exists: false },
+      submitted_at: { $exists: true },
+      status: { $nin: [...SLA_EXCLUDED_STATUSES] },
+    },
+  ]
+  if (atRiskClaimIds.length) branches.push({ id: { $in: atRiskClaimIds } })
+  return { $or: branches }
+}
+
+function parseIsoDateBoundary(value: string, boundary: 'start' | 'end'): Date | null {
+  if (!ISO_DATE_PATTERN.test(value)) return null
+  const suffix = boundary === 'start' ? 'T00:00:00.000Z' : 'T23:59:59.999Z'
+  const parsed = new Date(`${value}${suffix}`)
+  if (Number.isNaN(parsed.getTime())) return null
+  return parsed.toISOString().slice(0, 10) === value ? parsed : null
+}
+
+export function buildDateRangeFilter(
+  from: string | undefined,
+  to: string | undefined,
+): Record<string, Date> | null {
+  const range: Record<string, Date> = {}
+  const fromDate = from ? parseIsoDateBoundary(from, 'start') : null
+  const toDate = to ? parseIsoDateBoundary(to, 'end') : null
+  if (fromDate) range.$gte = fromDate
+  if (toDate) range.$lte = toDate
+  return Object.keys(range).length ? range : null
+}

package/src/modules/warranty_claims/lib/dictionaries.ts

@@ -0,0 +1,212 @@
+import type { EntityManager } from '@mikro-orm/postgresql'
+import { Dictionary, DictionaryEntry } from '@open-mercato/core/modules/dictionaries/data/entities'
+import {
+  normalizeDictionaryValue,
+  sanitizeDictionaryColor,
+  sanitizeDictionaryIcon,
+} from '@open-mercato/core/modules/dictionaries/lib/utils'
+import type { WarrantyClaimDictionaryKind } from '../data/constants'
+
+type WarrantyClaimDictionaryDefinition = {
+  key: string
+  name: string
+  singular: string
+  description: string
+  resourceKind: string
+  commandPrefix: string
+}
+
+type WarrantyClaimDictionarySeed = {
+  value: string
+  label: string
+  color?: string | null
+  icon?: string | null
+}
+
+type SeedScope = {
+  tenantId: string
+  organizationId: string
+}
+
+const DEFINITIONS: Record<WarrantyClaimDictionaryKind, WarrantyClaimDictionaryDefinition> = {
+  'warranty-claim-fault-code': {
+    key: 'warranty_claims.warranty_claim_fault_code',
+    name: 'Warranty claim fault codes',
+    singular: 'Warranty claim fault code',
+    description: 'Configurable fault codes used on warranty claim lines.',
+    resourceKind: 'warranty_claims.warranty-claim-fault-code',
+    commandPrefix: 'warranty_claims.warranty-claim-fault-codes',
+  },
+  'warranty-claim-reason': {
+    key: 'warranty_claims.warranty_claim_reason',
+    name: 'Warranty claim reasons',
+    singular: 'Warranty claim reason',
+    description: 'Configurable reasons used when creating warranty and return claims.',
+    resourceKind: 'warranty_claims.warranty-claim-reason',
+    commandPrefix: 'warranty_claims.warranty-claim-reasons',
+  },
+  'warranty-claim-rejection-reason': {
+    key: 'warranty_claims.warranty_claim_rejection_reason',
+    name: 'Warranty claim rejection reasons',
+    singular: 'Warranty claim rejection reason',
+    description: 'Configurable reasons used when rejecting warranty and return claims.',
+    resourceKind: 'warranty_claims.warranty-claim-rejection-reason',
+    commandPrefix: 'warranty_claims.warranty-claim-rejection-reasons',
+  },
+}
+
+const FAULT_CODE_DEFAULTS: WarrantyClaimDictionarySeed[] = [
+  { value: 'defective', label: 'Defective', color: '#ef4444', icon: 'lucide:triangle-alert' },
+  { value: 'damaged-in-transit', label: 'Damaged in transit', color: '#f59e0b', icon: 'lucide:truck' },
+  { value: 'wrong-item', label: 'Wrong item', color: '#6366f1', icon: 'lucide:package-x' },
+  { value: 'worn', label: 'Worn', color: '#94a3b8', icon: 'lucide:rotate-ccw' },
+  { value: 'doa', label: 'Dead on arrival', color: '#dc2626', icon: 'lucide:zap-off' },
+]
+
+const CLAIM_REASON_DEFAULTS: WarrantyClaimDictionarySeed[] = [
+  { value: 'warranty-defect', label: 'Warranty defect', color: '#ef4444', icon: 'lucide:shield-alert' },
+  { value: 'customer-remorse', label: 'Customer remorse', color: '#94a3b8', icon: 'lucide:undo-2' },
+  { value: 'wrong-order', label: 'Wrong order', color: '#6366f1', icon: 'lucide:list-x' },
+  { value: 'core-exchange', label: 'Core exchange', color: '#0d9488', icon: 'lucide:repeat-2' },
+  { value: 'vendor-recall', label: 'Vendor recall', color: '#f59e0b', icon: 'lucide:megaphone' },
+]
+
+const REJECTION_REASON_DEFAULTS: WarrantyClaimDictionarySeed[] = [
+  { value: 'out-of-warranty', label: 'Out of warranty', color: '#ef4444', icon: 'lucide:calendar-x' },
+  { value: 'no-proof-of-purchase', label: 'No proof of purchase', color: '#f59e0b', icon: 'lucide:receipt' },
+  { value: 'physical-abuse', label: 'Physical abuse', color: '#dc2626', icon: 'lucide:hammer' },
+  { value: 'not-our-product', label: 'Not our product', color: '#6366f1', icon: 'lucide:package-search' },
+  { value: 'duplicate-claim', label: 'Duplicate claim', color: '#94a3b8', icon: 'lucide:copy-x' },
+]
+
+export function getWarrantyClaimDictionaryDefinition(
+  kind: WarrantyClaimDictionaryKind
+): WarrantyClaimDictionaryDefinition {
+  return DEFINITIONS[kind]
+}
+
+export type WarrantyClaimDictionaryOption = {
+  value: string
+  label: string
+}
+
+export async function loadWarrantyClaimDictionaryOptions(
+  em: EntityManager,
+  scope: SeedScope,
+  kind: WarrantyClaimDictionaryKind
+): Promise<WarrantyClaimDictionaryOption[]> {
+  const def = getWarrantyClaimDictionaryDefinition(kind)
+  const dictionary = await em.findOne(Dictionary, {
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    key: def.key,
+    isActive: true,
+    deletedAt: null,
+  })
+  if (!dictionary) return []
+  const entries = await em.find(
+    DictionaryEntry,
+    { dictionary, tenantId: scope.tenantId, organizationId: scope.organizationId },
+    { orderBy: { position: 'asc', label: 'asc' } }
+  )
+  return entries.map((entry) => ({ value: entry.value, label: entry.label }))
+}
+
+export async function ensureWarrantyClaimDictionary(params: {
+  em: EntityManager
+  tenantId: string
+  organizationId: string
+  kind: WarrantyClaimDictionaryKind
+}): Promise<Dictionary> {
+  const { em, tenantId, organizationId, kind } = params
+  const def = getWarrantyClaimDictionaryDefinition(kind)
+  let dictionary = await em.findOne(Dictionary, {
+    tenantId,
+    organizationId,
+    key: def.key,
+    deletedAt: null,
+  })
+  if (!dictionary) {
+    dictionary = em.create(Dictionary, {
+      tenantId,
+      organizationId,
+      key: def.key,
+      name: def.name,
+      description: def.description,
+      isSystem: true,
+      isActive: true,
+      managerVisibility: 'hidden',
+      createdAt: new Date(),
+      updatedAt: new Date(),
+    })
+    em.persist(dictionary)
+    await em.flush()
+  }
+  return dictionary
+}
+
+async function ensureWarrantyClaimDictionaryEntry(
+  em: EntityManager,
+  scope: SeedScope,
+  kind: WarrantyClaimDictionaryKind,
+  seed: WarrantyClaimDictionarySeed
+): Promise<DictionaryEntry | null> {
+  const value = seed.value?.trim()
+  if (!value) return null
+  const dictionary = await ensureWarrantyClaimDictionary({
+    em,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    kind,
+  })
+  const normalizedValue = normalizeDictionaryValue(value)
+  const color = seed.color === undefined ? undefined : sanitizeDictionaryColor(seed.color)
+  const icon = seed.icon === undefined ? undefined : sanitizeDictionaryIcon(seed.icon)
+  const existing = await em.findOne(DictionaryEntry, {
+    dictionary,
+    tenantId: scope.tenantId,
+    organizationId: scope.organizationId,
+    normalizedValue,
+  })
+  if (existing) return existing
+  const now = new Date()
+  const entry = em.create(DictionaryEntry, {
+    dictionary,
+    organizationId: scope.organizationId,
+    tenantId: scope.tenantId,
+    value,
+    label: seed.label?.trim() || value,
+    normalizedValue,
+    color: color ?? null,
+    icon: icon ?? null,
+    createdAt: now,
+    updatedAt: now,
+  })
+  em.persist(entry)
+  return entry
+}
+
+async function seedWarrantyClaimDictionary(
+  em: EntityManager,
+  scope: SeedScope,
+  kind: WarrantyClaimDictionaryKind,
+  defaults: WarrantyClaimDictionarySeed[]
+): Promise<void> {
+  for (const seed of defaults) {
+    await ensureWarrantyClaimDictionaryEntry(em, scope, kind, seed)
+  }
+}
+
+export async function seedWarrantyClaimDictionaries(
+  em: EntityManager,
+  scope: SeedScope
+): Promise<void> {
+  await seedWarrantyClaimDictionary(em, scope, 'warranty-claim-fault-code', FAULT_CODE_DEFAULTS)
+  await seedWarrantyClaimDictionary(em, scope, 'warranty-claim-reason', CLAIM_REASON_DEFAULTS)
+  await seedWarrantyClaimDictionary(
+    em,
+    scope,
+    'warranty-claim-rejection-reason',
+    REJECTION_REASON_DEFAULTS
+  )
+}

package/src/modules/warranty_claims/lib/dictionaryLabels.ts

@@ -0,0 +1,16 @@
+export type DictionaryLabelKind = 'reason' | 'fault' | 'rejection'
+
+const PREFIX: Record<DictionaryLabelKind, string> = {
+  reason: 'warranty_claims.reasonOption',
+  fault: 'warranty_claims.faultOption',
+  rejection: 'warranty_claims.rejectionOption',
+}
+
+export function localizeDictionaryLabel(
+  t: (key: string, fallback?: string) => string,
+  kind: DictionaryLabelKind,
+  value: string,
+  fallbackLabel: string,
+): string {
+  return t(`${PREFIX[kind]}.${value}`, fallbackLabel)
+}