@hed-hog/catalog

1. Visão geral do módulo

O módulo @hed-hog/catalog é responsável pela gestão do catálogo de produtos, marcas, sites, categorias e atributos relacionados. Ele oferece funcionalidades para criação, atualização, listagem, exclusão e comparação de produtos, além de gerenciar a estrutura de categorias e atributos que definem as características dos produtos no sistema.

2. Escopo e responsabilidades

• Gerenciar produtos, incluindo seus atributos e status.
• Gerenciar marcas associadas aos produtos.
• Gerenciar sites que agrupam categorias e produtos.
• Gerenciar categorias, incluindo hierarquia e layout de atributos.
• Gerenciar grupos de atributos e atributos individuais.
• Permitir comparação entre produtos da mesma categoria.
• Garantir integridade e validação dos dados relacionados ao catálogo.

3. Endpoints

Todos os endpoints requerem autenticação e autorização com roles admin ou admin-catalog.

Produtos

| Método | Path | Autenticação | Descrição | |--------|-----------------------|--------------|----------------------------------| | GET | /catalog/products | Sim | Lista produtos com paginação e filtros opcionais. | | POST | /catalog/products | Sim | Cria um novo produto. | | PATCH | /catalog/products/:id | Sim | Atualiza um produto existente. | | DELETE | /catalog/products/:id | Sim | Exclui um produto. |

Parâmetros GET /catalog/products:

• Query:
  • site_id (number, obrigatório): ID do site para filtrar produtos.
  • catalog_category_id (number, opcional): ID da categoria para filtrar.
  • status (string, opcional): Status do produto (draft, published, archived, all).
  • Parâmetros de paginação: page, pageSize.

Body POST/PATCH /catalog/products:

• name (string, obrigatório)
• slug (string, obrigatório)
• site_id (number, obrigatório)
• catalog_category_id (number, obrigatório)
• brand_id (number, opcional)
• icon_file_id (number, opcional)
• short_description (string, opcional)
• description (string, opcional)
• status (string, opcional, default draft)
• comparison_status (string, opcional, valores: draft, ready, excluded)
• is_active (boolean, opcional, default true)

Resposta:

Objeto do produto criado/atualizado/listado com campos principais.

Erros comuns:

• 400 Bad Request: Campos obrigatórios ausentes ou inválidos.
• 404 Not Found: Produto não encontrado.

Marcas

| Método | Path | Autenticação | Descrição | |--------|---------------------|--------------|-------------------------------| | GET | /catalog/brands | Sim | Lista marcas com paginação. | | POST | /catalog/brands | Sim | Cria uma nova marca. | | PATCH | /catalog/brands/:id | Sim | Atualiza uma marca existente. | | DELETE | /catalog/brands/:id | Sim | Exclui uma marca. |

Parâmetros GET /catalog/brands:

• Query:
  • status (string, opcional, default active, valores: active, inactive, all)
  • Parâmetros de paginação.

Body POST/PATCH /catalog/brands:

• name (string, obrigatório)
• slug (string, obrigatório)
• logo_file_id (number, opcional)
• status (string, opcional, default active)
• website_url (string, opcional)

Erros comuns:

• 400 Bad Request: Campos obrigatórios ausentes.
• 404 Not Found: Marca não encontrada.

Sites

| Método | Path | Autenticação | Descrição | |--------|-------------------|--------------|-----------------------------| | GET | /catalog/sites | Sim | Lista sites com paginação. | | POST | /catalog/sites | Sim | Cria um novo site. | | PATCH | /catalog/sites/:id | Sim | Atualiza um site existente. | | DELETE | /catalog/sites/:id | Sim | Exclui um site. |

Parâmetros GET /catalog/sites:

• Query:
  • status (string, opcional, default active, valores: active, inactive, all)
  • Parâmetros de paginação.

Body POST/PATCH /catalog/sites:

