Inteligência Artificial

Especificação do Agente de IA

Arquitetura e funcionamento do sistema de inteligência artificial do DBCHECKOUT

Versão 1.0Última atualização: Janeiro 2025

1Objetivo do Agente de IA

Analista de Negócio Automatizado

O Agente de IA do DBCHECKOUT atua como um analista de negócio sênior automatizado, capaz de processar KPIs consolidados e gerar insights estratégicos acionáveis para gestores de redes de food service.

Diferente de sistemas de ETL ou dashboards passivos, o agente interpreta contexto, identifica padrões, detecta anomalias e recomenda ações baseadas em análise multidimensional dos dados.

Funções Principais

  • Identificar oportunidades de crescimento e otimização
  • Detectar anomalias operacionais e financeiras
  • Prever tendências e sazonalidades
  • Recomendar ajustes de preço, mix e estoque
  • Comparar performance entre lojas e períodos
  • Gerar relatórios executivos automatizados

Princípios de Design

  • Isolamento: Não acessa bancos legados diretamente
  • Contextual: Recebe apenas KPIs consolidados relevantes
  • Explicável: Justifica cada insight com dados e confiança
  • Acionável: Recomenda ações específicas e mensuráveis
  • Seguro: Opera em ambiente isolado e auditável
  • Escalável: Processa múltiplas lojas simultaneamente

2Tipos de Insights Gerados

Oportunidades de Crescimento

Identificação de potenciais de aumento de receita através de análise de comportamento de compra, elasticidade de preço e padrões de consumo.

Exemplos:

  • • Cross-sell: "Clientes que compram Pizza Grande têm 68% de chance de adicionar Refrigerante 2L"
  • • Upsell: "42% dos pedidos de Pizza Média aceitariam upgrade para Grande por +R$ 8"
  • • Bundle: "Combo Pizza + Bebida + Sobremesa pode aumentar ticket em 22%"

Detecção de Anomalias

Identificação automática de desvios estatísticos significativos em métricas operacionais, financeiras e de estoque que requerem atenção imediata.

Exemplos:

  • • Estoque: "Consumo de mussarela 35% acima da média nos últimos 3 dias"
  • • Vendas: "Queda de 18% nas vendas da Loja Centro sem causa aparente"
  • • Delivery: "Tempo médio de entrega aumentou 40% na última semana"

Otimização de Preços

Análise de elasticidade de demanda, comparação com mercado e recomendações de ajuste de preço para maximizar margem sem perda de volume.

Exemplos:

  • • "Pizza Margherita Grande está 8% abaixo do mercado, elasticidade permite aumento"
  • • "Reduzir preço de Pizza Calabresa Média em 5% pode aumentar volume em 15%"
  • • "Produtos premium têm margem 12% inferior ao potencial"

Previsão de Demanda

Machine learning para prever vendas futuras baseado em histórico, sazonalidade, eventos externos e tendências de consumo.

Exemplos:

  • • "Próximo final de semana: aumento esperado de 28% devido a evento esportivo"
  • • "Demanda de Pizza Portuguesa deve crescer 15% no próximo mês (histórico)"
  • • "Sexta-feira: pico de pedidos entre 19h-21h, ajustar equipe"

Análise de Performance

Comparação de performance entre lojas, identificação de melhores práticas e recomendações de replicação de estratégias bem-sucedidas.

Exemplos:

  • • "Loja Centro superou meta em 22%: tempo de entrega -15%, mix premium +18%"
  • • "Loja Sul tem ticket médio 18% superior: estratégia de combos eficaz"
  • • "Loja Norte: melhor margem da rede (42%), analisar gestão de custos"

Redução de Custos

Identificação de oportunidades de redução de custos operacionais, desperdícios e ineficiências sem comprometer qualidade ou experiência do cliente.

Exemplos:

  • • "Trocar fornecedor de embalagens pode reduzir custos em 12% sem perda de qualidade"
  • • "Desperdício de ingredientes 8% acima da média da rede"
  • • "Otimizar rotas de delivery pode economizar R$ 2.400/mês em combustível"

3Formato dos Dados de Entrada (JSON)

Princípio Fundamental

O Agente de IA não acessa tabelas legadas e não conhece o schema operacional. Recebe exclusivamente JSONs estruturados com KPIs consolidados, garantindo:

  • Segurança: Isolamento completo do banco operacional
  • Performance: Dados pré-processados e otimizados
  • Contexto: Apenas métricas relevantes para decisão

