omnichannel-deploy/README.md

# Omnichannel Sothis

Plataforma omnichannel para atendimento com foco inicial em WhatsApp. O sistema combina atendimento em tempo real, Agente Virtual para triagem, filas por especialidade, abertura ativa por template, agenda de contatos, painéis operacionais e administração de usuários/perfis.

O projeto foi construído para validar e evoluir um MVP de atendimento corporativo, com perfis de agente, supervisor e administrador.

## Clonando o Projeto

Este repositório funciona como o repositório de deploy/orquestração. O backend e o frontend ficam em repositórios separados e devem ser clonados dentro das pastas esperadas pelo `docker-compose.yml`.

Em uma pasta vazia:

```bash
git clone https://chaleiradev.sothistelecom.com/Sothis/omnichannel-deploy.git .
git clone https://chaleiradev.sothistelecom.com/Sothis/omnichannel-backend.git backend
git clone https://chaleiradev.sothistelecom.com/Sothis/omnichannel-frontend.git frontend
```

Ao final, a estrutura deve ficar assim:

```txt
omnichannel/
├── backend/
├── frontend/
├── database/
├── docker-compose.yml
└── README.md
```

## Principais Recursos

- Login corporativo via LDAP/Active Directory.
- Estrutura para Microsoft OAuth / Entra ID.
- JWT próprio da aplicação com perfis e especialidades.
- Atendimento WhatsApp em tempo real via `whatsapp-web.js`.
- Socket.IO para atualização de chats/mensagens.
- Agente Virtual Sothis para triagem e roteamento.
- Fila por especialidade.
- Assumir, liberar, transferir e fechar atendimento.
- Abertura ativa com templates aprovados.
- Agenda de contatos com WhatsApp, telefone/SMS, email, etiqueta e observação.
- Painel do agente.
- Painel operacional do supervisor.
- Painel administrativo com usuários, acessos, templates, IA, canais e configurações.
- Conteúdos da IA e regras/travas.
- Migrations SQL versionadas.

## Stack Técnica

### Backend

- Node.js 20+ recomendado.
- NestJS `^11.1`.
- TypeScript `^6.0`.
- PostgreSQL via `pg`.
- Socket.IO `^4.8`.
- `whatsapp-web.js` `^1.34`.
- LDAP via `ldapts`.
- JWT via `jsonwebtoken`.
- Logs com `winston`.

### Frontend

- React `^18.3`.
- Vite `^5.4`.
- React Router `^6.30`.
- Socket.IO Client `^4.8`.

### Banco

- PostgreSQL 16 recomendado.
- O banco não é gerenciado pelo `docker-compose.yml` deste repositório.
- As migrations ficam em `database/migrations`.

### Docker

O Docker Compose da raiz sobe somente:

- `backend`
- `frontend`

O banco deve ser externo ao compose: VM, banco corporativo, RDS, container separado ou PostgreSQL local gerenciado fora deste projeto.

## Estrutura do Repositório

```txt
omnichannel/
├── backend/              # API NestJS e regras de negócio
├── frontend/             # Interface React/Vite
├── database/migrations/  # Migrations SQL
├── docs/                 # Wiki operacional e arquitetura
├── docker-compose.yml    # Sobe backend e frontend
└── README.md
```

## Como Subir com Docker Compose

1. Configure `.env.development` na raiz com os dados do banco externo.
2. Garanta que o PostgreSQL externo esteja acessível a partir do container backend.
3. Suba backend e frontend:

```bash
docker compose up -d --build
```

URLs padrão:

- Frontend: `http://localhost:4000`
- Backend: `http://localhost:4001`

Health:

```bash
curl http://localhost:4001/health
```

## Deploy Automatizado

O deploy deve seguir pelo Gitea Actions. O antigo fluxo manual via arquivo `.bat` não faz mais parte do processo recomendado.

Responsabilidades esperadas da pipeline:

- baixar/clonar os repositórios necessários;
- configurar variáveis de ambiente do ambiente alvo;
- buildar backend e frontend;
- subir os serviços com Docker Compose;
- executar validações pós-deploy;
- não gerenciar o banco dentro do compose.

## Como Rodar em Desenvolvimento

Backend:

```bash
cd backend
npm install
npm run dev
```

Frontend:

```bash
cd frontend
npm install
npm run dev
```

URLs comuns:

- Frontend Vite: `http://localhost:5173`
- Backend: `http://localhost:3001`

## Banco e Migrations

As migrations SQL estão em:

```txt
database/migrations
```

Elas representam a intenção de schema final/evolutivo do produto, mas o projeto ainda precisa de um runner formal para aplicar tudo em ordem em ambientes novos.

Para ambiente novo, antes de subir backend para uso real:

1. criar o banco PostgreSQL;
2. aplicar as migrations em ordem;
3. validar tabelas principais;
4. criar/atribuir usuário admin;
5. subir backend e frontend.

Detalhes em:

- [Deploy e operação](./docs/deploy.md)
- [Database](./backend/docs/database.md)

## Documentação

Wiki raiz:

- [docs/README.md](./docs/README.md)
- [Deploy e operação](./docs/deploy.md)
- [Arquitetura geral](./docs/arquitetura.md)
- [Fluxos end-to-end](./docs/fluxos-end-to-end.md)
- [Regras de negócio](./docs/regras-negocio.md)
- [ADRs](./docs/adrs.md)
- [Ambientes](./docs/ambientes.md)
- [Runbook](./docs/runbook.md)

Backend:

- [backend/docs/README.md](./backend/docs/README.md)
- [Auth](./backend/docs/auth.md)
- [WhatsApp](./backend/docs/whatsapp.md)
- [Admin](./backend/docs/admin.md)
- [Swagger/OpenAPI](./backend/docs/swagger.md)

## Estado Atual e Próximos Passos

O produto já foi validado em demo com cliente final. Antes de produção real, os principais fechamentos são:

- implementar guards JWT no backend;
- validar autorização por perfil no backend;
- formalizar runner de migrations;
- configurar backup/restore do banco externo;
- persistir sessão WhatsApp em volume;
- criar Swagger com DTOs;
- adicionar testes nos fluxos críticos.