@hed-hog/catalog 0.0.276 → 0.0.278

package/README.md

@@ -0,0 +1,269 @@
+# @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.
+- **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)
+
+### Exemplo: `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`)  
+  - `slug` (varchar 255, único)  
+  - `name` (varchar 255)  
+  - `short_description` (varchar 500, nullable)  
+  - `description` (text, nullable)  
+  - `status` (enum: `draft`, `published`, `archived`, default `draft`)  
+  - `comparison_status` (enum: `draft`, `ready`, `disabled`, default `draft`)  
+  - `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`.  
+- **Índices:**  
+  - Único em `slug`  
+  - Índices em `category_id` + `status`, `brand_id` + `status`, `is_active`  
+
+*(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.
+- Exclusão e atualização verificam existência prévia do registro.
+- 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`.
+
+## 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
+```
+
+### Criar uma nova marca
+
+```http
+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
+
+```http
+PATCH /catalog/product/123
+Authorization: Bearer <token>
+Content-Type: application/json
+Accept-Language: pt-BR
+
+{
+  "name": "Nome Atualizado",
+  "status": "published"
+}
+```
+
+### Deletar uma oferta
+
+```http
+DELETE /catalog/offer/456
+Authorization: Bearer <token>
+Accept-Language: pt-BR
+```
+
+### Obter estatísticas de ofertas
+
+```http
+GET /catalog/offer/stats
+Authorization: Bearer <token>
+Accept-Language: pt-BR
+```
+
+### Listar imagens de um produto
+
+```http
+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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hed-hog/catalog",
-  "version": "0.0.276",
+  "version": "0.0.278",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "dependencies": {
@@ -9,14 +9,14 @@
     "@nestjs/core": "^11",
     "@nestjs/jwt": "^11",
     "@nestjs/mapped-types": "*",
+    "@hed-hog/api-pagination": "0.0.6",
     "@hed-hog/api-locale": "0.0.13",
+    "@hed-hog/core": "0.0.278",
     "@hed-hog/api": "0.0.4",
-    "@hed-hog/core": "0.0.276",
-    "@hed-hog/api-pagination": "0.0.6",
+    "@hed-hog/category": "0.0.278",
     "@hed-hog/api-prisma": "0.0.5",
-    "@hed-hog/category": "0.0.276",
-    "@hed-hog/content": "0.0.276",
-    "@hed-hog/tag": "0.0.276"
+    "@hed-hog/content": "0.0.278",
+    "@hed-hog/tag": "0.0.278"
   },
   "exports": {
     ".": {