Payload Consolidado por Loja/Período

payload_consolidado.json
{
  "network_id": 1,
  "store_id": 123,
  "store_name": "Loja Centro",
  "periodo": {
    "data_inicio": "2024-01-01",
    "data_fim": "2024-01-31",
    "tipo": "mensal"
  },
  "kpis_financeiros": {
    "faturamento_total": 125000.00,
    "ticket_medio": 45.50,
    "margem_bruta_percent": 38.5,
    "cmv_percent": 61.5,
    "lucro_bruto": 48125.00
  },
  "kpis_operacionais": {
    "total_pedidos": 2747,
    "pedidos_por_dia": 88.6,
    "taxa_cancelamento_percent": 2.3,
    "tempo_medio_preparo_min": 18.5,
    "taxa_recompra_percent": 34.2
  },
  "kpis_delivery": {
    "pedidos_delivery": 1923,
    "percent_delivery": 70.0,
    "tempo_medio_entrega_min": 32.5,
    "taxa_atraso_percent": 8.2,
    "ticket_medio_delivery": 52.30
  },
  "hierarquia_produtos": {
    "grupos": [
      {
        "grupo_id": 1,
        "grupo_nome": "Pizzas",
        "faturamento": 87500.00,
        "percent_mix": 70.0,
        "margem_percent": 42.5,
        "tipos": [
          {
            "tipo_id": 10,
            "tipo_nome": "Tradicionais",
            "faturamento": 52500.00,
            "percent_mix": 60.0,
            "margem_percent": 40.0,
            "tamanhos": [
              {
                "tamanho_id": 100,
                "tamanho_nome": "Grande",
                "faturamento": 35000.00,
                "percent_mix": 66.7,
                "margem_percent": 41.0,
                "produtos_top_5": [
                  {
                    "produto_id": 1001,
                    "produto_nome": "Pizza Margherita Grande",
                    "quantidade": 450,
                    "faturamento": 22500.00,
                    "preco_medio": 50.00,
                    "margem_percent": 43.0
                  }
                ]
              }
            ]
          }
        ]
      }
    ]
  },
  "comparativos": {
    "vs_mes_anterior": {
      "faturamento_variacao_percent": 8.5,
      "pedidos_variacao_percent": 6.2,
      "ticket_medio_variacao_percent": 2.1
    },
    "vs_mesmo_mes_ano_anterior": {
      "faturamento_variacao_percent": 15.3,
      "pedidos_variacao_percent": 12.8,
      "ticket_medio_variacao_percent": 2.2
    }
  },
  "historico_7_dias": [
    {
      "data": "2024-01-25",
      "faturamento": 4200.00,
      "pedidos": 92,
      "ticket_medio": 45.65
    }
  ]
}

Payload Comparativo Multi-Lojas

payload_rede.json
{
  "network_id": 1,
  "network_name": "Rede Pizza Express",
  "periodo": "2024-01",
  "kpis_rede": {
    "faturamento_total": 487000.00,
    "total_lojas": 4,
    "ticket_medio_rede": 46.80,
    "margem_media_rede": 39.2
  },
  "lojas": [
    {
      "store_id": 123,
      "store_name": "Loja Centro",
      "faturamento": 125000.00,
      "margem_percent": 38.5,
      "ranking_faturamento": 1,
      "ranking_margem": 3,
      "variacao_vs_media_rede": 8.5
    },
    {
      "store_id": 124,
      "store_name": "Loja Sul",
      "faturamento": 118000.00,
      "margem_percent": 42.0,
      "ranking_faturamento": 2,
      "ranking_margem": 1,
      "variacao_vs_media_rede": 2.3
    }
  ],
  "produtos_destaque_rede": [
    {
      "produto_nome": "Pizza Margherita Grande",
      "faturamento_total": 89000.00,
      "percent_mix_rede": 18.3,
      "margem_media": 41.5,
      "lojas_que_vendem": 4
    }
  ]
}

Características do Payload

  • Estruturado: Schema JSON bem definido e versionado
  • Consolidado: Dados já agregados e calculados
  • Contextual: Inclui comparativos e histórico relevante
  • Hierárquico: Respeita Grupo → Tipo → Tamanho → Produto
  • Completo: Todas as dimensões necessárias para análise

