omnichannel-backend/README.md

# Omnichannel Backend

![Node.js](https://img.shields.io/badge/Node.js-20.x-green)
![NestJS](https://img.shields.io/badge/NestJS-11.x-red)
![TypeScript](https://img.shields.io/badge/TypeScript-6.x-blue)
![PostgreSQL](https://img.shields.io/badge/Database-PostgreSQL-blue)
![Socket.IO](https://img.shields.io/badge/Realtime-Socket.IO-black)
![JWT](https://img.shields.io/badge/Auth-JWT-orange)
![WhatsApp](https://img.shields.io/badge/Channel-WhatsApp-25D366)

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, com Puppeteer/Chrome para controlar o WhatsApp Web
- 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`.

Para usar o canal WhatsApp, o backend tambem precisa conseguir iniciar Chrome/Chromium.

O `whatsapp-web.js` usa Puppeteer para abrir o WhatsApp Web em modo headless, autenticar por QR Code e manter a sessao local em `whatsapp-session`.

Em ambiente Docker/producao, persista esse diretorio em volume para nao perder a sessao a cada recriacao do container.

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`.