Adicionar Whatsapp

Whatsapp.md

@@ -0,0 +1,68 @@
+# Modulo WhatsApp
+
+Base tecnica:
+
+- Controller: `src/modules/whatsapp/whatsapp.controller.ts`
+- Service: `src/modules/whatsapp/whatsapp.service.ts`
+- Assignment: `src/modules/whatsapp/whatsapp-assignment.service.ts`
+- Gateway: `src/modules/whatsapp/whatsapp.gateway.ts`
+- Prefixo: `/whatsapp`
+
+## Responsabilidade
+
+Integra com `whatsapp-web.js`, controla chats, mensagens, midia, templates, abertura ativa, fila, atribuicao, transferencia e triagem do Agente Virtual.
+
+## Endpoints
+
+| Metodo | Rota | Descricao |
+|---|---|---|
+| GET | `/whatsapp/status` | Status da sessao WhatsApp |
+| GET | `/whatsapp/chats` | Lista conversas |
+| GET | `/whatsapp/messages/:chatId` | Lista mensagens de uma conversa |
+| GET | `/whatsapp/media/:chatId/:messageId` | Baixa midia de mensagem |
+| POST | `/whatsapp/send` | Envia texto/midia |
+| POST | `/whatsapp/start-attendance` | Inicia atendimento ativo por template |
+| POST | `/whatsapp/assign` | Assume conversa |
+| POST | `/whatsapp/transfer` | Transfere conversa |
+| DELETE | `/whatsapp/release/:chatId` | Libera conversa |
+| POST | `/whatsapp/close` | Fecha atendimento |
+| GET | `/whatsapp/assignment/:chatId` | Consulta atribuicao |
+| GET | `/whatsapp/templates` | Lista templates |
+| POST | `/whatsapp/templates` | Cria template |
+| POST | `/whatsapp/templates/update/:id` | Atualiza template |
+| POST | `/whatsapp/templates/approve-admin/:id` | Aprova template pelo admin |
+| POST | `/whatsapp/templates/reject-admin/:id` | Reprova template pelo admin |
+| DELETE | `/whatsapp/templates/:id` | Remove template |
+
+## Funcoes importantes
+
+### `whatsapp.service.ts`
+
+- Inicializa cliente WhatsApp Web.
+- Emite QR/status.
+- Lista chats e mensagens.
+- Envia mensagens e midias.
+- Dispara roteamento do bot ao receber mensagem.
+- Executa abertura ativa com template.
+
+### `whatsapp-assignment.service.ts`
+
+- Garante schema complementar em `onModuleInit()`.
+- Controla fila e atribuicao em `whatsapp_chat_atribuicoes`.
+- Impede envio quando atendimento ativo aguarda resposta do cliente.
+- Roteia conversas por area, fluxo configurado ou arvore do bot.
+- Monta observacao de transferencia do Agente Virtual.
+
+## Eventos em tempo real
+
+O `whatsapp.gateway.ts` usa Socket.IO para notificar o frontend sobre:
+
+- novas mensagens;
+- atualizacoes de chat;
+- status/QR quando aplicavel.
+
+## Code review
+
+- `whatsapp-assignment.service.ts` concentra regra critica e deve receber testes.
+- Permissao de agente/admin ainda precisa ser validada no backend.
+- `whatsapp-web.js` e bom para demo/MVP controlado, mas para producao robusta avaliar WhatsApp Cloud API.