Pular para conteúdo

Marketing Campaigns

O marketing-campaigns é o microsserviço analítico de inteligência de marketing, segmentação preditiva e recomendação de ofertas do EcomSmart Agents. Ele processa o histórico de pedidos e clientes para categorizar a base de compradores, identificar produtos correlacionados e calcular ofertas personalizadas com base em lógica nebulosa (Fuzzy Logic).

O microsserviço funciona de forma desacoplada: ele não envia mensagens aos clientes finais diretamente, mas expõe endpoints analíticos e um servidor MCP (Model Context Protocol) consumido pelo Copilot de Marketing do Painel Administrativo.


Papel na Plataforma

flowchart TD
    subgraph DataSources [Fontes de Dados de Pedidos]
        wc[WooCommerce Wrapper: Histórico da Loja]
        api[API Externa EcomSmart]
    end

    DataSources -->|Ingestão de Dados| mkt[Marketing Campaigns Engine]

    subgraph AnalyticalPipeline [Motor Matemático & Algoritmos]
        rfm[1. RFM & 9 Tiers Ozcan]
        apriori[2. Market Basket Apriori]
        fuzzy[3. Motor Mamdani O1..O14]
    end

    mkt --> AnalyticalPipeline
    AnalyticalPipeline --> snapshots[(Snapshots Analíticos PostgreSQL)]

    snapshots --> rest[API REST de Agregados]
    snapshots --> mcp[Servidor MCP JSON-RPC 2.0]

    rest --> panel[Painel SPA: Dashboards]
    mcp --> copilot[Copilot de Campanhas: LLM Tool-Calling]

    style mkt fill:#f0f9ff,stroke:#0284c7,stroke-width:2px,color:#0369a1
    style AnalyticalPipeline fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
    style snapshots fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
    style panel fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style copilot fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style wc fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
    style api fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b

Limites de Responsabilidade

É responsabilidade do Serviço NÃO é responsabilidade do Serviço
Executar segmentação RFM e classificar clientes nos 9 Tiers de Ozcan. Fazer o disparo de mensagens ativas pelo WhatsApp (WhatsApp Entrypoint).
Minerar regras de associação de produtos com o algoritmo Apriori (lift, suporte). Orquestrar o checkout ou receber pagamento de pedidos.
Priorizar ofertas (O1 a O14) via motor de inferência nebulosa Mamdani. Cadastrar ou editar produtos na loja virtual do lojista.
Servir ferramentas analíticas via servidor MCP para o Copilot de IA do painel. Manter sessões de lojistas ou autenticação de usuários (BFF).
Auditar execuções do pipeline em platform.marketing_pipeline_execucoes. Manter conexões com os números de WhatsApp dos clientes.

Modelos Analíticos & Pipeline Matemático

O cálculo de inteligência do serviço é executado periodicamente ou sob demanda para cada loja conectada:

flowchart LR
    orders[Pedidos & Clientes Ingeridos] --> rfm[Fuzzificação RFM]
    rfm --> ozcan[9 Tiers de Ozcan]
    orders --> apriori[Market Basket Analysis]
    ozcan & apriori --> mamdani[Inferência Fuzzy Mamdani O1..O14]
    mamdani --> ranking[Ranking de Ofertas por Cliente]

    style orders fill:#f8fafc,stroke:#64748b,stroke-width:1.5px,color:#1e293b
    style rfm fill:#f0f9ff,stroke:#0284c7,stroke-width:1.5px,color:#0369a1
    style ozcan fill:#f0fdf4,stroke:#16a34a,stroke-width:1.5px,color:#166534
    style apriori fill:#fefce8,stroke:#d97706,stroke-width:1.5px,color:#92400e
    style mamdani fill:#faf5ff,stroke:#9333ea,stroke-width:1.5px,color:#6b21a8
    style ranking fill:#f0fdf4,stroke:#16a34a,stroke-width:2px,color:#166534
  1. Segmentação RFM & 9 Tiers de Ozcan: Transforma Recência (dias desde a última compra), Frequência (quantidade de pedidos) e Valor Monetário (ticket acumulado) em graus de pertinência difusos, classificando cada comprador em 9 perfis:
  2. Campeão, Fidelizado, Promissor, Novo, Possível lead, Precisa de atenção, Em risco, Quase hibernando, Hibernando.
  3. Market Basket Analysis (Apriori): Analisa compras conjuntas para determinar itens frequentemente comprados em conjunto, calculando suporte, confiança e lift (probabilidade estatística de compra complementar).
  4. Motor Fuzzy Mamdani (Ofertas O1 a O14): Combina nível de estoque dos produtos, recência do cliente, categoria de maior afinidade e histórico para calcular o grau de atratividade de até 14 tipos de receitas promocionais (desconto de giro, cross-sell, reengajamento, etc.).
  5. Persistência de Snapshots: Os resultados são persistidos em tabelas dedicadas (rfm_snapshot, fuzzy_segmento_snapshot, prioridade_ofertas_snapshot), permitindo consultas imediatas em milissegundos sem reprocessar toda a base.

