DOCS: Adicionado documentação inicial do FrontEnd
parent
9972a4b864
commit
1c1335a005
80
Chat-e-WhatsApp.md
Normal file
80
Chat-e-WhatsApp.md
Normal file
@ -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.
|
||||||
61
Estrutura-de-Pastas.md
Normal file
61
Estrutura-de-Pastas.md
Normal file
@ -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.
|
||||||
75
Gerenciamento-de-Estado.md
Normal file
75
Gerenciamento-de-Estado.md
Normal file
@ -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.
|
||||||
74
Rotas-e-Protecao.md
Normal file
74
Rotas-e-Protecao.md
Normal file
@ -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
|
||||||
|
```
|
||||||
87
Telas-e-Modulos.md
Normal file
87
Telas-e-Modulos.md
Normal file
@ -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.
|
||||||
50
Variaveis-de-Ambiente.md
Normal file
50
Variaveis-de-Ambiente.md
Normal file
@ -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.
|
||||||
Loading…
Reference in New Issue
Block a user