@hed-hog/contact-us 0.0.270 → 0.0.273

package/README.md

@@ -0,0 +1,373 @@
+# @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
+
+- **Autenticação:** Pública
+- **Descrição:** Retorna as configurações relacionadas ao contato, como telefone e e-mail de contato.
+- **Parâmetros:** Nenhum
+- **Resposta:** Objeto com as configurações `contact-us-phone` e `contact-us-email`.
+- **Erros:** Nenhum específico.
+
+---
+
+### GET /contact-us/stats
+
+- **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:**
+  ```json
+  {
+    "total": number,
+    "totalNew": number,
+    "totalResponded": number,
+    "totalProgress": number,
+    "totalArchived": number
+  }
+  ```
+- **Erros:** Nenhum específico.
+
+---
+
+### GET /contact-us/:id
+
+- **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:** Objeto com os dados completos da mensagem, incluindo usuário e resposta.
+- **Erros:**
+  - `404 Not Found`: Mensagem não encontrada.
+
+---
+
+### GET /contact-us
+
+- **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:**
+  ```json
+  {
+    "data": [/* array de mensagens */],
+    "total": number,
+    "page": number,
+    "pageSize": number,
+    "prev": number | null,
+    "next": number | null,
+    "lastPage": number
+  }
+  ```
+- **Erros:** Nenhum específico.
+
+---
+
+### DELETE /contact-us/:id
+
+- **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.
+- **Erros:**
+  - `404 Not Found`: Mensagem não encontrada.
+
+---
+
+### PATCH /contact-us/status/:id
+
+- **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:**
+  ```json
+  {
+    "status": "new" | "progress" | "answered" | "archived"
+  }
+  ```
+- **Resposta:** Objeto da mensagem atualizada.
+- **Erros:**
+  - `404 Not Found`: Mensagem não encontrada.
+  - `400 Bad Request`: Status inválido.
+
+---
+
+### POST /contact-us/response/:id
+
+- **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:**
+  ```json
+  {
+    "response": "string"
+  }
+  ```
+- **Resposta:** Texto da resposta enviada.
+- **Erros:**
+  - `404 Not Found`: Mensagem não encontrada.
+  - `400 Bad Request`: Resposta inválida.
+
+---
+
+### POST /contact-us
+
+- **Autenticação:** Pública
+- **Descrição:** Cria uma nova mensagem de contato.
+- **Body:**
+  ```json
+  {
+    "name": "string",
+    "email": "string (email válido)",
+    "message": "string"
+  }
+  ```
+- **Resposta:** Objeto da mensagem criada.
+- **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)
+
+```ts
+{
+  name: string; // obrigatório, string
+  email: string; // obrigatório, email válido
+  message: string; // obrigatório, string
+}
+```
+
+### ContactUsResponseDTO (resposta a mensagem)
+
+```ts
+{
+  response: string; // obrigatório, string
+}
+```
+
+### ContactUsStatusDTO (atualização de status)
+
+```ts
+{
+  status: 'new' | 'progress' | 'answered' | 'archived'; // obrigatório, enum válido
+}
+```
+
+### Resposta padrão de listagem
+
+```ts
+{
+  data: ContactUsMessage[],
+  total: number,
+  page: number,
+  pageSize: number,
+  prev: number | null,
+  next: number | null,
+  lastPage: number
+}
+```
+
+### ContactUsMessage (exemplo de objeto mensagem)
+
+```ts
+{
+  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)
+
+```yaml
+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` e registra o usuário que respondeu.
+- 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.
+- 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.
+
+## 9. Guia rápido de uso (exemplos)
+
+### Criar mensagem (público)
+
+```http
+POST /contact-us
+Content-Type: application/json
+
+{
+  "name": "João Silva",
+  "email": "joao@example.com",
+  "message": "Gostaria de mais informações sobre o produto."
+}
+```
+
+Resposta:
+
+```json
+{
+  "id": 123,
+  "name": "João Silva",
+  "email": "joao@example.com",
+  "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)
+
+```http
+GET /contact-us?status=new&search=joao&take=10&skip=0
+Authorization: Bearer <token>
+```
+
+Resposta:
+
+```json
+{
+  "data": [ /* array de mensagens filtradas */ ],
+  "total": 5,
+  "page": 1,
+  "pageSize": 10,
+  "prev": null,
+  "next": 2,
+  "lastPage": 1
+}
+```
+
+---
+
+### Atualizar status de mensagem (admin)
+
+```http
+PATCH /contact-us/status/123
+Authorization: Bearer <token>
+Content-Type: application/json
+
+{
+  "status": "progress"
+}
+```
+
+Resposta: objeto da mensagem atualizada.
+
+---
+
+### Responder mensagem (admin)
+
+```http
+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:
+
+```json
+"Olá João, obrigado pelo contato. Vamos enviar as informações solicitadas."
+```
+
+---
+
+### Excluir mensagem (admin)
+
+```http
+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.

package/package.json

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