Central de Ajuda

O Involves Cowork é uma ferramenta complementar ao Involves Stage. Ele lê diretamente do Snowflake (cliente escolhido no canto inferior esquerdo da barra lateral) e ajuda o operador a:

• Avaliar a qualidade dos cadastros antes de operar.
• Antecipar o impacto de importações em lote, campo a campo.

Toda a aplicação é read-only — nenhum registro é alterado pelo Cowork. Para aplicar as mudanças, use a interface oficial de importação do Involves Stage com o CSV gerado aqui.

O Cowork cobre os 4 cadastros mais importantes do Involves Stage:

• PDV — Pontos de Venda. Scoring específico com regras de negócio (CNPJ, endereço, coordenadas, segmentações e prefixos de endereço).
• Produto SKU — Produtos no nível de SKU. Hierarquia SKU → Linha → Categoria → Supercategoria (Marca como campo livre).
• Linha de Produto — Agrupa SKUs. Tem marca, categoria, supercategoria e flag de origem (Próprio / Concorrente).
• Colaborador — Usuários operacionais do Stage. Template com 67 colunas (acesso, endereço, remuneração, equipamentos, etc.).

Roteiros e Sortimento estão no backlog — precisam de lógica específica (roteiro é fact table com chave composta; sortimento usa CSV multilinha).

• O Cowork usa um service account do Snowflake (PAT em variáveis de ambiente). Não há login no app: quem abre a URL entra.
• O chip de cliente no rodapé da barra lateral permite alternar entre os databases disponíveis (INVOLVES_<cliente>). Ao trocar, todos os caches do Health Check (PDV, SKU, Linha, Colaborador e Produtividade de Roteiros) são limpos automaticamente — assim dados de um cliente não vazam para outro contexto.
• O chip de ambiente ao lado filtra a base por DIMENSION_SOURCE_URL_PROJECT (útil quando o cliente tem mais de um ambiente).
• Os arquivos intermediários (oportunidades, diff, CSV padronizado, impacto de Loja Perfeita, cache da Produtividade) ficam em cache temporário no servidor e são regerados a cada análise. Apenas os perfis de de-para persistem em disco.

1. Abra Health Check no menu lateral. A tela tem 5 abas: Cadastros, Produtividade de Roteiros, Pesquisas, Loja Perfeita e Respostas de Pesquisa — todas já disponíveis.
2. No topo há um executor consolidado com 6 registros marcáveis — PDVs, Produtos — SKU, Produtos — Linha, Colaboradores, Produtividade de Roteiros e Pesquisas. Todos vêm marcados por padrão. Clique em Executar para rodar os selecionados em paralelo.
3. As abas Loja Perfeita e Respostas de Pesquisa rodam sob demanda, com filtros próprios (Estratégia / Formulário + período) — não entram no executor consolidado. Veja os artigos dedicados abaixo.
4. Cada chip mostra a hora da última análise (ou "sem análise"), ajudando a identificar o que está desatualizado.
5. A aba Cadastros mostra: score consolidado (média dos 3 motores) com veredito e cards clicáveis por entidade.
6. Nos detalhes, cada entidade exibe veredito, resumo em linguagem natural, oportunidades de ajuste (warnings com download em XLSX) e detalhamento técnico recolhível.
7. Para reexecutar uma única entidade, desmarque as outras no executor e clique em Executar — não há mais botão "Reanalisar" por entidade.

PDV — 6 pilares com regras de domínio

A nota total (0–100) é a soma de 6 pilares. Antes de pontuar, dois filtros são aplicados:

• Só PDVs ativos — registros com Ativo ≠ Sim são contados à parte e não pontuam nem geram warnings.
• PDVs de teste são excluídos — nomes com tokens como TESTE, TEMP, ANTIGO, DESATIVADO, DELETAR, REMOVER ou EXCLUIR saem do cálculo (exibidos como "X PDVs teste excluídos") para não distorcer o score.

SKU, Linha e Colaborador — scoring genérico

Sem regras de domínio específicas. Pesos atuais são estimativas iniciais (configuráveis em dq_generic.DEFAULT_WEIGHTS):

