Consolidação Temporal Oficial

Granularidade Temporal do DBCHECKOUT

Padrão oficial de consolidação temporal em 4 níveis: Ano, Mês, Semana e Dia

Princípio Fundamental

Todo dado consolidado no DBCHECKOUT deve obedecer, obrigatoriamente, a quatro granularidades temporais

Ano

Visão anual

Mês

Visão mensal

Semana

Visão semanal

Dia

Visão diária

Nada de consolidação solta

Nada de GROUP BY date_trunc em runtime

Tudo pré-calculado, versionado e consistente

Dimensão Tempo (BASE DO SISTEMA)

Tabela dim_tempo - Obrigatória e Imutável

SQL SchemaPostgreSQL

CREATE TABLE dim_tempo (
  data            DATE PRIMARY KEY,
  ano             INT,
  mes             INT,
  mes_nome        VARCHAR(20),
  semana_ano      INT,
  semana_mes      INT,
  dia_mes         INT,
  dia_semana      INT,
  dia_nome        VARCHAR(15),
  is_fim_semana   BOOLEAN
);

Imutável

Dados não são alterados após criação

Consistência

Garante alinhamento entre MySQL / Postgres / IA / Frontend

Modelo de Consolidação

Regra de Ouro: Não existe KPI sem chave temporal explícita

Toda tabela consolidada deve conter:

ano | mes | semana | data

Consolidação Diária (BASE)

Fonte Única

CREATE TABLE kpi_vendas_dia (
  rede_id         UUID,
  loja_id         UUID,
  data            DATE,
  ano             INT,
  mes             INT,
  semana          INT,
  faturamento     NUMERIC(14,2),
  pedidos         INT,
  quantidade      INT,
  ticket_medio    NUMERIC(10,2),
  margem          NUMERIC(14,2),
  PRIMARY KEY (rede_id, loja_id, data)
);

✓ Todas as outras consolidações derivam daqui

Consolidação Semanal

Derivada

CREATE TABLE kpi_vendas_semana (
  rede_id         UUID,
  loja_id         UUID,
  ano             INT,
  semana          INT,
  faturamento     NUMERIC(14,2),
  pedidos         INT,
  ticket_medio    NUMERIC(10,2),
  PRIMARY KEY (rede_id, loja_id, ano, semana)
);

Consolidação Mensal

Derivada

CREATE TABLE kpi_vendas_mes (
  rede_id         UUID,
  loja_id         UUID,
  ano             INT,
  mes             INT,
  faturamento     NUMERIC(14,2),
  pedidos         INT,
  ticket_medio    NUMERIC(10,2),
  PRIMARY KEY (rede_id, loja_id, ano, mes)
);

Consolidação Anual

Derivada

CREATE TABLE kpi_vendas_ano (
  rede_id         UUID,
  loja_id         UUID,
  ano             INT,
  faturamento     NUMERIC(14,2),
  pedidos         INT,
  ticket_medio    NUMERIC(10,2),
  PRIMARY KEY (rede_id, loja_id, ano)
);

Pipeline de Consolidação

Fluxo obrigatório - Nunca pular etapas

LEGADO

MySQL

STAGING

Dados crus

DIÁRIA

Base

SEMANAL

Agregada

MENSAL

Agregada

ANUAL

Agregada

Nunca pular etapas

Nunca recalcular direto do legado

Regras de Processamento

Ordem

1. Dia

2. Semana

3. Mês

4. Ano

Reprocessamento

✓ Permitido por data

✗ Nunca por período aberto

Imutabilidade

Dia fechado = não recalcula

Correção = versão nova (log)

Definição de Semana (ISO 8601)

Segunda-feira = início da semana. Evita divergência entre anos.

WEEK(data, 3) -- MySQL ISO

Impacto na IA

Dados estruturados para análise inteligente

Payload JSONEstruturado

{
  "ano": 2026,
  "mes": 1,
  "semana": 4,
  "data": "2026-01-29",
  "faturamento": 48230.50,
  "pedidos": 554,
  "ticket_medio": 87.09
}

Análises Possíveis

• Comparação M/M (mês sobre mês)

• Comparação S/S (semana sobre semana)

• Sazonalidade

• Previsão de demanda

Confiabilidade

IA recebe dados consistentes e pré-validados, garantindo insights precisos

Impacto no Frontend (React)

Filtros temporais oficiais

Ano

Visão estratégica

Mês

Visão tática

Semana

Visão operacional

Dia

Visão detalhada

Comportamento Responsivo

Mobile

Dia / Semana

Tablet

Semana / Mês

Desktop

Mês / Ano

Importante: O frontend não calcula datas, apenas escolhe a granularidade

Benefícios desta Decisão

Performance Extrema

Dados pré-calculados eliminam processamento em tempo real

KPIs Consistentes

Mesma métrica sempre retorna o mesmo valor

Comparações Corretas

Períodos alinhados garantem análises precisas

IA Confiável

Insights baseados em dados estruturados

Cache Simples

Estratégia de cache por granularidade

Multi-loja Escalável

Suporta milhares de lojas sem degradação

Erros que Você Evita

GROUP BY date() em produção

Cálculos em tempo real degradam performance

Comparações incoerentes

Períodos desalinhados geram análises incorretas

Filtros quebrados

Inconsistência temporal quebra filtros do dashboard

IA errática

Dados inconsistentes geram insights não confiáveis

Retrabalho futuro

Refatoração custosa para corrigir arquitetura temporal

Veredito Técnico

Essa decisão coloca o DBCHECKOUT no nível de BI corporativo

Dimensão tempo correta

Consolidação escalável

Base sólida para IA

Frontend rápido

Especificação Geral Setup Supabase