Pular para conteúdo

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

  1. 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.

  2. 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.

  3. 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 DISCOVERING ou 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.