# @hed-hog/tag

## 1. Visão geral do módulo

O módulo `@hed-hog/tag` é responsável pela gestão de tags dentro do ecossistema HedHog. Ele oferece funcionalidades para criação, leitura, atualização, exclusão e estatísticas de tags, que são identificadas por um slug único, possuem uma cor e um status (ativo ou inativo). O módulo é construído com NestJS e utiliza Prisma para acesso ao banco de dados.

## 2. Escopo e responsabilidades

- Gerenciar tags com atributos: slug, cor e status.
- Fornecer endpoints para CRUD (Create, Read, Update, Delete) de tags.
- Permitir paginação e busca simples por slug.
- Disponibilizar estatísticas básicas sobre as tags (total, ativas, inativas).
- Garantir validação e integridade dos dados.
- Controlar acesso via roles específicas.

## 3. Endpoints

### Listar tags

- **Método:** GET  
- **Path:** `/tag`  
- **Autenticação:** Requer role `admin` ou `admin-tag`  
- **Descrição:** Retorna uma lista paginada de tags, com opção de busca parcial e case-insensitive por slug.  
- **Query Parameters:**  
  - `skip` (number): quantidade de registros a pular (para paginação)  
  - `take` (number): quantidade de registros a retornar  
  - `search` (string, opcional): termo para busca parcial no slug  
