@hed-hog/content 0.0.270 → 0.0.274

package/README.md

@@ -0,0 +1,397 @@
+# @hed-hog/content
+
+## 1. Visão geral do módulo
+
+O módulo `@hed-hog/content` é responsável pela gestão de conteúdos multilíngues no sistema HedHog. Ele oferece funcionalidades para criação, leitura, atualização e exclusão (CRUD) de conteúdos, suportando múltiplos idiomas e controle de status (rascunho ou publicado). O módulo integra-se com serviços de paginação, localização e persistência via Prisma.
+
+## 2. Escopo e responsabilidades
+
+- Gerenciar conteúdos com suporte a múltiplos idiomas.
+- Controlar status dos conteúdos (`draft` ou `published`).
+- Fornecer estatísticas gerais sobre os conteúdos.
+- Aplicar paginação e filtros nas listagens.
+- Garantir validação e integridade dos dados.
+- Restringir acesso via roles específicas.
+
+## 3. Endpoints
+
+| Método | Path           | Autenticação | Descrição                              |
+|--------|----------------|--------------|--------------------------------------|
+| GET    | /content/stats | Autenticada  | Retorna estatísticas gerais dos conteúdos. |
+| GET    | /content/:id   | Autenticada  | Retorna conteúdo específico pelo ID, com dados multilíngues. |
+| GET    | /content       | Autenticada  | Lista conteúdos com paginação e filtros. |
+| POST   | /content       | Autenticada  | Cria um novo conteúdo multilíngue.  |
+| PATCH  | /content/:id   | Autenticada  | Atualiza conteúdo existente pelo ID. |
+| DELETE | /content/:id   | Autenticada  | Remove conteúdo pelo ID.              |
+
+### Detalhes dos endpoints
+
+---
+
+#### GET /content/stats
+
+- **Autenticação:** Requer role `admin`.
+- **Descrição:** Retorna estatísticas gerais dos conteúdos, incluindo total, total publicados, total em rascunho e total de idiomas habilitados.
+- **Parâmetros:** Nenhum.
+- **Resposta:**
+  ```json
+  {
+    "total": number,
+    "totalPublished": number,
+    "totalDraft": number,
+    "totalEnabledLanguages": number
+  }
+  ```
+- **Erros comuns:** Nenhum específico.
+
+---
+
+#### GET /content/:id
+
+- **Autenticação:** Requer role `admin`.
+- **Descrição:** Busca um conteúdo pelo seu ID, retornando dados básicos e traduções disponíveis.
+- **Parâmetros:**
+  - `id` (path, number): ID do conteúdo.
+  - Header `Locale`: Código do idioma para mensagens de erro.
+- **Resposta:**
+  ```json
+  {
+    "id": number,
+    "slug": string,
+    "status": "draft" | "published",
+    "created_at": string,
+    "updated_at": string,
+    "locales": {
+      "<locale_code>": {
+        "title": string,
+        "body": string
+      },
+      ...
+    }
+  }
+  ```
+- **Erros:**
+  - `404 Not Found`: Conteúdo não encontrado.
+
+---
+
+#### GET /content
+
+- **Autenticação:** Requer role `admin`.
+- **Descrição:** Lista conteúdos com paginação, filtro por status e busca insensível por slug.
+- **Query Parameters:**
+  - `page` (number, opcional): Página atual.
+  - `limit` (number, opcional): Itens por página.
+  - `status` (string, opcional): Filtra por status (`draft`, `published`, `all`).
+  - `search` (string, opcional): Termo para busca insensível no slug.
+- **Header:** `Locale` para idioma das mensagens.
+- **Resposta:**
+  ```json
+  {
+    "data": [
+      {
+        "id": number,
+        "slug": string,
+        "status": "draft" | "published",
+        "created_at": string,
+        "updated_at": string,
+        "title": string,
+        "body": string,
+        "available_locales": [
+          {
+            "id": number,
+            "code": string,
+            "name": string
+          },
+          ...
+        ]
+      },
+      ...
+    ],
+    "meta": {
+      "totalItems": number,
+      "itemCount": number,
+      "itemsPerPage": number,
+      "totalPages": number,
+      "currentPage": number
+    }
+  }
+  ```
+- **Erros:**
+  - `400 Bad Request`: Locale inválido ou não encontrado.
+
+---
+
+#### POST /content
+
+- **Autenticação:** Requer role `admin`.
+- **Descrição:** Cria um novo conteúdo com dados multilíngues.
+- **Body:**
+  ```json
+  {
+    "slug": "string",
+    "status": "draft" | "published",
+    "locale": {
+      "<locale_code>": {
+        "title": "string",
+        "body": "string"
+      },
+      ...
+    }
+  }
+  ```
+- **Header:** `Locale` para idioma das mensagens.
+- **Resposta:** Objeto do conteúdo criado (id, slug, status, timestamps).
+- **Erros:**
+  - `400 Bad Request`: Slug já existe.
+  - `400 Bad Request`: Dados de locale ausentes ou inválidos.
+  - `400 Bad Request`: Locale não encontrado.
+
+---
+
+#### PATCH /content/:id
+
+- **Autenticação:** Requer role `admin`.
+- **Descrição:** Atualiza um conteúdo existente, incluindo dados multilíngues.
+- **Parâmetros:**
+  - `id` (path, number): ID do conteúdo.
+- **Body:** Campos parciais do conteúdo, exemplo:
+  ```json
+  {
+    "slug": "string",
+    "status": "draft" | "published",
+    "locale": {
+      "<locale_code>": {
+        "title": "string",
+        "body": "string"
+      },
+      ...
+    }
+  }
+  ```
+- **Header:** `Locale` para idioma das mensagens.
+- **Resposta:** Objeto do conteúdo atualizado.
+- **Erros:**
+  - `404 Not Found`: Conteúdo não encontrado.
+  - `400 Bad Request`: Locale não encontrado.
+
+---
+
+#### DELETE /content/:id
+
+- **Autenticação:** Requer role `admin`, `admin-access` ou `admin-content`.
+- **Descrição:** Remove conteúdo pelo ID.
+- **Parâmetros:**
+  - `id` (path, number): ID do conteúdo.
+- **Header:** `Locale` para idioma das mensagens.
+- **Resposta:** Objeto do conteúdo deletado.
+- **Erros:**
+  - `404 Not Found`: Conteúdo não encontrado.
+
+## 4. Regras de autenticação e autorização
+
+- Todos os endpoints requerem autenticação.
+- Roles necessárias:
+  - `admin` para a maioria das operações.
+  - `admin-access` e `admin-content` também autorizados para exclusão.
+- Controle de acesso baseado em roles definido no arquivo `hedhog/data/route.yaml`.
+
+## 5. Estruturas de request/response
+
+### ContentCreateDTO
+
+```ts
+{
+  slug: string; // obrigatório, string
+  status: 'draft' | 'published'; // obrigatório, enum
+  locale: {
+    [localeCode: string]: {
+      title: string;
+      body: string;
+    }
+  }; // obrigatório, objeto com dados multilíngues
+}
+```
+
+### ContentUpdateDTO
+
+- Mesma estrutura do `ContentCreateDTO`, porém todos os campos são opcionais (partial).
+
+### Resposta de conteúdo individual
+
+```ts
+{
+  id: number;
+  slug: string;
+  status: 'draft' | 'published';
+  created_at: string;
+  updated_at: string;
+  locales: {
+    [localeCode: string]: {
+      title: string;
+      body: string;
+    }
+  };
+}
+```
+
+### Resposta de listagem paginada
+
+```ts
+{
+  data: Array<{
+    id: number;
+    slug: string;
+    status: 'draft' | 'published';
+    created_at: string;
+    updated_at: string;
+    title: string;
+    body: string;
+    available_locales: Array<{
+      id: number;
+      code: string;
+      name: string;
+    }>;
+  }>;
+  meta: {
+    totalItems: number;
+    itemCount: number;
+    itemsPerPage: number;
+    totalPages: number;
+    currentPage: number;
+  };
+}
+```
+
+## 6. Erros comuns
+
+| Código | Mensagem                         | Causa comum                              |
+|--------|---------------------------------|-----------------------------------------|
+| 400    | Locale não encontrado            | Código de idioma inválido ou não habilitado. |
+| 400    | Conteúdo com este slug já existe | Tentativa de criar conteúdo com slug duplicado. |
+| 400    | Dados de locale são obrigatórios | Falta de dados multilíngues no payload. |
+| 404    | Conteúdo não encontrado          | ID informado não existe no banco.       |
+
+## 7. Banco de dados (tabelas YAML)
+
+### Tabela `content`
+
+Finalidade: Armazenar conteúdos multilíngues com status e timestamps.
+
+```yaml
+columns:
+  - type: pk
+  - type: slug
+  - name: status
+    type: enum
+    values: [draft, published]
+  - name: title
+    type: locale_varchar
+    locale:
+      en: Title
+      pt: Título
+  - name: body
+    type: locale_text
+    locale:
+      en: Body
+      pt: Corpo
+  - type: created_at
+  - type: updated_at
+```
+
+- **Colunas:**
+  - `id` (PK, auto-incremento)
+  - `slug` (string, único)
+  - `status` (enum: `draft` ou `published`)
+  - `title` (campo multilíngue varchar)
+  - `body` (campo multilíngue texto)
+  - `created_at` (timestamp)
+  - `updated_at` (timestamp)
+- **Defaults:** `created_at` e `updated_at` gerenciados automaticamente.
+- **Nulabilidade:** `slug`, `status`, `title` e `body` não nulos.
+- **Integridade:** `slug` único.
+- **Índices:** Índice primário em `id`, índice único em `slug`.
+- **Enums:** `status` com valores `draft` e `published`.
+
+## 8. Regras de negócio relevantes
+
+- Slug deve ser único para cada conteúdo.
+- Conteúdos podem estar em múltiplos idiomas, cada um com título e corpo.
+- Status controla visibilidade: `draft` para rascunho, `published` para conteúdo ativo.
+- Ao criar ou atualizar, deve-se validar existência dos idiomas informados.
+- Exclusão só é permitida para usuários com roles específicas.
+- Paginação e busca são insensíveis a maiúsculas/minúsculas no campo slug.
+- Mensagens de erro são localizadas conforme o header `Locale`.
+
+## 9. Guia rápido de uso (exemplos)
+
+### Criar conteúdo
+
+```http
+POST /content
+Authorization: Bearer <token>
+Content-Type: application/json
+Locale: pt
+
+{
+  "slug": "exemplo-conteudo",
+  "status": "draft",
+  "locale": {
+    "pt": {
+      "title": "Título Exemplo",
+      "body": "Corpo do conteúdo em português."
+    },
+    "en": {
+      "title": "Example Title",
+      "body": "Content body in English."
+    }
+  }
+}
+```
+
+### Atualizar conteúdo
+
+```http
+PATCH /content/1
+Authorization: Bearer <token>
+Content-Type: application/json
+Locale: pt
+
+{
+  "status": "published",
+  "locale": {
+    "pt": {
+      "title": "Título Atualizado",
+      "body": "Corpo atualizado."
+    }
+  }
+}
+```
+
+### Listar conteúdos com filtro e paginação
+
+```http
+GET /content?status=published&page=1&limit=10&search=exemplo
+Authorization: Bearer <token>
+Locale: en
+```
+
+### Obter conteúdo por ID
+
+```http
+GET /content/1
+Authorization: Bearer <token>
+Locale: pt
+```
+
+### Deletar conteúdo
+
+```http
+DELETE /content/1
+Authorization: Bearer <token>
+Locale: pt
+```
+
+---
+
+Este módulo é fundamental para a gestão de conteúdos multilíngues no HedHog, garantindo flexibilidade, segurança e organização na administração dos textos exibidos nas aplicações.

package/package.json

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