Download the PHP package egsn/store-intelligence without Composer

Egsn_StoreIntelligence

Módulo de diagnóstico e otimização de lojas Magento 2 alimentado por IA. Coleta métricas de performance, erros e vendas através de 30 collectors e envia os dados para um provedor de IA (Claude, OpenAI ou Gemini) para gerar análises, recomendações prioritizadas e estimativas de impacto.

Requisitos

• Magento 2.4.7+
• PHP ~8.2 || ~8.3 || ~8.4

Instalação

Via Composer:

Configuração

Lojas > Configurações > Egsn > Store Intelligence

Consumers via cron: configure o cron_consumers_runner no app/etc/env.php (cron_run: true + consumers_wait_for_messages: 0) para o Magento reciclar o consumer egsn.store.intelligence.consumer automaticamente — evita daemons com código antigo em memória após deploys.

Funcionalidades

• 30 collectors organizados em 3 categorias: Performance (7), Erros (8) e Vendas (15)
• Análise por IA: envia dados coletados para Claude (Anthropic), OpenAI ou Gemini (Google AI Studio) e processa a resposta em recomendações acionáveis
• Painel admin: dashboard com score geral, histórico de análises e lista de recomendações priorizadas (crítico / aviso / melhoria)
• GraphQL API: endpoints para consultar análises, recomendações e dispensar itens
• REST API: endpoints GET /V1/egsn-si/analysis e POST /V1/egsn-si/analysis/run
• Cron automático: janela de execução configurável, com suporte a horários que cruzam a meia-noite
• Notificações por email: relatório HTML com score, resumo da IA e recomendações críticas
• Exportação CSV: exportação de análise completa com todos os resultados dos collectors
• Message Queue: execução assíncrona via RabbitMQ/MySQL queue

Collectors disponíveis

Performance

• OpcacheCollector — status do OPcache
• CacheHitRatioCollector — taxa de acerto do cache Magento
• SlowQueriesCollector — queries MySQL lentas
• UnoptimizedImagesCollector — imagens acima do threshold configurado
• JsCssMinificationCollector — minificação de JS/CSS habilitada
• PageLoadTimeCollector — tempo de carregamento estimado
• ModulePerformanceCollector — módulos com impacto em performance

Erros

• ExceptionLogCollector — exceções no exception.log
• SystemLogCollector — erros no system.log
• Missing404ImagesCollector — imagens referenciadas mas ausentes
• BrokenLinksCollector — links quebrados detectados
• FailedPaymentsCollector — pagamentos com falha recentes
• CronFailuresCollector — falhas no cron Magento
• EmailQueueCollector — emails com falha na fila
• IntegrationErrorsCollector — erros em logs de integrações (ERP, API, etc.)

Vendas

• AbandonedCartsCollector — carrinhos abandonados
• ZeroResultSearchesCollector — buscas sem resultado
• CheckoutFunnelCollector — abandono no funil de checkout
• ProductsMissingImageCollector — produtos sem imagem
• ProductsMissingDescriptionCollector — produtos sem descrição
• EmptyCategoriesCollector — categorias sem produtos
• ExpiredCouponsCollector — cupons vencidos ativos
• PriceBelowCostCollector — produtos com preço abaixo do custo
• OutOfStockCollector — produtos esgotados
• NoSalesCollector — produtos sem vendas no período configurado
• CrossSellOpportunitiesCollector — oportunidades de cross-sell
• InactiveCustomersCollector — clientes inativos no período configurado
• LeastViewedProductsCollector — produtos menos visualizados
• TopSellingProductsCollector — produtos mais vendidos
• NegativeReviewsCollector — avaliações negativas recentes

Changelog

Todas as mudanças relevantes deste módulo são documentadas neste arquivo. O formato segue boas práticas inspiradas em Keep a Changelog e Semantic Versioning.

[Unreleased]

Changed

