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

  {
    "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)

{
  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.

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

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

PATCH /category/1
Authorization: Bearer <token>
Content-Type: application/json

{
  "color": "#00FF00",
  "locale": {
    "pt": { "name": "Eletrônicos Atualizados" }
  }
}

Listar categorias raiz

GET /category/root?locale=pt
Authorization: Bearer <token>

Obter estatísticas

GET /category/stats
Authorization: Bearer <token>

Buscar categorias com filtro e paginação

GET /category?status=active&parent=root&page=1&limit=10&locale=pt
Authorization: Bearer <token>

Deletar categoria

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.