This commit is contained in:
parent
cb08a9f48a
commit
b2aa1a7712
87
README.md
Normal file
87
README.md
Normal file
@ -0,0 +1,87 @@
|
||||
# Omnichannel Backend
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
Backend da plataforma Omnichannel da Sothis, responsavel por autenticacao, atendimento, integracao com WhatsApp, gestao administrativa, contatos, base de conhecimento e servicos de apoio ao painel web.
|
||||
|
||||
Este repositorio contem apenas a API. Para subir o projeto completo com frontend, backend e configuracao de deploy, utilize o repositorio de orquestracao:
|
||||
|
||||
https://chaleiradev.sothistelecom.com/Sothis/omnichannel-deploy
|
||||
|
||||
## Stack
|
||||
|
||||
- Node.js
|
||||
- NestJS
|
||||
- TypeScript
|
||||
- PostgreSQL
|
||||
- Socket.IO
|
||||
- whatsapp-web.js
|
||||
- JSON Web Token para autenticacao
|
||||
- LDAP/AD e Microsoft OAuth como provedores de login configuraveis
|
||||
|
||||
## Documentacao da API
|
||||
|
||||
A documentacao detalhada das rotas fica disponivel no Swagger do backend no ambiente publicado.
|
||||
|
||||
Para documentacao tecnica complementar do backend, decisoes, modulos e operacao, acesse a wiki:
|
||||
|
||||
https://chaleiradev.sothistelecom.com/Sothis/omnichannel-backend/wiki
|
||||
|
||||
## Execucao local
|
||||
|
||||
Instale as dependencias:
|
||||
|
||||
```bash
|
||||
npm install
|
||||
```
|
||||
|
||||
Crie o arquivo de ambiente a partir do exemplo:
|
||||
|
||||
```bash
|
||||
cp .env.example .env.development
|
||||
```
|
||||
|
||||
Configure as variaveis de banco, JWT, CORS e integracoes no `.env.development`.
|
||||
|
||||
Execute em modo desenvolvimento:
|
||||
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Por padrao, a API usa a porta configurada em `PORT` ou `BACKEND_PORT`. Se nenhuma variavel for definida, utiliza `3001`.
|
||||
|
||||
## Build e producao
|
||||
|
||||
Gere o build:
|
||||
|
||||
```bash
|
||||
npm run build
|
||||
```
|
||||
|
||||
Execute a versao compilada:
|
||||
|
||||
```bash
|
||||
npm start
|
||||
```
|
||||
|
||||
## Estrutura principal
|
||||
|
||||
- `src/infra`: configuracao, banco de dados, logger e infraestrutura compartilhada.
|
||||
- `src/modules/auth`: autenticacao, JWT, LDAP/AD e Microsoft OAuth.
|
||||
- `src/modules/admin`: recursos administrativos, base de conhecimento, contatos e controles de acesso.
|
||||
- `src/modules/whatsapp`: conexao WhatsApp, QR Code, mensagens, transferencia e eventos em tempo real.
|
||||
- `src/modules/attendance`: apoio as regras de atendimento.
|
||||
- `src/modules/call`, `src/modules/chat` e `src/modules/home`: modulos de apoio as telas e fluxos do frontend.
|
||||
|
||||
## Observacoes
|
||||
|
||||
- O banco de dados nao e criado por este repositorio. A configuracao deve apontar para uma instancia PostgreSQL existente.
|
||||
- Arquivos locais como `.env*`, logs, `dist`, dumps e sessoes do WhatsApp ficam fora do Git.
|
||||
- Para operacao completa, deploy e atualizacao em producao, consulte o repositorio `omnichannel-deploy`.
|
||||
@ -1,351 +0,0 @@
|
||||
# Controle de Acesso, Areas e Usuarios
|
||||
|
||||
## Visao geral
|
||||
|
||||
O backend agora usa o banco PostgreSQL para manter o usuario interno da aplicacao e suas atribuicoes operacionais.
|
||||
|
||||
A autenticacao continua sendo feita por provedores externos:
|
||||
|
||||
- LDAP / Active Directory
|
||||
- Microsoft OAuth
|
||||
|
||||
Depois que o provedor confirma a identidade, o backend sincroniza esse usuario no banco e consulta:
|
||||
|
||||
- perfis de acesso
|
||||
- areas vinculadas
|
||||
- area principal
|
||||
- status de acesso
|
||||
|
||||
Esse status determina qual experiencia o frontend deve renderizar em `/home`.
|
||||
|
||||
---
|
||||
|
||||
## Fluxo de login com banco
|
||||
|
||||
```text
|
||||
Frontend
|
||||
-> POST /auth/login ou OAuth Microsoft
|
||||
-> Backend autentica no provedor externo
|
||||
-> Backend cria/atualiza usuarios
|
||||
-> Backend cria/atualiza usuarios_provedores
|
||||
-> Backend consulta usuarios_perfis e usuarios_areas
|
||||
-> Backend emite JWT com perfis/areas
|
||||
-> Frontend salva authToken/authUser
|
||||
-> Frontend navega para /home
|
||||
```
|
||||
|
||||
O provedor externo valida identidade. O banco define acesso dentro do Omnichannel.
|
||||
|
||||
---
|
||||
|
||||
## Tabelas usadas
|
||||
|
||||
### `usuarios`
|
||||
|
||||
Representa uma pessoa autenticada no produto.
|
||||
|
||||
Campos principais:
|
||||
|
||||
- `id`
|
||||
- `nome`
|
||||
- `email`
|
||||
- `ativo`
|
||||
- `created_at`
|
||||
- `updated_at`
|
||||
|
||||
### `usuarios_provedores`
|
||||
|
||||
Relaciona o usuario interno com o provedor externo usado no login.
|
||||
|
||||
Exemplos:
|
||||
|
||||
- `ldap` + username do AD
|
||||
- `microsoft` + userPrincipalName/email
|
||||
|
||||
### `perfis_acesso`
|
||||
|
||||
Define os niveis de acesso.
|
||||
|
||||
Perfis iniciais:
|
||||
|
||||
- `Agente`
|
||||
- `Supervisor`
|
||||
- `Admin`
|
||||
|
||||
### `usuarios_perfis`
|
||||
|
||||
Relaciona usuarios e perfis.
|
||||
|
||||
Hoje o frontend usa o perfil principal para decidir a experiencia em `/home`.
|
||||
|
||||
### `areas`
|
||||
|
||||
Representa as areas operacionais.
|
||||
|
||||
Areas iniciais:
|
||||
|
||||
- `Suporte`
|
||||
- `Financeiro`
|
||||
- `Comercial`
|
||||
|
||||
### `usuarios_areas`
|
||||
|
||||
Relaciona usuarios e areas.
|
||||
|
||||
Um usuario pode ter mais de uma area, mas a regra atual permite no maximo uma area principal por usuario.
|
||||
|
||||
---
|
||||
|
||||
## Status de acesso
|
||||
|
||||
O backend devolve `accessStatus` no usuario autenticado.
|
||||
|
||||
Valores:
|
||||
|
||||
- `assigned`: usuario tem pelo menos um perfil e uma area
|
||||
- `unassigned`: usuario existe/autenticou, mas ainda nao tem perfil ou area
|
||||
|
||||
### Comportamento no frontend
|
||||
|
||||
```text
|
||||
assigned + Admin -> /home renderiza painel Admin
|
||||
assigned + Supervisor -> /home renderiza painel Supervisor
|
||||
assigned + Agente -> /home renderiza tela do Atendente
|
||||
unassigned -> /home renderiza tela de acesso aguardando configuracao
|
||||
```
|
||||
|
||||
Esse comportamento permite que um usuario novo entre via AD/OAuth, seja criado no banco e fique bloqueado ate um Admin atribuir perfil e area.
|
||||
|
||||
---
|
||||
|
||||
## Payload do usuario autenticado
|
||||
|
||||
Exemplo de resposta do login:
|
||||
|
||||
```json
|
||||
{
|
||||
"token": "jwt",
|
||||
"user": {
|
||||
"id": "1",
|
||||
"databaseId": 1,
|
||||
"name": "Atendente Demo",
|
||||
"email": "atendente@sothis.com.br",
|
||||
"username": "atendente",
|
||||
"provider": "ldap",
|
||||
"perfis": ["Agente"],
|
||||
"profiles": ["Agente"],
|
||||
"areas": ["Suporte"],
|
||||
"areaPrincipal": "Suporte",
|
||||
"accessStatus": "assigned"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
No JWT tambem entram:
|
||||
|
||||
- `name`
|
||||
- `email`
|
||||
- `provider`
|
||||
- `username`
|
||||
- `perfis`
|
||||
- `profiles`
|
||||
- `areas`
|
||||
- `areaPrincipal`
|
||||
- `accessStatus`
|
||||
|
||||
---
|
||||
|
||||
## Variaveis de ambiente
|
||||
|
||||
O backend le as variaveis de banco pelo `.env.development` em desenvolvimento.
|
||||
|
||||
```env
|
||||
DB_HOST=10.0.120.75
|
||||
DB_PORT=5432
|
||||
DB_USER=desenvolvimento
|
||||
DB_PASSWORD=********
|
||||
DB_NAME=omnichannel-dev
|
||||
```
|
||||
|
||||
Observacao:
|
||||
|
||||
- `npm run dev` usa `NODE_ENV=development` e carrega `.env.development`.
|
||||
- `npm run start` usa `NODE_ENV=production`; nesse caso, configure `.env.production` ou variaveis do ambiente.
|
||||
|
||||
---
|
||||
|
||||
## Endpoints administrativos
|
||||
|
||||
Base path:
|
||||
|
||||
```text
|
||||
/admin/access
|
||||
```
|
||||
|
||||
### Listar opcoes de acesso
|
||||
|
||||
```http
|
||||
GET /admin/access/options
|
||||
```
|
||||
|
||||
Resposta:
|
||||
|
||||
```json
|
||||
{
|
||||
"profiles": [
|
||||
{ "id": 3, "nome": "Admin" },
|
||||
{ "id": 1, "nome": "Agente" },
|
||||
{ "id": 2, "nome": "Supervisor" }
|
||||
],
|
||||
"areas": [
|
||||
{ "id": 3, "nome": "Comercial" },
|
||||
{ "id": 2, "nome": "Financeiro" },
|
||||
{ "id": 1, "nome": "Suporte" }
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Listar usuarios
|
||||
|
||||
```http
|
||||
GET /admin/access/users
|
||||
```
|
||||
|
||||
Resposta:
|
||||
|
||||
```json
|
||||
[
|
||||
{
|
||||
"id": 1,
|
||||
"nome": "Admin Demo",
|
||||
"email": "admin@sothis.com.br",
|
||||
"ativo": true,
|
||||
"perfis": [{ "id": 3, "nome": "Admin" }],
|
||||
"areas": [{ "id": 1, "nome": "Suporte", "principal": true }],
|
||||
"perfilPrincipal": { "id": 3, "nome": "Admin" },
|
||||
"areaPrincipal": { "id": 1, "nome": "Suporte", "principal": true },
|
||||
"accessStatus": "assigned"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
### Atualizar acesso de usuario
|
||||
|
||||
```http
|
||||
PUT /admin/access/users/:id
|
||||
Content-Type: application/json
|
||||
```
|
||||
|
||||
Body:
|
||||
|
||||
```json
|
||||
{
|
||||
"perfilId": 2,
|
||||
"areaId": 1
|
||||
}
|
||||
```
|
||||
|
||||
Comportamento atual:
|
||||
|
||||
- remove perfis anteriores do usuario
|
||||
- remove areas anteriores do usuario
|
||||
- cria o novo perfil informado
|
||||
- cria a nova area como principal
|
||||
- retorna o usuario atualizado
|
||||
|
||||
Para remover atribuicoes:
|
||||
|
||||
```json
|
||||
{
|
||||
"perfilId": null,
|
||||
"areaId": null
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Usuarios de demonstracao
|
||||
|
||||
A migration `003_demo_access.sql` cria usuarios iniciais para demonstracao:
|
||||
|
||||
| Usuario | Email | Perfil | Area |
|
||||
|---|---|---|---|
|
||||
| Admin Demo | `admin@sothis.com.br` | Admin | Suporte |
|
||||
| Supervisor Demo | `supervisor@sothis.com.br` | Supervisor | Suporte |
|
||||
| Atendente Demo | `atendente@sothis.com.br` | Agente | Suporte |
|
||||
|
||||
Esses usuarios existem no banco, mas nao substituem a autenticacao real.
|
||||
|
||||
Para logar pela tela de login, o usuario precisa existir no AD ou no provedor Microsoft configurado.
|
||||
|
||||
---
|
||||
|
||||
## Como testar
|
||||
|
||||
### Backend
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Endpoints de validacao:
|
||||
|
||||
```text
|
||||
http://localhost:3001/admin/access/options
|
||||
http://localhost:3001/admin/access/users
|
||||
```
|
||||
|
||||
### Frontend sem depender de AD
|
||||
|
||||
No console do navegador:
|
||||
|
||||
```js
|
||||
localStorage.setItem('authUser', JSON.stringify({
|
||||
username: 'admin@sothis.com.br',
|
||||
name: 'Admin Demo',
|
||||
email: 'admin@sothis.com.br',
|
||||
perfis: ['Admin'],
|
||||
profiles: ['Admin'],
|
||||
areas: ['Suporte'],
|
||||
accessStatus: 'assigned'
|
||||
}));
|
||||
localStorage.setItem('authToken', 'dev-token');
|
||||
location.href = '/home';
|
||||
```
|
||||
|
||||
Para usuario sem atribuicao:
|
||||
|
||||
```js
|
||||
localStorage.setItem('authUser', JSON.stringify({
|
||||
username: 'novo.usuario',
|
||||
name: 'Novo Usuario',
|
||||
email: 'novo.usuario@sothis.com.br',
|
||||
perfis: [],
|
||||
profiles: [],
|
||||
areas: [],
|
||||
accessStatus: 'unassigned'
|
||||
}));
|
||||
localStorage.setItem('authToken', 'dev-token');
|
||||
location.href = '/home';
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Limitacoes atuais
|
||||
|
||||
- Os endpoints `/admin/access/*` ainda nao possuem guard JWT nem checagem de perfil Admin.
|
||||
- A alteracao de acesso substitui perfil/area atuais por um unico perfil e uma unica area principal.
|
||||
- Ainda nao ha auditoria das alteracoes de acesso.
|
||||
- O painel Admin consome os endpoints reais, mas ainda possui fallback visual mockado se o backend estiver indisponivel.
|
||||
- A senha do banco nao deve ser commitada; arquivos `.env.*` seguem ignorados pelo Git.
|
||||
|
||||
---
|
||||
|
||||
## Proximos passos sugeridos
|
||||
|
||||
- Adicionar `AuthGuard` JWT.
|
||||
- Proteger `/admin/access/*` para `Admin`.
|
||||
- Registrar auditoria em `logs_auditoria`.
|
||||
- Criar endpoints CRUD completos para `areas`.
|
||||
- Permitir multiplas areas por usuario na UI, mantendo uma area principal.
|
||||
268
docs/auth.md
268
docs/auth.md
@ -1,268 +0,0 @@
|
||||
# Módulo de Autenticação
|
||||
|
||||
## Visão geral
|
||||
|
||||
O módulo `auth` centraliza toda a lógica de autenticação do Omnichannel. Ele suporta múltiplos provedores de identidade e emite JWT próprio da aplicação, independente de qual provedor foi usado.
|
||||
|
||||
Provedores implementados:
|
||||
|
||||
- **LDAP / Active Directory** — login com usuário e senha do AD corporativo
|
||||
- **Microsoft OAuth (Entra ID)** — login via conta Microsoft com redirect OAuth 2.0
|
||||
|
||||
A arquitetura foi desenhada para facilitar a adição de novos provedores no futuro.
|
||||
|
||||
---
|
||||
|
||||
## Estrutura de arquivos
|
||||
|
||||
```
|
||||
src/modules/auth/
|
||||
├── auth.module.ts # Registro do módulo no NestJS
|
||||
├── auth.controller.ts # Rotas HTTP
|
||||
├── auth.service.ts # Fachada — delega para os providers
|
||||
├── auth.config.ts # Leitura de variáveis de ambiente
|
||||
├── auth-token.service.ts # Emissão de JWT da aplicação
|
||||
├── auth.types.ts # Interfaces TypeScript compartilhadas
|
||||
└── providers/
|
||||
├── ldap-auth.provider.ts # Autenticação LDAP/AD
|
||||
├── microsoft-oauth.provider.ts # Autenticação Microsoft OAuth
|
||||
└── oauth-state.service.ts # Proteção CSRF para OAuth
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Rotas disponíveis
|
||||
|
||||
| Método | Rota | Descrição |
|
||||
|--------|---------------------------------|------------------------------------------------|
|
||||
| GET | `/auth/config` | Retorna quais provedores estão habilitados |
|
||||
| POST | `/auth/login` | Login com usuário e senha (LDAP/AD) |
|
||||
| GET | `/auth/oauth/microsoft/start` | Inicia o fluxo OAuth com a Microsoft |
|
||||
| GET | `/auth/oauth/microsoft/callback`| Callback que a Microsoft chama após o login |
|
||||
|
||||
---
|
||||
|
||||
## Variáveis de ambiente
|
||||
|
||||
```env
|
||||
# Servidor
|
||||
PORT=3001
|
||||
FRONTEND_URL=http://localhost:3000
|
||||
|
||||
# JWT
|
||||
JWT_SECRET=uma-chave-longa-e-aleatoria
|
||||
JWT_EXPIRES_IN=8h
|
||||
|
||||
# Provedores ativos (separados por vírgula)
|
||||
AUTH_PROVIDERS=ldap
|
||||
|
||||
# LDAP / Active Directory
|
||||
LDAP_ENABLED=true
|
||||
LDAP_URL=ldaps://servidor-ad:636
|
||||
LDAP_DOMAIN=empresa.com.br
|
||||
LDAP_USER_DN_TEMPLATE={{username}}@empresa.com.br
|
||||
LDAP_SEARCH_BASE=DC=empresa,DC=com
|
||||
LDAP_SEARCH_FILTER=(&(objectClass=user)(sAMAccountName={{username}}))
|
||||
LDAP_TIMEOUT_MS=5000
|
||||
|
||||
# Microsoft Entra ID (desabilitado por padrão)
|
||||
MICROSOFT_ENABLED=false
|
||||
MICROSOFT_TENANT_ID=common
|
||||
MICROSOFT_CLIENT_ID=
|
||||
MICROSOFT_CLIENT_SECRET=
|
||||
MICROSOFT_REDIRECT_URI=http://localhost:3001/auth/oauth/microsoft/callback
|
||||
MICROSOFT_SUCCESS_REDIRECT_URL=http://localhost:3000/login
|
||||
```
|
||||
|
||||
> `JWT_SECRET` deve ser uma string longa e aleatória. Em produção, nunca use o valor padrão do `.env.development`.
|
||||
|
||||
---
|
||||
|
||||
## Fluxo LDAP / Active Directory
|
||||
|
||||
```
|
||||
Frontend
|
||||
→ POST /auth/login { username, password }
|
||||
→ AuthController
|
||||
→ AuthService.loginWithLdap()
|
||||
→ LdapAuthProvider.authenticate()
|
||||
→ Conecta no servidor AD (LDAP_URL)
|
||||
→ Faz bind com o usuário e senha
|
||||
→ Se o bind falhar: UnauthorizedException
|
||||
→ Busca dados do usuário no diretório (se LDAP_SEARCH_BASE configurado)
|
||||
→ Monta objeto AuthenticatedUser
|
||||
→ AuthTokenService.issueToken()
|
||||
→ Gera JWT assinado com JWT_SECRET
|
||||
→ Retorna { token, user } para o frontend
|
||||
```
|
||||
|
||||
O AD apenas valida a identidade. O JWT emitido é da aplicação, não do AD.
|
||||
|
||||
---
|
||||
|
||||
## Fluxo Microsoft OAuth
|
||||
|
||||
```
|
||||
1. Frontend redireciona para GET /auth/oauth/microsoft/start
|
||||
→ Backend gera um state assinado (proteção CSRF)
|
||||
→ Backend redireciona para login.microsoftonline.com
|
||||
|
||||
2. Usuário autentica na Microsoft
|
||||
|
||||
3. Microsoft chama GET /auth/oauth/microsoft/callback?code=...&state=...
|
||||
→ Backend valida o state (assinatura + expiração)
|
||||
→ Backend troca o code por access_token (chamada server-to-server)
|
||||
→ Backend consulta Microsoft Graph /me para obter dados do usuário
|
||||
→ AuthTokenService.issueToken() gera JWT próprio
|
||||
→ Backend redireciona para MICROSOFT_SUCCESS_REDIRECT_URL?token=...
|
||||
|
||||
4. Frontend salva o token e navega para /home
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Proteção CSRF com OAuth State
|
||||
|
||||
O `OAuthStateService` protege o fluxo OAuth contra ataques de CSRF.
|
||||
|
||||
**Como funciona:**
|
||||
|
||||
1. No início do fluxo, o backend cria um state:
|
||||
- Gera um nonce aleatório + timestamp
|
||||
- Converte para base64url
|
||||
- Assina com HMAC-SHA256 usando o `JWT_SECRET`
|
||||
- Formato final: `payload.assinatura`
|
||||
|
||||
2. No callback, o backend verifica:
|
||||
- O state tem os dois pedaços (`payload.assinatura`)
|
||||
- A assinatura é válida (recalcula e compara com `timingSafeEqual`)
|
||||
- O state não expirou (padrão: 10 minutos, configurável via `MICROSOFT_STATE_MAX_AGE_MS`)
|
||||
|
||||
Se qualquer verificação falhar, o callback é rejeitado com `400 Bad Request`.
|
||||
|
||||
---
|
||||
|
||||
## JWT da aplicação
|
||||
|
||||
Após qualquer autenticação bem-sucedida, o `AuthTokenService` emite um JWT com o seguinte payload:
|
||||
|
||||
```json
|
||||
{
|
||||
"sub": "identificador-do-usuario",
|
||||
"name": "Nome Completo",
|
||||
"email": "usuario@empresa.com",
|
||||
"provider": "ldap",
|
||||
"username": "usuario"
|
||||
}
|
||||
```
|
||||
|
||||
O `sub` é atualmente o email ou identificador externo. Quando houver banco de dados, deve ser substituído pelo ID interno da tabela `users`.
|
||||
|
||||
---
|
||||
|
||||
## Como adicionar um novo provedor
|
||||
|
||||
1. Crie o arquivo em `src/modules/auth/providers/novo-provedor.provider.ts`:
|
||||
|
||||
```typescript
|
||||
import { Injectable } from '@nestjs/common';
|
||||
import { AuthConfigService } from '../auth.config';
|
||||
import { AuthTokenService } from '../auth-token.service';
|
||||
import { AuthResult } from '../auth.types';
|
||||
|
||||
@Injectable()
|
||||
export class NovoProvedorProvider {
|
||||
constructor(
|
||||
private readonly authConfig: AuthConfigService,
|
||||
private readonly authToken: AuthTokenService,
|
||||
) {}
|
||||
|
||||
async authenticate(/* dados necessários */): Promise<AuthResult> {
|
||||
// 1. Valide as credenciais no provedor externo
|
||||
// 2. Monte o objeto AuthenticatedUser
|
||||
// 3. Emita o token com this.authToken.issueToken(user)
|
||||
// 4. Retorne { token, user }
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
2. Registre o provider em `auth.module.ts`:
|
||||
|
||||
```typescript
|
||||
providers: [
|
||||
AuthConfigService,
|
||||
AuthService,
|
||||
AuthTokenService,
|
||||
LdapAuthProvider,
|
||||
MicrosoftOAuthProvider,
|
||||
OAuthStateService,
|
||||
NovoProvedorProvider, // adicione aqui
|
||||
],
|
||||
```
|
||||
|
||||
3. Injete no `AuthService` e exponha o método necessário:
|
||||
|
||||
```typescript
|
||||
constructor(
|
||||
private readonly authConfig: AuthConfigService,
|
||||
private readonly ldapAuthProvider: LdapAuthProvider,
|
||||
private readonly microsoftOAuthProvider: MicrosoftOAuthProvider,
|
||||
private readonly novoProvedorProvider: NovoProvedorProvider, // injete aqui
|
||||
) {}
|
||||
|
||||
loginComNovoProvedor(dados: any) {
|
||||
return this.novoProvedorProvider.authenticate(dados);
|
||||
}
|
||||
```
|
||||
|
||||
4. Adicione a rota no `AuthController`.
|
||||
|
||||
5. Se o provedor precisar de configuração, adicione as variáveis no `AuthConfigService` e no `.env`.
|
||||
|
||||
---
|
||||
|
||||
## Diagnóstico de problemas
|
||||
|
||||
### Login LDAP falha com `UnauthorizedException`
|
||||
|
||||
- Verifique se `LDAP_URL` está acessível a partir do servidor backend
|
||||
- Confirme que `LDAP_DOMAIN` ou `LDAP_USER_DN_TEMPLATE` está correto
|
||||
- Teste a conectividade: `ldapsearch -H ldaps://servidor:636 -x`
|
||||
- Verifique `LDAP_TIMEOUT_MS` — servidores lentos podem estar expirando
|
||||
- O erro é genérico intencionalmente para não vazar informações. Adicione um `console.log(_error)` temporário no `catch` do `ldap-auth.provider.ts` para ver o erro real
|
||||
|
||||
### Login Microsoft falha com `400 Bad Request`
|
||||
|
||||
- O state expirou (padrão: 10 minutos). Se o usuário demorou muito na tela da Microsoft, repita o fluxo
|
||||
- Verifique se `MICROSOFT_REDIRECT_URI` no `.env` é idêntico ao cadastrado no Azure App Registration
|
||||
- Confirme que `MICROSOFT_CLIENT_ID` e `MICROSOFT_CLIENT_SECRET` estão corretos e não expiraram
|
||||
|
||||
### Token inválido no frontend
|
||||
|
||||
- Verifique se `JWT_SECRET` não mudou entre deploys — isso invalida todos os tokens emitidos anteriormente
|
||||
- Confirme que o frontend está enviando o header `Authorization: Bearer <token>`
|
||||
|
||||
### `GET /auth/config` retorna os provedores errados
|
||||
|
||||
- Verifique `LDAP_ENABLED` e `MICROSOFT_ENABLED` no `.env`
|
||||
- Reinicie o servidor — variáveis de ambiente são lidas na inicialização
|
||||
|
||||
---
|
||||
|
||||
## O que ainda falta para produção
|
||||
|
||||
- [ ] Tabela `users` no banco de dados
|
||||
- [ ] Tabela `auth_identities` para vincular provedores externos ao usuário interno
|
||||
- [ ] `sub` do JWT usando ID interno do banco, não email externo
|
||||
- [ ] Guard NestJS para proteger rotas privadas (`@UseGuards(AuthGuard)`)
|
||||
- [ ] Roles e permissões
|
||||
- [ ] Auditoria de login
|
||||
- [ ] Trocar token na query string por cookie HTTP-only (reduz exposição no browser)
|
||||
|
||||
---
|
||||
|
||||
## Documentacao complementar
|
||||
|
||||
A sincronizacao de usuarios autenticados com o banco, os perfis de acesso, as areas operacionais e os endpoints administrativos estao documentados em:
|
||||
|
||||
- [`access-control.md`](./access-control.md)
|
||||
@ -1,132 +0,0 @@
|
||||
# Modulo de Chat WhatsApp (Backend)
|
||||
|
||||
## Visao geral
|
||||
|
||||
O modulo de WhatsApp do backend e desenvolvido em **NestJS** e utiliza a biblioteca **whatsapp-web.js** (que roda uma instancia headless do Chromium via **Puppeteer**) para integrar a aplicacao diretamente com o WhatsApp Web em tempo real.
|
||||
|
||||
A arquitetura e constituida por quatro pilares:
|
||||
1. **Puppeteer Client**: Controla o WhatsApp Web, gera o QR Code para autenticacao e escuta eventos de novas mensagens.
|
||||
2. **WebSocket Gateway**: Transmite eventos em tempo real (novas mensagens, atualizacao de status) para o frontend usando Socket.io.
|
||||
3. **Persistencia Hibrida**: Mantem conversas indexadas localmente via JSON para performance e o status de atribuicao de atendimento gravado no banco relacional (PostgreSQL).
|
||||
4. **Servico de Atribuicao**: Gerencia o vinculo dos chats com os atendentes (`usuarios`) e suas respectivas `areas` operacionais.
|
||||
|
||||
---
|
||||
|
||||
## Fluxo de Eventos e Mensagens
|
||||
|
||||
### 1. Inicializacao e Conexao
|
||||
* O backend inicia o cliente do `whatsapp-web.js` na porta configurada.
|
||||
* Se nenhuma sessao ativa for encontrada na pasta `/whatsapp-session`, o cliente gera um QR Code em formato Base64.
|
||||
* Esse QR Code e enviado via WebSocket (`qr`) para o frontend configurar o dispositivo.
|
||||
* Uma vez conectado, o status muda para `CONNECTED` e a pasta de sessao e gravada localmente.
|
||||
|
||||
### 2. Captura de Mensagens (`message_create`)
|
||||
Utilizamos o evento global `message_create` para capturar tanto mensagens recebidas do cliente quanto mensagens enviadas pelo proprio atendente (seja pela tela ou por outro dispositivo sincronizado):
|
||||
|
||||
```text
|
||||
Puppeteer (Message)
|
||||
-> Trata de-duplicacao ou broadcast
|
||||
-> Se possuir midia, baixa os buffers em tempo real
|
||||
-> Transmite via WebSocket 'message' para o frontend
|
||||
-> Salva ou atualiza a conversa na persistencia local JSON
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Persistencia e Banco de Dados
|
||||
|
||||
### 1. Cache Local JSON (`whatsapp-chats-persist.json`)
|
||||
Para evitar sobrecarregar o banco relacional e garantir latencias imperceptiveis de scroll, os chats e seus metadados de visualizacao sao armazenados de forma persistente em um arquivo JSON local na raiz do backend.
|
||||
|
||||
### 2. Tabela de Atribuicao de Chat (`whatsapp_chat_atribuicoes`)
|
||||
O controle de quem esta atendendo qual chat e estritamente transacional e reside no banco PostgreSQL.
|
||||
|
||||
A estrutura da tabela e criada pela migration `004_whatsapp.sql`:
|
||||
|
||||
```sql
|
||||
CREATE TABLE IF NOT EXISTS whatsapp_chat_atribuicoes (
|
||||
id SERIAL PRIMARY KEY,
|
||||
chat_id VARCHAR(255) NOT NULL,
|
||||
user_id SERIAL REFERENCES usuarios(id) ON DELETE CASCADE,
|
||||
area_id SERIAL REFERENCES areas(id) ON DELETE SET NULL,
|
||||
assigned_at TIMESTAMP WITH TIME ZONE DEFAULT CURRENT_TIMESTAMP,
|
||||
UNIQUE(chat_id)
|
||||
);
|
||||
```
|
||||
|
||||
#### Regras de Atribuicao:
|
||||
* `chat_id`: Identificador unico da conversa no WhatsApp (ex: `5511999999999@c.us` ou `...@lid`).
|
||||
* `user_id`: ID inteiro (`usuarios.id`) do atendente que assumiu.
|
||||
* `area_id`: ID inteiro (`areas.id`) do setor sob o qual o atendimento esta sendo prestado (ex: `1` para Suporte).
|
||||
|
||||
---
|
||||
|
||||
## Endpoints do Modulo
|
||||
|
||||
Base path: `/whatsapp`
|
||||
|
||||
### 1. Enviar Mensagem
|
||||
```http
|
||||
POST /whatsapp/send
|
||||
Content-Type: application/json
|
||||
```
|
||||
**Payload**:
|
||||
```json
|
||||
{
|
||||
"to": "5511999999999@c.us",
|
||||
"message": "Ola, tudo bem?",
|
||||
"media": {
|
||||
"data": "base64String...",
|
||||
"mimetype": "image/png",
|
||||
"filename": "comprovante.png"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Atribuir Chat
|
||||
```http
|
||||
POST /whatsapp/assign
|
||||
Content-Type: application/json
|
||||
```
|
||||
**Payload**:
|
||||
```json
|
||||
{
|
||||
"chatId": "5511999999999@c.us",
|
||||
"userId": 4,
|
||||
"areaId": 1
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Liberar Chat
|
||||
```http
|
||||
DELETE /whatsapp/release/:chatId
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Limitacoes e Solucoes de Bugs
|
||||
|
||||
### 1. Payload Too Large (Upload de Midia)
|
||||
Para permitir o envio de imagens, videos e audios pesados codificados em Base64, o limite padrao de payload do NestJS foi estendido para **50MB** no `main.ts` tanto para formato JSON quanto para `urlencoded`.
|
||||
|
||||
### 2. Nomes Numericos do WhatsApp (Smart Name Resolution)
|
||||
Devido a latencias do WhatsApp Web, as mensagens recebidas as vezes reportam apenas o telefone/JID como nome do contato. O servico de WhatsApp contem uma camada reativa de reparacao automatica:
|
||||
* Checa se o nome e puramente numerico.
|
||||
* Se for, faz uma chamada em background para o Puppeteer (`client.getContactById`) para obter o `notifyName` real do cliente e atualizar o cache local.
|
||||
|
||||
---
|
||||
|
||||
## Como Rodar e Testar
|
||||
|
||||
### Requisitos locais
|
||||
* Node.js v18+
|
||||
* PostgreSQL ativo com as migrations executadas
|
||||
* Google Chrome ou Chromium instalado (o Puppeteer tentara usar o bundle local se omitido)
|
||||
|
||||
### Executando em desenvolvimento
|
||||
```bash
|
||||
cd backend
|
||||
npm run dev
|
||||
```
|
||||
|
||||
Os logs do NestJS no terminal indicarao as fases de inicializacao do Puppeteer, geracao de QR Code ou recuperacao de sessao ativa.
|
||||
Loading…
Reference in New Issue
Block a user