- **Resposta:**  
  ```json
  {
    "data": [
      {
        "id": number,
        "slug": string,
        "color": string,
        "status": "active" | "inactive",
        "created_at": string,
        "updated_at": string
      },
      ...
    ],
    "total": number,
    "page": number,
    "pageSize": number,
    "prev": number | null,
    "next": number | null,
    "lastPage": number
  }

• Erros:
  • 401 Unauthorized (se não autenticado ou sem permissão)

Obter estatísticas de tags

• Método: GET
• Path: /tag/stats
• Autenticação: Requer role admin ou admin-tag
• Descrição: Retorna contagem total de tags, tags ativas e inativas.
• Resposta:

  {
    "total": number,
    "active": number,
    "inactive": number
  }

• Erros:
  • 401 Unauthorized

Obter tag por ID

• Método: GET
• Path: /tag/:id
• Autenticação: Requer role admin ou admin-tag
• Descrição: Retorna os dados da tag identificada pelo ID.
• Parâmetros:
  • id (number): ID da tag
• Resposta:

  {
    "id": number,
    "slug": string,
    "color": string,
    "status": "active" | "inactive",
    "created_at": string,
    "updated_at": string
  }

• Erros:
  • 400 Bad Request: Tag não encontrada
  • 401 Unauthorized

Criar nova tag

• Método: POST
• Path: /tag
• Autenticação: Requer role admin ou admin-tag
• Descrição: Cria uma nova tag com os dados fornecidos.
• Body:

  {
    "slug": "string",
    "color": "#RRGGBB ou #RGB",
    "status": "active" | "inactive" (opcional, padrão "active")
  }

• Resposta:
  Objeto da tag criada com todos os campos preenchidos.
• Erros:
  • 400 Bad Request: Formato inválido de cor ou dados inválidos
  • 401 Unauthorized

Atualizar tag existente

• Método: PATCH
• Path: /tag/:id
• Autenticação: Requer role admin ou admin-tag
• Descrição: Atualiza parcialmente os dados da tag identificada pelo ID.
• Parâmetros:
  • id (number): ID da tag
• Body:

  {
    "slug"?: "string",
    "color"?: "#RRGGBB ou #RGB",
    "status"?: "active" | "inactive"
  }

• Resposta:
  Objeto da tag atualizado.
• Erros:
  • 400 Bad Request: Tag não encontrada ou dados inválidos
  • 401 Unauthorized

Deletar tag

• Método: DELETE
• Path: /tag/:id
• Autenticação: Requer role admin ou admin-tag
• Descrição: Remove a tag identificada pelo ID.
• Parâmetros:
  • id (number): ID da tag
• Resposta:
  Objeto da tag deletada.
• Erros:
  • 400 Bad Request: Tag não encontrada
  • 401 Unauthorized

4. Regras de autenticação e autorização

• Todos os endpoints requerem autenticação.
• Acesso restrito a usuários com roles admin ou admin-tag.
• Roles definidas no sistema HedHog:
  • admin-tag: Administrador com acesso total à gestão de tags.

5. Estruturas de request/response

TagDTO (Request Body para criação e atualização)

| Campo | Tipo | Obrigatório | Descrição | |--------|----------------------|-------------|----------------------------------| | slug | string | Sim | Identificador único da tag | | color | string (hexadecimal) | Sim | Cor da tag no formato #RGB ou #RRGGBB | | status | enum (active, inactive) | Não (default active) | Status da tag |

Resposta de tag

| Campo | Tipo | Descrição | |------------|----------------------|----------------------------------| | id | number | Identificador único da tag | | slug | string | Identificador único da tag | | color | string | Cor da tag | | status | enum (active, inactive) | Status da tag | | created_at | string (timestamp) | Data de criação | | updated_at | string (timestamp) | Data da última atualização |

6. Erros comuns

| Código | Mensagem | Causa provável | |--------|---------------------------------|---------------------------------------------| | 400 | Tag not found | ID informado não corresponde a nenhuma tag | | 400 | Invalid color format | Cor informada não está no formato hexadecimal válido (#RGB ou #RRGGBB) | | 401 | Unauthorized | Usuário não autenticado ou sem permissão | | 422 | Validation errors (ex: slug must be string) | Dados enviados não passaram na validação do DTO |

7. Banco de dados (tabelas YAML)

Tabela tag

• Finalidade: Armazenar tags com slug, cor e status para categorização e marcação de conteúdos.
• Colunas:

| Nome | Tipo | Nullable | Default | Descrição | |------------|---------------|----------|----------|--------------------------------| | id | Primary Key | Não | - | Identificador único da tag | | slug | Slug (string) | Não | - | Identificador textual único | | color | string | Não | - | Cor da tag em formato hexadecimal (#RGB ou #RRGGBB) | | status | enum | Sim | active | Status da tag: active ou inactive | | created_at | timestamp | Não | - | Data de criação | | updated_at | timestamp | Não | - | Data da última atualização |

• Integridade:
  • slug deve ser único (imposto pelo tipo slug).
  • status é enum com valores permitidos active e inactive.
• Índices:
  • Índice primário em id.
• Enums:
  • status: active, inactive.

8. Regras de negócio relevantes

• O campo color deve estar no formato hexadecimal válido, aceitando tanto 3 dígitos (#RGB) quanto 6 dígitos (#RRGGBB). Caso contrário, retorna erro 400.
• O campo status é opcional na criação e atualização, assumindo active como padrão.
• A busca na listagem é feita por correspondência parcial e case-insensitive no campo slug.
• Exclusão, atualização e consulta por ID retornam erro 400 caso a tag não exista.
• Paginação é suportada via parâmetros skip e take, com informações de página atual, anterior, próxima e última página retornadas.

9. Guia rápido de uso (exemplos)

Listar tags com paginação e busca

GET /tag?skip=0&take=10&search=tech
Authorization: Bearer <token>

Resposta:

{
  "data": [
    { "id": 1, "slug": "technology", "color": "#ff0000", "status": "active", "created_at": "...", "updated_at": "..." }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 10,
  "prev": null,
  "next": null,
  "lastPage": 1
}

Criar uma nova tag

POST /tag
Authorization: Bearer <token>
Content-Type: application/json

{
  "slug": "news",
  "color": "#00ff00",
  "status": "active"
}

Resposta:

{
  "id": 2,
  "slug": "news",
  "color": "#00ff00",
  "status": "active",
  "created_at": "...",
  "updated_at": "..."
}

Atualizar uma tag

PATCH /tag/2
Authorization: Bearer <token>
Content-Type: application/json

{
  "color": "#0000ff"
}

Resposta:

{
  "id": 2,
  "slug": "news",
  "color": "#0000ff",
  "status": "active",
  "created_at": "...",
  "updated_at": "..."
}

Deletar uma tag

DELETE /tag/2
Authorization: Bearer <token>

Resposta:

{
  "id": 2,
  "slug": "news",
  "color": "#0000ff",
  "status": "active",
  "created_at": "...",
  "updated_at": "..."
}

Obter estatísticas de tags

GET /tag/stats
Authorization: Bearer <token>

Resposta:

{
  "total": 10,
  "active": 8,
  "inactive": 2
}

Este módulo é parte integrante do monorepo HedHog e deve ser utilizado conforme as regras de autenticação e autorização definidas.