Servidor MCP (Model Context Protocol)

O microsserviço inclui um servidor MCP integrado compatível com a especificação JSON-RPC 2.0 (POST /api/marketing/mcp), permitindo que agentes LLM executem chamadas de função dinâmicas durante o uso do Copilot do painel:

Ferramenta MCP Descrição
tier_resumo Retorna o total consolidado de clientes agrupados por cada um dos 9 tiers Ozcan.
melhor_oferta_hoje Identifica as ofertas promocionais de maior alcance e impacto para o dia atual.
distribuicao_ofertas Fornece a quantidade de clientes elegíveis e grau médio de afinidade por receita de oferta.
buscar_produto_por_nome Converte nomes ou termos de pesquisa em product_id exato do WooCommerce.
clientes_por_produto_estoque Localiza clientes prioritários para queima de estoque de um SKU específico.
produtos_sugeridos Retorna recomendações de cross-sell calculadas pelo Market Basket Analysis.
renderizar_mensagem Preenche templates de campanha substituindo variáveis pelo contexto do cliente.

Contratos de API REST

As rotas REST são expostas internamente sob o prefixo /api/marketing e usam o token Bearer configurado em MARKETING_API_TOKEN. O painel não acessa o serviço diretamente: o frontend-entrypoint aplica autenticação e autorização da sessão antes de encaminhar a operação. O endpoint MCP tem proteção própria por MCP_INTERNAL_KEY (aceito em X-Internal-Key ou Authorization: Bearer).

Agregados e Métricas (/lojas/{loja_id}/)

Método Rota Finalidade
GET /lojas/{loja_id}/clientes/por-tier Distribuição de clientes nos 9 tiers para exibição nos gráficos do painel.
GET /lojas/{loja_id}/ofertas/distribuicao Clientes elegíveis e pontuação de atratividade por oferta (O1..O14).
GET /lojas/{loja_id}/ofertas/melhor-hoje Ranking das campanhas mais recomendadas no dia.
GET /lojas/{loja_id}/produtos/{product_id}/clientes-estoque Lista de compradores ideais para queima de estoque do produto.

Ingestão & Recálculo

Método Rota Descrição
POST /lojas/{loja_id}/recalcular Dispara o pipeline analítico consumindo a loja WooCommerce via woocommerce-wrapper.
POST /lojas/{loja_id}/recalcular-api Dispara o pipeline consumindo dados históricos da API central da EcomSmart.
GET /regras/{motor} Retorna as regras fuzzy configuradas para inspeção no painel admin.
PUT /regras/{motor}/{regra_nome} Atualiza o peso de consequente de uma regra de negócio (persiste em YAML).

Configuração por loja

Usuários da equipe podem personalizar mensagens e regras de direcionamento por loja no painel. As alterações passam pelo BFF e são persistidas como diferenças em platform.marketing_campaign_settings; não alteram o motor padrão nem outras lojas.

Método Rota interna do serviço Uso no painel
GET /lojas/{loja_id}/configuracao-campanhas Carrega textos e regras efetivas da loja.
PUT /lojas/{loja_id}/configuracao-campanhas/mensagens/{oferta} Salva ou restaura o texto de um objetivo/oferta.
PUT /lojas/{loja_id}/configuracao-campanhas/regras/{name} Salva ou restaura a configuração de uma regra.

Consulte Configuração por Loja para o comportamento de textos, critérios e publicação.


Configuração Essencial

Variável Descrição
MARKETING_API_TOKEN Token Bearer das rotas REST do serviço.
MCP_INTERNAL_KEY Chave do endpoint MCP; sem ela, o MCP permanece inacessível.
DATABASE_URL Conexão PostgreSQL onde ficam gravados os snapshots analíticos.
WOOCOMMERCE_WRAPPER_URL Endereço interno do container woocommerce-wrapper para ingestão de pedidos.
PLATFORM_API_URL Endereço do BFF para consulta de credenciais de lojistas cadastrados.
LOG_LEVEL Nível de detalhamento dos logs de processamento analítico (padrão: INFO).

Diagnóstico Rápido

  1. Dashboard de marketing sem dados exibidos: Verifique se o recálculo da loja foi executado com sucesso consultando a tabela platform.marketing_pipeline_execucoes. Lojas recém-conectadas precisam de uma execução inicial de /recalcular.
  2. Copilot de IA não consegue chamar ferramentas: Verifique o endpoint do MCP em POST /api/marketing/mcp. O payload deve ser uma mensagem JSON-RPC válida contendo {"jsonrpc": "2.0", "method": "tools/call", "params": {...}}.
  3. Consumo excessivo de memória em lojas grandes: O cálculo do Apriori para lojas com dezenas de milhares de pedidos pode ser ajustado modificando o parâmetro de suporte mínimo (min_support) para evitar sobrecarga no algoritmo de combinações frequentes.