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.
1. Visão Geral da Gestão de Catálogo
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.