# @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:

  {
    "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:

  {
    "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:

  {
    "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:

  {
    "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

{
  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

{
  id: number;
  slug: string;
  status: 'draft' | 'published';
  created_at: string;
  updated_at: string;
  locales: {
    [localeCode: string]: {
      title: string;
      body: string;
    }
  };
}

Resposta de listagem paginada

{
  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.

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

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

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

GET /content?status=published&page=1&limit=10&search=exemplo
Authorization: Bearer <token>
Locale: en

Obter conteúdo por ID

GET /content/1
Authorization: Bearer <token>
Locale: pt

Deletar conteúdo

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.