Interpretação do score:

• ≥ 80 Base saudável — manter o processo atual.
• 60–79 Precisa de atenção — há lacunas importantes.
• < 60 Requer ação urgente — problemas críticos.

Além da nota, o Health Check de PDVs gera warnings — chamados na tela de achados ou oportunidades de ajuste. Cada warning é uma regra específica e aponta o conjunto de PDVs que falharam nela; um mesmo PDV pode cair em vários ao mesmo tempo.

A tabela "Oportunidades de ajuste" lista todos os warnings ordenados por criticidade, com pilar, quantidade de PDVs, % da base e pontos recuperáveis. Filtros por pilar e criticidade.

Níveis:

• high — problema grave; priorizar.
• medium — atenção; impacto relevante.
• low — melhoria incremental ou aviso informativo.

Cada warning baixa em XLSX os PDVs afetados — 32 colunas do template do Stage + coluna final Avisos detectados. O botão Baixar combinado junta vários warnings sem repetir PDV.

Pilar Endereço

Completude considera 5 campos: Endereço, Bairro, Cidade, UF e CEP. O campo Número não entra (rodovias, zona rural, condomínios).

Pilar Segmentação (Tipo / Perfil / Canal)

Pilar Nome do PDV

Pilar CNPJ

Pilar Roteirização

Pilar neutro — vale sempre 9/9. Mantém só warnings informativos baseados em FACT_SURVEY.

Pilar Padronização cosmética

Aba do Health Check que avalia o cumprimento de visitas (realizadas vs. planejadas) a partir do FACT_VISIT. Meta padrão: 95%, ajustável (50–100%) na própria tile Meta do dashboard — sem nova consulta ao Snowflake.

• Cumprimento mensal dos últimos 6 meses, com a linha-alvo na meta configurada.
• Top 10 com maior oportunidade de lift (30d) — ranking de promotores, supervisores ou regionais pelo volume absoluto de visitas não realizadas. Mínimo de 10 visitas planejadas para entrar na lista.
• Toggle Promotor / Supervisor / Regional: mesma tabela em três recortes.
• Baixar CSV: exporta a aba ativa do Top 10.
• Lift hipotético global: ganho em pontos percentuais se o top 10 atingisse a meta configurada.

Aba on-demand que lê as tabelas FACT_/DIMENSION_PERFECT_STORE_* do Snowflake para diagnosticar a operação corrente de uma Estratégia de Loja Perfeita — diferente do impacto de importação medido no Diagnóstico. Não entra no executor consolidado.

1. Escolha a Estratégia (o seletor é populado por consulta ao Snowflake) e o período (30 / 60 / 90 / 180 dias; padrão 90) e clique em Diagnosticar.
2. O resumo traz o score por PDV, a contagem de condições nunca satisfeitas (+ raramente satisfeitas) e de falhas localizadas por segmento.
3. Pilares: score e pontuação perdida por pilar, com tendência mensal.
4. Regras: ordenadas pela pontuação perdida, separando não-conformidade (condição avaliada e não pontuou) de cobertura (condição nunca medida no PDV).
5. Condições: nunca satisfeitas (avaliadas ≥ N vezes no período, com zero pontuações) e raramente satisfeitas (taxa de sucesso abaixo do piso).
6. Falhas localizadas: condição que pontua bem no geral mas zera num segmento (Perfil / Canal / Regional) — responde "a condição X só falha quando o PDV é do perfil Y".

Exporta o diagnóstico em CSV e a estrutura completa (pilares → regras → condições → produtos) em Markdown para análise por IA externa.

Configuração oficial (gabarito). Ao lado de Diagnosticar, o botão Ver configuração (gabarito) mostra o que está configurado como regra no score engine (lê as tabelas PS_SCORE_*): por Pilar → Regra, os produtos esperados, a pontuação, o tipo de checagem e a segmentação (a quais PDVs cada regra se aplica), no ciclo de validade mais recente. É o "gabarito" que o diagnóstico do executado, sozinho, não enxerga. Funciona independente do diagnóstico e exporta em Markdown.