• name (string, obrigatório)
• slug (string, obrigatório)
• base_url (string, opcional)
• logo_file_id (number, opcional)
• status (string, opcional, default active)

Erros comuns:

• 400 Bad Request: Campos obrigatórios ausentes.
• 404 Not Found: Site não encontrado.

Categorias

| Método | Path | Autenticação | Descrição | |--------|-------------------------------|--------------|-------------------------------------------| | GET | /catalog/categories | Sim | Lista categorias com paginação e filtros.| | POST | /catalog/categories | Sim | Cria uma nova categoria. | | PATCH | /catalog/categories/:id | Sim | Atualiza uma categoria existente. | | DELETE | /catalog/categories/:id | Sim | Exclui uma categoria. | | PATCH | /catalog/categories/:id/move| Sim | Move uma categoria para outro pai/posição.|

Parâmetros GET /catalog/categories:

• Query:
  • site_id (number, obrigatório)
  • status (string, opcional, valores: active, inactive, all)
  • Parâmetros de paginação.

Body POST/PATCH /catalog/categories:

• name (string, obrigatório)
• slug (string, obrigatório)
• site_id (number, obrigatório)
• image_file_id (number, opcional)
• status (string, opcional, default active)
• parent_category_id (number, opcional)

Body PATCH /catalog/categories/:id/move:

• parent_category_id (number, opcional): Novo pai da categoria.
• position (number, opcional): Nova posição na ordem dos irmãos.

Erros comuns:

• 400 Bad Request: Campos obrigatórios ausentes, ciclo na hierarquia ou site incompatível.
• 404 Not Found: Categoria não encontrada.

Atributos de Categoria

| Método | Path | Autenticação | Descrição | |--------|---------------------------------------|--------------|-------------------------------------------| | GET | /catalog/categories/:id/attributes | Sim | Lista atributos associados a uma categoria. | | GET | /catalog/categories/:id/attribute-layout | Sim | Obtém layout dos atributos da categoria. | | PUT | /catalog/categories/:id/attribute-layout | Sim | Atualiza layout dos atributos da categoria.|

Body PUT /catalog/categories/:id/attribute-layout:

• groups (array): Grupos de atributos com seus atributos e configurações.

Erros comuns:

• 400 Bad Request: Dados inválidos no layout.
• 404 Not Found: Categoria não encontrada.

Grupos de Atributos

| Método | Path | Autenticação | Descrição | |--------|-------------------------|--------------|-------------------------------| | GET | /catalog/attribute-groups | Sim | Lista grupos de atributos com paginação.|

Parâmetros GET /catalog/attribute-groups:

• Query:
  • status (string, opcional, valores: active, inactive, all)
  • Parâmetros de paginação.

Atributos

| Método | Path | Autenticação | Descrição | |--------|--------------------|--------------|-------------------------------| | GET | /catalog/attributes | Sim | Lista atributos com paginação e filtros.|

Parâmetros GET /catalog/attributes:

• Query:
  • status (string, opcional, valores: active, inactive, all)
  • data_type (string, opcional, valores: text, long_text, number, boolean, option, date, all)
  • Parâmetros de paginação.

Atributos de Produto

| Método | Path | Autenticação | Descrição | |--------|-------------------------------|--------------|----------------------------------| | GET | /catalog/products/:id/attributes | Sim | Lista atributos e valores de um produto. | | PUT | /catalog/products/:id/attributes | Sim | Atualiza valores dos atributos de um produto.|

Body PUT /catalog/products/:id/attributes:

• values (array): Lista de valores de atributos com campos como attribute_id, attribute_option_id, value_text, value_number, value_boolean, value_date, value_unit, source_type, is_verified.

Erros comuns:

• 400 Bad Request: Atributos obrigatórios ausentes ou inválidos.
• 404 Not Found: Produto não encontrado.

Comparações

