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
- 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:
- Campeão, Fidelizado, Promissor, Novo, Possível lead, Precisa de atenção, Em risco, Quase hibernando, Hibernando.
- 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).
- 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.).
- 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
- 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. - 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": {...}}. - 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.