• Cobertura da configuração (gabarito × executado). Quando há diagnóstico e gabarito da mesma Estratégia, cruza as duas visões e destaca as regras configuradas que nunca foram avaliadas no período — pontos cegos da operação.

Aba on-demand que lê FACT_SURVEY_ANSWER cruzada com formulário, pergunta e produto para mostrar como as respostas se distribuem por Produto × Pergunta num formulário e janela de período. Não entra no executor consolidado.

1. Escolha o Formulário (seletor populado por consulta ao Snowflake) e o período (30 / 60 / 90 dias; padrão 30) e clique em Analisar.
2. O resumo traz total de respostas, PDVs pesquisados, nº de perguntas, produtos (SKU) e células Produto × Pergunta.
3. Rankings de perguntas e de produtos por volume.
4. Anomalias de frequência de aparição: SKUs cuja cobertura (fração de PDVs pesquisados em que o SKU aparece) destoa dentro de um segmento de PDV (Tipo, Perfil, Canal, Centro Comercial, Regional) em relação à cobertura geral.

Exporta a análise completa em Markdown (resumo + perguntas + produtos + matriz, com apêndice JSON) e as anomalias de presença em CSV.

1. Abra Assistente de Importação → Diagnóstico no menu lateral.
2. Escolha o tipo de registro (PDV, SKU, Linha ou Colaborador) nos cards do topo.
3. Envie o arquivo (CSV, XLSX ou XLS). Codificações UTF-8, Latin-1 e CP1252 são aceitas.
4. A aplicação sempre abre a tela de mapeamento para você conferir o de-para — inclusive quando o cabeçalho já está 100% no formato oficial.
5. Após confirmar, a validação roda automaticamente: o CSV padronizado é comparado com a base do Snowflake e cada linha cai em um dos 4 fluxos.
6. A tela do diagnóstico abre com um hero compacto e os detalhes colapsados:
   • 4 cards de status lado a lado (Editados / Criados / Sem mudança / ID não encontrado). Cada card mostra contagem, sub-contadores (lat·long alterados, roteiros impactados, etc.) e badges de alerta.
   • Botão "↓ CSV" dentro de cada card — baixa só aquele fluxo.
   • Chips secundários abaixo dos cards (Inválidas, Loja Perfeita, Detalhes do mapeamento) — só aparecem se relevantes.
   • Clicar em qualquer card abre o painel de deep-dive. Vários painéis podem ficar abertos ao mesmo tempo para comparar fluxos.

Todos os arquivos .csv baixados do Cowork (template, padronizado, recortes por fluxo, achados, comparativo e impacto de Loja Perfeita) saem em UTF-8 com BOM. O BOM faz o Excel do Windows detectar a codificação correta, então acentos como São Paulo e Atibaia abrem certos — sem mais São Paulo.

• O conteúdo não muda: o separador continua vírgula e as colunas são as mesmas. O BOM é só uma marca invisível no começo do arquivo.
• Os arquivos seguem válidos para reimportar no Involves Stage e para reenviar no próprio Cowork — o BOM é descartado automaticamente na leitura.

Cada linha do arquivo passa por uma classificação de fluxo + um conjunto de checks de qualidade + checks específicos de criação. O resultado consolidado entra como coluna Alertas nos CSVs de Editados e Criados.

1. Classificação por fluxo

Cada linha cai em exatamente um fluxo. A classificação é baseada no campo ID e na presença do registro no Snowflake.

A regra de precedência (preencher campos vazios ou manter campos vazios) é aplicada antes da classificação, ao gerar o CSV padronizado.

2. Checks de qualidade (Criados e Editados)

Mesmos checks aplicados pelo Health Check, antecipados para o momento da importação. Cada check só dispara se a coluna correspondente foi enviada no arquivo.

Endereço:

Geolocalização:

Segmentação:

CNPJ:

Nome:

3. Checks adicionais — só para Criados

4. Alerta categórico — Criados e Editados

PDVs normalmente seguem o conjunto já existente de Regional, Macrorregional, Tipo, Perfil e Canal. Quando o CSV introduz um valor que não consta da base, o motor avisa.

