# @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

GET /catalog/product?page=1&limit=10&status=published
Authorization: Bearer <token>
Accept-Language: pt-BR

Criar uma nova marca

POST /catalog/brand
Authorization: Bearer <token>
Content-Type: application/json
Accept-Language: pt-BR

{
  "slug": "nova-marca",
  "name": "Nova Marca",
  "status": "active",
  "website_url": "https://novamarca.com"
}

Atualizar um produto

PATCH /catalog/product/123
Authorization: Bearer <token>
Content-Type: application/json
Accept-Language: pt-BR

{
  "name": "Nome Atualizado",
  "status": "published"
}

Deletar uma oferta

DELETE /catalog/offer/456
Authorization: Bearer <token>
Accept-Language: pt-BR

Obter estatísticas de ofertas

GET /catalog/offer/stats
Authorization: Bearer <token>
Accept-Language: pt-BR

Listar imagens de um produto

GET /catalog/products/123/images?page=1&limit=5
Authorization: Bearer <token>
Accept-Language: pt-BR

Este módulo deve ser utilizado por administradores do catálogo para gerenciar os dados essenciais do sistema de forma segura e consistente.