4Frequência de Execução

Análise Diária (EOD)

Executada automaticamente após consolidação dos dados do dia (End of Day).

Insights Gerados:

  • • Performance do dia vs meta
  • • Anomalias operacionais
  • • Produtos em destaque
  • • Alertas de estoque

Análise Semanal

Executada toda segunda-feira com dados consolidados da semana anterior.

Insights Gerados:

  • • Tendências semanais
  • • Comparativo entre lojas
  • • Oportunidades de cross-sell
  • • Ajustes de preço

Análise Mensal

Executada no primeiro dia útil do mês com dados consolidados do mês anterior.

Insights Gerados:

  • • Relatório executivo completo
  • • Previsão de demanda
  • • Análise de margem profunda
  • • Recomendações estratégicas

Análise sob Demanda

Gestores podem solicitar análises específicas a qualquer momento através do dashboard. O agente processa o payload customizado e retorna insights em até 30 segundos.

Casos de Uso:

  • • Análise de produto específico
  • • Comparação entre períodos customizados
  • • Simulação de cenários (preço, mix)
  • • Investigação de anomalias

Limitações:

  • • Máximo 10 análises/dia por usuário
  • • Período mínimo: 1 dia
  • • Período máximo: 12 meses
  • • Timeout: 60 segundos

5Tipos de Alertas

Crítico

URGENTE

Situações que requerem ação imediata e podem impactar significativamente a operação ou receita.

Exemplos:

  • • Queda de vendas superior a 20% sem causa identificada
  • • Ruptura de estoque de produto top 5
  • • Taxa de cancelamento acima de 15%
  • • Margem negativa em categoria importante
  • • Tempo de entrega 2x acima da média
Notificação: Email + SMS + Push + Dashboard

Atenção

IMPORTANTE

Desvios significativos que devem ser monitorados e podem requerer ação em breve.

Exemplos:

  • • Variação de vendas entre 10-20% vs período anterior
  • • Consumo de ingrediente 20-30% acima da média
  • • Taxa de atraso em delivery entre 10-15%
  • • Produto com margem 15% abaixo da categoria
  • • Ticket médio em queda por 3 dias consecutivos
Notificação: Email + Dashboard

Informativo

FYI

Informações relevantes sobre tendências, padrões e oportunidades que não requerem ação imediata.

Exemplos:

  • • Produto crescendo consistentemente há 4 semanas
  • • Padrão sazonal identificado (ex: vendas maiores em finais de semana)
  • • Oportunidade de cross-sell com confiança moderada (60-75%)
  • • Loja performando dentro da média da rede
  • • Novo produto com boa aceitação inicial
Notificação: Dashboard apenas

Positivo

BOA NOTÍCIA

Reconhecimento de performance excepcional e identificação de melhores práticas para replicação.

Exemplos:

  • • Loja superou meta mensal em mais de 15%
  • • Margem bruta aumentou 5+ pontos percentuais
  • • Taxa de recompra cresceu significativamente
  • • Tempo de entrega melhorou 20% vs mês anterior
  • • Produto novo se tornou top 10 em menos de 30 dias
Notificação: Email + Dashboard

Configuração de Alertas

Gestores podem personalizar thresholds e canais de notificação para cada tipo de alerta através do painel de configurações.

Thresholds Customizáveis

Ajustar limites de variação, margem, tempo, etc.

Canais de Notificação

Escolher entre Email, SMS, Push, Dashboard

Horários de Envio

Definir janelas para receber notificações

6Limitações do Agente

Limitações Fundamentais

É essencial compreender o que o Agente de IA não faz e não pode fazerpara evitar expectativas incorretas e garantir uso adequado da ferramenta.

Não Acessa Dados Legados Diretamente

O agente não tem acesso ao banco MySQL legado das lojas e não conheceo schema operacional. Opera exclusivamente com KPIs consolidados pré-processados.

Não Realiza ETL ou Transformação de Dados

O agente não é responsável por ingestão, validação, limpeza ou consolidação de dados. Essas tarefas são executadas pela camada de ETL antes do payload chegar ao agente.

Não Modifica Dados Operacionais

O agente não pode alterar preços, estoque, produtos ou qualquer dado operacional. Apenas recomenda ações que devem ser executadas manualmente pelos gestores.

Não Opera em Tempo Real

