Connections
Status: 🟡 Em fluxo (hub centralizado de status — sem tabelas próprias) Code: backend/app/modules/connections UI: frontend/src/app/(admin)/[slug]/admin/connections Última revisão deste doc: 2026-05-13 por Felipe + Claude Dependências fortes: lê de whatsapp/instagram/billing/settings (não escreve)
1. Identidade
O que faz (uma frase)
Hub read-only que agrega status de integrações (WhatsApp Evolution/Meta Cloud, Instagram, Email Brevo, Video Daily/Bunny, Billing Asaas) — exibe num lugar só "o que está conectado, qual saúde, se token expirou".
Por que existe (negócio)
Sem este módulo, Felipe abre 5 telas diferentes pra ver se tudo está funcionando. Com Connections:
- 1 página
/admin/connectionsmostra tudo. - Health Evolution (score por instância).
- Meta Cloud token válido?
- Instagram conta ativa?
- Daily/Bunny configurados?
Status atual
Em fluxo — base read-only funciona, mas writes ainda delegados aos módulos donos (whatsapp, settings).
Próxima mudança: OAuth flows centralizados aqui (hoje espalhados).
2. Cases de uso reais
Case 1: Felipe verifica saúde de tudo
UI /admin/connections → backend chama:
- WhatsApp:
whatsapp_provider_account+whatsapp_provider_health(score por account). - Instagram:
instagram_accountativos. - Email: env var Brevo configurada?
- Video: env vars Daily + Bunny.
- Billing:
tenant_provider_credentialsprovider=asaas status=active.
Página mostra cards verde/amarelo/vermelho.
3. Oportunidades de negócio
- Centralized OAuth flows: hoje espalhados, mover pra Connections seria UX killer.
- Health alerts: se algo degrada, notify admin.
- Multi-provider per tenant: suportar N providers de email/billing.
4. Arquitetura interna
Arquivos
routes.py— 7 endpoints.service.py— funções de status.
Tasks
Sem Celery. Status sob demanda.
5. Tabelas
0 tabelas próprias. Lê de:
whatsapp_provider_account+whatsapp_provider_healthinstagram_accounttenant_provider_credentials
6. API / Endpoints (7)
Prefixo /api/connections.
| Método | Rota | O que faz |
|---|---|---|
| GET | /whatsapp | Lista instâncias com status real (queries Evolution ou Meta Cloud Graph API) |
| POST | /whatsapp | Cria nova instância (Evolution ou Meta Cloud) |
| PATCH | /whatsapp/{id} | Atualiza label ou is_active |
| GET | /instagram | Status conta IG conectada |
| GET | /email | Provedor configurado (Brevo/SMTP/etc.) |
| GET | /video | {daily_configured, bunny_configured} |
| GET | /billing | {provider: "asaas", configured: bool} |
7. Configuração
Env vars (consumidas, não definidas)
- WhatsApp:
EVOLUTION_API_URL,EVOLUTION_API_KEY. - Email:
EMAIL_PROVIDER,BREVO_SENDER_EMAIL. - Video:
DAILY_API_KEY,BUNNY_STREAM_API_KEY.
8. Operações + Troubleshooting
Sintoma: Health WhatsApp stale
Causa: whatsapp_provider_health.checked_at > 1h.
Fix: UI deve avisar "última check em X minutos". Trigger manual via whatsapp.tasks.score_health_all.
Sintoma: Meta Cloud HTTP timeout em GET /connections/whatsapp
Causa: Service faz HTTP síncrono pra Graph API. Fix: Refactor pra async queue futuro.
9. Limitações e débitos técnicos
| # | Item |
|---|---|
| 1 | Read-only — writes em outros módulos |
| 2 | Meta Cloud HTTP síncrono — pode timeout |
| 3 | Health stale |
| 4 | Email provider singular |
| 5 | Sem OAuth centralizado |
10. Histórico
Em fluxo desde Suite v2. Refactor pra OAuth centralizado é roadmap.