Movimento
As procedures de Movimento expõem, para clientes com acesso direto ao banco de dados, exatamente os mesmos números apresentados no aplicativo WeRetail.
Não são consultas novas: cada procedure executa o mesmo script utilizado pelo aplicativo, mantido centralizadamente na configuração da plataforma. Isso garante que o resultado obtido via banco seja idêntico ao resultado exibido no app, mesmo após evoluções na regra de cálculo.
Os cálculos de Movimento dependem de parâmetros (período, tipo de comparação, filtros). Uma view não recebe parâmetros — por isso a interface pública é uma stored procedure.
Conceito
Toda procedure de Movimento retorna, em uma única linha (ou em uma linha por dia), dois blocos de indicadores:
| Bloco | Sufixo | Significado |
|---|---|---|
| TY (This Year) | _TY | Período informado em @DataInicio .. @DataFim |
| LY (Last Year) | _LY | Período comparativo, calculado conforme @ComparacaoTipo |
O nome LY é histórico: o período comparativo não é necessariamente o ano anterior, e sim o período de comparação escolhido (mês anterior, semana anterior, período customizado etc.).
Tipos de retorno (@Tipo)
Cada procedure aceita o parâmetro @Tipo, que define o formato do resultado:
@Tipo | Formato | Uso típico |
|---|---|---|
RANGE | Agrupado — uma linha com o acumulado de todo o período | KPIs, cartões, totalizadores |
EXTRACT | Extrato — uma linha por dia do período | Gráficos de evolução, exportações, conferência diária |
No formato EXTRACT, cada dia do período TY é alinhado ao dia correspondente do período LY pela posição relativa dentro do intervalo (1º dia com 1º dia, 2º dia com 2º dia, e assim por diante).
Níveis de agregação
Os dados de movimento são materializados em diferentes níveis. Cada nível possui a sua própria procedure e os seus próprios filtros opcionais.
| Nível | Procedure | Filtros adicionais |
|---|---|---|
| Rede (consolidado) | p_SALES_MOVIMENTOPERIODO | — |
| Canal | p_SALES_CANALMOVIMENTOPERIODO | @Canal |
| Marca | p_SALES_MARCAMOVIMENTOPERIODO | @Marca |
| Canal + Marca | p_SALES_CANALMARCAMOVIMENTOPERIODO | @Canal, @Marca |
| Canal + Marca + Loja | p_SALES_CANALMARCALOJAMOVIMENTOPERIODO | @Canal, @Marca, @Loja |
| Canal + Marca + Loja + Vendedor | p_SALES_CANALMARCALOJAVENDEDORMOVIMENTOPERIODO | @Canal, @Marca, @Loja, @CodVendedor |
| Cluster | p_SALES_CLUSTERMOVIMENTOPERIODO | @Cluster |
Regras gerais dos níveis:
- Escolha sempre o nível mais alto que atenda à necessidade. Consultar o consolidado da rede em
p_SALES_MOVIMENTOPERIODOé muito mais barato do que somar o nível de vendedor. - Filtros adicionais são opcionais: quando não informados (
NULL), a procedure retorna todas as ocorrências daquele nível. - Colunas de identificação (
CHANNEL,BRAND,SOCIALID,CLUSTER, etc.) aparecem apenas nos níveis em que fazem sentido.
Parâmetros comuns
Todos os níveis compartilham o mesmo conjunto de parâmetros de período e comparação.
| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
|---|---|---|---|---|
@Tipo | varchar(20) | Não | RANGE | RANGE (agrupado) ou EXTRACT (extrato diário) |
@DataInicio | date | Sim | — | Primeiro dia do período TY |
@DataFim | date | Sim | — | Último dia do período TY |
@ComparacaoTipo | varchar(40) | Não | ANO_ANTERIOR | Regra de cálculo do período LY |
@ComparacaoValor | int | Não | 1 | Quantas vezes a regra de comparação é aplicada (deve ser ≥ 1) |
@DataInicioLY | date | Não | NULL | Primeiro dia do período LY (uso com CUSTOMIZADO) |
@DataFimLY | date | Não | NULL | Último dia do período LY (uso com CUSTOMIZADO) |
Tipos de comparação (@ComparacaoTipo)
| Valor | Como o período LY é calculado |
|---|---|
ANO_ANTERIOR | Mesmo intervalo, @ComparacaoValor ano(s) para trás |
MES_ANTERIOR | Mesmo intervalo, @ComparacaoValor mês(es) para trás |
SEMANA_ANTERIOR | Mesmo intervalo, @ComparacaoValor semana(s) para trás |
DIAS_ANTERIORES | Mesmo intervalo, deslocado @ComparacaoValor dia(s) para trás |
PERIODO_ANTERIOR_MESMOS_DIAS | Intervalo imediatamente anterior, com a mesma quantidade de dias |
RETAIL_454 | Dia equivalente do calendário varejista 4-5-4 (aceita apenas @ComparacaoValor = 1) |
CUSTOMIZADO | Intervalo livre informado em @DataInicioLY e @DataFimLY |
Se @DataInicioLY ou @DataFimLY forem informados, a procedure assume CUSTOMIZADO automaticamente, independentemente do valor de @ComparacaoTipo. Nesse caso, ambos precisam ser preenchidos.
Validações
As procedures interrompem a execução (erro 50000) nos seguintes casos:
@DataInicioou@DataFimnão informados;@DataIniciomaior que@DataFim;@ComparacaoValormenor que1;@ComparacaoTipofora da lista aceita;CUSTOMIZADOsem@DataInicioLYe@DataFimLY;- intervalo LY invertido (
@DataInicioLYmaior que@DataFimLY); @Tipodiferente deRANGEouEXTRACT.
Convenções de leitura do resultado
- Colunas numéricas nunca retornam
NULL: quando não há movimento, o valor é0. LASTUPDATEindica o momento da última atualização dos dados de movimento no período TY — use-a para saber o quão "fresco" está o número.- Valor líquido: as colunas
TOTAL_*representam a venda bruta. Para o líquido, subtraia as devoluções (RETURNS_DAY_*). - Algumas colunas existem por compatibilidade de contrato com o aplicativo e são consideradas legado: podem vir zeradas ou vazias e serão removidas futuramente. Elas estão sinalizadas na documentação de cada procedure.
- Os totais consideram a base diária de movimento.
Pré-requisitos de acesso
Valem as mesmas condições da integração via banco de dados:
- IP fixo liberado no firewall (ou liberação dinâmica pelo aplicativo);
- usuário de leitura fornecido pela equipe WeRetail, com permissão de
EXECUTEnas procedures de Movimento.