Pular para conteúdo

Jornada de Catálogo B2B

O domínio de Gestão B2B (b2b_handler) orquestra a experiência do lojista no WhatsApp. Ele permite cadastrar e manter produtos, ajustar estoque e preço e enriquecer fotos e descrições com IA diretamente pelo celular.

O módulo opera em dois modos complementares: 1. Flow Exchange: Navegação dinâmica entre telas de formulários nativos do WhatsApp (WhatsApp Flows), com resposta síncrona. 2. Eventos de Conversa (FSM): Máquina de estados que guia diálogos no chat para revisão de textos de IA, melhoria de imagens e confirmações de segurança.


flowchart TB
    admin([Lojista envia comando no WhatsApp]) --> menu["Menu Operacional (CRUD_MENU)"]

    menu --> create_flow["Cadastrar Novo Produto"]
    menu --> manage_flow["Gerenciar / Editar Catálogo"]

    subgraph Criacao ["Ciclo de Cadastro Assistido"]
        direction TB
        create_flow --> upload["1. Upload de Fotos"]
        upload --> cat["2. Tipo ou categoria"]
        cat --> form["3. Campos do produto"]
        form --> ai_desc["4. Sugestões de IA, quando habilitadas"]
        ai_desc --> var["5. Variações, quando aplicáveis"]
        var --> details["6. Detalhes complementares"]
        details --> review["7. Revisão Geral"]
    end

    subgraph Publicacao ["Publicação e Sincronização"]
        direction TB
        review --> save["Persistência no WooCommerce"]
        save --> sync_img["Upload de Fotos no MinIO"]
        sync_img --> sync_vec["Indexação Vetorial no Weaviate"]
        sync_vec --> done([Produto Ativo na Loja!])
    end

    style admin fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
    style menu fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style Criacao fill:#f8fafc,stroke:#cbd5e1,stroke-dasharray: 4 4,color:#475569
    style Publicacao fill:#f8fafc,stroke:#cbd5e1,stroke-dasharray: 4 4,color:#475569
    style done fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#15803d

2. Telas do WhatsApp Flow (flow_exchange)

A interação visual no aplicativo do lojista é baseada no arquivo crud_menu.json. O backend decide dinamicamente a próxima tela a ser renderizada a cada ação do lojista:

Fluxo de Criação de Produto (create)

CRUD_MENU 
   │
   ▼
CREATE_IMAGE_UPLOAD         (Upload das fotos do produto via WhatsApp)
   │
   ├──────────────► CREATE_CATEGORY_SELECT (quando a categoria/tipo precisar ser escolhido)
   │                              │
   ▼                              ▼
CREATE_FORM_FIELDS          (Campos definidos para o tipo de produto)
   │
   ▼
REVIEW_AI_FORM ou CREATE_NO_AI_NOTICE (IA disponível ou indisponível)
   │
   ▼
CREATE_VARIATION_CATEGORIES (Caso o produto seja variável: Cor, Tamanho, etc.)
   │
   ▼
CREATE_VARIATION_VALUES     (Tabela de preços e estoques por variação)
   │
   ▼
CREATE_EXTRA_DETAILS        (Campos complementares do tipo)
   │
   ▼
REVIEW_PRODUCT              (Resumo final antes da publicação oficial)

Fluxo de Gerenciamento e Exclusão (manage)

CRUD_MENU 
   │
   ▼
MANAGE_NAME_PROMPT          (Busca de produto existente por nome ou SKU)
   │
   ▼
MANAGE_ACTION_PROMPT        (Escolha da ação: Alterar Preço/Estoque, IA ou Excluir)
   │
   ├──► UPDATE_FORM                (Formulário com os dados atuais preenchidos)
   ├──► UPDATE_VARIATION_VALUES    (Ajuste rápido de grade de variações)
   └──► DELETE_CONFIRMATION        (Confirmação com aviso de impacto)

3. Máquina de Estados da Conversa (Chat FSM)

