@hed-hog/catalog 0.0.293 → 0.0.295

package/README.md

@@ -1,379 +1,409 @@
-```markdown
 # @hed-hog/catalog
 
-## 1. Visão geral do módulo
-
-O módulo `@hed-hog/catalog` é responsável pela gestão centralizada dos recursos do catálogo, incluindo produtos, ofertas, marcas, atributos, comparações, imagens e regras relacionadas. Ele oferece uma API REST para operações CRUD, listagem paginada, estatísticas e manipulação de imagens de produtos, integrando-se com outros módulos do monorepo HedHog.
-
-## 2. Escopo e responsabilidades
-
-- Gerenciar recursos do catálogo como produtos, ofertas, marcas, atributos, comparações, imagens, entre outros.
-- Fornecer endpoints para criação, leitura, atualização, exclusão e listagem paginada de recursos.
-- Aplicar filtros e buscas sensíveis a campos configurados para cada recurso.
-- Gerar estatísticas básicas dos recursos.
-- Controlar imagens associadas a produtos.
-- Garantir autenticação e autorização baseadas em papéis específicos.
-- Integrar com serviços de paginação, localização e banco de dados Prisma.
-
-## 3. Endpoints
-
-### Listar imagens de um produto
-
-- **Método:** GET  
-- **Path:** `/catalog/products/:id/images`  
-- **Autenticação:** Sim (roles: `admin`, `admin-catalog`)  
-- **Descrição:** Lista imagens associadas a um produto, com paginação e ordenação por `sort_order`.  
-- **Parâmetros:**  
-  - `id` (path): ID numérico do produto  
-  - Query params de paginação (ex: `page`, `limit`)  
-  - Header `Accept-Language` para locale (ex: `pt-BR`)  
-- **Resposta:** Lista paginada de imagens do produto com campos conforme tabela `catalog_product_image`.  
-- **Erros:**  
-  - 400 Bad Request: recurso não suportado  
-  - 401 Unauthorized: acesso não autorizado  
-
----
-
-### Obter estatísticas de um recurso
-
-- **Método:** GET  
-- **Path:** `/catalog/:resource/stats`  
-- **Autenticação:** Sim (roles: `admin`, `admin-catalog`)  
-- **Descrição:** Retorna estatísticas básicas do recurso, como total de registros e quantidade ativa (se aplicável).  
-- **Parâmetros:**  
-  - `resource` (path): nome do recurso (ex: `product`, `brand`)  
-  - Header `Accept-Language` para locale  
-- **Resposta:**  
-  ```json
-  {
-    "total": number,
-    "active": number (opcional)
-  }
-  ```  
-- **Erros:**  
-  - 400 Bad Request: recurso não suportado  
-  - 401 Unauthorized  
-
----
-
-### Obter recurso por ID
-
-- **Método:** GET  
-- **Path:** `/catalog/:resource/:id`  
-- **Autenticação:** Sim (roles: `admin`, `admin-catalog`)  
-- **Descrição:** Retorna um registro específico do recurso pelo ID.  
-- **Parâmetros:**  
-  - `resource` (path): nome do recurso  
-  - `id` (path): ID numérico do registro  
-  - Header `Accept-Language` para locale  
-- **Resposta:** Objeto do recurso com campos conforme configuração.  
-- **Erros:**  
-  - 400 Bad Request: recurso não suportado  
-  - 404 Not Found: recurso não encontrado  
-  - 401 Unauthorized  
-
----
-
-### Atualizar recurso por ID
-
-- **Método:** PATCH  
-- **Path:** `/catalog/:resource/:id`  
-- **Autenticação:** Sim (roles: `admin`, `admin-catalog`)  
-- **Descrição:** Atualiza campos permitidos de um registro do recurso.  
-- **Parâmetros:**  
-  - `resource` (path): nome do recurso  
-  - `id` (path): ID do registro  
-  - Body JSON: campos a atualizar (somente campos configurados para o recurso)  
-  - Header `Accept-Language` para locale  
-- **Resposta:** Objeto atualizado do recurso.  
-- **Erros:**  
-  - 400 Bad Request: recurso não suportado ou payload inválido  
-  - 404 Not Found: recurso não encontrado  
-  - 401 Unauthorized  
-
----
-
-### Deletar recurso por ID
-
-- **Método:** DELETE  
-- **Path:** `/catalog/:resource/:id`  
-- **Autenticação:** Sim (roles: `admin`, `admin-catalog`)  
-- **Descrição:** Remove um registro do recurso pelo ID.  
-- **Parâmetros:**  
-  - `resource` (path): nome do recurso  
-  - `id` (path): ID do registro  
-  - Header `Accept-Language` para locale  
-- **Resposta:** Objeto do recurso deletado.  
-- **Erros:**  
-  - 400 Bad Request: recurso não suportado  
-  - 404 Not Found: recurso não encontrado  
-  - 401 Unauthorized  
-
----
-
-### Listar recursos com paginação e filtros
-
-- **Método:** GET  
-- **Path:** `/catalog/:resource`  
-- **Autenticação:** Sim (roles: `admin`, `admin-catalog`)  
-- **Descrição:** Lista registros do recurso com paginação, ordenação e filtros configurados.  
-- **Parâmetros:**  
-  - `resource` (path): nome do recurso  
-  - Query params: filtros conforme campos configurados, paginação (`page`, `limit`)  
-  - Header `Accept-Language` para locale  
-- **Resposta:** Lista paginada de registros do recurso.  
-- **Erros:**  
-  - 400 Bad Request: recurso não suportado ou filtro inválido  
-  - 401 Unauthorized  
-
----
-
-### Criar novo recurso
-
-- **Método:** POST  
-- **Path:** `/catalog/:resource`  
-- **Autenticação:** Sim (roles: `admin`, `admin-catalog`)  
-- **Descrição:** Cria um novo registro do recurso com os campos permitidos.  
-- **Parâmetros:**  
-  - `resource` (path): nome do recurso  
-  - Body JSON: campos para criação (somente campos configurados para o recurso)  
-  - Header `Accept-Language` para locale  
-- **Resposta:** Objeto criado do recurso.  
-- **Erros:**  
-  - 400 Bad Request: recurso não suportado ou payload inválido  
-  - 401 Unauthorized  
-
-## 4. Regras de autenticação e autorização
-
-- Todos os endpoints são protegidos e requerem autenticação.
-- Apenas usuários com os papéis `admin` ou `admin-catalog` podem acessar os endpoints do módulo.
-- A autorização é baseada em roles definidas no sistema, conforme arquivo `hedhog/data/role.yaml`.
-
-## 5. Estruturas de request/response
-
-- **Request Body:**  
-  - Campos aceitos são somente os definidos na configuração do recurso (`catalogResourceConfig`), ignorando campos extras.
-  - Valores booleanos podem ser enviados como strings `"true"` ou `"false"`.
-  - Valores numéricos podem ser enviados como strings numéricas e serão convertidos automaticamente.
-- **Response:**  
-  - Objetos JSON com os campos do recurso conforme tabelas do banco.
-  - Listagens paginadas seguem o padrão do serviço de paginação do HedHog.
-
-## 6. Erros comuns
-
-- **400 Bad Request:** Recurso não suportado, payload inválido ou filtro inválido.
-- **401 Unauthorized:** Usuário não autenticado ou sem permissão.
-- **404 Not Found:** Registro não encontrado para o ID informado.
-
-## 7. Banco de dados (tabelas YAML)
-
-### catalog_product
-
-- **Finalidade:** Armazena os produtos do catálogo.
-- **Colunas principais:**  
-  - `id` (PK)  
-  - `brand_id` (FK para `catalog_brand`, nullable)  
-  - `category_id` (FK para `category`)  
-  - `primary_content_id` (FK para `content`, nullable)  
-  - `slug` (varchar 255, único)  
-  - `name` (varchar 255)  
-  - `short_description` (varchar 500, nullable)  
-  - `description` (text, nullable)  
-  - `model_name` (varchar 255, nullable)  
-  - `sku` (varchar 120, nullable)  
-  - `gtin` (varchar 120, nullable)  
-  - `status` (enum: `draft`, `published`, `archived`, default `draft`)  
-  - `comparison_status` (enum: `draft`, `ready`, `disabled`, default `draft`)  
-  - `release_date` (datetime, nullable)  
-  - `spec_snapshot_json` (json, nullable)  
-  - `comparison_snapshot_json` (json, nullable)  
-  - `is_active` (boolean, default `true`)  
-  - `created_at`, `updated_at` (timestamps)  
-- **Defaults:** Conforme descrito acima.  
-- **Nulabilidade:** Campos como `brand_id`, `primary_content_id`, `short_description`, `description`, `model_name`, `sku`, `gtin`, `release_date`, `spec_snapshot_json`, `comparison_snapshot_json` são opcionais.  
-- **Integridade:** FK para `catalog_brand`, `category`, `content`.  
-- **Índices:**  
-  - Único em `slug`  
-  - Índices em `category_id` + `status`, `brand_id` + `status`, `primary_content_id`, `is_active`  
-
----
-
-### catalog_product_image
-
-- **Finalidade:** Armazena imagens associadas a produtos.
-- **Colunas principais:**  
-  - `id` (PK)  
-  - `product_id` (FK para `catalog_product`)  
-  - `file_id` (FK para `file`)  
-  - `role` (enum: `primary`, `gallery`, `thumbnail`, `lifestyle`, `technical`, default `gallery`)  
-  - `sort_order` (int, default 0)  
-  - `is_primary` (boolean, default false)  
-  - `alt_text` (varchar 255, nullable)  
-  - `created_at`, `updated_at` (timestamps)  
-- **Defaults:** Conforme descrito acima.  
-- **Nulabilidade:** `alt_text` é opcional.  
-- **Integridade:** FK para `catalog_product` e `file`.  
-- **Índices:**  
-  - Índices em `product_id` + `sort_order`, `product_id` + `is_primary`, `file_id`  
-
----
-
-### catalog_brand
-
-- **Finalidade:** Armazena marcas do catálogo.
-- **Colunas principais:**  
-  - `id` (PK)  
-  - `slug` (varchar 255, único)  
-  - `name` (varchar 255)  
-  - `normalized_name` (varchar 255)  
-  - `logo_file_id` (FK para `file`, nullable)  
-  - `status` (enum: `active`, `inactive`, default `active`)  
-  - `website_url` (varchar 500, nullable)  
-  - `created_at`, `updated_at` (timestamps)  
-- **Defaults:** Conforme descrito acima.  
-- **Nulabilidade:** `logo_file_id` e `website_url` são opcionais.  
-- **Integridade:** FK para `file`.  
-- **Índices:**  
-  - Único em `slug`  
-  - Índices em `normalized_name`, `logo_file_id`, `status`  
-
----
-
-### catalog_offer
-
-- **Finalidade:** Armazena ofertas vinculadas a produtos e comerciantes.
-- **Colunas principais:**  
-  - `id` (PK)  
-  - `product_id` (FK para `catalog_product`)  
-  - `merchant_id` (FK para `catalog_merchant`)  
-  - `affiliate_program_id` (FK para `catalog_affiliate_program`, nullable)  
-  - `site_id` (FK para `catalog_site`, nullable)  
-  - `external_offer_id` (varchar 255)  
-  - `title` (varchar 255)  
-  - `price_amount` (decimal 14,2)  
-  - `price_currency` (varchar 3)  
-  - `original_price_amount` (decimal 14,2, nullable)  
-  - `installment_json` (json, nullable)  
-  - `availability_status` (enum: `in_stock`, `out_of_stock`, `pre_order`, `unknown`, default `unknown`)  
-  - `affiliate_url` (varchar 500, nullable)  
-  - `deep_link_url` (varchar 500, nullable)  
-  - `priority_score` (int, default 0)  
-  - `is_featured` (boolean, default false)  
-  - `valid_from` (datetime, nullable)  
-  - `valid_until` (datetime, nullable)  
-  - `last_seen_at` (datetime, nullable)  
-  - `created_at`, `updated_at` (timestamps)  
-- **Defaults:** Conforme descrito acima.  
-- **Nulabilidade:** Campos como `affiliate_program_id`, `site_id`, `original_price_amount`, `installment_json`, `affiliate_url`, `deep_link_url`, `valid_from`, `valid_until`, `last_seen_at` são opcionais.  
-- **Integridade:** FK para `catalog_product`, `catalog_merchant`, `catalog_affiliate_program`, `catalog_site`.  
-- **Índices:**  
-  - Único em `product_id`, `merchant_id`, `external_offer_id`  
-  - Índices em `product_id`, `availability_status`, `price_amount`  
-  - Índices em `site_id`, `is_featured`  
-
----
-
-### catalog_affiliate_program
-
-- **Finalidade:** Armazena programas de afiliados vinculados a comerciantes.
-- **Colunas principais:**  
-  - `id` (PK)  
-  - `merchant_id` (FK para `catalog_merchant`, nullable)  
-  - `slug` (varchar 255, único)  
-  - `name` (varchar 255)  
-  - `network_type` (enum: `amazon`, `mercado_livre`, `aliexpress`, `kabum`, `direct`, `network`, default `direct`)  
-  - `tracking_template` (text, nullable)  
-  - `commission_type` (enum: `percentage`, `fixed`, default `percentage`)  
-  - `default_commission_value` (decimal 8,2, default 0)  
-  - `status` (enum: `active`, `inactive`, default `active`)  
-  - `created_at`, `updated_at` (timestamps)  
-- **Defaults:** Conforme descrito acima.  
-- **Nulabilidade:** `merchant_id` e `tracking_template` são opcionais.  
-- **Integridade:** FK para `catalog_merchant`.  
-- **Índices:**  
-  - Único em `slug`  
-  - Índices em `merchant_id`, `status`  
-
----
-
-*(Outras tabelas seguem padrão similar, com chaves primárias, estrangeiras, enums e índices conforme arquivos YAML fornecidos.)*
-
-## 8. Regras de negócio relevantes
-
-- O módulo suporta múltiplos recursos configurados dinamicamente via `catalogResourceMap`.
-- Campos de busca e filtro são configurados por recurso para permitir consultas eficientes.
-- Campos booleanos e numéricos são normalizados automaticamente no payload (ex: strings `"true"`, `"false"` e números em string são convertidos).
-- Exclusão e atualização verificam existência prévia do registro, retornando erro 404 se não encontrado.
-- Estatísticas incluem contagem total e contagem por status ativo quando aplicável.
-- Imagens de produtos são ordenadas por `sort_order` e podem ter uma imagem primária.
-- O sistema suporta múltiplos idiomas via parâmetro `locale` (header `Accept-Language`).
-- Autorização é restrita a usuários com papéis `admin` e `admin-catalog`.
-
-## 9. Guia rápido de uso (exemplos)
-
-### Listar produtos com paginação e filtro por status
-
-```http
-GET /catalog/product?page=1&limit=10&status=published
-Authorization: Bearer <token>
-Accept-Language: pt-BR
-```
+## Overview
 
-### Criar uma nova marca
+`@hed-hog/catalog` is the central catalog module for HedHog. It manages:
 
-```http
-POST /catalog/brand
-Authorization: Bearer <token>
-Content-Type: application/json
-Accept-Language: pt-BR
+- catalog categories
+- brands, merchants, sites, offers, and products
+- structured technical attributes by category
+- product attribute values with typed storage
+- product images and comparison-oriented payloads
 