| Método | Path | Autenticação | Descrição | |--------|-------------------|--------------|----------------------------------| | GET | /catalog/comparisons | Sim | Compara produtos informados por IDs.|

Query GET /catalog/comparisons:

• product_ids (array ou string separada por vírgula, obrigatório): IDs dos produtos para comparação (mínimo 2).

Erros comuns:

• 400 Bad Request: Menos de 2 produtos ou produtos de categorias diferentes.
• 404 Not Found: Produto(s) não encontrado(s).

4. Regras de autenticação e autorização

• Todos os endpoints requerem autenticação.
• Acesso restrito a usuários com roles admin ou admin-catalog.
• Roles definidas no sistema para controle de acesso ao catálogo.

5. Estruturas de request/response

Produto (exemplo simplificado)

{
  "id": 1,
  "slug": "produto-exemplo",
  "name": "Produto Exemplo",
  "site_id": 1,
  "status": "draft",
  "comparison_status": "draft",
  "is_active": true,
  "catalog_category_id": 2,
  "brand_id": 3,
  "icon_file_id": null,
  "created_at": "2024-01-01T00:00:00Z",
  "updated_at": "2024-01-01T00:00:00Z"
}

Atributo de Produto (exemplo simplificado)

{
  "attribute_id": 10,
  "attribute_option_id": 5,
  "value_text": "Exemplo",
  "value_number": 123.45,
  "value_boolean": true,
  "value_date": "2024-01-01",
  "value_unit": "kg",
  "source_type": "manual",
  "is_verified": false
}

Layout de Atributos de Categoria (exemplo simplificado)

{
  "category": { "id": 1, "name": "Categoria Exemplo" },
  "groups": [
    {
      "id": 1,
      "attribute_group_id": 2,
      "slug": "general",
      "name": "Geral",
      "sort_order": 0,
      "is_collapsed_default": false,
      "attributes": [
        {
          "id": 10,
          "slug": "peso",
          "name": "Peso",
          "data_type": "number",
          "comparison_mode": "lower_better",
          "category_attribute": {
            "is_required": true,
            "weight": 1
          },
          "options": [],
          "value": null
        }
      ]
    }
  ],
  "available_groups": [...],
  "available_attributes": [...]
}

6. Erros comuns

• 400 Bad Request: Dados obrigatórios ausentes, formato inválido, tentativa de criar ciclo em categorias, atributos obrigatórios não preenchidos.
• 404 Not Found: Entidade (produto, marca, site, categoria) não encontrada.
• 403 Forbidden: Usuário sem permissão para acessar o recurso.

7. Banco de dados (tabelas YAML)

catalog_attribute

• Finalidade: Define atributos que podem ser associados a categorias e produtos.

• Colunas principais:

  • id (PK)
  • slug (string)
  • code (string, único)
  • name (string)
  • description (texto, opcional)
  • data_type (enum: text, long_text, number, boolean, option, date; default: text)
  • comparison_mode (enum: none, higher_better, lower_better, newer_better, older_better, option_rank, boolean_true_better; default: none)
  • score_weight_default (numérico, opcional)
  • highlight_eligible (boolean, default true)
  • badge_formula_role (enum: none, overall, value, efficiency, launch_recency; default none)
  • unit (string, opcional)
  • is_filterable (boolean, default false)
  • is_sortable (boolean, default false)
  • is_comparable (boolean, default true)
  • is_required_default (boolean, default false)
  • status (enum: active, inactive; default active)
  • display_order (int, default 0)
  • created_at, updated_at

• Índices: data_type, comparison_mode, comparison_group, badge_formula_role, status, is_filterable, is_sortable, is_comparable, display_order.

catalog_attribute_group

• Finalidade: Agrupa atributos para organização.

• Colunas principais:

  • id (PK)
  • slug (string, único)
  • name (string)
  • description (texto, opcional)
  • status (enum: active, inactive; default active)
  • order (int)
  • created_at, updated_at

