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

package/src/modules/warranty_claims/backend/warranty_claims/troubleshooting-guides/page.tsx

@@ -0,0 +1,477 @@
+"use client"
+
+import * as React from 'react'
+import Link from 'next/link'
+import { useRouter } from 'next/navigation'
+import type { LegacyColumnDef as ColumnDef } from '@tanstack/react-table/legacy'
+import { Page, PageBody } from '@open-mercato/ui/backend/Page'
+import { DataTable, type BulkAction, type DataTableExportFormat } from '@open-mercato/ui/backend/DataTable'
+import { RowActions } from '@open-mercato/ui/backend/RowActions'
+import type { FilterDef, FilterValues } from '@open-mercato/ui/backend/FilterBar'
+import { ListEmptyState } from '@open-mercato/ui/backend/filters/ListEmptyState'
+import { Button } from '@open-mercato/ui/primitives/button'
+import { StatusBadge } from '@open-mercato/ui/primitives/status-badge'
+import { apiCall, withScopedApiRequestHeaders } from '@open-mercato/ui/backend/utils/apiCall'
+import { runBulkDelete } from '@open-mercato/ui/backend/utils/bulkDelete'
+import { buildCrudExportUrl, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
+import { buildOptimisticLockHeader } from '@open-mercato/ui/backend/utils/optimisticLock'
+import { flash } from '@open-mercato/ui/backend/FlashMessages'
+import { useConfirmDialog } from '@open-mercato/ui/backend/confirm-dialog'
+import { useGuardedMutation } from '@open-mercato/ui/backend/injection/useGuardedMutation'
+import { surfaceRecordConflict } from '@open-mercato/ui/backend/conflicts'
+import { useOrganizationScopeVersion } from '@open-mercato/shared/lib/frontend/useOrganizationScope'
+import { useLocale, useT, type TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+import { formatDateTime, formatRelativeTime } from '@open-mercato/shared/lib/time'
+import { Plus } from 'lucide-react'
+import type { TroubleshootingNode } from '../../../lib/troubleshooting'
+import { CLAIM_TYPES } from '../../../data/validators'
+import { localizeDictionaryLabel } from '../../../lib/dictionaryLabels'
+import { fetchClaimReasonOptions } from '../../components/claimReasonOptions'
+import {
+  activeLabel,
+  claimTypeLabel,
+  normalizeTroubleshootingGuide,
+  type TroubleshootingGuideRecord,
+} from './troubleshootingGuideForm'
+import { WarrantyWorkspace } from '../../components/WarrantyWorkspace'
+import { extensionPoints } from '../../../extension-points'
+
+type TroubleshootingGuidesResponse = {
+  items?: unknown[]
+  total?: number
+  totalPages?: number
+  error?: string
+}
+
+const PAGE_SIZE = 20
+type GuideSegment = 'all' | 'published' | 'draft'
+
+function reasonLabel(value: string | null, t: TranslateFn, storedLabels: Record<string, string>): string {
+  if (!value) return t('warranty_claims.troubleshootingGuides.reason.any', 'Any reason')
+  return localizeDictionaryLabel(t, 'reason', value, storedLabels[value] ?? value)
+}
+
+function toFilterString(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length ? value.trim() : null
+}
+
+function countGuideSteps(node: TroubleshootingNode | null): number {
+  if (!node) return 0
+  return 1 + node.options.reduce((count, option) => count + (option.next ? countGuideSteps(option.next) : 1), 0)
+}
+
+export default function WarrantyTroubleshootingGuidesPage() {
+  const t = useT()
+  const locale = useLocale()
+  const router = useRouter()
+  const scopeVersion = useOrganizationScopeVersion()
+  const { confirm, ConfirmDialogElement } = useConfirmDialog()
+  const [rows, setRows] = React.useState<TroubleshootingGuideRecord[]>([])
+  const [page, setPage] = React.useState(1)
+  const [total, setTotal] = React.useState(0)
+  const [totalPages, setTotalPages] = React.useState(1)
+  const [tabCounts, setTabCounts] = React.useState<Partial<Record<GuideSegment, number>>>({})
+  const [search, setSearch] = React.useState('')
+  const [filterValues, setFilterValues] = React.useState<FilterValues>({})
+  const [loading, setLoading] = React.useState(true)
+  const [reloadToken, setReloadToken] = React.useState(0)
+  const [reasonLabels, setReasonLabels] = React.useState<Record<string, string>>({})
+
+  React.useEffect(() => {
+    let cancelled = false
+    void fetchClaimReasonOptions(t)
+      .then((options) => {
+        if (cancelled) return
+        setReasonLabels(Object.fromEntries(options.map((option) => [option.value, option.label])))
+      })
+      .catch(() => {})
+    return () => { cancelled = true }
+  }, [t])
+
+  const mutationContextId = 'warranty-claim-troubleshooting-guides-list'
+  const { runMutation, retryLastMutation } = useGuardedMutation<{
+    formId: string
+    resourceKind: string
+    resourceId?: string
+    retryLastMutation: () => Promise<boolean>
+  }>({
+    contextId: mutationContextId,
+    blockedMessage: t('warranty_claims.troubleshootingGuides.list.error.blocked', 'Save blocked by validation.'),
+  })
+
+  const reload = React.useCallback(() => {
+    setReloadToken((current) => current + 1)
+  }, [])
+
+  const listQueryString = React.useMemo(() => {
+    const params = new URLSearchParams({
+      page: String(page),
+      pageSize: String(PAGE_SIZE),
+      sortField: 'updatedAt',
+      sortDir: 'desc',
+    })
+    if (search.trim()) params.set('search', search.trim())
+    const claimType = toFilterString(filterValues.claimType)
+    const isActive = toFilterString(filterValues.isActive)
+    if (claimType) params.set('claimType', claimType)
+    if (isActive) params.set('isActive', isActive)
+    return params.toString()
+  }, [filterValues.claimType, filterValues.isActive, page, search])
+
+  const currentParams = React.useMemo(
+    () => Object.fromEntries(new URLSearchParams(listQueryString)),
+    [listQueryString],
+  )
+
+  const exportConfig = React.useMemo(() => ({
+    view: {
+      getUrl: (format: DataTableExportFormat) =>
+        buildCrudExportUrl('warranty_claims/troubleshooting-guides', { ...currentParams, exportScope: 'view' }, format),
+    },
+    full: {
+      getUrl: (format: DataTableExportFormat) =>
+        buildCrudExportUrl('warranty_claims/troubleshooting-guides', { ...currentParams, exportScope: 'full', all: 'true' }, format),
+    },
+  }), [currentParams])
+
+  React.useEffect(() => {
+    let cancelled = false
+    async function loadGuides() {
+      setLoading(true)
+      try {
+        const fallback: TroubleshootingGuidesResponse = { items: [], total: 0, totalPages: 1 }
+        const call = await apiCall<TroubleshootingGuidesResponse>(
+          `/api/warranty_claims/troubleshooting-guides?${listQueryString}`,
+          undefined,
+          { fallback },
+        )
+        if (!call.ok) {
+          const message = call.result?.error ?? t('warranty_claims.troubleshootingGuides.list.error.load', 'Failed to load troubleshooting guides.')
+          flash(message, 'error')
+          return
+        }
+        if (cancelled) return
+        const items = Array.isArray(call.result?.items) ? call.result.items : []
+        setRows(items.map(normalizeTroubleshootingGuide).filter((row): row is TroubleshootingGuideRecord => row !== null))
+        setTotal(typeof call.result?.total === 'number' ? call.result.total : items.length)
+        setTotalPages(typeof call.result?.totalPages === 'number' ? call.result.totalPages : 1)
+      } catch (error) {
+        if (!cancelled) {
+          const message = error instanceof Error
+            ? error.message
+            : t('warranty_claims.troubleshootingGuides.list.error.load', 'Failed to load troubleshooting guides.')
+          flash(message, 'error')
+        }
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    }
+    void loadGuides()
+    return () => {
+      cancelled = true
+    }
+  }, [listQueryString, reloadToken, scopeVersion, t])
+
+  React.useEffect(() => {
+    const controller = new AbortController()
+    const segments: Array<readonly [GuideSegment, Record<string, string>]> = [
+      ['all', {}],
+      ['published', { isActive: 'true' }],
+      ['draft', { isActive: 'false' }],
+    ]
+    Promise.all(segments.map(async ([segment, query]) => {
+      const params = new URLSearchParams({ page: '1', pageSize: '1', ...query })
+      const fallback: TroubleshootingGuidesResponse = { items: [], total: 0, totalPages: 1 }
+      const call = await apiCall<TroubleshootingGuidesResponse>(
+        `/api/warranty_claims/troubleshooting-guides?${params.toString()}`,
+        { signal: controller.signal },
+        { fallback },
+      )
+      if (!call.ok) throw new Error('[internal] Failed to load guide counts')
+      return [segment, typeof call.result?.total === 'number' ? call.result.total : 0] as const
+    }))
+      .then((entries) => {
+        if (!controller.signal.aborted) setTabCounts(Object.fromEntries(entries))
+      })
+      .catch(() => {
+        if (!controller.signal.aborted) setTabCounts({})
+      })
+    return () => controller.abort()
+  }, [reloadToken, scopeVersion])
+
+  const executeDelete = React.useCallback(async (guide: TroubleshootingGuideRecord): Promise<unknown> => {
+    try {
+      await runMutation({
+        operation: () => withScopedApiRequestHeaders(
+          buildOptimisticLockHeader(guide.updatedAt),
+          () => deleteCrud('warranty_claims/troubleshooting-guides', guide.id, {
+            errorMessage: t('warranty_claims.troubleshootingGuides.list.error.delete', 'Failed to delete troubleshooting guide.'),
+          }),
+        ),
+        mutationPayload: { id: guide.id },
+        context: {
+          formId: mutationContextId,
+          resourceKind: 'warranty_claims.warranty_troubleshooting_guide',
+          resourceId: guide.id,
+          retryLastMutation,
+        },
+      })
+      return null
+    } catch (error) {
+      return error
+    }
+  }, [mutationContextId, retryLastMutation, runMutation, t])
+
+  const handleDelete = React.useCallback(async (guide: TroubleshootingGuideRecord) => {
+    const confirmed = await confirm({
+      title: t('warranty_claims.troubleshootingGuides.confirm.deleteTitle', 'Delete this troubleshooting guide?'),
+      variant: 'destructive',
+    })
+    if (!confirmed) return
+    const error = await executeDelete(guide)
+    if (error) {
+      if (surfaceRecordConflict(error, t, { onRefresh: reload })) return
+      flash(
+        error instanceof Error
+          ? error.message
+          : t('warranty_claims.troubleshootingGuides.list.error.delete', 'Failed to delete troubleshooting guide.'),
+        'error',
+      )
+      return
+    }
+    flash(t('warranty_claims.troubleshootingGuides.list.success.delete', 'Troubleshooting guide deleted.'), 'success')
+    reload()
+  }, [confirm, executeDelete, reload, t])
+
+  const handleBulkDelete = React.useCallback(async (selectedRows: TroubleshootingGuideRecord[]) => {
+    const { succeeded, failures } = await runBulkDelete(
+      selectedRows,
+      async (guide) => {
+        const error = await executeDelete(guide)
+        if (error) throw error
+      },
+      {
+        fallbackErrorMessage: t('warranty_claims.troubleshootingGuides.list.error.delete', 'Failed to delete troubleshooting guide.'),
+        logTag: 'warranty_claims.troubleshooting_guides.list',
+        progress: {
+          jobType: 'warranty_claims.troubleshooting_guides.bulk_delete',
+          name: t('warranty_claims.troubleshootingGuides.bulk.delete', 'Delete selected'),
+        },
+      },
+    )
+    const summary = t(
+      'warranty_claims.bulk.summary',
+      'Bulk action finished: {succeeded} succeeded, {failed} failed.',
+      { succeeded: succeeded.length, failed: failures.length },
+    )
+    if (failures.length) {
+      flash(`${summary} ${t('warranty_claims.bulk.firstError', 'First error: {message}', { message: failures[0].message })}`, 'warning')
+    } else {
+      flash(summary, 'success')
+    }
+    reload()
+    return { ok: true as const, affectedCount: succeeded.length }
+  }, [executeDelete, reload, t])
+
+  const bulkActions = React.useMemo<BulkAction<TroubleshootingGuideRecord>[]>(() => [
+    {
+      id: 'bulk-delete',
+      label: t('warranty_claims.troubleshootingGuides.bulk.delete', 'Delete selected'),
+      destructive: true,
+      onExecute: async (selectedRows) => {
+        if (!selectedRows.length) return false
+        const confirmed = await confirm({
+          title: t('warranty_claims.troubleshootingGuides.bulk.deleteTitle', 'Delete selected troubleshooting guides?'),
+          variant: 'destructive',
+        })
+        if (!confirmed) return false
+        return handleBulkDelete(selectedRows)
+      },
+    },
+  ], [confirm, handleBulkDelete, t])
+
+  const filters = React.useMemo<FilterDef[]>(() => [
+    {
+      id: 'claimType',
+      label: t('warranty_claims.troubleshootingGuides.list.filter.claimType', 'Claim type'),
+      type: 'select',
+      options: CLAIM_TYPES.map((value) => ({ value, label: claimTypeLabel(value, t) })),
+    },
+    {
+      id: 'isActive',
+      label: t('warranty_claims.troubleshootingGuides.list.filter.status', 'Status'),
+      type: 'select',
+      options: [
+        { value: 'true', label: t('warranty_claims.troubleshootingGuides.status.active', 'Active') },
+        { value: 'false', label: t('warranty_claims.troubleshootingGuides.status.inactive', 'Inactive') },
+      ],
+    },
+  ], [t])
+
+  const columns = React.useMemo<ColumnDef<TroubleshootingGuideRecord>[]>(() => [
+    {
+      accessorKey: 'title',
+      header: t('warranty_claims.troubleshootingGuides.list.column.title', 'Title'),
+      meta: { alwaysVisible: true, truncate: true, maxWidth: '280px' },
+      cell: ({ row }) => (
+        <Link
+          href={`/backend/warranty_claims/troubleshooting-guides/${row.original.id}/edit`}
+          className="font-medium hover:underline"
+        >
+          {row.original.title ?? t('warranty_claims.troubleshootingGuides.list.untitled', 'Untitled guide')}
+        </Link>
+      ),
+    },
+    {
+      accessorKey: 'claimType',
+      header: t('warranty_claims.troubleshootingGuides.list.column.claimType', 'Claim type'),
+      cell: ({ row }) => (
+        <span className="text-sm text-muted-foreground">
+          {claimTypeLabel(row.original.claimType, t)}
+        </span>
+      ),
+    },
+    {
+      accessorKey: 'reasonCode',
+      header: t('warranty_claims.troubleshootingGuides.list.column.reason', 'Reason'),
+      meta: { truncate: true, maxWidth: '220px' },
+      cell: ({ row }) => (
+        <span className="text-sm text-foreground">
+          {reasonLabel(row.original.reasonCode, t, reasonLabels)}
+        </span>
+      ),
+    },
+    {
+      id: 'steps',
+      header: t('warranty_claims.troubleshootingGuides.list.column.steps', 'Steps'),
+      meta: { maxWidth: '100px' },
+      cell: ({ row }) => <span className="text-sm text-muted-foreground">{countGuideSteps(row.original.steps)}</span>,
+    },
+    {
+      accessorKey: 'isActive',
+      header: t('warranty_claims.troubleshootingGuides.list.column.active', 'Status'),
+      cell: ({ row }) => (
+        <StatusBadge variant={row.original.isActive ? 'success' : 'neutral'}>
+          {activeLabel(row.original.isActive, t)}
+        </StatusBadge>
+      ),
+    },
+    {
+      accessorKey: 'updatedAt',
+      header: t('warranty_claims.troubleshootingGuides.list.column.updated', 'Updated'),
+      cell: ({ row }) => (
+        <span className="text-sm text-muted-foreground" title={formatDateTime(row.original.updatedAt) ?? undefined}>
+          {formatRelativeTime(row.original.updatedAt, { locale }) ?? t('warranty_claims.common.noValue', 'Not set')}
+        </span>
+      ),
+    },
+  ], [reasonLabels, locale, t])
+
+  const activeTab = toFilterString(filterValues.isActive) === 'true'
+    ? 'published'
+    : toFilterString(filterValues.isActive) === 'false'
+      ? 'draft'
+      : 'all'
+
+  const handleTabChange = React.useCallback((value: string) => {
+    if (value === 'published') setFilterValues({ isActive: 'true' })
+    else if (value === 'draft') setFilterValues({ isActive: 'false' })
+    else setFilterValues({})
+    setPage(1)
+  }, [])
+
+  return (
+    <Page>
+      <PageBody>
+        <WarrantyWorkspace
+          title={t('warranty_claims.troubleshootingGuides.list.title', 'Troubleshooting guides')}
+          action={(
+            <Button asChild>
+              <Link href="/backend/warranty_claims/troubleshooting-guides/create">
+                <Plus className="size-4" aria-hidden />
+                {t('warranty_claims.troubleshootingGuides.list.actions.new', 'New guide')}
+              </Link>
+            </Button>
+          )}
+          contentClassName="[&>[data-component-handle]>div:first-child]:px-8 [&>[data-component-handle]>div:first-child]:py-4 [&_:has(>[data-slot=search-input-wrapper])]:lg:w-56"
+          activeTab={activeTab}
+          onTabChange={handleTabChange}
+          tabs={[
+            { id: 'all', label: t('warranty_claims.troubleshootingGuides.list.tabs.all', 'All'), count: tabCounts.all },
+            { id: 'published', label: t('warranty_claims.troubleshootingGuides.list.tabs.published', 'Published'), count: tabCounts.published },
+            { id: 'draft', label: t('warranty_claims.troubleshootingGuides.list.tabs.draft', 'Draft'), count: tabCounts.draft },
+          ]}
+        >
+          <DataTable<TroubleshootingGuideRecord>
+          embedded
+          stickyFirstColumn
+          stickyActionsColumn
+          refreshButton={{
+            label: t('warranty_claims.troubleshootingGuides.list.actions.refresh', 'Refresh'),
+            onRefresh: reload,
+            isRefreshing: loading,
+          }}
+          columns={columns}
+          data={rows}
+          exporter={exportConfig}
+          searchValue={search}
+          onSearchChange={(value) => {
+            setSearch(value)
+            setPage(1)
+          }}
+          searchPlaceholder={t('warranty_claims.troubleshootingGuides.list.searchPlaceholder', 'Search guides…')}
+          filters={filters}
+          filterValues={filterValues}
+          onFiltersApply={(values) => {
+            setFilterValues(values)
+            setPage(1)
+          }}
+          onFiltersClear={() => {
+            setFilterValues({})
+            setPage(1)
+          }}
+          perspective={{ tableId: extensionPoints.hosts.troubleshootingGuidesTable.tableId }}
+          onRowClick={(row) => router.push(`/backend/warranty_claims/troubleshooting-guides/${row.id}/edit`)}
+          isLoading={loading}
+          bulkActions={bulkActions}
+          rowActions={(row) => (
+            <RowActions
+              items={[
+                {
+                  id: 'edit',
+                  label: t('warranty_claims.troubleshootingGuides.list.actions.edit', 'Edit'),
+                  onSelect: () => router.push(`/backend/warranty_claims/troubleshooting-guides/${row.id}/edit`),
+                },
+                {
+                  id: 'delete',
+                  label: t('warranty_claims.troubleshootingGuides.list.actions.delete', 'Delete'),
+                  destructive: true,
+                  onSelect: () => {
+                    void handleDelete(row)
+                  },
+                },
+              ]}
+            />
+          )}
+          emptyState={(
+            <ListEmptyState
+              title={t('warranty_claims.troubleshootingGuides.list.empty.title', 'No troubleshooting guides yet')}
+              description={t('warranty_claims.troubleshootingGuides.list.empty.description', 'Create a guide to offer guided decisions during claim intake and triage.')}
+              createHref="/backend/warranty_claims/troubleshooting-guides/create"
+              createLabel={t('warranty_claims.troubleshootingGuides.list.actions.new', 'New guide')}
+            />
+          )}
+          pagination={{
+            page,
+            pageSize: PAGE_SIZE,
+            total,
+            totalPages,
+            onPageChange: setPage,
+          }}
+          />
+        </WarrantyWorkspace>
+        {ConfirmDialogElement}
+      </PageBody>
+    </Page>
+  )
+}

package/src/modules/warranty_claims/backend/warranty_claims/troubleshooting-guides/troubleshootingGuideForm.tsx

@@ -0,0 +1,214 @@
+"use client"
+
+import * as React from 'react'
+import type { CrudField, CrudFieldOption, CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
+import { Switch } from '@open-mercato/ui/primitives/switch'
+import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
+import type { TranslateFn } from '@open-mercato/shared/lib/i18n/context'
+import { CLAIM_TYPES } from '../../../data/validators'
+import { localizeDictionaryLabel } from '../../../lib/dictionaryLabels'
+import { fetchClaimReasonOptions } from '../../components/claimReasonOptions'
+import {
+  parseGuideSteps,
+  type TroubleshootingNode,
+} from '../../../lib/troubleshooting'
+import { TroubleshootingTreeBuilder } from './TroubleshootingTreeBuilder'
+
+export type TroubleshootingGuideRecord = {
+  id: string
+  title: string | null
+  claimType: string | null
+  reasonCode: string | null
+  steps: TroubleshootingNode | null
+  isActive: boolean
+  updatedAt: string | null
+}
+
+export type TroubleshootingGuideFormValues = Partial<Omit<TroubleshootingGuideRecord, 'claimType' | 'steps'>> & {
+  claimType?: string | null
+  stepsJson?: string | null
+} & Record<string, unknown>
+
+const CLAIM_TYPE_ANY = 'any'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return value !== null && typeof value === 'object' && !Array.isArray(value)
+}
+
+function toStringOrNull(value: unknown): string | null {
+  return typeof value === 'string' && value.trim().length ? value.trim() : null
+}
+
+function nullableText(value: unknown): string | null {
+  return toStringOrNull(value)
+}
+
+function parseStepsJson(value: unknown, t: TranslateFn): TroubleshootingNode | null {
+  const text = typeof value === 'string' ? value.trim() : ''
+  if (!text) return null
+
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(text)
+  } catch {
+    const message = t('warranty_claims.troubleshootingGuides.form.stepsJson.invalidJson', 'Enter valid JSON for the troubleshooting steps.')
+    throw createCrudFormError(message, { stepsJson: message })
+  }
+
+  const steps = parseGuideSteps(parsed)
+  if (!steps) {
+    const message = t('warranty_claims.troubleshootingGuides.form.stepsJson.invalidTree', 'The steps JSON must contain a prompt and option branches with labels.')
+    throw createCrudFormError(message, { stepsJson: message })
+  }
+  return steps
+}
+
+function stepsToJson(steps: TroubleshootingNode | null): string {
+  return steps ? JSON.stringify(steps, null, 2) : ''
+}
+
+function createSwitchField(
+  label: string,
+  enabledLabel: string,
+  disabledLabel: string,
+): CrudField {
+  return {
+    id: 'isActive',
+    label,
+    type: 'custom',
+    component: ({ value, setValue, disabled }) => {
+      const checked = value !== false
+      return (
+        <div className="flex items-center gap-3">
+          <Switch
+            aria-label={label}
+            checked={checked}
+            disabled={disabled}
+            onCheckedChange={(next) => setValue(next)}
+          />
+          <span className="text-sm text-muted-foreground">
+            {checked ? enabledLabel : disabledLabel}
+          </span>
+        </div>
+      )
+    },
+  }
+}
+
+export function claimTypeLabel(value: string | null, t: TranslateFn): string {
+  if (!value || value === CLAIM_TYPE_ANY) return t('warranty_claims.troubleshootingGuides.claimType.any', 'Any claim type')
+  if (value === 'warranty') return t('warranty_claims.claimTypes.warranty', 'Warranty')
+  if (value === 'return') return t('warranty_claims.claimTypes.return', 'Return')
+  if (value === 'core_return') return t('warranty_claims.claimTypes.coreReturn', 'Core return')
+  if (value === 'vendor_recovery') return t('warranty_claims.claimTypes.vendorRecovery', 'Vendor recovery')
+  return value
+}
+
+export function activeLabel(value: boolean, t: TranslateFn): string {
+  return value
+    ? t('warranty_claims.troubleshootingGuides.status.active', 'Active')
+    : t('warranty_claims.troubleshootingGuides.status.inactive', 'Inactive')
+}
+
+export function normalizeTroubleshootingGuide(value: unknown): TroubleshootingGuideRecord | null {
+  if (!isRecord(value)) return null
+  const id = toStringOrNull(value.id)
+  if (!id) return null
+  return {
+    id,
+    title: toStringOrNull(value.title),
+    claimType: toStringOrNull(value.claimType),
+    reasonCode: toStringOrNull(value.reasonCode),
+    steps: parseGuideSteps(value.steps),
+    isActive: value.isActive !== false,
+    updatedAt: toStringOrNull(value.updatedAt),
+  }
+}
+
+export function toTroubleshootingGuideInitialValues(
+  guide: TroubleshootingGuideRecord,
+): TroubleshootingGuideFormValues {
+  return {
+    ...guide,
+    claimType: guide.claimType ?? CLAIM_TYPE_ANY,
+    stepsJson: stepsToJson(guide.steps),
+  }
+}
+
+export function buildTroubleshootingGuidePayload(
+  values: TroubleshootingGuideFormValues,
+  t: TranslateFn,
+  id?: string,
+): Record<string, unknown> {
+  const payload: Record<string, unknown> = {}
+  if (id) payload.id = id
+  const claimType = toStringOrNull(values.claimType)
+  payload.title = nullableText(values.title) ?? ''
+  payload.claimType = claimType && claimType !== CLAIM_TYPE_ANY ? claimType : null
+  payload.reasonCode = nullableText(values.reasonCode)
+  payload.steps = parseStepsJson(values.stepsJson, t)
+  payload.isActive = values.isActive !== false
+  return payload
+}
+
+export function useTroubleshootingGuideFormConfig(t: TranslateFn): { fields: CrudField[]; groups: CrudFormGroup[] } {
+  const claimTypeOptions = React.useMemo<CrudFieldOption[]>(() => [
+    { value: CLAIM_TYPE_ANY, label: claimTypeLabel(null, t) },
+    ...CLAIM_TYPES.map((value) => ({ value, label: claimTypeLabel(value, t) })),
+  ], [t])
+
+  const loadReasonCodeOptions = React.useCallback(() => fetchClaimReasonOptions(t), [t])
+
+  const fields = React.useMemo<CrudField[]>(() => [
+    {
+      id: 'title',
+      label: t('warranty_claims.troubleshootingGuides.form.title', 'Title'),
+      type: 'text',
+      required: true,
+    },
+    {
+      id: 'claimType',
+      label: t('warranty_claims.troubleshootingGuides.form.claimType', 'Claim type'),
+      type: 'select',
+      options: claimTypeOptions,
+    },
+    {
+      id: 'reasonCode',
+      label: t('warranty_claims.troubleshootingGuides.form.reasonCode', 'Reason code'),
+      type: 'combobox',
+      loadOptions: loadReasonCodeOptions,
+      allowCustomValues: true,
+      resolveLabel: (value: string) => localizeDictionaryLabel(t, 'reason', value, value),
+      description: t('warranty_claims.troubleshootingGuides.form.reasonCode.help', 'Leave empty to match any reason.'),
+    },
+    createSwitchField(
+      t('warranty_claims.troubleshootingGuides.form.isActive', 'Active'),
+      t('warranty_claims.troubleshootingGuides.form.isActive.enabled', 'Guide active'),
+      t('warranty_claims.troubleshootingGuides.form.isActive.disabled', 'Guide inactive'),
+    ),
+    {
+      id: 'stepsJson',
+      label: t('warranty_claims.troubleshootingGuides.form.decisionTree', 'Decision tree'),
+      type: 'custom',
+      layout: 'full',
+      component: ({ value, setValue, disabled }) => (
+        <TroubleshootingTreeBuilder value={value} setValue={setValue} disabled={disabled} />
+      ),
+    },
+  ], [claimTypeOptions, loadReasonCodeOptions, t])
+
+  const groups = React.useMemo<CrudFormGroup[]>(() => [
+    {
+      id: 'match',
+      title: t('warranty_claims.troubleshootingGuides.form.group.match', 'Guide match'),
+      fields: ['title', 'claimType', 'reasonCode', 'isActive'],
+    },
+    {
+      id: 'steps',
+      title: t('warranty_claims.troubleshootingGuides.form.group.steps', 'Decision tree'),
+      fields: ['stepsJson'],
+    },
+  ], [t])
+
+  return { fields, groups }
+}