@hed-hog/catalog 0.0.293 → 0.0.294

package/src/catalog.service.ts

@@ -1,15 +1,96 @@
-import { getLocaleText } from '@hed-hog/api-locale';
-import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
-import { PrismaService } from '@hed-hog/api-prisma';
-import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
-import { CatalogResourceConfig, catalogResourceMap } from './catalog-resource.config';
-
-@Injectable()
-export class CatalogService {
-  constructor(
-    private readonly prisma: PrismaService,
-    private readonly pagination: PaginationService,
-  ) {}
+import { getLocaleText } from '@hed-hog/api-locale';
+import { PaginationDTO, PaginationService } from '@hed-hog/api-pagination';
+import {
+  Prisma,
+  PrismaService,
+  type catalog_product_attribute_value_source_type_enum,
+} from '@hed-hog/api-prisma';
+import { AiService } from '@hed-hog/core';
+import { BadRequestException, Injectable, NotFoundException } from '@nestjs/common';
+import { CatalogResourceConfig, catalogResourceMap } from './catalog-resource.config';
+
+type CatalogAttributeValueInput = {
+  attribute_id?: number;
+  attribute_option_id?: number | null;
+  value_text?: string | null;
+  value_number?: number | null;
+  value_boolean?: boolean | null;
+  raw_value?: string | null;
+  value_unit?: string | null;
+  normalized_value?: string | null;
+  normalized_text?: string | null;
+  normalized_number?: number | null;
+  source_type?: string | null;
+  confidence_score?: number | null;
+  is_verified?: boolean | null;
+};
+
+type CatalogAttributeGroupPayload = {
+  id: number | null;
+  slug: string;
+  name: string;
+  attributes: Array<Record<string, any>>;
+};
+
+type CatalogAttributeSnapshotPayload = {
+  slug: string;
+  name: string;
+  data_type: string;
+  unit: string | null;
+  group_name: string;
+  is_required: boolean;
+  is_highlight: boolean;
+  is_filter_visible: boolean;
+  is_comparison_visible: boolean;
+  value: string | number | boolean | null;
+  value_text: string | null;
+  value_number: number | null;
+  value_boolean: boolean | null;
+  normalized_value: string | null;
+  raw_value: string | null;
+  option: {
+    id: number;
+    slug: string;
+    label: string;
+    option_value: string;
+  } | null;
+};
+
+type ProductRecordWithRelations = Record<string, any> & {
+  brand_id?: number | null;
+  catalog_category_id?: number | null;
+};
+
+type CatalogAiFieldContext = {
+  key: string;
+  label: string;
+  type: string;
+  required: boolean;
+  options: Array<{
+    value: string;
+    label: string;
+  }>;
+  relation?: {
+    endpoint?: string;
+    resource?: string;
+    labelKeys?: string[];
+  } | null;
+};
+
+type CatalogAiAssistInput = {
+  prompt: string;
+  current_values?: Record<string, unknown>;
+  fields?: Record<string, unknown>[];
+  current_attribute_values?: Record<string, unknown>[];
+};
+
+@Injectable()
+export class CatalogService {
+  constructor(
+    private readonly prisma: PrismaService,
+    private readonly pagination: PaginationService,
+    private readonly aiService: AiService,
+  ) {}
 
   private getConfig(resource: string, locale: string): CatalogResourceConfig {
     const config = catalogResourceMap.get(resource);
@@ -28,7 +109,7 @@ export class CatalogService {
     return this.prisma[config.model];
   }
 
-  private normalizeValue(value: unknown) {
+  private normalizeValue(value: unknown) {
     if (value === 'true') {
       return true;
     }
@@ -41,24 +122,666 @@ export class CatalogService {
       return value.includes('.') ? Number(value) : Number.parseInt(value, 10);
     }
 
-    return value;
-  }
-
-  private sanitizePayload(config: CatalogResourceConfig, body: Record<string, unknown>) {
-    const payload: Record<string, unknown> = {};
-
-    for (const field of config.fields) {
-      if (Object.prototype.hasOwnProperty.call(body, field) && body[field] !== undefined) {
-        payload[field] = body[field];
-      }
-    }
+    return value;
+  }
+
+  private extractJsonObject(content: string) {
+    const trimmed = String(content ?? '').trim();
+
+    if (!trimmed) {
+      throw new BadRequestException('AI returned an empty response');
+    }
+
+    const fencedMatch = trimmed.match(/```(?:json)?\s*([\s\S]*?)\s*```/i);
+    const candidate = fencedMatch?.[1]?.trim() || trimmed;
+
+    try {
+      return JSON.parse(candidate) as Record<string, unknown>;
+    } catch {
+      const firstBraceIndex = candidate.indexOf('{');
+      const lastBraceIndex = candidate.lastIndexOf('}');
+
+      if (firstBraceIndex >= 0 && lastBraceIndex > firstBraceIndex) {
+        try {
+          return JSON.parse(candidate.slice(firstBraceIndex, lastBraceIndex + 1)) as Record<string, unknown>;
+        } catch {
+          throw new BadRequestException('AI returned an invalid JSON payload');
+        }
+      }
+
+      throw new BadRequestException('AI returned an invalid JSON payload');
+    }
+  }
+
+  private normalizeComparableText(value: unknown) {
+    return String(value ?? '')
+      .normalize('NFD')
+      .replace(/[\u0300-\u036f]/g, '')
+      .trim()
+      .toLowerCase();
+  }
+
+  private normalizeAiFieldContext(
+    resource: string,
+    fields: Record<string, unknown>[],
+  ) {
+    const config = catalogResourceMap.get(resource);
+
+    if (!config) {
+      return [];
+    }
+
+    const allowedKeys = new Set(config.fields);
+
+    return fields
+      .map((field) => {
+        const key = String(field.key ?? '').trim();
+
+        if (!key || !allowedKeys.has(key)) {
+          return null;
+        }
+
+        const options = Array.isArray(field.options)
+          ? field.options
+              .map((option) => ({
+                value: String((option as Record<string, unknown>).value ?? '').trim(),
+                label: String((option as Record<string, unknown>).label ?? '').trim(),
+              }))
+              .filter((option) => option.value && option.label)
+          : [];
+        const relationData =
+          field.relation && typeof field.relation === 'object'
+            ? (field.relation as Record<string, unknown>)
+            : null;
+
+        return {
+          key,
+          label: String(field.label ?? key),
+          type: String(field.type ?? 'text'),
+          required: Boolean(field.required ?? false),
+          options,
+          relation: relationData
+            ? {
+                endpoint: relationData.endpoint
+                  ? String(relationData.endpoint)
+                  : undefined,
+                resource: relationData.resource
+                  ? String(relationData.resource)
+                  : undefined,
+                labelKeys: Array.isArray(relationData.labelKeys)
+                  ? relationData.labelKeys.map((item) => String(item))
+                  : [],
+              }
+            : null,
+        } satisfies CatalogAiFieldContext;
+      })
+      .filter(Boolean) as CatalogAiFieldContext[];
+  }
+
+  private normalizeBooleanSuggestion(value: unknown) {
+    if (typeof value === 'boolean') {
+      return value;
+    }
+
+    if (typeof value === 'number') {
+      return value !== 0;
+    }
+
+    const normalized = this.normalizeComparableText(value);
+
+    if (!normalized) {
+      return null;
+    }
+
+    if (['true', '1', 'yes', 'y', 'sim', 'ativo', 'active', 'enabled'].includes(normalized)) {
+      return true;
+    }
+
+    if (['false', '0', 'no', 'n', 'nao', 'não', 'inativo', 'inactive', 'disabled'].includes(normalized)) {
+      return false;
+    }
+
+    return null;
+  }
+
+  private normalizeNumberSuggestion(value: unknown) {
+    if (typeof value === 'number') {
+      return Number.isFinite(value) ? value : null;
+    }
+
+    const raw = String(value ?? '').trim();
+
+    if (!raw) {
+      return null;
+    }
+
+    const normalized = raw.replace(/[^\d,.\-]/g, '').replace(',', '.');
+    const parsed = Number(normalized);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+
+  private normalizeSelectSuggestion(
+    rawValue: unknown,
+    options: Array<{ value: string; label: string }>,
+  ) {
+    const normalized = this.normalizeComparableText(rawValue);
+
+    if (!normalized) {
+      return null;
+    }
+
+    const exact = options.find((option) => {
+      return (
+        this.normalizeComparableText(option.value) === normalized ||
+        this.normalizeComparableText(option.label) === normalized
+      );
+    });
+
+    if (exact) {
+      return exact.value;
+    }
+
+    const partial = options.find((option) => {
+      return (
+        this.normalizeComparableText(option.value).includes(normalized) ||
+        normalized.includes(this.normalizeComparableText(option.value)) ||
+        this.normalizeComparableText(option.label).includes(normalized) ||
+        normalized.includes(this.normalizeComparableText(option.label))
+      );
+    });
+
+    return partial?.value ?? null;
+  }
+
+  private async resolveRelationSuggestion(
+    field: CatalogAiFieldContext,
+    rawValue: unknown,
+  ) {
+    if (rawValue === null || rawValue === undefined || rawValue === '') {
+      return null;
+    }
+
+    const relation = field.relation;
+
+    if (!relation) {
+      return null;
+    }
+
+    const modelInfo = (() => {
+      if (relation.resource) {
+        const config = catalogResourceMap.get(relation.resource);
+
+        if (config) {
+          return {
+            model: config.model,
+            searchFields:
+              relation.labelKeys?.length ? relation.labelKeys : config.searchFields,
+            idField: 'id',
+          };
+        }
+      }
+
+      if (relation.endpoint === '/locale') {
+        return {
+          model: 'locale',
+          searchFields: relation.labelKeys?.length ? relation.labelKeys : ['name', 'code'],
+          idField: 'id',
+        };
+      }
+
+      if (relation.endpoint === '/content') {
+        return {
+          model: 'content',
+          searchFields: relation.labelKeys?.length ? relation.labelKeys : ['title', 'slug'],
+          idField: 'id',
+        };
+      }
+
+      return null;
+    })();
+
+    if (!modelInfo) {
+      return null;
+    }
+
+    const model = (this.prisma as Record<string, any>)[modelInfo.model];
+
+    if (!model?.findMany) {
+      return null;
+    }
+
+    const numericId = this.normalizeNumberSuggestion(rawValue);
+    if (numericId && Number.isInteger(numericId)) {
+      const byId = await model.findUnique({
+        where: { [modelInfo.idField]: numericId },
+      });
+
+      if (byId) {
+        return Number(byId[modelInfo.idField]);
+      }
+    }
+
+    const needle = String(rawValue ?? '').trim();
+
+    if (!needle) {
+      return null;
+    }
+
+    const results = await model.findMany({
+      where: {
+        OR: modelInfo.searchFields.map((fieldKey) => ({
+          [fieldKey]: {
+            contains: needle,
+            mode: 'insensitive',
+          },
+        })),
+      },
+      take: 5,
+    });
+
+    if (!results.length) {
+      return null;
+    }
+
+    const normalizedNeedle = this.normalizeComparableText(needle);
+    const exact = results.find((result: Record<string, unknown>) =>
+      modelInfo.searchFields.some((fieldKey) => {
+        return this.normalizeComparableText(result[fieldKey]) === normalizedNeedle;
+      }),
+    );
+
+    if (exact) {
+      return Number(exact[modelInfo.idField]);
+    }
+
+    return results.length === 1 ? Number(results[0][modelInfo.idField]) : null;
+  }
+
+  private async normalizeAiFieldSuggestion(
+    field: CatalogAiFieldContext,
+    rawValue: unknown,
+    warnings: string[],
+  ) {
+    if (rawValue === undefined) {
+      return undefined;
+    }
+
+    if (rawValue === null) {
+      return null;
+    }
+
+    switch (field.type) {
+      case 'switch': {
+        const value = this.normalizeBooleanSuggestion(rawValue);
+
+        if (value === null) {
+          warnings.push(`Boolean field "${field.label}" could not be resolved safely.`);
+          return undefined;
+        }
+
+        return value;
+      }
+      case 'number':
+      case 'currency': {
+        const value = this.normalizeNumberSuggestion(rawValue);
+
+        if (value === null) {
+          warnings.push(`Numeric field "${field.label}" could not be resolved safely.`);
+          return undefined;
+        }
+
+        return value;
+      }
+      case 'select': {
+        const value = this.normalizeSelectSuggestion(rawValue, field.options);
+
+        if (!value) {
+          warnings.push(`Select field "${field.label}" returned an invalid option.`);
+          return undefined;
+        }
+
+        return value;
+      }
+      case 'relation': {
+        const value = await this.resolveRelationSuggestion(field, rawValue);
+
+        if (!value) {
+          warnings.push(`Relation field "${field.label}" could not be resolved safely.`);
+          return undefined;
+        }
+
+        return value;
+      }
+      case 'upload':
+        warnings.push(`File field "${field.label}" must still be filled manually.`);
+        return undefined;
+      case 'json':
+        if (typeof rawValue === 'object') {
+          return rawValue;
+        }
+
+        try {
+          return JSON.parse(String(rawValue));
+        } catch {
+          warnings.push(`JSON field "${field.label}" returned an invalid value.`);
+          return undefined;
+        }
+      case 'date':
+      case 'datetime':
+      case 'text':
+      case 'url':
+      case 'textarea':
+      case 'richtext':
+      default:
+        return String(rawValue).trim() || null;
+    }
+  }
+
+  private buildCurrentAttributeValueMap(values: Record<string, unknown>[]) {
+    const valueMap = new Map<number, Record<string, unknown>>();
+
+    for (const value of values) {
+      const attributeId = Number(value.attribute_id ?? 0);
+
+      if (!attributeId) {
+        continue;
+      }
+
+      valueMap.set(attributeId, value);
+    }
+
+    return valueMap;
+  }
+
+  private buildAttributeContext(
+    attributesPayload: Awaited<ReturnType<CatalogService['buildCategoryAttributePayload']>>,
+    currentAttributeValues: Record<string, unknown>[],
+  ) {
+    const currentMap = this.buildCurrentAttributeValueMap(currentAttributeValues);
+
+    return (attributesPayload.groups ?? []).flatMap((group) =>
+      group.attributes.map((attribute) => {
+        const current = currentMap.get(Number(attribute.id)) ?? attribute.value ?? null;
+        const relation = (attribute.category_attribute ?? {}) as Record<string, unknown>;
+
+        return {
+          id: Number(attribute.id),
+          slug: String(attribute.slug ?? ''),
+          name: String(attribute.name ?? attribute.slug ?? ''),
+          data_type: String(attribute.data_type ?? 'text'),
+          unit: attribute.unit ? String(attribute.unit) : null,
+          group_name: String(group.name ?? attribute.group_name ?? 'General'),
+          is_required: Boolean(relation.is_required ?? false),
+          is_highlight: Boolean(relation.is_highlight ?? false),
+          is_filter_visible: Boolean(relation.is_filter_visible ?? false),
+          is_comparison_visible: Boolean(relation.is_comparison_visible ?? false),
+          options: Array.isArray(attribute.options)
+            ? attribute.options.map((option) => ({
+                id: Number(option.id),
+                slug: String(option.slug ?? ''),
+                label: String(option.label ?? option.option_value ?? ''),
+                option_value: String(option.option_value ?? ''),
+                normalized_value: option.normalized_value
+                  ? String(option.normalized_value)
+                  : null,
+              }))
+            : [],
+          current_value: current,
+        };
+      }),
+    );
+  }
+
+  private async normalizeAiProductAttributeSuggestions(
+    categoryId: number | null,
+    rawSuggestions: unknown,
+    currentAttributeValues: Record<string, unknown>[],
+    warnings: string[],
+  ) {
+    if (!categoryId || rawSuggestions === undefined || rawSuggestions === null) {
+      return [];
+    }
+
+    const attributesPayload = await this.buildCategoryAttributePayload(categoryId);
+    const attributeContext = this.buildAttributeContext(
+      attributesPayload,
+      currentAttributeValues,
+    );
+
+    const normalizedEntries = Array.isArray(rawSuggestions)
+      ? rawSuggestions
+      : rawSuggestions && typeof rawSuggestions === 'object'
+        ? Object.entries(rawSuggestions as Record<string, unknown>).map(
+            ([slug, value]) => ({
+              slug,
+              ...(value && typeof value === 'object'
+                ? (value as Record<string, unknown>)
+                : { value }),
+            }),
+          )
+        : [];
+
+    const normalizedSuggestions: Record<string, unknown>[] = [];
+
+    for (const entry of normalizedEntries) {
+      const entryRecord = (
+        entry && typeof entry === 'object'
+          ? entry
+          : { value: entry }
+      ) as Record<string, unknown>;
+      const rawIdentifier =
+        entryRecord.slug ??
+        entryRecord.attribute_slug ??
+        entryRecord.code ??
+        entryRecord.name ??
+        entryRecord.attribute ??
+        null;
+      const normalizedIdentifier = this.normalizeComparableText(rawIdentifier);
+
+      const attribute = attributeContext.find((item) => {
+        return (
+          item.id === Number(entryRecord.attribute_id ?? 0) ||
+          this.normalizeComparableText(item.slug) === normalizedIdentifier ||
+          this.normalizeComparableText(item.name) === normalizedIdentifier
+        );
+      });
+
+      if (!attribute) {
+        if (rawIdentifier) {
+          warnings.push(`Structured attribute "${String(rawIdentifier)}" is not available for the selected category.`);
+        }
+        continue;
+      }
+
+      const rawValue =
+        entryRecord.value ??
+        entryRecord.value_text ??
+        entryRecord.value_number ??
+        entryRecord.value_boolean ??
+        entryRecord.option ??
+        entryRecord.option_value ??
+        entryRecord.label;
+      const draft: Record<string, unknown> = {
+        attribute_id: attribute.id,
+        attribute_slug: attribute.slug,
+        attribute_name: attribute.name,
+        data_type: attribute.data_type,
+        group_name: attribute.group_name,
+        value_unit: attribute.unit ?? null,
+      };
+
+      if (attribute.data_type === 'option') {
+        const normalizedOption = this.normalizeComparableText(
+          entryRecord.option ??
+            entryRecord.option_value ??
+            entryRecord.label ??
+            rawValue,
+        );
+        const option = attribute.options.find((item) => {
+          return (
+            this.normalizeComparableText(item.option_value) === normalizedOption ||
+            this.normalizeComparableText(item.label) === normalizedOption ||
+            this.normalizeComparableText(item.slug) === normalizedOption
+          );
+        });
+
+        if (!option) {
+          warnings.push(`Option value for "${attribute.name}" could not be resolved safely.`);
+          continue;
+        }
+
+        draft.attribute_option_id = option.id;
+        draft.value_text = option.option_value;
+      } else if (attribute.data_type === 'number') {
+        const numberValue = this.normalizeNumberSuggestion(rawValue);
+
+        if (numberValue === null) {
+          warnings.push(`Numeric attribute "${attribute.name}" could not be resolved safely.`);
+          continue;
+        }
+
+        draft.value_number = numberValue;
+        draft.raw_value = String(numberValue);
+        draft.normalized_value = String(numberValue);
+        if (entryRecord.unit) {
+          draft.value_unit = String(entryRecord.unit).trim() || attribute.unit || null;
+        }
+      } else if (attribute.data_type === 'boolean') {
+        const booleanValue = this.normalizeBooleanSuggestion(rawValue);
+
+        if (booleanValue === null) {
+          warnings.push(`Boolean attribute "${attribute.name}" could not be resolved safely.`);
+          continue;
+        }
+
+        draft.value_boolean = booleanValue;
+        draft.raw_value = String(booleanValue);
+        draft.normalized_value = String(booleanValue);
+      } else {
+        const textValue = String(rawValue ?? '').trim();
+
+        if (!textValue) {
+          continue;
+        }
+
+        draft.value_text = textValue;
+        draft.raw_value = textValue;
+        draft.normalized_value = textValue;
+      }
+
+      normalizedSuggestions.push(draft);
+    }
+
+    return normalizedSuggestions;
+  }
+
+  private buildAiSystemPrompt(
+    resource: string,
+    locale: string,
+    fieldContext: CatalogAiFieldContext[],
+    currentValues: Record<string, unknown>,
+    productAttributes: Record<string, unknown>[],
+  ) {
+    const isPt = locale?.startsWith('pt');
+    const fieldLines = fieldContext.map((field) => {
+      const optionText = field.options.length
+        ? ` options=${field.options.map((option) => `${option.label} (${option.value})`).join(', ')}`
+        : '';
+      const relationText = field.relation
+        ? ` relation=${field.relation.resource || field.relation.endpoint || 'external'}`
+        : '';
+
+      return `- ${field.key}: type=${field.type}; required=${field.required ? 'yes' : 'no'}; label="${field.label}"${optionText}${relationText}`;
+    });
+    const productAttributeLines = productAttributes.map((attribute) => {
+      const options = Array.isArray(attribute.options) ? attribute.options : [];
+      const optionText = options.length
+        ? ` options=${options
+            .map((option) => `${String((option as Record<string, unknown>).label ?? '')} (${String((option as Record<string, unknown>).option_value ?? '')})`)
+            .join(', ')}`
+        : '';
+
+      return `- ${String(attribute.slug)}: type=${String(attribute.data_type)}; name="${String(attribute.name)}"; required=${Boolean(attribute.is_required) ? 'yes' : 'no'}; group="${String(attribute.group_name)}"${optionText}`;
+    });
+
+    return [
+      isPt
+        ? 'Voce preenche formularios administrativos do catalogo. Responda apenas com JSON valido.'
+        : 'You fill catalog admin forms. Respond with valid JSON only.',
+      isPt
+        ? `Recurso atual: ${resource}.`
+        : `Current resource: ${resource}.`,
+      isPt
+        ? 'Use apenas os campos permitidos listados abaixo. Nao invente ids, arquivos ou campos extras.'
+        : 'Use only the allowed fields listed below. Do not invent ids, files, or extra fields.',
+      isPt
+        ? 'Para campos relacionais, prefira nomes/slug legiveis; o backend tentara resolver com seguranca.'
+        : 'For relation fields, prefer readable names/slugs; the backend will resolve them safely.',
+      isPt
+        ? 'Para selects, prefira os valores validos informados.'
+        : 'For selects, prefer the valid values provided.',
+      isPt
+        ? 'Estrutura da resposta: {"fields": { ... }, "product_attributes": { ... }, "notes": ["..."]}.'
+        : 'Response shape: {"fields": { ... }, "product_attributes": { ... }, "notes": ["..."]}.',
+      isPt
+        ? 'Se nao souber um campo, simplesmente omita.'
+        : 'If you are unsure about a field, omit it.',
+      `Allowed fields:\n${fieldLines.join('\n')}`,
+      productAttributeLines.length
+        ? `Structured product attributes:\n${productAttributeLines.join('\n')}`
+        : '',
+      `Current values: ${JSON.stringify(currentValues)}`,
+    ]
+      .filter(Boolean)
+      .join('\n\n');
+  }
 
-    return payload;
-  }
+  private sanitizePayload(config: CatalogResourceConfig, body: Record<string, unknown>) {
+    const normalizedBody = { ...body };
+
+    if (config.resource === 'attributes') {
+      if (
+        normalizedBody.name === undefined &&
+        normalizedBody.label !== undefined
+      ) {
+        normalizedBody.name = normalizedBody.label;
+      }
+
+      if (normalizedBody.data_type === 'select') {
+        normalizedBody.data_type = 'option';
+      }
+    }
+
+    if (config.resource === 'category-attributes') {
+      if (
+        normalizedBody.is_highlight === undefined &&
+        normalizedBody.is_highlighted !== undefined
+      ) {
+        normalizedBody.is_highlight = normalizedBody.is_highlighted;
+      }
+
+      if (
+        normalizedBody.sort_order === undefined &&
+        normalizedBody.display_order !== undefined
+      ) {
+        normalizedBody.sort_order = normalizedBody.display_order;
+      }
+    }
+
+    const payload: Record<string, unknown> = {};
+
+    for (const field of config.fields) {
+      if (Object.prototype.hasOwnProperty.call(normalizedBody, field) && normalizedBody[field] !== undefined) {
+        payload[field] = normalizedBody[field];
+      }
+    }
+
+    return payload;
+  }
 
-  private buildWhere(config: CatalogResourceConfig, paginationParams: PaginationDTO, query: Record<string, unknown>) {
-    const OR = config.searchFields.length
-      ? this.prisma.createInsensitiveSearch(config.searchFields, paginationParams)
+  private buildWhere(config: CatalogResourceConfig, paginationParams: PaginationDTO, query: Record<string, unknown>) {
+    const OR = config.searchFields.length
+      ? this.prisma.createInsensitiveSearch(config.searchFields, paginationParams)
       : [];
     const AND: Record<string, unknown>[] = [];
 
@@ -72,24 +795,467 @@ export class CatalogService {
       }
     }
 
-    return { OR, AND };
-  }
-
-  async list(resource: string, locale: string, paginationParams: PaginationDTO, query: Record<string, unknown>) {
-    const config = this.getConfig(resource, locale);
-    const model = this.getModel(resource, locale);
-    const where = this.buildWhere(config, paginationParams, query);
-
-    return this.pagination.paginate(
-      model,
-      paginationParams,
-      {
-        where,
-        orderBy: config.defaultOrderBy ?? { id: 'desc' },
-      },
-      locale,
-    );
-  }
+    return { OR, AND };
+  }
+
+  private async ensureCategoryExists(categoryId: number) {
+    const category = await this.prisma.catalog_category.findUnique({
+      where: { id: categoryId },
+    });
+
+    if (!category) {
+      throw new NotFoundException('Catalog category not found');
+    }
+
+    return category;
+  }
+
+  private normalizeCategoryTree(items: Record<string, any>[]) {
+    const byId = new Map<number, Record<string, any>>();
+    const roots: Record<string, any>[] = [];
+
+    for (const item of items) {
+      byId.set(item.id, { ...item, children: [] });
+    }
+
+    for (const item of byId.values()) {
+      if (item.parent_category_id && byId.has(item.parent_category_id)) {
+        byId.get(item.parent_category_id)?.children.push(item);
+      } else {
+        roots.push(item);
+      }
+    }
+
+    return roots;
+  }
+
+  private async buildCategoryAttributePayload(categoryId: number, productId?: number) {
+    const category = await this.ensureCategoryExists(categoryId);
+    const categoryAttributes = await this.prisma.catalog_category_attribute.findMany({
+      where: { catalog_category_id: categoryId },
+      orderBy: [{ sort_order: 'asc' }, { id: 'asc' }],
+    });
+
+    const attributeIds = [...new Set(categoryAttributes.map((item) => item.attribute_id))];
+    const attributes = attributeIds.length
+      ? await this.prisma.catalog_attribute.findMany({
+          where: { id: { in: attributeIds } },
+          orderBy: [{ display_order: 'asc' }, { id: 'asc' }],
+        })
+      : [];
+    const groupIds = [...new Set(attributes.map((item) => item.group_id).filter((value): value is number => typeof value === 'number'))];
+    const groups = groupIds.length
+      ? await this.prisma.catalog_attribute_group.findMany({
+          where: { id: { in: groupIds } },
+        })
+      : [];
+    const options = attributeIds.length
+      ? await this.prisma.catalog_attribute_option.findMany({
+          where: { attribute_id: { in: attributeIds } },
+          orderBy: [{ sort_order: 'asc' }, { id: 'asc' }],
+        })
+      : [];
+    const values = productId && attributeIds.length
+      ? await this.prisma.catalog_product_attribute_value.findMany({
+          where: { product_id: productId, attribute_id: { in: attributeIds } },
+          include: {
+            catalog_attribute_option: true,
+          },
+        })
+      : [];
+
+    const categoryAttributeMap = new Map(
+      categoryAttributes.map((item) => [item.attribute_id, item]),
+    );
+    const optionMap = new Map<number, Record<string, any>[]>();
+    const valueMap = new Map(
+      values.map((item) => [item.attribute_id, item]),
+    );
+    const groupMap = new Map(
+      groups.map((item) => [item.id, item]),
+    );
+
+    for (const option of options) {
+      const bucket = optionMap.get(option.attribute_id) ?? [];
+      bucket.push(option);
+      optionMap.set(option.attribute_id, bucket);
+    }
+
+    const grouped = new Map<string, CatalogAttributeGroupPayload>();
+    for (const attribute of attributes) {
+      const relation = categoryAttributeMap.get(attribute.id);
+      if (!relation) {
+        continue;
+      }
+
+      const groupId = attribute.group_id ?? 0;
+      const group = attribute.group_id ? groupMap.get(attribute.group_id) : null;
+      const fallbackGroupName = String(attribute.group_name ?? '').trim() || 'General';
+      const groupKey = attribute.group_id ? String(groupId) : `name:${fallbackGroupName}`;
+      const existingGroup: CatalogAttributeGroupPayload = grouped.get(groupKey) ?? {
+        id: group?.id ?? null,
+        slug: group?.slug ?? fallbackGroupName.toLowerCase().replace(/\s+/g, '-'),
+        name: group?.name ?? fallbackGroupName,
+        attributes: [],
+      };
+
+      existingGroup.attributes.push({
+        ...attribute,
+        category_attribute: relation,
+        options: optionMap.get(attribute.id) ?? [],
+        value: valueMap.get(attribute.id) ?? null,
+      });
+
+      grouped.set(groupKey, existingGroup);
+    }
+
+    const resultGroups: CatalogAttributeGroupPayload[] = [...grouped.values()].map((group) => ({
+      ...group,
+      attributes: group.attributes.sort((left, right) => {
+        const leftRelation = left.category_attribute as Record<string, number>;
+        const rightRelation = right.category_attribute as Record<string, number>;
+        return (
+          Number(leftRelation.sort_order ?? 0) - Number(rightRelation.sort_order ?? 0) ||
+          Number(leftRelation.display_order ?? 0) - Number(rightRelation.display_order ?? 0) ||
+          Number(left.display_order ?? 0) - Number(right.display_order ?? 0) ||
+          Number(left.id ?? 0) - Number(right.id ?? 0)
+        );
+      }),
+    }));
+
+    resultGroups.sort((left, right) => String(left.name).localeCompare(String(right.name)));
+
+    return {
+      category,
+      product_id: productId ?? null,
+      groups: resultGroups,
+      attributes: resultGroups.flatMap((group) => group.attributes),
+    };
+  }
+
+  private isMeaningfulAttributeValue(value: CatalogAttributeValueInput) {
+    if (value.attribute_option_id !== undefined && value.attribute_option_id !== null) {
+      return true;
+    }
+
+    if (value.value_number !== undefined && value.value_number !== null) {
+      return true;
+    }
+
+    if (value.value_boolean !== undefined && value.value_boolean !== null) {
+      return true;
+    }
+
+    return String(value.value_text ?? '').trim().length > 0;
+  }
+
+  private buildAttributeSnapshotValue(attribute: Record<string, any>) {
+    const value = (attribute.value ?? null) as Record<string, any> | null;
+    const dataType = String(attribute.data_type ?? 'text');
+    const option = value?.catalog_attribute_option ?? null;
+
+    if (!value) {
+      return {
+        value: null,
+        value_text: null,
+        value_number: null,
+        value_boolean: null,
+        normalized_value: null,
+        raw_value: null,
+        option: null,
+      };
+    }
+
+    if (dataType === 'option') {
+      const optionPayload = option
+        ? {
+            id: Number(option.id),
+            slug: String(option.slug ?? ''),
+            label: String(option.label ?? option.option_value ?? ''),
+            option_value: String(option.option_value ?? ''),
+          }
+        : null;
+
+      return {
+        value: optionPayload?.option_value ?? value.value_text ?? null,
+        value_text: value.value_text ? String(value.value_text) : null,
+        value_number: null,
+        value_boolean: null,
+        normalized_value: value.normalized_value ? String(value.normalized_value) : null,
+        raw_value: value.raw_value ? String(value.raw_value) : null,
+        option: optionPayload,
+      };
+    }
+
+    if (dataType === 'number') {
+      return {
+        value: value.value_number === null || value.value_number === undefined
+          ? null
+          : Number(value.value_number),
+        value_text: value.value_text ? String(value.value_text) : null,
+        value_number:
+          value.value_number === null || value.value_number === undefined
+            ? null
+            : Number(value.value_number),
+        value_boolean: null,
+        normalized_value: value.normalized_value ? String(value.normalized_value) : null,
+        raw_value: value.raw_value ? String(value.raw_value) : null,
+        option: null,
+      };
+    }
+
+    if (dataType === 'boolean') {
+      return {
+        value:
+          value.value_boolean === null || value.value_boolean === undefined
+            ? null
+            : Boolean(value.value_boolean),
+        value_text: value.value_text ? String(value.value_text) : null,
+        value_number: null,
+        value_boolean:
+          value.value_boolean === null || value.value_boolean === undefined
+            ? null
+            : Boolean(value.value_boolean),
+        normalized_value: value.normalized_value ? String(value.normalized_value) : null,
+        raw_value: value.raw_value ? String(value.raw_value) : null,
+        option: null,
+      };
+    }
+
+    return {
+      value: value.value_text ? String(value.value_text) : null,
+      value_text: value.value_text ? String(value.value_text) : null,
+      value_number: null,
+      value_boolean: null,
+      normalized_value: value.normalized_value ? String(value.normalized_value) : null,
+      raw_value: value.raw_value ? String(value.raw_value) : null,
+      option: null,
+    };
+  }
+
+  private toAttributeSnapshot(attribute: Record<string, any>): CatalogAttributeSnapshotPayload {
+    const relation = (attribute.category_attribute ?? {}) as Record<string, any>;
+    const snapshotValue = this.buildAttributeSnapshotValue(attribute);
+
+    return {
+      slug: String(attribute.slug ?? ''),
+      name: String(attribute.name ?? attribute.slug ?? ''),
+      data_type: String(attribute.data_type ?? 'text'),
+      unit: attribute.unit ? String(attribute.unit) : null,
+      group_name: String(attribute.group_name ?? 'General'),
+      is_required: Boolean(relation.is_required ?? false),
+      is_highlight: Boolean(relation.is_highlight ?? false),
+      is_filter_visible: Boolean(relation.is_filter_visible ?? false),
+      is_comparison_visible: Boolean(relation.is_comparison_visible ?? false),
+      ...snapshotValue,
+    };
+  }
+
+  private async decorateProductRecords<T extends ProductRecordWithRelations>(records: T[]) {
+    if (!records.length) {
+      return records;
+    }
+
+    const brandIds = [...new Set(
+      records
+        .map((record) => record.brand_id)
+        .filter((value): value is number => typeof value === 'number'),
+    )];
+    const categoryIds = [...new Set(
+      records
+        .map((record) => record.catalog_category_id)
+        .filter((value): value is number => typeof value === 'number'),
+    )];
+
+    const [brands, categories] = await Promise.all([
+      brandIds.length
+        ? this.prisma.catalog_brand.findMany({
+            where: { id: { in: brandIds } },
+            select: { id: true, name: true, slug: true, logo_file_id: true },
+          })
+        : Promise.resolve([]),
+      categoryIds.length
+        ? this.prisma.catalog_category.findMany({
+            where: { id: { in: categoryIds } },
+            select: { id: true, name: true, slug: true },
+          })
+        : Promise.resolve([]),
+    ]);
+
+    const brandMap = new Map(brands.map((item) => [item.id, item]));
+    const categoryMap = new Map(categories.map((item) => [item.id, item]));
+
+    return records.map((record) => {
+      const brand = record.brand_id ? brandMap.get(record.brand_id) : null;
+      const category = record.catalog_category_id
+        ? categoryMap.get(record.catalog_category_id)
+        : null;
+
+      return {
+        ...record,
+        brand_name: brand?.name ?? null,
+        brand_slug: brand?.slug ?? null,
+        brand_logo_file_id: brand?.logo_file_id ?? null,
+        category_name: category?.name ?? null,
+        category_slug: category?.slug ?? null,
+      };
+    });
+  }
+
+  private validateAttributeValueByType(
+    attribute: {
+      id: number;
+      slug: string;
+      name: string;
+      data_type: string;
+    },
+    value: CatalogAttributeValueInput,
+  ) {
+    const hasText = String(value.value_text ?? '').trim().length > 0;
+    const hasNumber = value.value_number !== undefined && value.value_number !== null;
+    const hasBoolean = value.value_boolean !== undefined && value.value_boolean !== null;
+    const hasOption = value.attribute_option_id !== undefined && value.attribute_option_id !== null;
+    const filledKinds = [hasText, hasNumber, hasBoolean, hasOption].filter(Boolean).length;
+    const attributeLabel = attribute.name || attribute.slug || `#${attribute.id}`;
+
+    if (filledKinds > 1) {
+      throw new BadRequestException(
+        `Attribute "${attributeLabel}" must use a single value field compatible with its type`,
+      );
+    }
+
+    switch (attribute.data_type) {
+      case 'text':
+      case 'long_text':
+        if (hasNumber || hasBoolean || hasOption) {
+          throw new BadRequestException(`Attribute "${attributeLabel}" only accepts text values`);
+        }
+        break;
+      case 'number':
+        if (hasText || hasBoolean || hasOption) {
+          throw new BadRequestException(`Attribute "${attributeLabel}" only accepts number values`);
+        }
+        break;
+      case 'boolean':
+        if (hasText || hasNumber || hasOption) {
+          throw new BadRequestException(`Attribute "${attributeLabel}" only accepts boolean values`);
+        }
+        break;
+      case 'option':
+        if (hasText || hasNumber || hasBoolean) {
+          throw new BadRequestException(`Attribute "${attributeLabel}" only accepts option values`);
+        }
+        break;
+      default:
+        break;
+    }
+  }
+
+  private async buildProductStructuredPayload(productId: number) {
+    const product = await this.getById('products', productId, 'en');
+    const attributes = await this.listProductAttributes(productId);
+    const groups = (attributes.groups ?? []).map((group) => ({
+      id: group.id,
+      slug: group.slug,
+      name: group.name,
+      attributes: group.attributes.map((attribute) =>
+        this.toAttributeSnapshot(attribute as Record<string, any>),
+      ),
+    }));
+    const flatAttributes = groups.flatMap((group) => group.attributes);
+
+    return {
+      product,
+      category: attributes.category,
+      groups,
+      attributes: flatAttributes,
+      comparison: {
+        category: {
+          id: attributes.category?.id ?? null,
+          slug: attributes.category?.slug ?? null,
+          name: attributes.category?.name ?? null,
+        },
+        highlights: flatAttributes.filter((attribute) => attribute.is_highlight),
+        comparable_attributes: flatAttributes.filter(
+          (attribute) => attribute.is_comparison_visible,
+        ),
+        filter_attributes: flatAttributes.filter(
+          (attribute) => attribute.is_filter_visible,
+        ),
+      },
+    };
+  }
+
+  async materializeProductSnapshots(productId: number) {
+    const structured = await this.buildProductStructuredPayload(productId);
+    const specSnapshot = {
+      version: 1,
+      source: 'catalog_product_attribute_value',
+      category: structured.category
+        ? {
+            id: structured.category.id,
+            slug: structured.category.slug,
+            name: structured.category.name,
+          }
+        : null,
+      groups: structured.groups,
+      attributes: structured.attributes.reduce<Record<string, CatalogAttributeSnapshotPayload>>(
+        (acc, attribute) => {
+          acc[attribute.slug] = attribute;
+          return acc;
+        },
+        {},
+      ),
+      generated_at: new Date().toISOString(),
+    };
+    const comparisonSnapshot = {
+      version: 1,
+      source: 'catalog_product_attribute_value',
+      category: structured.comparison.category,
+      highlights: structured.comparison.highlights,
+      comparable_attributes: structured.comparison.comparable_attributes,
+      generated_at: new Date().toISOString(),
+    };
+
+    await this.prisma.catalog_product.update({
+      where: { id: productId },
+      data: {
+        // Snapshots remain secondary/derived fields for legacy reads and fast payloads.
+        spec_snapshot_json: specSnapshot,
+        comparison_snapshot_json: comparisonSnapshot,
+      },
+    });
+
+    return {
+      spec_snapshot_json: specSnapshot,
+      comparison_snapshot_json: comparisonSnapshot,
+    };
+  }
+
+  async list(resource: string, locale: string, paginationParams: PaginationDTO, query: Record<string, unknown>) {
+    const config = this.getConfig(resource, locale);
+    const model = this.getModel(resource, locale);
+    const where = this.buildWhere(config, paginationParams, query);
+
+    const result = await this.pagination.paginate(
+      model,
+      paginationParams,
+      {
+        where,
+        orderBy: config.defaultOrderBy ?? { id: 'desc' },
+      },
+      locale,
+    );
+
+    if (resource === 'products' && Array.isArray(result.data)) {
+      return {
+        ...result,
+        data: await this.decorateProductRecords(result.data as ProductRecordWithRelations[]),
+      };
+    }
+
+    return result;
+  }
 
   async stats(resource: string, locale: string) {
     const config = this.getConfig(resource, locale);
@@ -108,9 +1274,52 @@ export class CatalogService {
     return result;
   }
 
-  async getById(resource: string, id: number, locale: string) {
-    const model = this.getModel(resource, locale);
-    const item = await model.findUnique({ where: { id } });
+  async getById(resource: string, id: number, locale: string) {
+    if (resource === 'products') {
+      const item = await this.prisma.catalog_product.findUnique({
+        where: { id },
+        include: {
+          catalog_brand: {
+            select: {
+              id: true,
+              name: true,
+              slug: true,
+              logo_file_id: true,
+            },
+          },
+          catalog_category: {
+            select: {
+              id: true,
+              name: true,
+              slug: true,
+            },
+          },
+          catalog_product_image: {
+            orderBy: [{ sort_order: 'asc' }, { id: 'asc' }],
+            select: {
+              id: true,
+              file_id: true,
+              role: true,
+              sort_order: true,
+              is_primary: true,
+              alt_text: true,
+            },
+          },
+        },
+      });
+
+      if (!item) {
+        throw new NotFoundException(
+          getLocaleText('resourceNotFound', locale, 'Catalog resource not found'),
+        );
+      }
+
+      const [decorated] = await this.decorateProductRecords([item]);
+      return decorated;
+    }
+
+    const model = this.getModel(resource, locale);
+    const item = await model.findUnique({ where: { id } });
 
     if (!item) {
       throw new NotFoundException(
@@ -147,8 +1356,8 @@ export class CatalogService {
     return model.delete({ where: { id } });
   }
 
-  async listProductImages(productId: number, locale: string, paginationParams: PaginationDTO) {
-    const model = this.getModel('product-images', locale);
+  async listProductImages(productId: number, locale: string, paginationParams: PaginationDTO) {
+    const model = this.getModel('product-images', locale);
 
     return this.pagination.paginate(
       model,
@@ -161,7 +1370,311 @@ export class CatalogService {
           sort_order: 'asc',
         },
       },
-      locale,
-    );
-  }
-}
+      locale,
+    );
+  }
+
+  async getCategoriesTree() {
+    const categories = await this.prisma.catalog_category.findMany({
+      orderBy: [{ sort_order: 'asc' }, { name: 'asc' }],
+    });
+
+    return this.normalizeCategoryTree(categories);
+  }
+
+  async listCategoryAttributes(categoryId: number) {
+    return this.buildCategoryAttributePayload(categoryId);
+  }
+
+  async listProductAttributes(productId: number) {
+    const product = await this.prisma.catalog_product.findUnique({
+      where: { id: productId },
+    });
+
+    if (!product) {
+      throw new NotFoundException('Catalog product not found');
+    }
+
+    return this.buildCategoryAttributePayload(product.catalog_category_id, productId);
+  }
+
+  async getProductStructuredPayload(productId: number) {
+    return this.buildProductStructuredPayload(productId);
+  }
+
+  async getProductComparisonPayload(productId: number) {
+    const structured = await this.buildProductStructuredPayload(productId);
+    return structured.comparison;
+  }
+
+  async updateProductAttributes(productId: number, values: CatalogAttributeValueInput[]) {
+    const product = await this.prisma.catalog_product.findUnique({
+      where: { id: productId },
+    });
+
+    if (!product) {
+      throw new NotFoundException('Catalog product not found');
+    }
+
+    const categoryAttributes = await this.prisma.catalog_category_attribute.findMany({
+      where: { catalog_category_id: product.catalog_category_id },
+    });
+    const allowedAttributeIds = new Set(categoryAttributes.map((item) => item.attribute_id));
+    const requiredAttributeIds = new Set(
+      categoryAttributes
+        .filter((item) => item.is_required)
+        .map((item) => item.attribute_id),
+    );
+    const attributes = allowedAttributeIds.size
+      ? await this.prisma.catalog_attribute.findMany({
+          where: { id: { in: [...allowedAttributeIds] } },
+          select: {
+            id: true,
+            slug: true,
+            name: true,
+            data_type: true,
+          },
+        })
+      : [];
+    const attributeMap = new Map(attributes.map((item) => [item.id, item]));
+    const existingValues = await this.prisma.catalog_product_attribute_value.findMany({
+      where: { product_id: productId },
+    });
+    const optionIds = values
+      .map((value) => value.attribute_option_id)
+      .filter((value): value is number => typeof value === 'number');
+    const options = optionIds.length
+      ? await this.prisma.catalog_attribute_option.findMany({
+          where: { id: { in: optionIds } },
+        })
+      : [];
+    const optionMap = new Map(options.map((item) => [item.id, item]));
+
+    const incomingByAttribute = new Map<number, CatalogAttributeValueInput>();
+    for (const value of values) {
+      const attributeId = Number(value.attribute_id ?? 0);
+
+      if (!attributeId || !allowedAttributeIds.has(attributeId)) {
+        throw new BadRequestException(`Attribute ${attributeId} is not allowed for this category`);
+      }
+
+      const attribute = attributeMap.get(attributeId);
+
+      if (!attribute) {
+        throw new BadRequestException(`Attribute ${attributeId} was not found`);
+      }
+
+      this.validateAttributeValueByType(attribute, value);
+
+      incomingByAttribute.set(attributeId, value);
+    }
+
+    const incomingAttributeIds = new Set(incomingByAttribute.keys());
+
+    for (const attributeId of requiredAttributeIds) {
+      const requiredValue = incomingByAttribute.get(attributeId);
+
+      if (!requiredValue || !this.isMeaningfulAttributeValue(requiredValue)) {
+        const attribute = attributeMap.get(attributeId);
+        throw new BadRequestException(
+          `Attribute "${attribute?.name ?? attribute?.slug ?? attributeId}" is required for this category`,
+        );
+      }
+    }
+
+    for (const existingValue of existingValues) {
+      if (!incomingAttributeIds.has(existingValue.attribute_id)) {
+        await this.prisma.catalog_product_attribute_value.delete({
+          where: { id: existingValue.id },
+        });
+      }
+    }
+
+    for (const [attributeId, value] of incomingByAttribute.entries()) {
+      const option = value.attribute_option_id ? optionMap.get(value.attribute_option_id) : null;
+      const attribute = attributeMap.get(attributeId);
+
+      if (value.attribute_option_id && (!option || option.attribute_id !== attributeId)) {
+        throw new BadRequestException(
+          `Option ${value.attribute_option_id} does not belong to attribute ${attribute?.name ?? attributeId}`,
+        );
+      }
+
+      const normalizedText = value.normalized_text ?? option?.normalized_value ?? option?.option_value ?? value.value_text ?? null;
+      const sourceType: catalog_product_attribute_value_source_type_enum =
+        value.source_type === 'import' || value.source_type === 'computed'
+          ? value.source_type
+          : 'manual';
+      const payload = {
+        attribute_option_id: value.attribute_option_id ?? null,
+        value_text: option?.option_value ?? (String(value.value_text ?? '').trim() || null),
+        value_number: value.value_number ?? null,
+        value_boolean: value.value_boolean ?? null,
+        raw_value:
+          option?.option_value ??
+          (value.value_number !== undefined && value.value_number !== null
+            ? String(value.value_number)
+            : value.value_boolean !== undefined && value.value_boolean !== null
+              ? String(value.value_boolean)
+              : String(value.value_text ?? '').trim() || null),
+        value_unit: String(value.value_unit ?? '').trim() || null,
+        normalized_value:
+          normalizedText
+            ? String(normalizedText).trim()
+            : value.value_number !== undefined && value.value_number !== null
+              ? String(value.value_number)
+              : value.value_boolean !== undefined && value.value_boolean !== null
+                ? String(value.value_boolean)
+                : null,
+        normalized_text: normalizedText ? String(normalizedText).trim() : null,
+        normalized_number: value.normalized_number ?? value.value_number ?? null,
+        source_type: sourceType,
+        confidence_score: value.confidence_score ?? null,
+        is_verified: Boolean(value.is_verified ?? false),
+      } satisfies CatalogAttributeValueInput & {
+        source_type: catalog_product_attribute_value_source_type_enum;
+      };
+
+      const existingValue = existingValues.find((item) => item.attribute_id === attributeId);
+
+      if (!this.isMeaningfulAttributeValue(payload)) {
+        if (existingValue) {
+          await this.prisma.catalog_product_attribute_value.delete({
+            where: { id: existingValue.id },
+          });
+        }
+        continue;
+      }
+
+      if (existingValue) {
+        const updatePayload: Prisma.catalog_product_attribute_valueUncheckedUpdateInput = {
+          attribute_option_id: payload.attribute_option_id,
+          value_text: payload.value_text,
+          value_number: payload.value_number,
+          value_boolean: payload.value_boolean,
+          raw_value: payload.raw_value,
+          value_unit: payload.value_unit,
+          normalized_value: payload.normalized_value,
+          normalized_text: payload.normalized_text,
+          normalized_number: payload.normalized_number,
+          source_type: payload.source_type,
+          confidence_score: payload.confidence_score,
+          is_verified: payload.is_verified,
+        };
+
+        await this.prisma.catalog_product_attribute_value.update({
+          where: { id: existingValue.id },
+          data: updatePayload,
+        });
+      } else {
+        const createPayload: Prisma.catalog_product_attribute_valueUncheckedCreateInput = {
+          product_id: productId,
+          attribute_id: attributeId,
+          attribute_option_id: payload.attribute_option_id,
+          value_text: payload.value_text,
+          value_number: payload.value_number,
+          value_boolean: payload.value_boolean,
+          raw_value: payload.raw_value,
+          value_unit: payload.value_unit,
+          normalized_value: payload.normalized_value,
+          normalized_text: payload.normalized_text,
+          normalized_number: payload.normalized_number,
+          source_type: payload.source_type,
+          confidence_score: payload.confidence_score,
+          is_verified: payload.is_verified,
+        };
+
+        await this.prisma.catalog_product_attribute_value.create({
+          data: createPayload,
+        });
+      }
+    }
+
+    await this.materializeProductSnapshots(productId);
+
+    return this.listProductAttributes(productId);
+  }
+
+  async generateFormAssistSuggestion(
+    resource: string,
+    input: CatalogAiAssistInput,
+    locale: string,
+  ) {
+    const config = this.getConfig(resource, locale);
+    const fieldContext = this.normalizeAiFieldContext(resource, input.fields ?? []);
+    const currentValues = input.current_values ?? {};
+    const warnings: string[] = [];
+    const categoryId =
+      resource === 'products'
+        ? Number(currentValues.catalog_category_id ?? 0) || null
+        : null;
+    const productAttributeContext = categoryId
+      ? this.buildAttributeContext(
+          await this.buildCategoryAttributePayload(categoryId),
+          input.current_attribute_values ?? [],
+        )
+      : [];
+    const systemPrompt = this.buildAiSystemPrompt(
+      resource,
+      locale,
+      fieldContext,
+      currentValues,
+      productAttributeContext,
+    );
+    const aiResponse = await this.aiService.chat({
+      provider: 'openai',
+      model: 'gpt-4o-mini',
+      message: input.prompt,
+      systemPrompt,
+    });
+    const parsed = this.extractJsonObject(String(aiResponse.content ?? ''));
+    const rawFields =
+      parsed.fields && typeof parsed.fields === 'object'
+        ? (parsed.fields as Record<string, unknown>)
+        : {};
+    const normalizedFields: Record<string, unknown> = {};
+
+    for (const field of fieldContext) {
+      if (!Object.prototype.hasOwnProperty.call(rawFields, field.key)) {
+        continue;
+      }
+
+      const normalizedValue = await this.normalizeAiFieldSuggestion(
+        field,
+        rawFields[field.key],
+        warnings,
+      );
+
+      if (normalizedValue !== undefined) {
+        normalizedFields[field.key] = normalizedValue;
+      }
+    }
+
+    const productAttributes = await this.normalizeAiProductAttributeSuggestions(
+      categoryId,
+      parsed.product_attributes,
+      input.current_attribute_values ?? [],
+      warnings,
+    );
+
+    const appliedFields = fieldContext
+      .filter((field) => Object.prototype.hasOwnProperty.call(normalizedFields, field.key))
+      .map((field) => ({
+        key: field.key,
+        label: field.label,
+        type: field.type,
+        value: normalizedFields[field.key],
+      }));
+
+    return {
+      resource: config.resource,
+      fields: normalizedFields,
+      applied_fields: appliedFields,
+      product_attributes: productAttributes,
+      warnings: [
+        ...warnings,
+        ...(Array.isArray(parsed.notes) ? parsed.notes.map((note) => String(note)) : []),
+      ],
+    };
+  }
+}