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

```markdown
# @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:**  
  ```json
  {
    "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:**  
  ```json
  {
    "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:**  
  ```json
  {
    "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:**  
  ```json
  {
    "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

```http
GET /tag?skip=0&take=10&search=tech
Authorization: Bearer <token>
```

Resposta:

```json
{
  "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

```http
POST /tag
Authorization: Bearer <token>
Content-Type: application/json

{
  "slug": "news",
  "color": "#00ff00",
  "status": "active"
}
```

Resposta:

```json
{
  "id": 2,
  "slug": "news",
  "color": "#00ff00",
  "status": "active",
  "created_at": "...",
  "updated_at": "..."
}
```

---

### Atualizar uma tag

```http
PATCH /tag/2
Authorization: Bearer <token>
Content-Type: application/json

{
  "color": "#0000ff"
}
```

Resposta:

```json
{
  "id": 2,
  "slug": "news",
  "color": "#0000ff",
  "status": "active",
  "created_at": "...",
  "updated_at": "..."
}
```

---

### Deletar uma tag

```http
DELETE /tag/2
Authorization: Bearer <token>
```

Resposta:

```json
{
  "id": 2,
  "slug": "news",
  "color": "#0000ff",
  "status": "active",
  "created_at": "...",
  "updated_at": "..."
}
```

---

### Obter estatísticas de tags

```http
GET /tag/stats
Authorization: Bearer <token>
```

Resposta:

```json
{
  "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.
```