• Agendamento do cron de análise agora é controlado pelo admin no grupo Agendamento: novos campos "Frequência" (Diária/Semanal/Mensal) e "Horário de Início" definem quando o cron dispara. Campo adicional "Expressão Cron Personalizada" aceita sintaxe crontab completa (*, listas, intervalos, steps como */5 * * * * e atalhos @hourly/@daily/@weekly/@monthly/@yearly) e, quando preenchido, sobrescreve Frequência/Horário; expressões inválidas e @reboot são rejeitados na validação. Backend model compõe a expressão e grava em crontab/default/jobs/egsn_store_intelligence_run/schedule/cron_expr, consumida via config_path no crontab.xml (padrão Magento de cron configurável). Antes o disparo era fixo à 01:00 e janelas fora desse horário nunca executavam.

Added

• Nova opção "Cada website separadamente" no Escopo da Análise: cada execução (cron, manual ou API) publica uma mensagem por website e gera N análises por rodada, cada uma restrita ao seu website. O website_id viaja no payload da fila e o Orchestrator o usa no lugar do config.

Fixed

• Janela de execução (RunAnalysis) agora é comparada no timezone da loja, o mesmo usado pelo Magento para o match das expressões cron. Antes o check usava UTC, podendo pular execuções silenciosamente em janelas estreitas.

[1.1.0] - 2026-07-16

Fixed

• 11 collectors que falhavam silenciosamente em instalações com catalog staging (Adobe Commerce): joins EAV agora usam o linkField do MetadataPool (row_id/entity_id), compatível com CE e EE. Afetados: no_sales, least_viewed, cross_sell_opportunities, negative_reviews, missing_images_404, missing_image, missing_description, empty_categories, price_below_cost, out_of_stock (nome), expired_coupons (coluna uses_total inexistente → salesrule_coupon.times_used).
• least_viewed: coluna object_id inexistente em report_viewed_product_aggregated_daily → product_id.
• page_load_time não valida mais TLS ao medir a própria loja (certificado self-signed de dev impedia a medição).
• Notas de erro dos collectors agora incluem a mensagem real da exceção (antes só "tables not accessible").

Added

• Comando bin/magento egsn:si:selfcheck: roda os 30 collectors contra o banco real e retorna exit 1 se algum falhar — pega SQL quebrado que testes unitários (com banco mockado) não detectam.
• Webhook também notifica análises com falha (consumer e watchdog), incluindo o motivo.
• Coluna "Escopo" no Histórico (Global ou nome do website) e ID linkando para a nova página de detalhe da análise (status, score, resumo, resultados dos 30 collectors com observações, exportação CSV).
• Consumo de tokens de IA do mês (usado × orçamento) exibido no card Ações do dashboard.
• Data patch que dispensa duplicatas legadas de recomendações (versões antigas ativas do mesmo collector).
• CollectorPool compartilhado entre Orchestrator e self-check (lista única de collectors no di.xml).
• Watchdog no cron de limpeza: análises presas em "Em execução" além do timeout global são marcadas como falhas (com motivo).
• Coluna error_message na análise; o Histórico mostra o motivo da falha como tooltip no badge de status.
• Fallback de provider de IA: se o provider configurado falhar (rate limit, chave inválida), os demais providers configurados são tentados antes de marcar falha.
• Dashboard: cards de score por categoria (Performance / Erros / Vendas).
• Dashboard: card "O que mudou desde a última análise" comparando as duas últimas análises concluídas (problemas novos, resolvidos e persistentes).
• Botão "Analisar Agora" com acompanhamento do status (polling) e atualização automática da página ao concluir.
• Deduplicação de recomendações: ao concluir uma análise, versões antigas da mesma recomendação (mesmo collector + título) são dispensadas automaticamente.
• Notificação via webhook genérico ({"text": "..."}, compatível com Slack e Microsoft Teams).
• Orçamento mensal de tokens de IA com bloqueio da chamada de IA ao atingir o limite (a análise continua com score determinístico).
• Escopo de análise por website: collectors de vendas/pedidos filtram por store_id/website_id do website configurado; coluna website_id na análise.
• Data interfaces tipadas (AnalysisInterface, RecommendationInterface) fechando o contrato REST/GraphQL de getById/getLatest.
• i18n: strings do admin extraídas para __()/$t() com i18n/pt_BR.csv e i18n/en_US.csv.
• Testes para PromptBuilder, EmailNotifier, WebhookNotifier, CsvExporter, GarbageCollection (watchdog), ProviderPool (fallback) e collectors FailedPayments/AbandonedCarts.
• Coluna "Análise" na grid de recomendações, identificando de qual análise cada recomendação veio.
• Ícone SVG próprio (hexágono com circuito, derivado do logo EGSN) no grupo "Egsn" do menu lateral do admin, aplicado via CSS mask com currentColor.
• Link do título da recomendação na listagem para a tela de detalhe.

