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

```markdown
# @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 (role `admin`)                     | Retorna estatísticas gerais dos conteúdos. |
| GET    | /content/:id   | Autenticada (role `admin`)                     | Retorna conteúdo específico pelo ID, com dados multilíngues. |
| GET    | /content       | Autenticada (role `admin`)                     | Lista conteúdos com paginação e filtros. |
| POST   | /content       | Autenticada (role `admin`)                     | Cria um novo conteúdo multilíngue.  |
| PATCH  | /content/:id   | Autenticada (role `admin`)                     | Atualiza conteúdo existente pelo ID. |
| DELETE | /content/:id   | Autenticada (roles `admin`, `admin-access` ou `admin-content`) | 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 roles `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 (`admin`, `admin-access`, `admin-content`).
- 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`.
- Na atualização, se o conteúdo multilíngue para um idioma existir, ele é atualizado; caso contrário, é criado.
- Na listagem, o conteúdo retorna título e corpo conforme o idioma do header `Locale`, além das localidades disponíveis.

## 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.
```