Jornada e Máquina de Estados B2C
O domínio de Vendas B2C conduz o cliente final desde a primeira mensagem no WhatsApp até o recebimento do link de pagamento e confirmação do pedido no WooCommerce.
Para garantir que a conversa seja natural para o cliente, mas previsível e confiável para o sistema, o agente B2C é governado por uma Máquina de Estados Finitos (FSM) com 5 estados macro.
1. Visão Geral da Jornada do Cliente
Do ponto de vista do cliente, o fluxo é simples, rápido e sem fricção:
flowchart TD
start([Cliente envia mensagem]) --> welcome[Boas-vindas e Menu Inicial]
welcome --> search[Busca ou Navegação no Catálogo]
search --> cart[Montagem e Revisão do Carrinho]
cart --> flow[WhatsApp Flow: Endereço de Entrega]
flow --> shipping[Seleção da Modalidade de Frete]
shipping --> checkout[Criação do Pedido no WooCommerce]
checkout --> payment[Envio do Link de Pagamento / Pix]
payment --> confirmed([Pagamento Confirmado!])
style start fill:#e0f2fe,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style confirmed fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#15803d
2. A Máquina de Estados (FSM)
A arquitetura do agente B2C organiza o diálogo em 5 macro-estados semânticos. O diagrama abaixo separa com clareza o fluxo principal de compra das rotas de retorno ou exceção:
flowchart TB
idle["<b>1. IDLE</b><br>Boas-vindas e Menu Inicial"]
discovering["<b>2. DISCOVERING</b><br>Busca de Produtos, Catálogo e Carrinho"]
addressing["<b>3. ADDRESSING</b><br>WhatsApp Flow de Endereço e Cálculo de Frete"]
processing["<b>4. PROCESSING</b><br>Criação do Pedido no WooCommerce e Chave Pix"]
done["<b>5. DONE</b><br>Pagamento Aprovado e Pedido Concluído"]
idle ==>|"1. Cliente busca produto ou abre catálogo"| discovering
discovering ==>|"2. Cliente fecha o carrinho e avança"| addressing
addressing ==>|"3. Endereço preenchido e frete selecionado"| processing
processing ==>|"4. Webhook confirma compensação do Pix"| done
%% Retornos e exceções nas laterais
discovering -.->|"Cancelar compra / Menu"| idle
addressing -.->|"Voltar para alterar itens"| discovering
processing -.->|"Pagamento expirou / falhou"| discovering
done -.->|"Nova compra / mensagem futura"| idle
style idle fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
style discovering fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
style addressing fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
style processing fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
style done fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#15803d
3. Os 5 Estados em Detalhes
| Estado | Nome Semântico | O que acontece nessa fase | O que o cliente vê |
|---|---|---|---|
IDLE |
Repouso / Menu Inicial | Cliente iniciou contato ou encerrou uma compra anterior. O agente aguarda uma intenção de compra. | Mensagem de boas-vindas com botões de "Ver Catálogo", "Fazer Pedido" ou "Falar com Atendente". |
DISCOVERING |
Descoberta e Carrinho | O cliente está procurando produtos, escolhendo tamanhos/variações, avaliando complementos e ajustando quantidades no carrinho. | Cards de produtos com fotos, botões interativos para adicionar ao carrinho e resumo dos itens selecionados. |
ADDRESSING |
Endereço e Frete | Momento de coletar onde o pedido será entregue e calcular o valor e prazo de envio junto ao WooCommerce. | Tela nativa do WhatsApp Flow para digitação ágil do endereço e botões com as opções de frete disponíveis (ex: Sedex, PAC, Retirada). |
PROCESSING |
Pedido e Pagamento | O pedido foi registrado no WooCommerce e a cobrança foi gerada. O sistema aguarda a liquidação. | Resumo formal do pedido com código Pix Copia-e-Cola e/ou link seguro de pagamento. |
DONE |
Conclusão | Notificação de pagamento confirmado e despacho. A compra foi finalizada com sucesso. | Mensagem de agradecimento com orientações de entrega e acompanhamento. Qualquer nova mensagem reinicia em IDLE. |
4. O Mecanismo de Sub-passos (ui_hint)
Em vez de criar dezenas de estados rígidos no banco, a FSM utiliza o conceito de ui_hint.
O ui_hint é uma etiqueta dinâmica gravada na sessão do cliente indicando exatamente qual elemento visual foi exibido por último:
WELCOME_MENU: Menu principal ativo.SEARCH_PROMPT: Aguardando o cliente digitar o nome de um produto.VIEWING_RESULTS: Lista de produtos retornada pela busca.REVIEWING_COMPLEMENTS: Sugestão de produtos complementares (cross-selling).CART_REVIEW: Visualização do carrinho atual.ADDRESS_FLOW_OPEN: Formulário de endereço aberto na tela do WhatsApp.SHIPPING_OPTIONS: Opções de frete aguardando seleção.PAYMENT_LINK_SENT: Chave Pix / link enviados.
Fallback Inteligente (Soft-Reject)
Se o cliente enviar uma mensagem fora do contexto esperado (por exemplo, digitar "legal" quando deveria escolher o frete), o sistema não quebra e não reinicia a conversa.
O router consulta o ui_hint e devolve uma orientação amigável e precisa:
"Escolha uma das opções de frete que enviei acima para prosseguirmos com seu pedido 😊"
5. Resiliência e Proteção contra Abandono
-
Confirmação antes de descartar (
can_be_discarded): Se o cliente tocar em "Menu Inicial" enquanto estiver montando o carrinho (DISCOVERING), preenchendo endereço (ADDRESSING) ou aguardando pagamento (PROCESSING), o agente pergunta se ele realmente deseja descartar os itens antes de resetar a sessão. -
Memória de Sessão no Redis: O estado da FSM, os itens do carrinho e o endereço do cliente ficam preservados no Redis com TTL renovado a cada interação. Se o cliente demorar alguns minutos para responder, o contexto continua exatamente onde ele parou.
-
Retomada de Pagamento: Se a janela de pagamento expirar ou o cliente quiser alterar a forma de pagamento, a FSM faz a transição controlada de volta para
DISCOVERINGou reemite o link sem duplicar o pedido desnecessariamente.
6. Arquitetura Técnica de Sessão e Redis
Para os desenvolvedores e engenheiros que forem manter a stack, os detalhes de persistência e controle de concorrência no Redis seguem padrões estritos:
1. Padrão de Chaves no Redis
Todas as chaves do B2C são organizadas com isolamento multi-tenant pelo identificador da loja (merchant_id ou store_id) e telefone do cliente (sender):
| Chave | Tipo | TTL Padrão | Finalidade |
|---|---|---|---|
fsm:{store_id}:{sender}:state |
String (CheckoutState) |
24 horas | Guarda o estado macro atual (idle, discovering, addressing, processing, done). |
checkout:session:{store_id}:{sender} |
Hash / JSON | 24 horas | Estado completo da sessão: carrinho, ui_hint, CEP, endereço e IDs de pedido. |
checkout:cart:{store_id}:{sender} |
List / JSON | 24 horas | Lista serializada de itens atualmente no carrinho com variações e quantidades. |
checkout:lock:{store_id}:{sender} |
String (Token UUID) | 60 segundos | Lock distribuído para prevenir concorrência em cliques rápidos. |
2. Controle de Concorrência (Distributed Session Lock)
O WhatsApp pode enviar webhooks duplicados ou o cliente pode clicar no mesmo botão duas vezes em fração de segundos. Para evitar que duas transições da FSM rodem em paralelo:
* Um lock distribuído é adquirido via SET NX PX 60000 antes de qualquer processamento de evento.
* A liberação e a renovação de posse do lock são realizadas exclusivamente através de scripts Lua atômicos (_LUA_RELEASE_LOCK e _LUA_RENEW_LOCK), garantindo que uma thread lenta nunca delete o lock pertencente a outra thread.
* Timeout de aquisição: 15 segundos com retries a cada 50ms.
3. Exemplo de Payload de Sessão no Redis
{
"state": "addressing",
"ui_hint": "shipping_options",
"cart_items": [
{
"product_id": 1402,
"variation_id": 1405,
"name": "Camiseta Algodão Egípcio",
"price": "89.90",
"quantity": 1
}
],
"shipping_address": {
"cep": "59078-000",
"street": "Av. Senador Salgado Filho",
"number": "3000",
"neighborhood": "Lagoa Nova",
"city": "Natal",
"state": "RN"
},
"shipping_method": {
"id": "correios-sedex",
"title": "Sedex Expresso",
"cost": "24.50"
},
"order_id": null
}
7. Catálogo de Eventos Canônicos (CheckoutEvent)
Mapeamento dos eventos definidos em app.services.fsm.events.CheckoutEvent:
| Evento Canônico | Origem | Ação Desencadeada |
|---|---|---|
BUTTON_START_PURCHASE / BUTTON_VIEW_CATALOG |
Clique no menu inicial | Inicializa contexto e transiciona para DISCOVERING. |
TEXT_MESSAGE |
Mensagem de texto livre | Consulta o roteador de intenção (GenAI) ou busca semântica de produtos. |
PRODUCT_ID_SELECTED |
Seleção de item ou variação | Valida estoque no WooCommerce e insere no carrinho. |
BUTTON_CONFIRM_CART / BUTTON_FINISH |
Botão de fechar carrinho | Dispara formulário de WhatsApp Flow e transiciona para ADDRESSING. |
NFM_ADDRESS_SUBMITTED |
Retorno do WhatsApp Flow | Valida dados de entrega e calcula fretes disponíveis. |
SHIPPING_OPTION_SELECTED |
Clique na opção de frete | Cria pedido com status pending no WooCommerce e vai para PROCESSING. |
PAYMENT_SUCCESS |
Webhook de liquidação | Registra pagamento, notifica cliente e transiciona para DONE. |
FALLBACK_COMMAND / Erro de validação |
Mensagem fora de contexto | Devolve instrução do ui_hint sem alterar o estado da sessão. |