Após a submissão das telas do Flow (nfm_reply), o lojista retorna para o chat para interagir com a IA (revisando o texto gerado ou aprovando imagens melhoradas). Essa conversa é regida pela FSM do B2B:

flowchart TB
    in_flow["<b>IN_FLOW</b><br>Preenchendo telas no WhatsApp Flow"]
    awaiting_ai["<b>AWAITING_AI</b><br>Processamento de IA em background"]
    review_desc["<b>REVIEWING_DESCRIPTION</b><br>Revisando texto comercial / SEO"]
    edit_desc["<b>EDITING_DESCRIPTION</b><br>Digitando ajuste manual no chat"]
    img_select["<b>IMAGE_SELECTING</b><br>Escolhendo foto para tratamento"]
    img_process["<b>IMAGE_PROCESSING</b><br>Remoção de fundo / Upscaling"]
    img_approve["<b>IMAGE_APPROVING</b><br>Comparação antes e depois"]
    saving["<b>SAVING</b><br>Gravando no WooCommerce"]

    %% Transições de Criação
    in_flow ==>|"Submissão: nfm_reply_confirm_create"| awaiting_ai
    awaiting_ai ==>|"IA finalizou texto"| review_desc
    review_desc -->|"Tocar em Editar Texto"| edit_desc
    edit_desc -->|"Lojista digita nova descrição"| saving
    review_desc ==>|"Tocar em Aprovar Produto"| saving

    %% Transições de Melhoria de Imagem
    in_flow -.->|"Iniciar melhoria de imagem"| img_select
    img_select -->|"Foto selecionada"| img_process
    img_process -->|"Processamento concluído"| img_approve
    img_approve -->|"Aprovar nova imagem"| saving

    style in_flow fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
    style awaiting_ai fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
    style review_desc fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style edit_desc fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style img_select fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style img_process fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style img_approve fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style saving fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#15803d

4. Arquitetura Técnica de Rascunhos (ProductDraft) e Redis

Para evitar escritas parciais no banco de dados do WooCommerce enquanto o lojista ainda está preenchendo os dados, toda a jornada utiliza o padrão Draft em Memória (Redis).

1. Padrão de Chaves no Redis

Chave Tipo TTL Função
draft:{phone}:data JSON 48 horas Rascunho completo do produto em edição (ProductDraft).
draft:{phone}:images e draft:{phone}:sha256 JSON 48 horas Ordem e identificadores das imagens anexadas ao rascunho.
fsm:{phone}:state e fsm:{phone}:previous_state String 48 horas Estado atual e anterior da conversa B2B.
Lock de sessão String (UUID) Curto, renovável Impede processamento concorrente da mesma conversa. A chave é interna; investigue primeiro por telefone nos logs.

2. Estrutura do Objeto ProductDraft

O rascunho separa metadados da operação dos dados do produto. sender, ação, produto em edição, tipo, imagens e variações são campos conhecidos; os atributos comerciais ficam em fields.

Essa separação é importante: os campos do formulário são definidos pelo catálogo da loja (product_types e product_type_fields), não por uma lista fixa no B2B. Assim, um tipo pode habilitar cor, marca, dimensões ou qualquer campo importado/configurado, e a mesma estrutura serve para criação e atualização.


5. Persistência Final (ProductWriteService)

A gravação no WooCommerce só acontece após a aprovação explícita do lojista: 1. Validação de Integridade: Checagem de duplicação de SKU (product_invalid_sku). 2. Upload e Vinculação de Mídias: As fotos aprovadas são enviadas para a biblioteca de mídia do WooCommerce/WordPress. 3. Escrita no WooCommerce: Chamada via WooCommerceGateway criando produto simples ou variável. 4. Limpeza de Contexto: O rascunho no Redis é descartado e o menu inicial (CRUD_MENU) é reaberto com mensagem de sucesso. 5. Reindexação Imediata: O webhook de produto do WooCommerce dispara a atualização automática do índice vetorial no Weaviate, disponibilizando o item para a busca dos clientes no canal B2C em questão de segundos.