AutoFluxos
Automação de atendimento no WhatsApp. Você desenha o fluxo, o bot conduz a
conversa, o lead cai numa tela. IA é opcional.
Produto da 4YU.
Banco de produção compartilhado: AutoFluxos e Verandi usam o mesmo projeto
Supabase. O AutoFluxos mora em public; a Verandi, em app_verandi. Antes de
mexer em migration, Auth, RLS, Storage, extensão ou Data API, leia
docs/BANCO-COMPARTILHADO.md. Nunca rode
supabase db push contra produção.
Estado
Produto-base construído e expansão 0–5 concluída. Dá para desenhar o fluxo arrastando
blocos, testar a conversa ao lado, publicar (versão numerada e imutável), receber
mensagem pelo webhook e ver o lead cair na tela com o que o bot coletou. O que
resta está consolidado no plano mestre; parte é código e
parte depende das liberações da Meta.
No ar em https://autofluxos.4yu.com.br (painel protegido por senha).
Retomando o trabalho — humano ou agente? Comece por
docs/ESTADO.md. A seção "Leia isto primeiro" tem o estado
atual, as três regras que não se quebram, a fila do que fazer em seguida, e as
armadilhas que já custaram caro nesta base.
Para escolher e executar a próxima atividade, use
docs/PLANO-MESTRE.md, que reúne dívida, expansão,
gatilhos externos e critérios de aceite sem duplicar tarefas concluídas.
Veja docs/ARQUITETURA.md para o desenho completo e as
decisões por trás dele. O que o bot já responde sobre a agenda do cliente — e o
que ainda não — está em docs/PLANO-AGENDA.md.
Rodando
npm install
cp .env.example .env # valores em 4yu-apps/.secrets/4yu.env (prefixo AUTOFLUXOS_)
npm run dev # http://localhost:3000
npm test # 252 testes
npm run typecheck
Não precisa de Docker. O banco é Supabase na nuvem (projeto autofluxos,
região São Paulo).
Sem .env os testes que falam com o banco se pulam sozinhos, e o resto roda
normal — dá para clonar e rodar npm test sem credencial nenhuma.
Banco
Migrations em supabase/migrations/, aplicadas pela
Management API do Supabase.
Este não é mais um projeto Supabase exclusivo. A Verandi usa o mesmo projeto de
produção no schema app_verandi; os objetos deste produto permanecem em
public. Auth, Storage, extensões, Data API, cotas e backup são compartilhados.
A fonte de verdade operacional é
docs/BANCO-COMPARTILHADO.md.
A última migration atual é 0011; a próxima é 0012. Não reutilize os
números antigos citados em planos. Nunca aplique migrations da Verandi por este
repositório e nunca use supabase db push em produção.
clients, flows e flow_versions (passos 3 e 5); channels, contacts,
sessions, messages e handoffs (passo 6, criadas só quando já se sabia o
formato real do que o WhatsApp manda — tabela criada "por garantia" e nunca
usada só acumula divergência entre o desenho e o código).
A tela de leads lê a view leads (0004), que junta o contato com a última
mensagem e o handoff aberto. Ela é security_invoker = true: view é o jeito
clássico de furar RLS sem perceber, e sem isso a chave que vai para o navegador
leria a conversa de todo mundo.
RLS está ligada e sem nenhuma política, de propósito. A chave publishable
(que pode chegar ao navegador) não lê nem escreve nada; todo acesso passa pelo
servidor com a chave secret. Enquanto não existir login, esse é o estado
seguro. As políticas entram junto com o login, e não antes.
O editor
Abra um cliente → um fluxo. A tela tem três partes: a barra de blocos à
esquerda, o desenho no meio, e à direita duas abas — Bloco (editar o que
está selecionado) e Testar (conversar com o fluxo).
Para ramificar, arraste a bolinha ao lado de uma opção até o bloco de destino.
A setinha que você arrasta É a ramificação — não existe tela de configurar
branch em lugar nenhum.
Salva sozinho depois de uma pausa na digitação. Rascunho pela metade pode ser
salvo; o que o validador barra é a publicação.
Publicar
O rascunho é mutável e é o que você edita. Publicar tira uma foto dele e
guarda numa linha de flow_versions numerada que o banco se recusa a alterar —
não por convenção, por gatilho.
Por que isso importa: sem versão, você edita o fluxo às 15h e a conversa que
começou às 14h se vê num bloco que não existe mais. Quebra silenciosa, difícil de
reproduzir, e quem descobre é o cliente.
O botão só habilita se o validador deixar, mas a checagem de verdade está no
servidor (publicar() no repo). Botão desabilitado é conveniência; um fluxo
sem saída para humano tem que ser recusado venha a chamada de onde vier.
A aba Testar conversa com o fluxo em memória, então dá para experimentar
uma mudança antes de ela ser salva. Coisas que vale testar:
- escrever “quero falar com um atendente” a qualquer momento
- clicar no 🎤 para ver o que acontece quando a pessoa manda áudio
- responder “2” em vez de clicar no botão
- digitar besteira três vezes seguidas
Integrar com o sistema do cliente
O bloco API chama um endereço durante a conversa, guarda pedaços da resposta
em variáveis e segue o fluxo. É um bloco só, e é de propósito: ele cobre planilha
do Sheets (via Apps Script publicado), qualquer webhook, e n8n/Make/Zapier — que
sozinhos carregam os milhares de apps que nunca vamos integrar na mão.
Ele nasce chamando o ViaCEP, então dá para arrastar o bloco e ver a integração
respondendo na aba Testar antes de configurar qualquer coisa.
Três coisas que o produto garante, e que não dependem de quem desenha lembrar:
- A aba Testar chama de verdade. É o mesmo código da produção. Os disparos
vindos dali levam o cabeçalho
X-AutoFluxos-Teste: 1, para o sistema do
cliente separar teste de movimento real.
- Endereço interno é recusado no servidor, olhando o IP resolvido e não o
nome, inclusive a cada redirecionamento. A conexão é fixada nesse IP, então
não sobra segunda resolução para um atacante trocar (DNS rebinding).
- Credencial não acompanha redirecionamento para outro host, e nem o corpo
com o lead dentro.
- Falha não pendura ninguém. Por padrão a conversa vai para uma pessoa com o
motivo real;
continua mesmo assim é escolha explícita, para enriquecimento
que pode faltar sem prejuízo.
Para o que pede chave — CRM, ERP —, existem as Credenciais. Cada cliente
cadastra as dele uma vez, o bloco aponta pela referência, e o valor mora num
cofre fora do banco. Não existe campo onde digitar token dentro do fluxo, então
ele não tem como entrar na versão publicada, que é imutável. Trocar a chave
depois não exige republicar nada.
O desenho está em docs/NO-API.md e docs/CONEXOES.md.
A regra que sustenta o projeto
src/core/ não sabe o nome de nenhum cliente, não importa nada de Next, do
WhatsApp ou do banco, e não faz chamada de rede. Tudo que ele precisa entra por
parâmetro; tudo que ele decide sai no retorno.
executar(fluxo, sessao, entrada) → { acoes, sessao }
Consequências práticas:
- o simulador e a produção rodam o mesmo código — não existe "no teste funcionava"
- o motor tem teste unitário rodando em milissegundos, sem WhatsApp e sem banco
- roda em serverless, porque não existe estado vivo na memória
Quando alguém pedir uma feature, o teste é: isso é um nó/configuração, ou é
um cliente específico? Se for cliente específico, vai para o JSON do fluxo —
nunca para o src/.
Como um fluxo se parece
O formato é o nativo do React Flow, sem camada de tradução. A aresta que você
arrasta no editor é a ramificação:
{
"inicio": "boas-vindas",
"nodes": [
{ "id": "boas-vindas", "type": "mensagem", "position": { "x": 0, "y": 0 },
"data": { "texto": "Oi! Sou o assistente virtual 👋" } },
{ "id": "assunto", "type": "pergunta", "position": { "x": 0, "y": 160 },
"data": { "texto": "O que você procura?", "salvarEm": "assunto",
"opcoes": [{ "id": "orcamento", "rotulo": "Orçamento" }] } }
],
"edges": [
{ "id": "e1", "source": "boas-vindas", "target": "assunto" },
{ "id": "e2", "source": "assunto", "sourceHandle": "orcamento", "target": "..." }
]
}
Sete tipos de nó: mensagem, pergunta, condicao, salvar-campo, ia,
handoff, http.
Garantias que o motor dá de graça
Ninguém precisa lembrar de desenhar isso — o sistema faz sozinho:
- Escape global: "atendente", "humano", "falar com alguém" transferem de
qualquer ponto do fluxo
- Anti hello-loop: na 3ª resposta que o bot não entende, vai para uma pessoa
- Áudio, imagem e documento vão direto para uma pessoa — nunca "não entendi"
- Ciclo no desenho estoura uma trava e chama humano, em vez de prender alguém
- O validador recusa publicar fluxo que não tenha nenhum caminho até um humano
- Integração que falha não deixa ninguém pendurado: por padrão a conversa vai
para uma pessoa, com o motivo real já escrito no painel de leads
Segredo
Este repositório é público. .env está no .gitignore e chave nenhuma entra
aqui — nem temporariamente. Em produção a chave de IA é do cliente (BYOK) e mora
no Supabase Vault; o banco guarda só uma referência.
Veja .env.example para os nomes das variáveis.