• Em Criados: dispara para qualquer valor inédito em Regional, Macrorregional, Tipo, Perfil ou Canal.
• Em Editados: dispara apenas quando o campo categórico está sendo efetivamente alterado pelo CSV.
• Comparação ignora caixa e espaços (TRIM+UPPER).

5. Impactos colaterais

• Roteiros futuros impactados: para cada PDV editado, o motor conta em FACT_ITINERARY os roteiros com SCHEDULED_DATE ≥ hoje. Contadores e download split "com roteiro" / "sem roteiro" no card Editados.
• Lat/Long alterados: contador específico no card Editados — alterações de coordenadas costumam exigir validação no terreno.

6. Como tudo isso vira CSV

Editados e Criados vêm com coluna final Alertas, com os alertas formatados e separados por ·:

Obrigatório faltando: Regional - Obrigatório, Nome do PDV
Nome já existe na base
Nome similar a: Padaria Pão Quente Ltda
CEP em formato inválido · UF inválida
CNPJ repetido no próprio arquivo · CNPJ em formato inválido (≠ 14 dígitos)
Novo valor em Regional: Sul SP · Novo valor em Tipo do PDV: Conveniência
Latitude/Longitude inválida

Linhas sem alerta vêm com a célula em branco. Basta filtrar no Excel/Sheets para revisar só o que importa, corrigir e enviar para a importação oficial.

A tela de mapeamento foi pensada para deixar claro quais campos do template já foram atendidos, em vez de listar apenas as colunas do arquivo:

• Coluna esquerda: campos do template, agrupados por domínio, com ícone de status (★ obrigatório vazio · ✦ obrigatório preenchido · ○ opcional vazio · · opcional preenchido).
• Coluna direita: painel sticky com as colunas do arquivo como chips arrastáveis. Chip atribuído fica esmaecido com indicação do destino.
• Arraste um chip para o campo que ele representa. Para teclado, há um modo select.
• Duplicata é impossível por construção: a coluna selecionada some dos demais campos.
• Colunas não mapeadas ficam em "Colunas do arquivo não atribuídas" — lá você decide se viram custom field ou são ignoradas.
• Se algum campo obrigatório ficar em branco, um modal pede confirmação antes de gerar o CSV.

Perfis salvos (para cliente recorrente)

• Salvar como perfil: dá um nome e opcionalmente limita ao cliente atual.
• Perfis em ./mapping-profiles/<entidade>/ (persistem entre reinícios).
• Aplicação automática: se um perfil tem 100% dos cabeçalhos presentes no arquivo, ele é aplicado sozinho (com toast e botão Desfazer).
• Dropdown Aplicar perfil: mostra perfis disponíveis com quantos cabeçalhos batem.
• Engrenagem abre Gerenciar perfis — excluir, conferir metadados.

O card de precedência só aparece quando o campo ID está mapeado — só assim dá para combinar os dados do cliente com os da base. Duas opções:

• Preencher campos vazios Recomendado — cliente vence quando mandou um valor; se deixou em branco, mantém o valor atual do Involves.
• Manter campos vazios — qualquer valor do cliente vence, inclusive vazios: colunas em branco no CSV apagam os valores já preenchidos no Stage. Use com cautela.

Se um perfil foi salvo com uma regra específica, ele restaura essa regra ao ser aplicado.

Disponível para importações de Produtos SKU e Linhas de Produto. O Cowork verifica se a importação afeta condições ativas do módulo Loja Perfeita — porque o acoplamento entre condição e produto é feito por nome (textual), não por ID.

• Se o nome do produto vai mudar, qualquer condição que cita o nome atual fica órfã → alerta.
• Se o produto vai ser inativado, condições que o referenciam continuam rodando mas perdem o alvo → alerta.

O resultado aparece numa seção dedicada da tela do diff, agrupado por condição (estratégia → pilar → regra → condição), com os produtos que a impactam. Tem botão para baixar o CSV completo (uma linha por produto × condição) para enviar ao time de Loja Perfeita.

Se o cliente não usa Loja Perfeita (view ausente no Snowflake) ou não há impacto, a seção não aparece.