-{
-  "slug": "nova-marca",
-  "name": "Nova Marca",
-  "status": "active",
-  "website_url": "https://novamarca.com"
-}
-```
+The module keeps the existing generic CRUD backbone, pagination, locale, roles, Prisma integration, and admin experience. The main architectural change is that structured attribute tables are now the primary source of truth for technical metadata, while legacy JSON snapshots remain secondary and derived.
 
-### Atualizar um produto
+## Core architecture
 
-```http
-PATCH /catalog/product/123
-Authorization: Bearer <token>
-Content-Type: application/json
-Accept-Language: pt-BR
+### Primary domain entities
 
-{
-  "name": "Nome Atualizado",
-  "status": "published"
-}
-```
+- `catalog_category`
+  Product taxonomy used by the catalog itself.
+- `catalog_attribute`
+  Master definition of a technical/comparable attribute.
+- `catalog_attribute_option`
+  Enumerated values for `option` attributes.
+- `catalog_category_attribute`
+  Rules that define which attributes belong to a category and how they behave in UI/comparison.
+- `catalog_product_attribute_value`
+  Typed value storage for product attributes.
+- `catalog_product`
+  Main product record with brand, category, content, status, and secondary snapshots.
 
-### Deletar uma oferta
+### Supporting entities
 
-```http
-DELETE /catalog/offer/456
-Authorization: Bearer <token>
-Accept-Language: pt-BR
-```
+- `catalog_brand`
+  Supports `logo_file_id` via the shared `file` module.
+- `catalog_site`
+  Supports `logo_file_id` and site-specific JSON settings.
+- `catalog_merchant`
+  Supports `logo_file_id` when merchant branding is needed.
+- `catalog_product_image`
+  Product gallery/media records via `file_id`.
+- `catalog_offer`, `catalog_affiliate_program`, `catalog_product_site`, `catalog_comparison`, and related tables
+  Commercial/publication/comparison layers that build on top of products and attributes.
 
-### Obter estatísticas de ofertas
+## Structured attributes vs JSON snapshots
 
-```http
-GET /catalog/offer/stats
-Authorization: Bearer <token>
-Accept-Language: pt-BR
-```
+### Primary data
+
+The canonical source for technical product data is:
+
+1. `catalog_category`
+2. `catalog_attribute`
+3. `catalog_category_attribute`
+4. `catalog_product_attribute_value`
+
+This is what enables:
+
+- consistent admin forms
+- typed validation
+- category-aware required fields
+- filters and sorting by normalized values
+- comparison payload generation
+
+### Secondary data
+
+`catalog_product.spec_snapshot_json` and `catalog_product.comparison_snapshot_json` are still present for compatibility and fast reads.
+
+Important rules:
+
+- they are **not** the primary source of truth anymore
+- they should be treated as **derived/cache fields**
+- they are materialized from structured attributes
+- old data should not be deleted without a migration plan
+
+The service now exposes snapshot materialization helpers and keeps snapshots warm after attribute updates.
+
+## Main tables
+
+### `catalog_category`
+
+Suggested use:
+
+- create taxonomy nodes like `gpu`, `cpu`, `motherboard`, `ram`, `ssd`, `monitor`
+- optionally organize them with `parent_category_id`
+- control whether the category participates in comparison with `comparison_enabled`
+
+Key fields:
+
+- `slug`
+- `name`
+- `description`
+- `parent_category_id`
+- `comparison_enabled`
+- `status`
+- `sort_order`
+
+### `catalog_attribute`
+
+Defines the technical vocabulary shared across categories.
+
+Key fields:
+
+- `code`
+- `slug`
+- `name`
+- `description`
+- `data_type`
+- `unit`
+- `group_name`
+- `comparison_mode`
+- `is_filterable`
+- `is_sortable`
+- `is_comparable`
+- `is_required_default`
+- `status`
+- `display_order`
+
+Supported `data_type` values:
+
+- `text`
+- `long_text`
+- `number`
+- `boolean`
+- `option`
+
+### `catalog_attribute_option`
+
+Used when `catalog_attribute.data_type = option`.
+
+Key fields:
+
+- `attribute_id`
+- `slug`
+- `label`
+- `option_value`
+- `normalized_value`
+- `sort_order`
+- `status`
+- `is_default`
+
+### `catalog_category_attribute`
+
+Binds attributes to categories and controls behavior.
+
+Key fields:
+
+- `catalog_category_id`
+- `attribute_id`
+- `is_required`
+- `is_highlight`
+- `is_filter_visible`
+- `is_comparison_visible`
+- `sort_order`
+- `weight`
+- `facet_mode`
+
+### `catalog_product_attribute_value`
+
+Stores one typed value per `product_id + attribute_id`.
+
+Key fields:
+
+- `product_id`
+- `attribute_id`
+- `attribute_option_id`
+- `value_text`
+- `value_number`
+- `value_boolean`
+- `raw_value`
+- `value_unit`
+- `normalized_value`
+- `normalized_text`
+- `normalized_number`
+- `source_type`
+- `confidence_score`
+- `is_verified`
+
+## Attribute value rules
+
+Only one value channel should be used per attribute value row:
+
+- `text` and `long_text` use `value_text`
+- `number` uses `value_number`
+- `boolean` uses `value_boolean`
+- `option` uses `attribute_option_id`
+
+The backend validates this and rejects inconsistent payloads.
+
+## Initial catalog seeds
+
+The module now ships declarative YAML seeds in `libraries/catalog/hedhog/data`.
+
+Seeded categories:
+
+- `gpu`
+- `cpu`
+- `motherboard`
+- `ram`
+- `ssd`
+- `monitor`
+
+Seeded example attributes:
+
+### GPU
+
+- `chipset`
+- `vram_gb`
+- `memory_type`
+- `memory_bus_bits`
+- `boost_clock_mhz`
+- `tdp_w`
+- `length_mm`
+- `ray_tracing`
+
+### CPU
+
+- `cores`
+- `threads`
+- `base_clock_ghz`
+- `boost_clock_ghz`
+- `socket`
+- `tdp_w`
+- `integrated_graphics`
+
+Seeded example options:
 
-### Listar imagens de um produto
+- GPU memory types like `GDDR6`, `GDDR6X`, `GDDR7`, `HBM3`, `HBM3E`
+- CPU sockets like `AM4`, `AM5`, `LGA1700`, `LGA1851`, `sTR5`
 
-```http
-GET /catalog/products/123/images?page=1&limit=5
-Authorization: Bearer <token>
-Accept-Language: pt-BR
+## Admin resources
+
+The catalog admin supports generic CRUD plus specialized product attribute editing.
+
+Main resources:
+
+- `categories`
+- `brands`
+- `sites`
+- `products`
+- `attribute-groups`
+- `attributes`
+- `attribute-options`
+- `category-attributes`
+- `product-attributes`
+- `comparisons`
+- `offers`
+- `merchants`
+- `affiliate-programs`
+- `seo-rules`
+- `import-sources`
+
+### Product admin experience
+
+When editing a product:
+
+1. select `catalog_category_id`
+2. the admin loads category attributes dynamically
+3. fields are grouped by attribute group or `group_name`
+4. typed inputs are rendered for `text`, `long_text`, `number`, `boolean`, and `option`
+5. required fields are validated before save
+6. values are persisted into `catalog_product_attribute_value`
+
+The product screen also shows:
+
+- brand
+- category
+- status and active flag
+- grouped technical attributes
+- product images as a secondary block
+- snapshots as secondary/derived data
+
+## Logos and files
+
+The module uses the shared `file` flow already present in the monorepo.
+
+### Brand logo
+
+Use `catalog_brand.logo_file_id`.
+
+### Site logo
+
+Use `catalog_site.logo_file_id`.
+
+### Merchant logo
+
+Use `catalog_merchant.logo_file_id`.
+
+### Product gallery
+
+Use `catalog_product_image.file_id`.
+
+No custom upload mechanism was introduced. The admin uses the same file upload pattern already used across the project.
+
+## Runtime helpers
+
+`CatalogService` now includes helpers for:
+
+- listing category attributes
+- listing product attributes
+- building a structured product payload
+- building a comparison payload from structured attributes
+- materializing `spec_snapshot_json` and `comparison_snapshot_json`
+
+Relevant endpoints:
+
+- `GET /catalog/categories/tree`
+- `GET /catalog/categories/:id/attributes`
+- `GET /catalog/products/:id/attributes`
+- `PUT /catalog/products/:id/attributes`
+- `GET /catalog/products/:id/structured`
+- `GET /catalog/products/:id/comparison-payload`
+- `POST /catalog/products/:id/materialize-snapshots`
+- generic CRUD under `/catalog/:resource`
+
+## Safe transition strategy
+
+The module preserves snapshot fields to avoid destructive migration behavior.
+
+Current strategy:
+
+- structured attribute tables are canonical
+- snapshots remain readable
+- snapshots are regenerated from structured values
+- attribute updates trigger snapshot materialization
+- compatibility aliases are still accepted in a few payloads where the old UI/model used different names
+
+This keeps the module safe for gradual adoption while avoiding JSON-first modeling going forward.
+
+## How to apply schema and seeds
+
+This repository follows a database-first HedHog workflow.
+
+### Schema/data apply
+
+```powershell
+hedhog dev apply
+pnpm db:update
 ```
 