• Índices: slug (único), status, sort_order.

catalog_attribute_option

• Finalidade: Opções para atributos do tipo "option".

• Colunas principais:

  • id (PK)
  • attribute_id (FK para catalog_attribute, cascade delete)
  • slug (string)
  • option_value (string)
  • label (string)
  • normalized_value (string, opcional)
  • status (enum: active, inactive; default active)
  • is_default (boolean, default false)
  • order (int)
  • created_at, updated_at

• Índices: attribute_id, status, combinação attribute_id+slug (único), attribute_id+sort_order.

catalog_brand

• Finalidade: Marcas associadas a produtos.

• Colunas principais:

  • id (PK)
  • slug (string)
  • name (string)
  • logo_file_id (FK para file, opcional, set null on delete)
  • website_url (string, opcional)
  • status (enum: active, inactive; default active)
  • created_at, updated_at

• Índices: logo_file_id, status.

catalog_category

• Finalidade: Categorias de produtos, com hierarquia.

• Colunas principais:

  • id (PK)
  • site_id (FK para catalog_site, cascade delete)
  • parent_category_id (FK para catalog_category, opcional, set null on delete)
  • image_file_id (FK para file, opcional, set null on delete)
  • slug (string)
  • name (string)
  • description (texto, opcional)
  • comparison_enabled (boolean, default true)
  • status (enum: active, inactive; default active)
  • order (int)
  • created_at, updated_at

• Índices: site_id, parent_category_id, image_file_id, status, comparison_enabled, sort_order, combinação site_id+status+sort_order.

catalog_category_attribute

• Finalidade: Relação entre categorias e atributos, com configurações específicas.

• Colunas principais:

  • id (PK)
  • catalog_category_id (FK para catalog_category, cascade delete)
  • attribute_id (FK para catalog_attribute, cascade delete)
  • category_attribute_group_id (FK para catalog_category_attribute_group, opcional, set null on delete)
  • is_required (boolean, default false)
  • is_highlight (boolean, default false)
  • is_filter_visible (boolean, default true)
  • is_comparison_visible (boolean, default true)
  • winner_visible (boolean, default true)
  • order (int)
  • weight (int, default 1)
  • facet_mode (enum: default, exact, range, boolean; default default)
  • created_at, updated_at

• Índices: combinação catalog_category_id+attribute_id (único), category_attribute_group_id, catalog_category_id+sort_order, is_filter_visible, is_comparison_visible, winner_visible.

catalog_category_attribute_group

• Finalidade: Grupos de atributos dentro de uma categoria.

• Colunas principais:

  • id (PK)
  • catalog_category_id (FK para catalog_category, cascade delete)
  • attribute_group_id (FK para catalog_attribute_group, cascade delete)
  • is_collapsed_default (boolean, default false)
  • order (int)
  • created_at, updated_at

• Índices: combinação catalog_category_id+attribute_group_id (único), catalog_category_id+sort_order, attribute_group_id.

catalog_product

• Finalidade: Produtos do catálogo.

• Colunas principais:

  • id (PK)
  • brand_id (FK para catalog_brand, opcional, set null on delete)
  • catalog_category_id (FK para catalog_category, cascade delete)
  • icon_file_id (FK para file, opcional, set null on delete)
  • slug (string)
  • name (string)
  • short_description (texto, opcional)
  • description (texto, opcional)
  • status (enum: draft, published, archived; default draft)
  • comparison_status (enum: draft, ready, excluded; default draft)
  • is_active (boolean, default true)
  • created_at, updated_at

• Índices: brand_id, catalog_category_id, icon_file_id, status, comparison_status, is_active, combinação catalog_category_id+status+is_active.

catalog_product_attribute_value

• Finalidade: Valores dos atributos para cada produto.