Changed

• ⚠️ Enums do GraphQL (AnalysisStatus, AnalysisCategory, RecommendationPriority) agora em SCREAMING_SNAKE_CASE (COMPLETED, PERFORMANCE, CRITICAL…), conforme o padrão Magento — breaking para clientes GraphQL que usavam valores minúsculos.
• ⚠️ AnalysisRepositoryInterface::getById/getLatest retornam AnalysisInterface tipada (antes array); getLatest lança NoSuchEntityException quando não há análise concluída (antes retornava vazio).
• Conformidade total com o Magento Coding Standard: 0 erros e 0 warnings no PHPCS (docblocks completos, linhas ≤120, Filesystem/Io\File no lugar de is_dir/basename; raw SQL dos collectors mantido com phpcs:disable justificado).
• ⚠️ Score geral agora é calculado deterministicamente (média dos scores dos collectors ponderada pela severidade do status) em vez de gerado pela IA — análises com os mesmos dados produzem o mesmo score. A escala muda em relação às análises antigas, cujo score era um julgamento subjetivo do modelo.
• Providers de IA (Claude, OpenAI, Gemini) passam a usar temperature: 0, e o prompt instrui a IA a citar somente problemas presentes nos dados — reduz variação e alucinação em resumos/recomendações.
• Documentação atualizada para incluir o provedor Gemini (Google AI Studio).
• db_schema.xml com identity="false" explícito em colunas int/smallint não auto-incremento.

Fixed

• Conformidade com o Magento Coding Standard (0 erros no PHPCS): escapes explícitos nos templates, $escaper no lugar dos métodos de escape do block, interfaces HttpGet/HttpPostActionInterface nos controllers, AnalysisRepository migrado para select builder com log de falhas, EmailNotifier com Escaper, CsvExporter com Filesystem do framework, remoção de código de debug e dos ui_components/grid collections sem uso, setup_version removido do module.xml e dismissRecommendation retornando o resultado real do update.
• Ícone fantasma antes de "Dashboard" no menu admin: o id Egsn_StoreIntelligence::dashboard gerava a classe CSS item-dashboard, que colide com o ícone do Dashboard nativo do tema admin; id do item de menu renomeado para Egsn_StoreIntelligence::si_dashboard (recurso de ACL inalterado).
• Labels de data no gráfico de evolução do score do dashboard (coluna created_at ausente no getList).
• Plural incorreto "recomendaçãoões" na listagem de recomendações.
• Teste unitário do ClaudeProvider atualizado para o construtor com EncryptorInterface.

[1.0.0] - 2026-06-25 - EGSN-0000

Added

• Versão inicial do módulo com 30 collectors, integração com Claude e OpenAI, painel administrativo, API REST, GraphQL, cron automático e notificações por email.

Licença

OSL-3.0 / AFL-3.0

Apoie o projeto

Este módulo é gratuito e mantido nas horas vagas. Se ele te poupou tempo ou dinheiro, considere fazer uma doação via PIX:

Chave PIX (CNPJ): 49.168.504/0001-04   

Aponte a câmera do seu banco para o QR Code acima ou use a chave copia-e-cola. Qualquer valor ajuda a manter o desenvolvimento e o suporte ativos. Obrigado! 🙏

Qualquer dúvida ou sugestão, entre em contato pelo email: [email protected] ou por Whatsapp: +55 (21) 98653-0487