• PDVs de um warning (Health Check · Cadastros): cada warning da tabela "Oportunidades de ajuste" baixa em XLSX os PDVs afetados — 32 colunas do template do Stage + coluna Avisos detectados. O botão "Baixar combinado" junta vários warnings sem repetir PDV.
• Top 10 com maior oportunidade de lift (Produtividade de Roteiros): exporta a tabela visível na visão ativa (top10-lift-promotor-30d.csv etc.).
• CSV por fluxo (Diagnóstico): cada card de status tem botão "↓ CSV":
  • {entidade}_template_padronizado_editados.csv — alteradas + Alertas (PDV apenas).
  • {entidade}_template_padronizado_criados.csv — a criar + Alertas (PDV apenas).
  • {entidade}_template_padronizado_sem_mudanca.csv — inalteradas.
  • {entidade}_template_padronizado_nao_encontrados.csv — ID não achado na base.
• Comparativo (antes e depois) (Diagnóstico · card Editados): CSV das linhas alteradas com uma coluna (original) pareada a cada coluna modificada.
• Com / sem roteiro (PDV · card Editados): split das linhas editadas pelo impacto em roteiros futuros (FACT_ITINERARY com SCHEDULED_DATE ≥ hoje). Use para priorizar revisões em campo.
• CSV padronizado completo (Diagnóstico · rodapé): o arquivo do cliente já ajustado ao template oficial, em arquivo único com todos os fluxos.
• Impacto em Loja Perfeita (só SKU/Linha): uma linha por (produto × condição afetada) com motivo.

PDV

Ponto de Venda cadastrado no Involves Stage.

SKU

Produto em seu nível mais granular (cada variação = um SKU).

Linha de Produto

Agrupamento de SKUs semelhantes. Tem Marca, Categoria, Supercategoria e Origem (Próprio / Concorrente).

Template oficial

CSV padrão do Involves Stage para importação. Cada entidade tem o seu; o Cowork disponibiliza downloads dentro do fluxo.

De-para

Mapeamento entre as colunas do arquivo do cliente e os campos do template oficial.

Perfil de de-para

De-para salvo com nome e (opcionalmente) filtro por cliente. Pode ser aplicado manualmente ou automaticamente quando o arquivo bate 100%.

Custom field

Coluna do arquivo do cliente que não existe no template oficial; sai junto no CSV padronizado como coluna extra.

Regra de precedência

Ao combinar cliente × base Snowflake, define quem prevalece. Só aparece quando o campo ID é mapeado.

Diff

Resultado do Diagnóstico: a diferença, campo a campo, entre o CSV e a base viva.

Condição de Loja Perfeita

Regra ativa no módulo Loja Perfeita do Stage que exige uma resposta específica para um produto em um PDV. Acoplada por nome.

Funcionário teste

Colaborador marcado em DIMENSION_EMPLOYEE.TEST = TRUE. Suas visitas são descartadas pelo motor de Produtividade. NULL é tratado como não-teste.

Afinidade

Nas matrizes de cruzamento do Health Check de PDV (Tipo × Perfil × Canal), mede o quanto dois valores aparecem juntos comparado ao esperado se fossem independentes. ≈ 1 é o esperado; > 1 = combinação natural; < 1 = anti-correlação (abaixo do limiar vira combinação suspeita, provável erro de cadastro).

Lift

Em Produtividade de Roteiros, o ganho hipotético em pontos percentuais que o cliente teria se os promotores do top 10 atingissem a meta de cumprimento.

Roteiro futuro

Visita planejada em FACT_ITINERARY com SCHEDULED_DATE ≥ hoje e não-deletada.

Pilar (Health Check de PDV)

Uma das 6 dimensões avaliadas — Endereço, Segmentação, Nome, CNPJ, Roteirização e Padronização. Cada pilar tem peso próprio e gera seus próprios warnings.

Warning / Achado

Regra de validação do Health Check que falhou para um conjunto de registros. Aparece na tabela "Oportunidades de ajuste" com criticidade high, medium ou low.

Oportunidade de melhoria

Item detectado pelas análises que pode ser corrigido para subir o score.