---
id: varejo/assistente-ia-diretoria-lojas
industria: Varejo e e-commerce
uso: muito usado
esforco: médio
grao: Uma tabela semântica por finalidade: loja x dia, item fiscal, produto x filial, item de pedido
---

# Assistente de IA para diretoria e lojas

Diretoria e gerentes perguntam no chat ou no WhatsApp quanto vendeu, quanto tem em estoque e qual a margem, e cada um só vê a própria loja.

## Resumo executivo

**Para quem:** Diretoria e gerentes de loja de redes de varejo que querem respostas sem abrir o BI.

**O que resolve**

- A IA responde venda líquida, estoque disponível e margem com a mesma regra do dashboard.
- Cada gerente vê só a sua loja; dados sensíveis ficam com a diretoria.
- A IA executa a consulta antes de responder e diz quando o dado não existe ou está atrasado.

**Por que importa:** A IA erra com confiança quando a tabela não explica o que é cada número: já confundiu venda bruta com líquida e zerou um dia de venda por erro de fuso. Um assistente sem acesso por loja expõe dado de outras unidades e de operadores. Com camada semântica e permissões certas, a pergunta do WhatsApp vira o mesmo número do fechamento.

**Perguntas de negócio que responde**

- Quanto a minha loja vendeu ontem, líquido?
- Qual o faturamento e a margem por loja neste mês?
- Tem o produto X disponível no CD? Quantos dias de cobertura?
- O que precisa da atenção da diretoria hoje?
- Quais SKUs explicam o desvio de cada canal contra a meta?
- Quais produtos da curva A estão perto de romper?

**O que você precisa**

- ERP, PDV ou hub conectados na Nekt, com as tabelas de venda, estoque e margem já tratadas
- A lista de lojas e de quem pode ver cada uma
- As definições oficiais de venda líquida, margem e estoque disponível

**O que você recebe**

- Tabelas semânticas por finalidade, com grão e medidas descritos para a IA
- Uma view por loja com permissão própria, e views completas só para a diretoria
- Context document com as regras que a IA deve seguir
- Monitor de frescor que avisa quando a carga não rodou

## Detalhado

### O problema

Diretoria e gerentes querem perguntar em linguagem natural e receber o número oficial. Sem descrição semântica, a IA escolhe a coluna errada (bruta no lugar de líquida), aplica fuso em campo que já é data comercial e soma filiais que dividem o mesmo estoque. Sem permissão por tabela, o gerente de uma loja consulta a outra, e o assistente expõe cancelamentos que identificam o operador.

### Regras de negócio

