Ingestão de Dados Legado → DBCHECKOUT
Processo de extração, transformação e consolidação de dados dos sistemas legados
1Tipos de Ingestão Suportados
Conexão Direta MySQL (Recomendado)
Conexão read-only ao banco MySQL legado para extração via SQL
- • Vantagens: Tempo real, sem intermediários, queries otimizadas
- • Requisitos: Acesso de rede, usuário read-only, whitelist de IPs
- • Segurança: VPN ou túnel SSH, credenciais criptografadas
- • Performance: Connection pooling, timeout configurável
Upload de CSV
Exportação manual de dados em formato CSV
- • Uso: Lojas sem conectividade ou por segurança
- • Formato: UTF-8, delimitador vírgula ou ponto-e-vírgula
- • Validação: Schema validation antes do processamento
- • Limitação: Máximo 50MB por arquivo
API REST (JSON)
Sistema legado envia dados via POST para endpoint do DBCHECKOUT
- • Endpoint: POST /api/v1/ingestion/push
- • Autenticação: API Key por loja
- • Payload: JSON estruturado com pedidos, itens, pagamentos
- • Resposta: Status de processamento e validações
Arquivo JSON
Upload de arquivo JSON com estrutura padronizada
- • Uso: Migração inicial ou carga histórica
- • Estrutura: Schema JSON validado
- • Vantagem: Suporta dados complexos e aninhados
- • Limitação: Máximo 100MB por arquivo
2Frequência de Ingestão
EOD (End of Day)
Consolidação ao final do dia operacional
- • Horário: Após fechamento de caixa
- • Dados: Dia completo consolidado
- • Uso: Padrão para maioria das lojas
- • Agendamento: Automático (ex: 02:00)
Por Turno
Consolidação a cada turno operacional
- • Frequência: 2-3x por dia
- • Dados: Turno específico
- • Uso: Lojas com alta demanda
- • Vantagem: Visibilidade intraday
Manual
Ingestão sob demanda pelo gestor
- • Trigger: Botão no dashboard
- • Dados: Período selecionado
- • Uso: Reprocessamento ou correções
- • Limite: 1x por hora por loja
3Estrutura de Staging (Área Temporária)
Fluxo de Staging
Dados brutos extraídos do legado são inseridos em tabelas de staging
Verificação de schema, tipos de dados, valores obrigatórios
Cálculo de KPIs, agregações, joins com hierarquia de produtos
Dados transformados são inseridos nas tabelas analíticas finais
Tabelas de staging são truncadas após sucesso
Tabelas de Staging
staging_ordersPedidos brutos extraídos
staging_order_itemsItens dos pedidos
staging_paymentsPagamentos dos pedidos
staging_productsProdutos e hierarquia
4Validações Obrigatórias
Validações Bloqueantes
Erros que impedem o processamento
- • Campos obrigatórios ausentes: store_id, date, order_id
- • Tipos de dados inválidos: texto em campo numérico
- • Valores negativos inválidos: preço, quantidade negativa
- • Datas futuras: pedidos com data maior que hoje
- • Referências quebradas: produto_id inexistente
Validações de Alerta
Avisos que não impedem processamento
- • Valores atípicos: ticket médio 10x maior que média
- • Dados incompletos: campos opcionais vazios
- • Inconsistências leves: soma de itens difere do total
- • Produtos sem grupo/tipo: hierarquia incompleta
Validações de Integridade
Verificações de consistência matemática
- • Total do pedido: SUM(itens) = total_pedido
- • Pagamentos: SUM(pagamentos) = total_pedido
- • Margem: margem = receita - custo
- • Percentuais: soma de % não excede 100%
5Estratégia de Deduplicação
Identificação de Duplicatas
store_id + order_id + date
Combinação única que identifica um pedido específico de uma loja em uma data
MD5(order_id + items + total + timestamp)
Detecta se o mesmo pedido foi enviado múltiplas vezes sem alterações
Estratégias de Resolução
Em caso de duplicata, manter o registro com timestamp mais recente
Combinar informações complementares de registros duplicados
Se hash é idêntico, descartar silenciosamente
Notificar sobre duplicatas com diferenças significativas
6Estratégia de Reprocessamento
Reprocessamento por Período
Permite reprocessar dados de um período específico
- • Gestor seleciona data inicial e final no dashboard
- • Sistema deleta KPIs consolidados do período
- • Extrai novamente dados do legado
- • Reconsolida e recalcula todos os KPIs
- • Útil para correções de dados ou ajustes de cálculo
Reprocessamento Automático de Falhas
Sistema tenta reprocessar automaticamente jobs que falharam
- • Retry com backoff exponencial: 1min, 5min, 15min, 1h
- • Máximo de tentativas: 5 retries
- • Após 5 falhas: Alerta para equipe técnica
- • Logs detalhados: Rastreamento de cada tentativa
Histórico de Reprocessamentos
Rastreabilidade completa de todas as operações
- • Tabela
etl_history - • Registra: quem, quando, período, motivo, status
- • Permite auditoria e troubleshooting
- • Dashboard com histórico de execuções
7Logs e Auditoria
Níveis de Log
Início e fim de jobs, registros processados
Validações de alerta, dados atípicos
Falhas de conexão, validações bloqueantes
Queries SQL executadas, payloads detalhados
Informações Registradas
- • job_id (UUID único)
- • store_id, network_id
- • start_time, end_time
- • duration (segundos)
- • status (success/failed)
- • records_extracted
- • records_validated
- • records_inserted
- • records_updated
- • records_rejected
- • error_count
- • warning_count
- • error_messages (JSON)
- • failed_records (sample)
- • extraction_time
- • transformation_time
- • load_time
- • records_per_second
Retenção de Logs
- • Logs operacionais: 90 dias (rotação automática)
- • Logs de auditoria: 7 anos (conformidade fiscal)
- • Logs de erro: 1 ano (troubleshooting)
- • Arquivamento: Compressão e storage S3/Glacier
8Tratamento de Falhas
Falha de Conexão com Banco Legado
- • Ação: Retry automático com backoff exponencial
- • Timeout: 30 segundos por tentativa
- • Fallback: Após 5 falhas, notificar gestor
- • Impacto: Dashboard exibe "Dados desatualizados"
Dados Corrompidos ou Inválidos
- • Ação: Rejeitar registros inválidos
- • Log: Registrar detalhes do erro e payload
- • Notificação: Email para gestor com registros rejeitados
- • Continuidade: Processar registros válidos normalmente
Timeout em Queries Longas
- • Limite: 5 minutos por query
- • Ação: Cancelar query e logar
- • Otimização: Sugerir índices ou particionamento
- • Alternativa: Processar em lotes menores
Transações e Rollback
- • Toda consolidação ocorre dentro de transação
- • Em caso de erro, rollback completo
- • Garante consistência: tudo ou nada
- • Staging é limpo apenas após commit bem-sucedido
Alertas e Notificações
- • Email: Falhas críticas para gestor e equipe técnica
- • Dashboard: Badge de alerta em lojas com falha
- • Webhook: Integração com Slack/Teams (opcional)
- • SMS: Falhas recorrentes (3+ consecutivas)
Especificação de Ingestão
DBCHECKOUT - Ingestão de Dados v1.0