Plano de execução das considerações do cliente

Produto: GV - Gestor de Vendas

Documento de origem: Considerações - Dbai.pdf

Data da consolidação: 30/07/2026

Situação: plano aprovado parcialmente e aguardando execução incremental

Objetivo

Consolidar os ajustes solicitados pelo cliente para metas, campanhas, relatórios, permissões e cadastro de lojas. A implementação será dividida em PRs pequenas, com teste automatizado, QA em homologação, documentação e possibilidade de reversão.

Decisões confirmadas

Perfis e escopo

• Administradores e perfis de backoffice podem cadastrar e editar metas.
• Supervisores podem consultar somente suas lojas, funcionários, metas, campanhas, vendas e relatórios.
• Líderes podem consultar somente sua loja, funcionários, metas, campanhas, vendas e relatórios.
• Supervisores e líderes terão metas em modo somente leitura.
• Vendedores não acessam o backoffice; utilizam apenas a Visão do Vendedor e os fluxos operacionais autorizados.
• O escopo deve ser aplicado no backend e no frontend. Ocultar uma opção na tela não substitui a validação da API.

Metas e sazonalidade

• A etapa 5 deve partir da meta diária da loja definida pela sazonalidade.
• A meta de cada dia será dividida entre os vendedores disponíveis naquele dia.
• Disponibilidade considera loja aberta, feriados, pontos facultativos, vínculo com a loja, cobertura, transferência, férias, ausências e situação ativa.
• Meta 1, Meta 2 e Meta 3 utilizarão a mesma curva de sazonalidade.
• Diferenças de centavos serão ajustadas deterministicamente para preservar o total mensal exato.
• Feriados excluídos da distribuição não podem manter metas diárias.
• Se um feriado afetar uma meta existente, o administrador receberá um alerta para decidir se deseja recalcular. A decisão e a alteração serão auditadas.

Importação de metas

• Será disponibilizado um modelo oficial para download na modal de importação.
• O modelo inicial terá loja, período, Meta 1, Meta 2, Meta 3 e peso diário de sazonalidade.
• A importação terá pré-visualização, validação por linha, relatório de erros, confirmação e gravação transacional.
• O formato de sazonalidade já usado pelo cliente será avaliado quando uma amostra for disponibilizada. Poderá ser incluído como formato compatível sem remover o modelo oficial do GV.

Campanhas

• Campanhas poderão usar métrica financeira, quantidade por SKU ou valor por SKU.
• Uma campanha poderá conter um ou vários SKUs.
• A abrangência dos vencedores poderá ser geral, por loja ou ambas.
• Em caso de empate, todos os participantes empatados serão considerados vencedores.
• Resultados e vencedores poderão ser exportados.

Relatórios

• A comparação padrão será o mesmo período do ano anterior, identificado como L.Y..
• A opção de período imediatamente anterior será preservada como alternativa.
• O Raio-X seguirá a ordem visual do Indeva e receberá as colunas de Meta atual e usabilidade.
• Enquanto não houver outra definição, Meta atual será apresentada em relação à Meta 1.
• Tabelas extensas terão rolagem horizontal e vertical, cabeçalho fixo e dimensões adequadas para uso sem reduzir o zoom do navegador.
• Os cards do dashboard terão layout uniforme e comparação visual entre período atual e L.Y.

Lojas

• O catálogo de tipos de loja receberá a opção OUTLET.
• O novo tipo será suportado pelo banco, API, formulários, filtros, importações e auditoria.

Plano incremental

PR A - Segurança de escopo, navegação e tipo de loja

1. Revalidar autorização de todas as APIs por empresa, supervisor e loja.
2. Garantir que supervisor nunca receba dados de lojas fora de sua gestão.
3. Garantir que líder nunca receba dados de outra loja.
4. Bloquear criação e edição de metas para supervisor e líder.
5. Bloquear acesso de vendedor às rotas e APIs do backoffice.
6. Mover Relatórios para logo depois do Dashboard no menu.
7. Adicionar o tipo de loja OUTLET, com migration Prisma.
8. Criar testes de autorização negativos e positivos para cada perfil.

Critério de aceite: alterar filtros, URL ou payload manualmente não permite consultar nem modificar dados fora do escopo.

PR B - Modelo de importação e nova distribuição de metas

1. Disponibilizar o botão Baixar modelo na modal de importação.
2. Implementar parser e validação do modelo oficial.
3. Criar endpoint transacional de importação e relatório de resultado.
4. Implementar a curva diária de sazonalidade da loja.
5. Dividir cada meta diária entre os vendedores disponíveis no respectivo dia.
6. Manter edição por valor e percentual, preservando o fechamento das três metas.
7. Adicionar rolagem, cabeçalho fixo e melhor navegação no editor diário.
8. Registrar criação, importação, edição, recálculo e publicação em auditoria.

Dependência: receber a planilha de sazonalidade do cliente para adicionar um segundo adaptador de importação, se necessário.

PR C - Feriados e recálculo assistido

1. Detectar metas atuais ou futuras afetadas ao cadastrar ou editar um feriado.
2. Exibir ao administrador as lojas, ciclos e datas afetados.
3. Perguntar se deseja recalcular.
4. Remover a meta do dia excluído e redistribuir o valor pelos demais dias válidos.
5. Não alterar a distribuição quando o administrador recusar.
6. Registrar usuário, resposta, valores anteriores e valores novos.
7. Impedir no backend a gravação de metas em dias excluídos.