1. **Uma tabela semântica por finalidade.** Crie tabelas de consumo por pergunta: venda diária por loja, item fiscal, estoque por produto e filial, margem por item. Cada uma tem o grão declarado na descrição em uma frase ("Uma linha por loja, por dia"). Não exponha uma tabela genérica que mistura grãos, e não use campo financeiro de uma tabela operacional como faturamento. (Evite: Uma tabela unificada com tudo e a IA escolhendo as colunas.)
2. **Anote cada coluna para a IA.** Comece a descrição da coluna com a marcação: @pk para chave do grão, @fk para chave estrangeira, @measure additive para somável em qualquer dimensão, @measure non_additive para ticket médio e percentuais, @grain=daily ou monthly. Depois, em texto: origem, regra de cálculo e armadilha. Documente a tabela, não só a transformação. (Evite: Coluna "venda" sem descrição e ticket médio somado por mês.)
3. **Venda líquida é o padrão, e a IA diz qual usou.** "Quanto vendeu" é respondido com a venda líquida (bruta menos descontos menos cancelamentos). A resposta sempre nomeia a métrica, o período e a loja. Bruta só quando pedida. (Evite: Responder a bruta porque a coluna se chama total_vendas.)
4. **Nada de fuso em data comercial.** Campos de data do ERP gravados como meia-noite UTC já são o dia comercial. A IA calcula hoje e ontem em America/Sao_Paulo e compara direto, sem converter o campo. A regra fica escrita na descrição da coluna e no context document. (Evite: A IA aplicar conversão de fuso em toda coluna de data.)
5. **Acesso por loja com permissão por view.** Na Nekt, a permissão vale por camada inteira ou por tabela e view, com papéis de leitura e edição. Pastas no catálogo são só organização visual e não protegem nada. Crie uma view por loja (venda diária filtrada para aquela loja) e conceda a cada gerente só a sua. Use token com escopo por tabela para o assistente de cada público. (Evite: Separar as views de loja em pastas e achar que isso restringe acesso.)
6. **Dado sensível só no escopo da diretoria.** Cancelamentos e tentativas de cancelamento identificam o operador de caixa e servem para avaliação e investigação. Eles não entram nas views de loja, nem filtrados para a própria loja. Ficam em views da diretoria, auditoria e RH. (Evite: Dar ao gerente a tabela de cancelamento filtrada pela loja dele.)
7. **Sem SQL não há número.** O assistente nunca responde número sem executar a consulta. Também não recusa por falta de dado antes de ler a estrutura da tabela semântica do domínio. Métricas marcadas como "a validar" não são inferidas. Quando o campo não existe, a resposta é "dado não localizado nesta fonte". (Evite: Responder de memória ou dizer que não tem o dado sem consultar.)
8. **Estoque disponível por grupo de estoque.** Disponível = quantidade total menos reservada, nunca negativo. Filiais que espelham o mesmo estoque físico são agregadas pelo grupo de estoque, nunca somadas. Produtos com estoque ilimitado ficam fora. Produto inexistente e produto sem estoque têm respostas diferentes. Códigos de produto são padronizados (por exemplo, zeros à esquerda até 18 posições no SAP) antes de cruzar com venda. (Evite: Somar o saldo de duas filiais espelho e dobrar o estoque.)
9. **Frescor declarado em toda resposta.** As views do assistente rodam por evento logo depois da tabela de origem, nunca com gatilho manual. Um monitor com agendamento próprio detecta ausência de execução (por exemplo, mais de 120 minutos sem carga). A resposta informa a data e hora da última atualização. (Evite: Views com gatilho manual que param de atualizar sem ninguém perceber.)
10. **Intercompany não é receita.** Empresas do mesmo grupo podem aparecer como contas ou lojas distintas. Transferências entre elas não são receita nem despesa operacional e são eliminadas no consolidado. A margem vem da tabela oficial de margem, nunca recalculada pela IA com outra regra. (Evite: Somar a venda de uma empresa do grupo para a outra no faturamento consolidado.)

### Qual tabela responde cada pergunta

Roteamento para o context document do assistente.

- **Quanto a loja vendeu, ticket médio** → Venda diária por loja (`uma linha por loja, por dia`)
- **Produto vendido, impostos, CFOP** → Item fiscal (`uma linha por item de cupom ou nota`)
- **Tem em estoque? Onde?** → Estoque por produto e filial (`uma linha por produto, por filial`)
- **Ruptura e giro no tempo** → Snapshot de estoque (`uma linha por produto, por filial, por medição`)
- **Margem por SKU e canal** → Margem de contribuição (`uma linha por item de pedido`)
- **Meta, gap e projeção** → Metas x realizado (`uma linha por loja ou produto, por mês`)
- **Cancelamento por operador** → Só diretoria e auditoria (`fora das views de loja`)

### Definições

| Métrica | Definição |
|---|---|
| Venda líquida | venda bruta menos descontos menos cancelamentos, por loja e dia comercial; medida somável |
| Ticket médio | venda líquida / cupons válidos no recorte pedido; medida não somável |
| Estoque disponível | maior entre (quantidade total menos reservada) e zero, por produto e grupo de estoque, na última medição |
| Cobertura em dias | (estoque disponível + em trânsito) / venda média diária dos últimos 30 dias, por produto e filial |
| Necessidade líquida | requisição aberta menos (estoque disponível + pedido de compra aberto), por produto e curva ABC |
| Margem | soma do lucro bruto / soma do faturamento no período, pela tabela oficial de margem |
| Frescor | tempo desde a última execução bem sucedida da tabela consultada, em minutos |

