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