Adicionar RunBook

RunBook.md

@@ -0,0 +1,168 @@
+# Runbook
+
+Procedimentos para incidentes e operacao do Omnichannel.
+
+## Sistema fora do ar
+
+1. Verificar containers da aplicacao:
+
+```bash
+docker compose ps
+```
+
+2. Ver logs:
+
+```bash
+docker compose logs --tail=200 backend
+docker compose logs --tail=200 frontend
+```
+
+3. Reiniciar servico especifico:
+
+```bash
+docker compose restart backend
+```
+
+## Backend nao sobe
+
+Verificar:
+
+- variaveis `.env.development`;
+- conexao com PostgreSQL externo;
+- porta 4001 ocupada;
+- erro de build TypeScript;
+- conectividade com LDAP/AD, se usado na inicializacao/fluxo.
+
+Comandos:
+
+```bash
+docker compose logs -f backend
+docker compose build backend
+```
+
+## Banco externo indisponivel
+
+O banco nao roda dentro deste compose. Validar fora do Docker:
+
+```bash
+psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" -c "select 1"
+```
+
+Verificar:
+
+- host e porta;
+- firewall;
+- credenciais;
+- permissao de conexao remota no PostgreSQL;
+- rota de rede entre VM/container e banco.
+
+## Migrations nao aplicadas
+
+Sintoma:
+
+- erro de tabela/coluna inexistente;
+- admin nao carrega usuarios;
+- WhatsApp assignment falha;
+- conteudos da IA ou agenda falham.
+
+Confirmar schema:
+
+```bash
+psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" -c "\dt"
+```
+
+Aplicar migrations em ordem:
+
+```bash
+for file in database/migrations/*.sql; do
+  psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" -f "$file"
+done
+```
+
+## WhatsApp desconectado
+
+Sintomas:
+
+- `/whatsapp/status` nao esta conectado;
+- frontend pede QR Code;
+- mensagens nao chegam.
+
+Acao:
+
+1. Abrir tela admin `/admin/whatsapp`.
+2. Ler QR Code.
+3. Ver logs do backend.
+4. Se travado, reiniciar backend.
+
+```bash
+docker compose restart backend
+```
+
+Se persistir, limpar sessao WhatsApp conforme volume configurado.
+
+## Login LDAP falhando
+
+Verificar:
+
+- usuario/senha;
+- conectividade da VM com LDAP;
+- `LDAP_URL`;
+- `LDAP_USER_DN_TEMPLATE`;
+- certificado LDAPS;
+- tempo de resposta do AD.
+
+Logs:
+
+```bash
+docker compose logs backend | grep -i ldap
+```
+
+## Login Microsoft falhando
+
+Verificar:
+
+- redirect URI no Entra ID;
+- `MICROSOFT_CLIENT_ID`;
+- `MICROSOFT_CLIENT_SECRET`;
+- `MICROSOFT_SUCCESS_REDIRECT_URL`;
+- hora do servidor.
+
+## Frontend sem dados
+
+Verificar:
+
+- `VITE_API_URL`;
+- CORS `FRONTEND_URL`;
+- backend ativo;
+- console do navegador;
+- rota de rede entre navegador e backend.
+
+## Fazer backup emergencial
+
+```bash
+pg_dump "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" > backup-emergencial.sql
+```
+
+## Restaurar backup
+
+Somente com janela de manutencao:
+
+```bash
+docker compose stop backend
+psql "postgresql://$DB_USER:$DB_PASSWORD@$DB_HOST:$DB_PORT/$DB_NAME" < backup-emergencial.sql
+docker compose up -d backend
+```
+
+## Escalar para desenvolvimento
+
+Abrir issue com:
+
+- horario do erro;
+- ambiente;
+- usuario afetado;
+- chatId se for WhatsApp;
+- print da tela;
+- logs backend;
+- acao tentada;
+- ultima migration aplicada;
+- commit/versao em execucao.