# @hed-hog/contact-us

## 1. Visão geral do módulo

O módulo `@hed-hog/contact-us` é responsável pela gestão das mensagens enviadas pelos usuários através do formulário "Contact Us". Ele permite o envio, consulta, atualização de status, resposta e exclusão dessas mensagens, além de fornecer estatísticas e configurações relacionadas ao contato.

## 2. Escopo e responsabilidades

- Receber mensagens de contato enviadas por usuários (público).
- Listar, consultar, atualizar status, responder e excluir mensagens (restrito a administradores).
- Enviar notificações por e-mail para o usuário e para o time responsável.
- Fornecer estatísticas sobre as mensagens recebidas.
- Disponibilizar configurações relacionadas ao contato.

## 3. Endpoints

### GET /contact-us/settings

- **Método:** GET  
- **Autenticação:** Pública  
- **Descrição:** Retorna as configurações relacionadas ao contato, como telefone e e-mail de contato.  
- **Parâmetros:** Nenhum  
- **Resposta:**  
  ```json
  {
    "contact-us-phone": "string",
    "contact-us-email": "string"
  }

• Erros: Nenhum específico.

GET /contact-us/stats

• Método: GET
• Autenticação: Requer papel admin ou admin-contact-us
• Descrição: Retorna estatísticas das mensagens de contato, incluindo totais por status.
• Parâmetros: Nenhum
• Resposta:

  {
    "total": number,
    "totalNew": number,
    "totalResponded": number,
    "totalProgress": number,
    "totalArchived": number
  }

• Erros: Nenhum específico.

GET /contact-us/:id

• Método: GET
• Autenticação: Requer papel admin ou admin-contact-us
• Descrição: Retorna os detalhes de uma mensagem de contato pelo seu ID.
• Parâmetros:
  • id (path): número inteiro identificador da mensagem.
• Resposta:

  {
    "id": number,
    "name": "string",
    "email": "string",
    "message": "string",
    "response": "string | null",
    "status": "new" | "progress" | "answered" | "archived",
    "created_at": "string (datetime)",
    "updated_at": "string (datetime)",
    "response_at": "string (datetime) | null",
    "user_id": number | null,
    "response_id": number | null,
    "user_contact_us_response_idTouser": object,
    "user_contact_us_user_idTouser": object
  }

• Erros:
  • 404 Not Found: Mensagem não encontrada.

GET /contact-us

• Método: GET
• Autenticação: Requer papel admin ou admin-contact-us
• Descrição: Lista mensagens de contato com paginação e filtro opcional por status e busca textual.
• Query Parameters:
  • status (string, opcional): filtro por status (new, progress, answered, archived, all).
  • Parâmetros de paginação via @hed-hog/api-pagination (ex: take, skip, search).
• Resposta:

  {
    "data": [
      {
        "id": number,
        "name": "string",
        "email": "string",
        "message": "string",
        "response": "string | null",
        "status": "new" | "progress" | "answered" | "archived",
        "created_at": "string (datetime)",
        "updated_at": "string (datetime)",
        "response_at": "string (datetime) | null",
        "user_id": number | null,
        "response_id": number | null
      }
    ],
    "total": number,
    "page": number,
    "pageSize": number,
    "prev": number | null,
    "next": number | null,
    "lastPage": number
  }

• Erros: Nenhum específico.

DELETE /contact-us/:id

• Método: DELETE
• Autenticação: Requer papel admin ou admin-contact-us
• Descrição: Exclui uma mensagem de contato pelo seu ID.
• Parâmetros:
  • id (path): número inteiro identificador da mensagem.
• Resposta: Objeto da mensagem excluída (mesma estrutura do objeto mensagem).
• Erros:
  • 404 Not Found: Mensagem não encontrada.

PATCH /contact-us/status/:id

• Método: PATCH
• Autenticação: Requer papel admin ou admin-contact-us
• Descrição: Atualiza o status de uma mensagem de contato.
• Parâmetros:
  • id (path): número inteiro identificador da mensagem.
• Body:

  {
    "status": "new" | "progress" | "answered" | "archived"
  }

• Resposta: Objeto da mensagem atualizada (mesma estrutura do objeto mensagem).
• Erros:
  • 404 Not Found: Mensagem não encontrada.
  • 400 Bad Request: Status inválido.

POST /contact-us/response/:id

• Método: POST
• Autenticação: Requer papel admin ou admin-contact-us
• Descrição: Envia uma resposta para uma mensagem de contato e notifica o usuário por e-mail.
• Parâmetros:
  • id (path): número inteiro identificador da mensagem.
• Body:

  {
    "response": "string"
  }

• Resposta: Texto da resposta enviada.
• Erros:
  • 404 Not Found: Mensagem não encontrada.
  • 400 Bad Request: Resposta inválida.

POST /contact-us

• Método: POST
• Autenticação: Pública
• Descrição: Cria uma nova mensagem de contato.
• Body:

  {
    "name": "string",
    "email": "string (email válido)",
    "message": "string"
  }

• Resposta: Objeto da mensagem criada (mesma estrutura do objeto mensagem).
• Erros:
  • 400 Bad Request: E-mail inválido ou dados inválidos.

4. Regras de autenticação e autorização

• Endpoints de listagem, consulta, atualização, resposta e exclusão requerem autenticação com papel admin ou admin-contact-us.
• Endpoints de criação de mensagem e obtenção de configurações são públicos.
• O papel admin-contact-us é um administrador com acesso total à gestão de mensagens de contato.

5. Estruturas de request/response

ContactUsSendDTO (criação de mensagem)

{
  name: string; // obrigatório, string
  email: string; // obrigatório, email válido
  message: string; // obrigatório, string
}

ContactUsResponseDTO (resposta a mensagem)

{
  response: string; // obrigatório, string
}

ContactUsStatusDTO (atualização de status)

{
  status: 'new' | 'progress' | 'answered' | 'archived'; // obrigatório, enum válido
}

Resposta padrão de listagem

{
  data: ContactUsMessage[],
  total: number,
  page: number,
  pageSize: number,
  prev: number | null,
  next: number | null,
  lastPage: number
}

ContactUsMessage (exemplo de objeto mensagem)

{
  id: number,
  name: string,
  email: string,
  message: string,
  response?: string | null,
  status: 'new' | 'progress' | 'answered' | 'archived',
  created_at: string (datetime),
  updated_at: string (datetime),
  response_at?: string | null,
  user_id?: number | null,
  response_id?: number | null,
  user_contact_us_response_idTouser?: object,
  user_contact_us_user_idTouser?: object
}

6. Erros comuns

• 404 Not Found: Mensagem de contato não encontrada para o ID informado.
• 400 Bad Request: Dados inválidos, como e-mail mal formatado ou status inválido.
• 401 Unauthorized / 403 Forbidden: Acesso negado para endpoints restritos sem o papel adequado.

7. Banco de dados (tabela contact_us)

finalidade: Armazenar mensagens enviadas pelo formulário "Contact Us" e suas respostas.

colunas:
  - id: primary key (auto-increment)
  - name: string, não nulo
  - email: string, não nulo
  - message: text, não nulo
  - response: text, nulo permitido
  - status: enum ['new', 'progress', 'answered', 'archived'], padrão 'new', não nulo
  - response_at: datetime, nulo permitido
  - user_id: foreign key para user.id, nulo permitido, onDelete CASCADE
  - response_id: foreign key para user.id, nulo permitido, onDelete SET NULL
  - created_at: datetime, não nulo, timestamp de criação
  - updated_at: datetime, não nulo, timestamp de atualização

defaults:
  - status: 'new'

nulabilidade:
  - response: nullable
  - response_at: nullable
  - user_id: nullable
  - response_id: nullable

integridade:
  - user_id referencia user.id com onDelete CASCADE
  - response_id referencia user.id com onDelete SET NULL

indices:
  - primary key em id

enums:
  - status: ['new', 'progress', 'answered', 'archived']

8. Regras de negócio relevantes

• O status inicial de uma mensagem é sempre new.
• A resposta a uma mensagem atualiza o status para answered, registra o usuário que respondeu e a data da resposta.
• Mensagens podem ser filtradas por status e texto em nome, e-mail, mensagem ou resposta.
• Ao criar uma mensagem, se o e-mail estiver associado a um usuário, o user_id é vinculado automaticamente.
• Envio automático de e-mails:
  • Confirmação para o cliente que enviou a mensagem.
  • Notificação para o e-mail configurado em contact-us-email-to.
  • Resposta enviada ao cliente quando um administrador responde.
• Validação rigorosa do e-mail no momento da criação da mensagem.
• Exclusão de mensagens remove o registro do banco.
• Atualização de status aceita somente os valores válidos do enum, ignorando o valor all (que é convertido para new internamente).

9. Guia rápido de uso (exemplos)

Criar mensagem (público)

POST /contact-us
Content-Type: application/json

{
  "name": "João Silva",
  "email": "[email protected]",
  "message": "Gostaria de mais informações sobre o produto."
}

Resposta:

{
  "id": 123,
  "name": "João Silva",
  "email": "[email protected]",
  "message": "Gostaria de mais informações sobre o produto.",
  "status": "new",
  "created_at": "2024-06-01T12:00:00Z",
  ...
}

Listar mensagens com filtro e paginação (admin)

GET /contact-us?status=new&search=joao&take=10&skip=0
Authorization: Bearer <token>

Resposta:

{
  "data": [ /* array de mensagens filtradas */ ],
  "total": 5,
  "page": 1,
  "pageSize": 10,
  "prev": null,
  "next": 2,
  "lastPage": 1
}

Atualizar status de mensagem (admin)

PATCH /contact-us/status/123
Authorization: Bearer <token>
Content-Type: application/json

{
  "status": "progress"
}

Resposta: objeto da mensagem atualizada.

Responder mensagem (admin)

POST /contact-us/response/123
Authorization: Bearer <token>
Content-Type: application/json

{
  "response": "Olá João, obrigado pelo contato. Vamos enviar as informações solicitadas."
}

Resposta:

"Olá João, obrigado pelo contato. Vamos enviar as informações solicitadas."

Excluir mensagem (admin)

DELETE /contact-us/123
Authorization: Bearer <token>

Resposta: objeto da mensagem excluída.

Este módulo integra-se com os módulos @hed-hog/api-locale, @hed-hog/api-prisma, @hed-hog/api-pagination e @hed-hog/core para funcionalidades de localização, acesso ao banco de dados, paginação e envio de e-mails.