----
+`hedhog dev apply` applies table YAML and the declarative data under `hedhog/data`, so the catalog seed data lives in the same standard workflow as the rest of the project.
 
-Este módulo deve ser utilizado por administradores do catálogo para gerenciar os dados essenciais do sistema de forma segura e consistente.
+### Build checks
+
+```powershell
+pnpm --filter api build
+pnpm --filter @hed-hog/catalog build
+pnpm --filter admin build
 ```
+
+## Example flows
+
+### 1. Create a brand with logo
+
+1. Open `Catalog > Brands`
+2. Create a brand with `name`, `slug`, and optional `website_url`
+3. Upload the logo through the shared upload field
+4. Save, which stores the uploaded file in `logo_file_id`
+
+### 2. Create a category
+
+1. Open `Catalog > Categories`
+2. Create `gpu`-like or business-specific categories
+3. Configure `comparison_enabled`, hierarchy, and status
+
+### 3. Create an attribute
+
+1. Open `Catalog > Attributes`
+2. Define `code`, `slug`, `name`, `data_type`, and `group_name`
+3. Mark whether the attribute is filterable/sortable/comparable
+
+### 4. Link an attribute to a category
+
+1. Open `Catalog > Category Attributes`
+2. Pick the category and the attribute
+3. Configure required/highlight/filter/comparison behavior
+4. Save ordering and facet mode
+
+### 5. Create a product
+
+1. Open `Catalog > Products`
+2. Fill the base product fields
+3. Choose brand and category
+4. Save the product
+
+### 6. Save product technical attributes
+
+1. In the same product sheet, after category selection, the technical fields load automatically
+2. Fill typed values
+3. Save the product
+4. The admin persists values to `catalog_product_attribute_value`
+5. Snapshots are materialized as derived JSON
+
+## Starting with GPU and CPU
+
+The seeded data is enough to bootstrap a real first catalog slice:
+
+1. create brands like `NVIDIA`, `AMD`, `Intel`
+2. create products under `gpu` and `cpu`
+3. fill structured attributes
+4. optionally attach product images
+5. use comparison payload endpoints to power future storefront or editorial flows
+
+## Future improvements
+
+- automatic snapshot materialization on more product lifecycle events
+- richer import pipelines that map external payloads directly to structured attributes
+- category-specific admin presets and product templates
+- storefront queries optimized for faceting and comparison at scale
+- deeper read models for SEO, rankings, and recommendation features