@hed-hog/tag 0.0.270 → 0.0.273

package/README.md

@@ -0,0 +1,342 @@
+# @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 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.

package/package.json

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