• Colunas principais:

  • id (PK)
  • product_id (FK para catalog_product, cascade delete)
  • attribute_id (FK para catalog_attribute, cascade delete)
  • attribute_option_id (FK para catalog_attribute_option, opcional, set null on delete)
  • value_text (texto, opcional)
  • value_number (numérico, opcional)
  • value_boolean (boolean, opcional)
  • value_date (date, opcional)
  • raw_value (texto, opcional)
  • value_unit (string, opcional)
  • normalized_value (string, opcional)
  • normalized_text (string, opcional)
  • normalized_number (numérico, opcional)
  • source_type (enum: manual, imported, ai; default manual)
  • confidence_score (numérico, opcional)
  • is_verified (boolean, default false)
  • created_at, updated_at

• Índices: combinação product_id+attribute_id (único), product_id, attribute_id, attribute_option_id, normalized_value, normalized_number, is_verified, attribute_id+normalized_number, attribute_id+normalized_value.

catalog_product_image

• Finalidade: Imagens associadas a produtos.

• Colunas principais:

  • id (PK)
  • product_id (FK para catalog_product, cascade delete)
  • file_id (FK para file, cascade delete)
  • role (enum: gallery, thumbnail, icon, hero; default gallery)
  • is_primary (boolean, default false)
  • order (int)
  • status (enum: active, inactive; default active)
  • created_at, updated_at

• Índices: product_id, file_id, status, combinação product_id+file_id (único), product_id+role, product_id+is_primary, product_id+sort_order.

catalog_site

• Finalidade: Sites que agrupam categorias e produtos.

• Colunas principais:

  • id (PK)
  • slug (string, único)
  • name (string)
  • base_url (string, opcional)
  • logo_file_id (FK para file, opcional, set null on delete)
  • status (enum: active, inactive; default active)
  • created_at, updated_at

• Índices: slug (único), base_url, logo_file_id, status.

8. Regras de negócio relevantes

• Produtos devem pertencer a uma categoria que pertence a um site válido.
• Categorias podem ter hierarquia, mas não podem formar ciclos.
• Atributos podem ser agrupados e configurados para cada categoria.
• Atributos obrigatórios devem ser preenchidos para produtos.
• Comparação de produtos só é permitida entre produtos da mesma categoria.
• Status e visibilidade dos produtos e atributos influenciam na exibição e comparação.
• Layout de atributos pode ser customizado por categoria, incluindo criação de novos atributos e grupos.
• Valores de atributos possuem diferentes tipos e modos de comparação para cálculo de scores e vencedores.
• Atualizações em atributos e categorias são feitas em transações para garantir integridade.

9. Guia rápido de uso (exemplos)

Listar produtos de um site e categoria

GET /catalog/products?site_id=1&catalog_category_id=2&page=1&pageSize=10
Authorization: Bearer <token>

Criar um novo produto

POST /catalog/products
Authorization: Bearer <token>
Content-Type: application/json

{
  "name": "Produto Novo",
  "slug": "produto-novo",
  "site_id": 1,
  "catalog_category_id": 2,
  "brand_id": 3,
  "status": "draft",
  "is_active": true
}

Atualizar atributos de um produto

PUT /catalog/products/10/attributes
Authorization: Bearer <token>
Content-Type: application/json

{
  "values": [
    {
      "attribute_id": 5,
      "value_number": 123.45,
      "source_type": "manual",
      "is_verified": true
    },
    {
      "attribute_id": 6,
      "attribute_option_id": 2
    }
  ]
}

Mover categoria para outro pai e posição

PATCH /catalog/categories/3/move
Authorization: Bearer <token>
Content-Type: application/json

{
  "parent_category_id": 1,
  "position": 2
}

Comparar produtos

GET /catalog/comparisons?product_ids=10,11,12
Authorization: Bearer <token>

Este módulo é fundamental para a gestão estruturada e comparativa do catálogo de produtos, garantindo flexibilidade e integridade dos dados para aplicações que dependem de informações detalhadas e organizadas de produtos e suas características.