npm package: @hed-hog/category
Description: ```markdown # @hed-hog/category
Latest version: 0.0.303

```markdown
# @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 (roles: admin, admin-category) | Retorna categorias raiz ativas no idioma solicitado. |
| GET    | `/category/stats`          | Autenticada (roles: admin, admin-category) | Retorna estatísticas gerais das categorias.      |
| GET    | `/category/:id`            | Autenticada (roles: admin, admin-category) | Retorna categoria pelo ID com localizações.      |
| GET    | `/category/parent/:categoryId` | Autenticada (roles: admin, admin-category) | Retorna categorias filhas de uma categoria pai.  |
| GET    | `/category`                | Autenticada (roles: admin, admin-category) | Lista categorias com paginação, filtro por status e categoria pai. |
| POST   | `/category`                | Autenticada (roles: admin, admin-category) | Cria uma nova categoria com localizações.        |
| PATCH  | `/category/:id`            | Autenticada (roles: admin, admin-category) | Atualiza uma categoria existente parcialmente.   |
| DELETE | `/category/:id`            | Autenticada (roles: admin, admin-category) | Remove uma categoria pelo ID.                      |

---

### Detalhes dos endpoints

#### GET `/category/root`

- **Autenticação:** Necessária (roles: admin, admin-category)
- **Query:** 
  - `locale` (string, obrigatório) — código do idioma para as localizações.
- **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.
- **Query:** 
  - `locale` (string, obrigatório) — código do idioma para as localizações.
- **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.
- **Query:** 
  - `locale` (string, obrigatório) — código do idioma para as localizações.
- **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:**
  - `locale` (string, obrigatório) — código do idioma para as localizações.
  - `status` (string, opcional): Filtra por status (`active`, `inactive`, `all`).
  - `parent` (string, opcional): Filtra por categoria pai (`slug`, `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.
```