Insights são baseados em dados consolidados (EOD, semanal, mensal). O agente não monitoratransações em tempo real nem gera alertas instantâneos durante a operação.

Não Substitui Análise Humana

O agente é uma ferramenta de apoio à decisão, não um substituto para julgamento humano. Insights devem ser validados por gestores considerando contexto de negócio.

Não Acessa Dados Externos

O agente não consulta APIs externas, preços de concorrentes, dados de mercado ou informações fora do ecossistema DBCHECKOUT (exceto se explicitamente integrado).

Não Garante 100% de Precisão

Insights são baseados em modelos estatísticos e machine learning. Cada insight possui um nível de confiança (60-95%) que deve ser considerado na tomada de decisão.

Uso Adequado do Agente

Para obter máximo valor do Agente de IA, utilize-o como:

  • Assistente estratégico para identificar oportunidades não óbvias
  • Sistema de alerta precoce para anomalias e desvios
  • Ferramenta de benchmarking entre lojas e períodos
  • Gerador de hipóteses para testes e experimentos

7Estratégia de Explicabilidade

Transparência e Confiança

Todo insight gerado pelo agente deve ser explicável, rastreável e justificável. Gestores precisam entender por que o insight foi gerado e comoa conclusão foi alcançada para confiar nas recomendações.

Estrutura de um Insight Explicável

insight_explicavel.json
{
  "insight_id": "INS-2024-001-0123",
  "tipo": "oportunidade",
  "titulo": "Oportunidade de Cross-sell",
  "descricao": "Clientes que compram Pizza Grande têm 68% de chance de adicionar Refrigerante 2L quando oferecido no checkout.",
  "impacto_estimado": {
    "valor": 8500.00,
    "unidade": "BRL/mês",
    "metrica": "receita_adicional"
  },
  "confianca": 92,
  "explicacao": {
    "metodologia": "Análise de associação de produtos (Market Basket Analysis)",
    "dados_utilizados": [
      "Histórico de 90 dias de pedidos",
      "2.847 pedidos com Pizza Grande",
      "1.936 pedidos com Pizza Grande + Refrigerante 2L"
    ],
    "calculo": "1.936 / 2.847 = 68% de co-ocorrência",
    "premissas": [
      "Taxa de conversão de sugestão: 40%",
      "Preço médio Refrigerante 2L: R$ 8,50",
      "Pedidos Pizza Grande/mês: 950"
    ],
    "formula_impacto": "950 pedidos × 68% chance × 40% conversão × R$ 8,50 = R$ 2.193/semana ≈ R$ 8.500/mês"
  },
  "evidencias": [
    {
      "tipo": "estatistica",
      "descricao": "68% dos pedidos com Pizza Grande incluem Refrigerante 2L",
      "fonte": "pedidos_itens (últimos 90 dias)"
    },
    {
      "tipo": "comparativo",
      "descricao": "Taxa de co-ocorrência 3.2x maior que a média geral de bebidas",
      "fonte": "análise de mix de produtos"
    }
  ],
  "acao_recomendada": {
    "titulo": "Implementar sugestão automática",
    "descricao": "Adicionar pop-up no checkout sugerindo Refrigerante 2L quando Pizza Grande estiver no carrinho",
    "prioridade": "alta",
    "esforco": "baixo",
    "prazo_sugerido": "7 dias"
  },
  "metricas_acompanhamento": [
    "Taxa de conversão da sugestão",
    "Receita incremental de Refrigerante 2L",
    "Impacto no ticket médio"
  ],
  "data_geracao": "2024-01-15T08:30:00Z",
  "validade": "2024-02-15T23:59:59Z"
}

Nível de Confiança

Cada insight possui um score de confiança (0-100%) baseado em:

  • Volume de dados: Mais dados = maior confiança
  • Consistência: Padrão repetido = maior confiança
  • Significância estatística: p-value < 0.05
  • Validação cruzada: Múltiplas lojas/períodos

Interpretação:

  • • 90-100%: Alta confiança, ação recomendada
  • • 75-89%: Boa confiança, validar contexto
  • • 60-74%: Confiança moderada, testar
  • • <60%: Baixa confiança, apenas informativo

Rastreabilidade

Todo insight pode ser rastreado até os dados originais:

  • ID único: Identificador permanente do insight
  • Timestamp: Data/hora exata de geração
  • Payload original: JSON usado como entrada
  • Versão do modelo: Qual versão da IA gerou

