> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pingoai.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# Flow Builder completo

> Guia completo do Flow Builder: tipos de no, execucao, mapeamentos e boas praticas.

## Visao geral

O Flow Builder do ExclusiveDay tem duas camadas importantes:

* **Editor visual (frontend)**: onde o time monta os nós e conexões.
* **Engine de execucao (backend/channel)**: onde o fluxo roda de verdade.

Arquivos-chave:

* Editor: `frontend/src/pages/FlowBuilderEditor/index.js`
* Engine principal de nos (channel): `channel-2/src/services/flow/runner.ts`
* Registro de handlers de nos (channel): `channel-2/src/services/flow/nodes/index.ts`
* Normalizacao do diagrama: `channel-2/src/services/flow/utils/flow.utils.ts`
* Runner alternativo/simulacao (backend): `Backend-1/src/services/FlowBuilderServices/FlowRunner.ts`

## Como a execucao funciona (channel)

1. Carrega o diagrama (`nodes`, `edges`, `validation`).
2. Inicializa variaveis de contexto (`flow.user`, `flow.ticket`, `flow.channel`, saudacao, datas).
3. Identifica o no `start`.
4. Executa no atual e escolhe proximo target.
5. Para nós que aguardam resposta, salva contexto de espera em sessao.
6. Quando o usuario responde, retoma no target correspondente.
7. Encerra no `endFlow` (limpa sessao e finaliza trace).

## Tipos de no no editor (frontend)

Lista declarada em `NODE_TYPES` no `FlowBuilderEditor`:

* `aiAgent` (AI Agent)
* `message` (Mensagem)
* `cta` (CTA)
* `hsm` (Template HSM)
* `interactive` (Botoes/Listas)
* `carousel` (Carrossel)
* `tag` (Tags)
* `queueTransfer` (Transferir Atendimento)
* `closeTicket` (Finalizar Atendimento)
* `randomizer` (Distribuidor)
* `condition` (Condicao)
* `delay` (Delay)
* `api` (API Externa)
* `webhook` (Webhook)
* `variable` (Variavel)
* `flowEnd` (Fim do Fluxo)

## O que cada no faz na execucao

### `start`

* inicia trace do fluxo
* escolhe target `success` (ou `next`)
* passa para o primeiro no funcional

Handler: `nodes/start/index.ts`

### `message`

* envia texto e/ou midia por canal
* suporta blocos e formatos de mensagem
* pode ativar espera de resposta (`waitResponse`/`returnOptions`)
* pode configurar inatividade e fallback por tempo

Handler: `nodes/message/index.ts`

### `interactive` (botoes/listas)

* envia mensagem interativa (buttons/list)
* limita botoes e linhas conforme payload montado
* grava sessao aguardando resposta do usuario
* resposta selecionada determina o proximo target

Handler: `nodes/interactive/index.ts`

### `tag` (tags do contato/ticket)

* vincula tags ao contato do ticket
* evita duplicar tags existentes
* segue para `success` (ou fallback)

Handler: `nodes/tagTicket/index.ts`

### `queueTransfer`

* transfere ticket para fila/usuario/status
* atualiza tracking do ticket
* pode emitir notificacao socket

Handler: `nodes/ticketTransfer/index.ts`

### `closeTicket`

* fecha ticket (`status: closed`)
* atualiza tracking de finalizacao
* emite evento de remocao no socket

Handler: `nodes/closeTicket/index.ts`

### `condition`

* avalia condicoes com comparadores (`eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `contains`, etc.)
* escolhe branch por indice (`condition-0`, `condition-1`, ...)
* usa `else` quando nenhuma condicao casa

Handler: `nodes/conditional/index.ts`

### `delay`

* aguarda tempo configurado (segundos na engine do channel)
* depois segue para `next`

Handler: `nodes/waitTime/index.ts`

### `variable`

* grava/atualiza variaveis de fluxo em sessao
* permite reaproveitar dados em nos seguintes

Handler: `nodes/flowVariable/index.ts`

### `saveMessage` (captura resposta)

* salva resposta do usuario em variavel customizada
* pode atualizar campos padrao (nome/email) e custom fields
* segue para `success`

Handler: `nodes/saveMessage/index.ts`

### `randomizer` / `split`

* distribui caminho por percentual/peso
* escolhe target com base probabilistica

Handler: `nodes/split/index.ts`

### `jump`

* salta para outro flow publicado
* carrega snapshot do flow destino
* opcionalmente retorna ao fluxo original

Handler: `nodes/jump/index.ts`

### `chatgpt`

* chama API de completions da OpenAI
* salva resposta no contexto para proximo no
* segue por `success` ou `error`

Handler: `nodes/chatgpt/index.ts`

### `endFlow` / `flowEnd`

* encerra fluxo e trace
* limpa sessoes relacionadas
* ajusta ticket para estado de saida (pending no handler atual)

Handler: `nodes/endFlow/index.ts`

## Nos presentes no editor mas sem handler dedicado no channel

No registro `nodes/index.ts`, estes tipos estao em **genericHandler** (placeholder):

* `json`
* `request`
* `dbQuery`
* `graphql`
* `code`
* `smtp`
* `closeTicket` (existe handler dedicado em arquivo separado, mas no indice atual aparece generic)
* `split` (existe handler dedicado em arquivo separado, mas no indice atual aparece generic)
* `timeInterval`

Observacao importante:

* o editor mostra tipos como `api`, `webhook`, `cta`, `hsm`, `carousel`, `aiAgent`.
* para esses tipos, parte do comportamento pode depender de normalizacao/conversao de tipo e/ou fallback.
* em producao, sempre validar o caminho real no diagrama salvo (`validation`) e nos logs do runner.

## Diferenca entre runner do channel e runner do backend

Existe tambem um runner em `Backend-1/src/services/FlowBuilderServices/FlowRunner.ts`:

* cobre fluxo simplificado (`start`, `message`, `condition`, `delay`, `end`)
* trata `cta`/`interactive` no bloco de mensagem simplificada
* usado em cenarios especificos de execucao/simulacao

Para fluxos ricos (com handlers de nos de integracao), o canal `channel-2` e a referencia principal.

## Boas praticas para construir fluxos

* sempre comecar por um `start` claro
* manter um caminho de erro/fallback por no critico
* em `condition`, nomear condicoes e revisar targets
* usar `variable` + `saveMessage` para contexto explicito
* evitar loops sem `delay` ou condicao de saida
* sempre fechar com `flowEnd` em caminhos terminais

## Checklist de teste do Flow Builder

1. Publicar flow e confirmar `validation` com targets corretos.
2. Testar caminho feliz completo (inicio -> fim).
3. Testar caminho alternativo de condicao.
4. Testar timeout/inatividade quando configurado.
5. Testar captura de variavel e reutilizacao em mensagem seguinte.
6. Validar transferencia/finalizacao de ticket quando houver esses nos.
7. Conferir logs do runner para no executado e proximo target.