From 1c1335a005c9280276794575e0de9a025ceb2daf Mon Sep 17 00:00:00 2001 From: Rafael Lopes Date: Fri, 29 May 2026 15:41:56 -0300 Subject: [PATCH] =?UTF-8?q?DOCS:=20Adicionado=20documenta=C3=A7=C3=A3o=20i?= =?UTF-8?q?nicial=20do=20FrontEnd?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- Chat-e-WhatsApp.md | 80 +++++++++++++++++++++++++++++++++++ Estrutura-de-Pastas.md | 61 ++++++++++++++++++++++++++ Gerenciamento-de-Estado.md | 75 ++++++++++++++++++++++++++++++++ Rotas-e-Protecao.md | 74 ++++++++++++++++++++++++++++++++ Telas-e-Modulos.md | 87 ++++++++++++++++++++++++++++++++++++++ Variaveis-de-Ambiente.md | 50 ++++++++++++++++++++++ 6 files changed, 427 insertions(+) create mode 100644 Chat-e-WhatsApp.md create mode 100644 Estrutura-de-Pastas.md create mode 100644 Gerenciamento-de-Estado.md create mode 100644 Rotas-e-Protecao.md create mode 100644 Telas-e-Modulos.md create mode 100644 Variaveis-de-Ambiente.md diff --git a/Chat-e-WhatsApp.md b/Chat-e-WhatsApp.md new file mode 100644 index 0000000..ec0cee2 --- /dev/null +++ b/Chat-e-WhatsApp.md @@ -0,0 +1,80 @@ +# Chat e WhatsApp + +## Visao geral + +O frontend conversa com o backend por HTTP e Socket.IO. + +HTTP e usado para: + +- listar chats; +- carregar mensagens; +- enviar mensagens; +- assumir/liberar/transferir/fechar atendimento; +- baixar midia; +- consultar status. + +Socket.IO e usado para: + +- receber QR Code; +- receber status do WhatsApp; +- receber novas mensagens em tempo real. + +## Socket.IO + +Namespace: + +```text +/whatsapp +``` + +Arquivo compartilhado: + +```text +src/shared/hooks/useWhatsappSocket.js +``` + +Tela administrativa: + +```text +src/modules/management/pages/WhatsappAdminPage.jsx +``` + +## Autenticacao no socket + +O token JWT e enviado no handshake: + +```javascript +io(WHATSAPP_SOCKET_URL, { + auth: { + token: getAuthToken() + } +}); +``` + +Sem token valido, o backend recusa a conexao. + +## QR Code + +O QR Code aparece na tela `/admin/whatsapp`. + +Fluxo: + +```text +Backend emite evento qr +Frontend recebe qr +Frontend renderiza imagem para pareamento do WhatsApp +``` + +## Mensagens em tempo real + +Quando o backend recebe mensagem pelo WhatsApp, ele emite: + +```text +message +``` + +O hook `useWhatsappSocket` armazena a ultima mensagem recebida para o chat atualizar a conversa. + +## Observacao + +Mesmo com Socket.IO, as acoes sensiveis continuam acontecendo por HTTP protegido com Bearer token. diff --git a/Estrutura-de-Pastas.md b/Estrutura-de-Pastas.md new file mode 100644 index 0000000..c38b281 --- /dev/null +++ b/Estrutura-de-Pastas.md @@ -0,0 +1,61 @@ +# Estrutura de Pastas + +## Visao geral + +O frontend e organizado por modulos funcionais dentro de `src/modules` e por recursos compartilhados dentro de `src/shared`. + +```text +src/ +|-- main.jsx +|-- routes/ +|-- shared/ +`-- modules/ +``` + +## `src/routes` + +Define as rotas principais da aplicacao. + +Arquivos importantes: + +- `router.jsx`: mapa de rotas. +- `ProtectedRoute.jsx`: bloqueia acesso a paginas privadas quando nao existe sessao autenticada. + +## `src/shared` + +Contem recursos usados por mais de um modulo: + +- `services/apiConfig.js`: URL da API e URL do Socket.IO. +- `services/authFetch.js`: intercepta chamadas `fetch` para enviar Bearer token. +- `hooks/useWhatsappSocket.js`: conexao Socket.IO com o namespace `/whatsapp`. +- `styles/global.css`: estilos globais. + +## `src/modules` + +Cada pasta representa uma area funcional: + +- `auth`: login, sessao e provedores de autenticacao. +- `home`: experiencia inicial conforme perfil. +- `chat`: atendimento em tempo real. +- `call`: painel do atendente. +- `attendance`: novo atendimento e abertura ativa. +- `management`: painel administrativo e supervisor. + +## Padrao de organizacao por modulo + +Quando o modulo cresce, a estrutura esperada e: + +```text +modulo/ +|-- components/ +|-- hooks/ +|-- pages/ +`-- services/ +``` + +Regra pratica: + +- `pages`: telas roteadas. +- `components`: partes reutilizaveis da tela. +- `hooks`: estado e comportamento de tela. +- `services`: chamadas para API ou normalizacao de dados. diff --git a/Gerenciamento-de-Estado.md b/Gerenciamento-de-Estado.md new file mode 100644 index 0000000..6c0591a --- /dev/null +++ b/Gerenciamento-de-Estado.md @@ -0,0 +1,75 @@ +# Gerenciamento de Estado + +## Visao geral + +O frontend nao usa Redux, Zustand ou Context global amplo. + +O estado e mantido de forma local por: + +- `useState`; +- `useEffect`; +- hooks especificos por modulo; +- `sessionStorage` para sessao autenticada. + +## Sessao + +Arquivo: + +```text +src/modules/auth/services/sessionService.js +``` + +Responsavel por: + +- ler usuario atual; +- ler token atual; +- identificar perfil; +- limpar sessao. + +## Chat + +Arquivo principal: + +```text +src/modules/chat/hooks/useChat.js +``` + +Concentra: + +- contatos/conversas; +- mensagens por contato; +- conversa ativa; +- envio de mensagem; +- assumir/liberar/fechar atendimento; +- transferencia; +- carregamento de midia. + +## WhatsApp Socket + +Arquivo: + +```text +src/shared/hooks/useWhatsappSocket.js +``` + +Mantem estado de: + +- conexao; +- QR Code; +- status do WhatsApp; +- ultima mensagem recebida. + +## Painel administrativo + +O modulo `management` usa estado local por tela/componente. + +Servicos em `src/modules/management/services` fazem a comunicacao com a API e retornam dados normalizados. + +## Diretriz + +Antes de adicionar uma ferramenta global de estado, prefira: + +1. estado local na tela; +2. hook especifico do modulo; +3. service para API; +4. somente depois avaliar estado global. diff --git a/Rotas-e-Protecao.md b/Rotas-e-Protecao.md new file mode 100644 index 0000000..652dbc3 --- /dev/null +++ b/Rotas-e-Protecao.md @@ -0,0 +1,74 @@ +# Rotas e Protecao + +## Rotas principais + +Arquivo: + +```text +src/routes/router.jsx +``` + +Rotas: + +| Rota | Tela | Protegida | +|---|---|---| +| `/` | redireciona para `/login` | nao | +| `/login` | LoginPage | nao | +| `/home` | ProfileHomePage | sim | +| `/chat` | ChatPage | sim | +| `/call` | CallPage | sim | +| `/new-attendance` | AgentNewAttendancePage | sim | +| `/mass-message` | AgentMassMessagePage | sim | +| `/contacts` | ContactsPage | sim | +| `/admin/whatsapp` | WhatsappAdminPage | sim | + +## ProtectedRoute + +Arquivo: + +```text +src/routes/ProtectedRoute.jsx +``` + +Responsabilidade: + +- verificar se existe `authToken` e `authUser` em `sessionStorage`; +- redirecionar para `/login` quando nao houver sessao; +- impedir que `/home` renderize telas mockadas sem login. + +## Resolucao de perfil + +Arquivo: + +```text +src/modules/auth/services/sessionService.js +``` + +O perfil e calculado a partir de dados reais retornados pelo backend: + +- `perfis`; +- `profiles`; +- `perfil`; +- `role`; +- `accessStatus`. + +Fallbacks de demo por username foram removidos. + +## Comportamento esperado + +Sem login: + +```text +/home -> /login +/chat -> /login +/admin/whatsapp -> /login +``` + +Com login: + +```text +Admin -> painel administrativo +Supervisor -> painel operacional +Agente -> painel do atendente +Unassigned -> tela aguardando configuracao +``` diff --git a/Telas-e-Modulos.md b/Telas-e-Modulos.md new file mode 100644 index 0000000..50c1918 --- /dev/null +++ b/Telas-e-Modulos.md @@ -0,0 +1,87 @@ +# Telas e Modulos + +## Auth + +Responsavel por login, provedores disponiveis, armazenamento de sessao e resolucao de perfil. + +Arquivos principais: + +- `modules/auth/pages/LoginPage.jsx` +- `modules/auth/hooks/useLogin.js` +- `modules/auth/services/authService.js` +- `modules/auth/services/sessionService.js` + +## Home + +Responsavel por direcionar a experiencia inicial conforme perfil. + +Arquivo principal: + +- `modules/home/pages/ProfileHomePage.jsx` + +Fluxo: + +```text +Admin -> AdminPage +Supervisor -> SupervisorPage +Agente -> HomePage +Unassigned -> UnassignedHomePage +``` + +## Chat + +Atendimento em tempo real via WhatsApp. + +Funcionalidades: + +- listar conversas; +- carregar mensagens; +- enviar mensagem; +- anexar midia; +- assumir atendimento; +- liberar atendimento; +- transferir atendimento; +- fechar atendimento. + +## Attendance + +Fluxos de abertura de atendimento. + +Inclui: + +- novo atendimento; +- abertura ativa por template; +- selecao de contato; +- envio em massa quando aplicavel. + +## Call + +Painel do atendente. + +Centraliza a experiencia operacional do agente. + +## Management + +Painel administrativo e supervisor. + +Inclui: + +- dashboard; +- usuarios/acessos; +- areas; +- contatos; +- canais e integracoes; +- base de conhecimento; +- conteudos da IA; +- configuracoes; +- WhatsApp QR Code. + +## Shared + +Recursos compartilhados entre modulos: + +- hooks; +- services; +- estilos; +- componentes comuns; +- assets. diff --git a/Variaveis-de-Ambiente.md b/Variaveis-de-Ambiente.md new file mode 100644 index 0000000..1a389cf --- /dev/null +++ b/Variaveis-de-Ambiente.md @@ -0,0 +1,50 @@ +# Variaveis de Ambiente + +## Variavel principal + +```env +VITE_API_URL=http://localhost:3001 +``` + +O frontend usa `VITE_API_URL` para montar: + +- URL base da API; +- URL do Socket.IO do WhatsApp. + +Arquivo: + +```text +src/shared/services/apiConfig.js +``` + +## Comportamento padrao + +Se `VITE_API_URL` nao for definida, o frontend usa: + +```text +http://localhost:3001 +``` + +## Desenvolvimento local + +Exemplo de `.env.development`: + +```env +VITE_API_URL=http://localhost:3001 +``` + +## Docker/Deploy + +Em ambiente com compose ou proxy, a URL deve apontar para a API publicada. + +Exemplo: + +```env +VITE_API_URL=https://omnichannel-api.empresa.com +``` + +## Observacoes + +- Variaveis do Vite precisam iniciar com `VITE_`. +- Alteracoes no `.env` exigem reinicio do servidor Vite. +- Nunca coloque segredo no frontend. Tudo que esta no build pode ser visto pelo navegador.