### Armadilhas

- **Bruta confundida com líquida.** A IA respondeu a venda bruta como líquida e errou em seis dígitos o resultado de uma única loja num único dia. Como evitar: Venda líquida como padrão, com @measure e regra escritas na descrição.
- **Dia zerado por fuso.** A IA converteu para BRT um campo de data que já era o dia comercial e respondeu zero venda num dia de venda alta. Como evitar: Descrição da coluna dizendo que não há conversão de fuso.
- **View parada por mais de uma semana.** As views por loja foram criadas com gatilho manual e ficaram mais de uma semana sem atualizar, com a fonte em dia. Como evitar: Gatilho por evento após a tabela de origem e monitor de ausência de execução.
- **Pasta tratada como segurança.** As views de loja estavam em pastas separadas e a equipe supôs que o gerente só via a sua. Pasta é organização visual. Como evitar: Permissão concedida view a view, testada com o usuário de cada loja.
- **Estoque dobrado ou sumido.** Duas filiais espelho somadas dobraram o saldo. Em outra base, extrair o código do produto do campo de URL em vez do código de referência perdeu cerca de 80% do estoque. Como evitar: Agregar por grupo de estoque e extrair o código do campo de referência.

### Teste de aceitação

- [ ] Para um conjunto de 10 perguntas de referência (venda líquida de uma loja ontem, estoque de um produto num CD, margem de um canal no mês), o assistente devolve exatamente o número do dashboard em todas.
- [ ] Com o usuário de uma loja, consultar outra loja ou a tabela de cancelamentos retorna sem permissão.
- [ ] O estoque de um grupo de filiais espelho é igual ao saldo de uma filial do grupo, não à soma.
- [ ] Toda resposta numérica traz a data da última atualização, e o monitor alerta quando a carga passa do limite sem rodar.

### Context document

```text
Assistente de vendas, estoque e margem
- Não responda número sem executar SQL. Não recuse por falta de dado antes de ler o DDL da tabela semântica do domínio.
- Roteamento: venda e ticket por loja na venda diária por loja; produto e imposto no item fiscal; estoque no estoque por produto e filial; ruptura no snapshot de estoque; margem na tabela de margem de contribuição; meta na tabela de metas.
- "Quanto vendeu" = venda líquida (bruta menos descontos menos cancelamentos). Diga sempre a métrica, o período e a loja.
- Datas de venda do ERP são o dia comercial gravado como meia-noite UTC. Não converta fuso. Hoje e ontem em America/Sao_Paulo.
- Ticket médio e percentuais não são somáveis: recalcule a partir das somas.
- Estoque disponível = total menos reservado, mínimo zero. Agregue filiais espelho pelo grupo de estoque. Diga se o produto não existe ou se só está sem estoque.
- Métricas marcadas como "a validar" não são inferidas. Campo inexistente: "dado não localizado nesta fonte".
- Transferências entre empresas do grupo não são receita.
- Informe a data da última atualização em toda resposta numérica.
Exceções por cliente:
- <cliente>: filiais <A> e <B> são espelho do mesmo estoque (grupo <grupo>).
- <cliente>: lojas sem venda direta <lista>.
- <cliente>: empresas do grupo <lista>; vendas entre elas são intercompany.
```

### Variações

- **Busca de produto por apelido:** Dicionário de abreviações do cadastro (qj para queijo) e índice invertido para achar o produto como o vendedor escreve.
- **Avaliação do assistente:** Guardar perguntas e respostas do WhatsApp numa tabela para revisar acertos e erros.
- **Pós-venda e oficina:** Mesma camada para OS, peças e mão de obra, separando faturamento do resultado e volume de passagens.