Auditoria:

Gestores podem clicar em "Ver Detalhes" para acessar o payload completo, metodologia detalhada e dados utilizados no cálculo.

Feedback Loop

Sistema de feedback para melhorar continuamente a qualidade dos insights:

Útil

Insight foi relevante e acionável

Parcialmente Útil

Insight correto mas contexto incompleto

Não Útil

Insight incorreto ou irrelevante

Aprendizado contínuo: Feedback dos gestores é usado para retreinar modelos e ajustar thresholds, melhorando a precisão ao longo do tempo.

8Armazenamento dos Resultados

Tabela: ai_insights

schema_ai_insights.sql
CREATE TABLE ai_insights (
  id BIGSERIAL PRIMARY KEY,
  insight_id VARCHAR(50) UNIQUE NOT NULL,
  network_id INT NOT NULL,
  store_id INT,  -- NULL para insights de rede
  
  -- Classificação
  tipo VARCHAR(50) NOT NULL,  -- oportunidade, anomalia, otimizacao, previsao, performance, custo
  categoria VARCHAR(50),  -- vendas, produtos, delivery, financeiro, operacional
  prioridade VARCHAR(20),  -- critica, alta, media, baixa
  
  -- Conteúdo
  titulo VARCHAR(255) NOT NULL,
  descricao TEXT NOT NULL,
  impacto_valor DECIMAL(12,2),
  impacto_unidade VARCHAR(20),  -- BRL/mês, %, pedidos, etc
  confianca INT NOT NULL,  -- 0-100
  
  -- Explicabilidade
  metodologia TEXT,
  dados_utilizados JSONB,
  calculo TEXT,
  premissas JSONB,
  evidencias JSONB,
  
  -- Ação
  acao_titulo VARCHAR(255),
  acao_descricao TEXT,
  acao_prioridade VARCHAR(20),
  acao_esforco VARCHAR(20),
  acao_prazo_dias INT,
  
  -- Payload original
  payload_entrada JSONB,
  
  -- Metadados
  modelo_versao VARCHAR(50),
  data_geracao TIMESTAMP NOT NULL DEFAULT NOW(),
  validade TIMESTAMP,
  
  -- Status
  status VARCHAR(20) DEFAULT 'ativo',  -- ativo, arquivado, implementado, descartado
  feedback VARCHAR(20),  -- util, parcial, nao_util
  feedback_comentario TEXT,
  feedback_usuario_id INT,
  feedback_data TIMESTAMP,
  
  -- Implementação
  implementado BOOLEAN DEFAULT FALSE,
  data_implementacao TIMESTAMP,
  resultado_real JSONB,  -- Resultado após implementação
  
  -- Índices
  created_at TIMESTAMP DEFAULT NOW(),
  updated_at TIMESTAMP DEFAULT NOW()
);

-- Índices para performance
CREATE INDEX idx_ai_insights_network ON ai_insights(network_id);
CREATE INDEX idx_ai_insights_store ON ai_insights(store_id);
CREATE INDEX idx_ai_insights_tipo ON ai_insights(tipo);
CREATE INDEX idx_ai_insights_status ON ai_insights(status);
CREATE INDEX idx_ai_insights_data ON ai_insights(data_geracao DESC);
CREATE INDEX idx_ai_insights_confianca ON ai_insights(confianca DESC);

Retenção de Dados

  • Insights Ativos:

    Mantidos indefinidamente enquanto relevantes

  • Insights Implementados:

    Arquivados após 90 dias com resultado registrado

  • Insights Descartados:

    Mantidos por 30 dias para auditoria, depois removidos

  • Histórico Completo:

    Backup mensal para análise de evolução da IA

Métricas de Performance da IA

  • Taxa de Implementação:

    % de insights que foram implementados

  • Precisão de Impacto:

    Comparação entre impacto estimado vs real

  • Satisfação dos Usuários:

    Média de feedback (útil/parcial/não útil)

  • Tempo de Resposta:

    Latência média de geração de insights

Segurança e Privacidade

Controle de Acesso:

  • • Insights isolados por network_id e store_id
  • • RBAC garante acesso apenas a dados autorizados
  • • Logs de acesso para auditoria

Anonimização:

  • • Payloads não contêm dados pessoais (PII)
  • • Apenas métricas agregadas e KPIs
  • • Conformidade com LGPD/GDPR