Especificação do Agente de IA
Arquitetura e funcionamento do sistema de inteligência artificial do DBCHECKOUT
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
{
"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
{
"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
URGENTESituaçõ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
Atenção
IMPORTANTEDesvios 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
Informativo
FYIInformaçõ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
Positivo
BOA NOTÍCIAReconhecimento 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
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_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
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
Especificações Técnicas Relacionadas
Especificação do Agente de IA
DBCHECKOUT - Inteligência Artificial Contextual v1.0