Critério de aceite: o dia excluído fica zerado e o total mensal permanece exatamente igual após o recálculo.

PR D - Campanhas por SKU e vencedores

1. Corrigir a integração Protheus para persistir código, descrição, quantidade e valor real dos itens da nota.
2. Reprocessar itens históricos cuja carga contenha SKU no payload original.
3. Adicionar seleção múltipla de SKUs na campanha.
4. Permitir métrica por quantidade ou valor vendido.
5. Permitir apuração geral, por loja ou ambas.
6. Substituir o ranking demonstrativo por cálculo no backend usando período, lojas, vendedores, SKUs, métrica e elegibilidade da campanha.
7. Implementar empate com múltiplos vencedores.
8. Criar tela de resultados e exportação .xlsx.
9. Ajustar a modal para rolagem interna, cabeçalho e rodapé fixos.

Critério de aceite: o resultado exportado pode ser reproduzido a partir do Analítico de vendas para os mesmos SKUs, lojas e período.

PR E - Raio-X, usabilidade e comparação L.Y.

1. Reordenar as colunas a partir de Meta: Meta, Vendas, Meta atual, % da Meta 1, Taxa de conversão, P.A., Ticket médio, Preço médio, Atendimentos, Quantidade vendida, Peças, Trocas, Usabilidade, Usab. (+) e Usab. (-).
2. Formalizar e documentar as fórmulas de usabilidade.
3. Aplicar a mesma ordem na tela e na exportação.
4. Adicionar rolagem horizontal e vertical com cabeçalho fixo.
5. Alterar o comparador para usar o mesmo intervalo do ano anterior por padrão.
6. Preservar período imediatamente anterior como opção.
7. Aplicar L.Y. ao dashboard, desempenho, lojas, ranking, detalhamento e gráficos.
8. Padronizar todos os cards e mostrar período atual e L.Y. com legenda e tooltip.

Dependência funcional: validar com o cliente a fórmula de Usabilidade, Usab. (+) e Usab. (-). Até essa definição, as colunas não devem apresentar números estimados como se fossem oficiais.

PR F - QA, documentação e homologação

1. Executar testes unitários das regras de distribuição, comparação e ranking.
2. Executar testes de integração das APIs e permissões.
3. Executar QA visual em desktop e tablet.
4. Validar exportações contra os dados exibidos.
5. Atualizar API, processos, treinamentos e roteiro de apresentação.
6. Fazer backup, deploy em homologação e smoke test dos três ambientes.
7. Realizar QA conjunto antes da promoção para produção.

Carga histórica Protheus 2025

A carga do período de 01/01/2025 a 31/12/2025 foi executada na homologação em 30/07/2026 com os seguintes controles:

1. backup completo do PostgreSQL antes da carga;
2. registro da quantidade e do valor existentes em 2025;
3. importação em lotes mensais;
4. interrupção imediata se algum CNPJ falhar;
5. relatório JSON por mês;
6. conferência de quantidade, valor, peças, lojas, vendedores e cobertura mensal;
7. segunda execução amostral para comprovar idempotência;
8. registro das divergências de NF no validador, sem sobrescrever silenciosamente uma nota já existente.

O carregamento de 2025 é necessário para que o comparador L.Y. apresente dados reais quando o usuário consultar períodos de 2026.

Resultado da carga

• Backup anterior à carga validado e acompanhado de checksum SHA-256.
• 12 relatórios mensais concluídos com sucesso.
• 50.409 movimentos recebidos da origem.
• 50.404 vendas únicas persistidas.
• Cinco movimentos repetidos na origem foram tratados de forma idempotente.
• Nenhuma chave de documento ficou duplicada no banco.
• Faturamento líquido carregado: R$ 35.548.211,07.
• Peças carregadas: 135.496.
• 11 lojas e 119 vendedores com vendas no ano.
• 75 vendas sem vendedor, registradas no Validador NF.
• Cinco divergências de troca de vendedor, registradas no Validador NF.
• 80 pendências de NF no total.
• Uma falha transitória 502 ocorreu em outubro para um CNPJ. A nova execução reconheceu 2.955 vendas existentes e criou somente as 835 restantes, comprovando a idempotência do processo.
• A loja Salvador WS possui vendas a partir de 17/06/2025; por isso os meses de janeiro a maio possuem movimentação em dez das onze lojas.

Limitação identificada para campanhas por SKU

As 50.404 vendas foram carregadas com um item de SKU genérico PROTHEUS. O payload original permanece preservado, mas a rotina horária ainda não transforma os campos de produto em itens reais. A PR de campanhas por SKU deve corrigir essa persistência e reprocessar os payloads históricos antes de publicar rankings por produto.

Pendências para a reunião

• Obter uma amostra real da planilha de sazonalidade utilizada pelo cliente.
• Definir as fórmulas oficiais de Usabilidade, Usab. (+) e Usab. (-).
• Confirmar se campanhas por SKU terão quantidade mínima, valor mínimo ou faixas de premiação além do ranking.