@hed-hog/catalog 0.0.278 → 0.0.285

package/README.md

@@ -1,3 +1,4 @@
+```markdown
 # @hed-hog/catalog
 
 ## 1. Visão geral do módulo
@@ -153,7 +154,7 @@ O módulo `@hed-hog/catalog` é responsável pela gestão centralizada dos recur
 - **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.
+  - 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.
@@ -166,27 +167,134 @@ O módulo `@hed-hog/catalog` é responsável pela gestão centralizada dos recur
 
 ## 7. Banco de dados (tabelas YAML)
 
-### Exemplo: `catalog_product`
+### 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`, `short_description`, `description` são opcionais.  
-- **Integridade:** FK para `catalog_brand`, `category` e `content`.  
+- **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`, `is_active`  
+  - Í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.)*
 
@@ -194,11 +302,12 @@ O módulo `@hed-hog/catalog` é responsável pela gestão centralizada dos recur
 
 - 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.
-- Exclusão e atualização verificam existência prévia do registro.
+- 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`.
+- 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)
 
@@ -267,3 +376,4 @@ 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.
+```