@hed-hog/category 0.0.270 → 0.0.273

package/README.md

@@ -0,0 +1,332 @@
+# @hed-hog/category
+
+## 1. Visão geral do módulo
+
+O módulo `@hed-hog/category` é responsável pela gestão de categorias no sistema HedHog. Ele oferece funcionalidades para criação, leitura, atualização e exclusão (CRUD) de categorias, incluindo suporte a múltiplos idiomas via localizações, hierarquia de categorias (categorias pai e raiz), e controle de status (ativo/inativo). O módulo integra-se com serviços de paginação e localização para facilitar consultas e traduções.
+
+## 2. Escopo e responsabilidades
+
+- Gerenciar categorias com atributos como slug, cor, ícone, status e hierarquia.
+- Suportar múltiplas localizações para o nome da categoria.
+- Fornecer endpoints para consulta de categorias raiz, categorias por pai, estatísticas e listagem paginada.
+- Validar dados de entrada e garantir integridade referencial.
+- Controlar acesso via roles específicas para administração de categorias.
+
+## 3. Endpoints
+
+| Método | Path                  | Autenticação | Descrição                                      |
+|--------|-----------------------|--------------|------------------------------------------------|
+| GET    | `/category/root`       | Autenticada  | Retorna categorias raiz ativas no idioma solicitado. |
+| GET    | `/category/stats`      | Autenticada  | Retorna estatísticas gerais das categorias.    |
+| GET    | `/category/:id`        | Autenticada  | Retorna categoria pelo ID com localizações.    |
+| GET    | `/category/parent/:categoryId` | Autenticada  | Retorna categorias filhas de uma categoria pai. |
+| GET    | `/category`            | Autenticada  | Lista categorias com paginação, filtro por status e categoria pai. |
+| POST   | `/category`            | Autenticada  | Cria uma nova categoria com localizações.      |
+| PATCH  | `/category/:id`        | Autenticada  | Atualiza uma categoria existente parcialmente. |
+| DELETE | `/category/:id`        | Autenticada  | Remove uma categoria pelo ID.                    |
+
+### Detalhes dos endpoints
+
+---
+
+#### GET `/category/root`
+
+- **Autenticação:** Necessária (roles: admin, admin-category)
+- **Query:** Nenhuma
+- **Resposta:** Lista de categorias raiz ativas com traduções no idioma solicitado.
+- **Erros comuns:**
+  - 400 Bad Request: Locale inválido ou não encontrado.
+
+---
+
+#### GET `/category/stats`
+
+- **Autenticação:** Necessária (roles: admin, admin-category)
+- **Resposta:**
+  ```json
+  {
+    "total": number,
+    "totalActive": number,
+    "totalInactive": number,
+    "totalRoot": number
+  }
+  ```
+- **Erros comuns:** Nenhum específico.
+
+---
+
+#### GET `/category/:id`
+
+- **Autenticação:** Necessária (roles: admin, admin-category)
+- **Parâmetros:**
+  - `id` (number, obrigatório): ID da categoria.
+- **Resposta:** Objeto categoria com localizações.
+- **Erros comuns:**
+  - 404 Not Found: Categoria não encontrada.
+
+---
+
+#### GET `/category/parent/:categoryId`
+
+- **Autenticação:** Necessária (roles: admin, admin-category)
+- **Parâmetros:**
+  - `categoryId` (string, obrigatório): ID da categoria pai.
+- **Resposta:** Lista de categorias filhas com localizações.
+- **Erros comuns:**
+  - 400 Bad Request: Locale inválido.
+  - 404 Not Found: Categoria pai não encontrada ou sem filhos.
+
+---
+
+#### GET `/category`
+
+- **Autenticação:** Necessária (roles: admin, admin-category)
+- **Query:**
+  - `status` (string, opcional): Filtra por status (`active`, `inactive`, `all`).
+  - `parent` (string, opcional): Filtra por categoria pai (`slug` ou `root` ou `all`).
+  - Parâmetros de paginação via cabeçalho ou query (padrão do módulo de paginação).
+- **Resposta:** Objeto paginado com categorias e localizações.
+- **Erros comuns:**
+  - 400 Bad Request: Locale inválido.
+
+---
+
+#### POST `/category`
+
+- **Autenticação:** Necessária (roles: admin, admin-category)
+- **Body:**
+  ```json
+  {
+    "slug": "string",
+    "category_id": "number (opcional)",
+    "color": "#hexadecimal (opcional)",
+    "icon": "string (opcional)",
+    "status": "active|inactive (opcional)",
+    "locale": {
+      "en": { "name": "string" },
+      "pt": { "name": "string" },
+      ...
+    }
+  }
+  ```
+- **Resposta:** Objeto da categoria criada.
+- **Erros comuns:**
+  - 400 Bad Request: Dados inválidos, locale ausente, categoria pai não encontrada.
+
+---
+
+#### PATCH `/category/:id`
+
+- **Autenticação:** Necessária (roles: admin, admin-category)
+- **Parâmetros:**
+  - `id` (number, obrigatório): ID da categoria.
+- **Body:** Campos parciais do objeto de criação (mesma estrutura do POST, todos opcionais).
+- **Resposta:** Objeto da categoria atualizada.
+- **Erros comuns:**
+  - 400 Bad Request: Categoria pai não encontrada, locale inválido.
+  - 404 Not Found: Categoria não encontrada.
+
+---
+
+#### DELETE `/category/:id`
+
+- **Autenticação:** Necessária (roles: admin, admin-category)
+- **Parâmetros:**
+  - `id` (number, obrigatório): ID da categoria.
+- **Resposta:** Objeto da categoria deletada.
+- **Erros comuns:**
+  - 404 Not Found: Categoria não encontrada.
+
+## 4. Regras de autenticação e autorização
+
+- Todos os endpoints requerem autenticação.
+- Acesso restrito a usuários com roles `admin` ou `admin-category`.
+- Controle de acesso definido via roles no arquivo `hedhog/data/role.yaml`.
+
+## 5. Estruturas de request/response
+
+### CategoryDTO (para criação e atualização)
+
+```ts
+{
+  slug: string; // obrigatório, string não vazia
+  category_id?: number; // opcional, ID da categoria pai
+  color?: string; // opcional, cor hexadecimal (#RRGGBB ou #RGB)
+  icon?: string; // opcional, string representando ícone
+  status?: 'active' | 'inactive'; // opcional, status da categoria
+  locale: { // obrigatório, objeto com chaves de código de idioma
+    [localeCode: string]: {
+      name: string; // nome da categoria no idioma
+    }
+  }
+}
+```
+
+### Resposta padrão de categoria
+
+Inclui campos:
+
+- `id`: número identificador
+- `slug`: string
+- `icon`: string ou null
+- `color`: string (hexadecimal)
+- `category_id`: número ou null (categoria pai)
+- `status`: 'active' | 'inactive'
+- `category_locale`: array com traduções (nome e locale_id)
+- `created_at`, `updated_at`: timestamps
+
+## 6. Erros comuns
+
+- **400 Bad Request**
+  - Locale inválido ou não encontrado.
+  - Dados obrigatórios ausentes (ex: slug, locale).
+  - Categoria pai referenciada não existe.
+  - Formato inválido para campos (ex: cor não hexadecimal).
+- **404 Not Found**
+  - Categoria não encontrada para o ID informado.
+  - Categoria pai não encontrada.
+  - Nenhuma categoria filha encontrada para o pai informado.
+
+## 7. Banco de dados (tabelas YAML)
+
+### Tabela `category`
+
+Finalidade: Armazenar categorias com hierarquia, status e atributos visuais.
+
+```yaml
+columns:
+  - type: pk
+  - type: slug
+  - name: icon
+    isNullable: true
+  - name: color
+    isNullable: true
+    default: '#000000'
+  - name: category_id
+    type: fk
+    isNullable: true
+    references:
+      table: category
+      column: id
+      onDelete: CASCADE
+  - name: status
+    type: enum
+    isNullable: true
+    values: [active, inactive]
+    default: active
+  - name: name
+    type: locale_varchar
+    length: 255
+    locale:
+      en: Name
+      pt: Nome
+  - type: created_at
+  - type: updated_at
+```
+
+- **Colunas:**
+  - `id` (PK): Identificador único.
+  - `slug`: Identificador textual único da categoria.
+  - `icon`: Ícone opcional da categoria.
+  - `color`: Cor hexadecimal, padrão `#000000`.
+  - `category_id`: FK para categoria pai, nullable, com deleção em cascata.
+  - `status`: Enum `active` ou `inactive`, padrão `active`.
+  - `name`: Campo localizado para o nome da categoria.
+  - `created_at`, `updated_at`: Timestamps automáticos.
+
+- **Defaults:**
+  - `color`: `#000000`
+  - `status`: `active`
+
+- **Nulabilidade:**
+  - `icon` e `category_id` são opcionais (nullable).
+  - Outros campos obrigatórios conforme tipo.
+
+- **Integridade:**
+  - FK `category_id` referencia `category.id` com `onDelete: CASCADE`.
+  - `slug` deve ser único (implícito pelo tipo slug).
+
+- **Índices:**
+  - Índice primário em `id`.
+  - Índice único em `slug` (implícito).
+
+- **Enums:**
+  - `status`: valores possíveis `active`, `inactive`.
+
+## 8. Regras de negócio relevantes
+
+- Categorias podem ser hierárquicas, com categorias pai opcionais.
+- Apenas categorias com status `active` são retornadas em listagens raiz.
+- Ao criar ou atualizar, é obrigatório informar pelo menos uma localização válida.
+- Atualizações de localizações são feitas por idioma, criando ou atualizando registros conforme necessário.
+- Exclusão de categoria remove também suas categorias filhas devido à regra de deleção em cascata.
+- Filtros de listagem permitem busca insensível por slug, status e categoria pai.
+- Paginação é aplicada nas listagens para controle de volume de dados.
+
+## 9. Guia rápido de uso (exemplos)
+
+### Criar categoria
+
+```http
+POST /category
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "slug": "eletronicos",
+  "color": "#FF0000",
+  "icon": "tv",
+  "status": "active",
+  "locale": {
+    "en": { "name": "Electronics" },
+    "pt": { "name": "Eletrônicos" }
+  }
+}
+```
+
+### Atualizar categoria
+
+```http
+PATCH /category/1
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "color": "#00FF00",
+  "locale": {
+    "pt": { "name": "Eletrônicos Atualizados" }
+  }
+}
+```
+
+### Listar categorias raiz
+
+```http
+GET /category/root?locale=pt
+Authorization: Bearer <token>
+```
+
+### Obter estatísticas
+
+```http
+GET /category/stats
+Authorization: Bearer <token>
+```
+
+### Buscar categorias com filtro e paginação
+
+```http
+GET /category?status=active&parent=root&page=1&limit=10&locale=pt
+Authorization: Bearer <token>
+```
+
+### Deletar categoria
+
+```http
+DELETE /category/1
+Authorization: Bearer <token>
+```
+
+---
+
+Este módulo é essencial para a organização e categorização dos conteúdos e produtos no sistema HedHog, garantindo flexibilidade e suporte multilíngue com controle de acesso robusto.

package/package.json

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