Manual — Conferência Inteligente

Sistema de auditoria de estoque com foco em prevenção de perdas. O operador conta no celular; o gestor revisa divergências, aplica ajustes reais no estoque e acompanha padrões de perda no desktop. Este manual descreve o sistema como ele realmente funciona hoje — screenshots da tela real, sem dado inventado.

1Acesso e perfis

O login é o mesmo do resto do CotaFácil — usuários reais cadastrados em Configurações → Usuários, senha com hash (bcrypt), sessão válida por 12h de uso contínuo. Não existem credenciais fixas de teste; cada loja tem seus próprios usuários.

Perfil	O que vê	Financeiro (R$)
admin	Tudo — Auditorias, Histórico & Padrões, Localizações, Ajustes pendentes	Sim (default)
gerente	Igual ao admin, exceto gerir outros usuários	Sim (default)
operador	Só o coletor mobile (bipagem)	Não vê preço/perda em R$ (default)

Permissões granulares (Configurações → Usuários, checkbox por pessoa)

Permissão	O que libera
ver_custo	Ver valores em R$ (custo, perda, divergência financeira)
aplicar_ajuste_estoque	Escrever o novo estoque de verdade no Firebird a partir de um ajuste pendente. Default false até pra admin — é confiança por pessoa, não por cargo.

Não existe uma permissão separada para "aprovar divergência" — qualquer usuário autenticado que acessa a tela de revisão pode aprovar ou pedir recontagem. A permissão sensível de verdade é a que escreve estoque real (aplicar_ajuste_estoque).

Tela de login do CotaFácil

2Tipos de auditoria

Uma auditoria (chamada de gancho no banco, por herança histórica) sempre parte de um escopo — de onde vem a lista de produtos esperados. Existem 3:

Escopo	Como funciona	Esperado vem de
GRUPO	Escolhe um grupo do catálogo (inclui todos os subgrupos automaticamente) — pré-carrega TODOS os produtos ativos daquele(s) grupo(s)	Estoque do Firebird (`EST_DISP`) no momento da criação
FORNECEDOR	Escolhe um fornecedor — pré-carrega todos os produtos ativos dele	Estoque do Firebird (`EST_DISP`) no momento da criação
LOCALIZAÇÃO	Escolhe uma prateleira física cadastrada — pré-carrega os produtos já vinculados a ela (pode ser vazio, na 1ª vez)	Última contagem NESSA prateleira (nunca o estoque da loja inteira, que não faz sentido por prateleira)

Uma auditoria "solta" (sem escopo, só um título) também é possível — modelo mais antigo, ainda funciona, mas não pré-carrega nada: só registra o que for bipado na hora.

3Fluxo no celular (operador)

Página própria, separada do painel do gestor: /conferencia-mobile.html. Tema escuro, botões grandes, feito pra uso com uma mão, em pé, no chão da loja.

Etapa 1 — Criar/abrir a auditoria

Toque em Nova Auditoria, escolha o tipo (Grupo / Fornecedor / Localização) e dê um título. Se o escopo for Localização, aparece uma etapa extra chamada Prova de Presença: o operador precisa bipar (ou digitar) o código da etiqueta física colada na prateleira antes de continuar — isso garante que ele está fisicamente lá, não conferindo de memória.

Modal "Nova Auditoria" com o toggle Grupo / Fornecedor / Localização

Etapa 2 — Bipagem

Toque em Ler código (abre a câmera, leitura toque-a-toque — não é leitura contínua, decisão deliberada pra evitar ler a peça errada por engano) ou digite manualmente. Cada leitura:

Se o produto já está na lista, soma +1 (ou a quantidade digitada) na contagem.
Se é a 1ª vez que aparece nessa auditoria e não fazia parte do escopo pré-carregado, entra como "FORA DA LISTA" (grupo/fornecedor) ou "VÍNCULO NOVO" (localização — tom positivo, é o sistema aprendendo, não um erro).
Um card grande mostra o resultado: verde (bateu), vermelho (faltou), âmbar (sobrou).

Tela principal de bipagem — card de resultado + lista de itens

Etapa 3 — Fechar e resumo

Toque em Fechar conferência. Se houver item divergente ainda não revisado, o sistema NÃO fecha — abre a tela de revisão (ver seção 4). Sem pendência, fecha direto e mostra o relatório: itens, divergentes, unidades faltando/sobrando e valor da perda (só pra quem tem ver_custo).

Relatório final ao fechar a auditoria

4Revisão e fechamento

Toda divergência real (contado ≠ esperado) precisa passar por revisão antes de a auditoria poder fechar — o sistema nunca deixa fechar "no automático" escondendo uma diferença.

Ao tentar fechar com pendência, a tela de revisão abre sozinha, listando cada item divergente.
Pra cada item, duas ações possíveis: Aprovar (a diferença é real, deixa passar) ou Recontar (zera a contagem e libera bipar esse produto de novo).
Só depois de toda divergência estar aprovado o botão "Aprovar e fechar" libera.

Item pré-carregado que ninguém bipou ainda ("não conferido") também entra na revisão ao fechar — é o achado mais grave numa auditoria anti-furto (produto que devia estar lá e ninguém nem achou), mas NÃO conta como "divergente" durante a contagem em si, pra não gerar alarme falso enquanto a auditoria ainda está em andamento.

5Painel do gestor (desktop)

Menu Conferência, 3 abas:

Auditorias

Lista todas as auditorias (abertas e fechadas), com progresso e status. Clique numa linha pra expandir e ver os itens.

Aba Auditorias

Histórico & Padrões

Cruza todas as auditorias fechadas em 3 cortes: por produto (maior perda acumulada), por operador (quem bipou os itens que depois viraram ajuste — correlação, nunca acusação) e linha do tempo (uma linha por auditoria fechada).

Aba Histórico & Padrões

Localizações

Cadastro das prateleiras físicas (nome, código de barras da etiqueta, corredor, lado). Aqui o gestor cria a localização; a etiqueta física em si (impressão) ainda precisa ser gerada por fora do sistema — não há impressão integrada hoje.

Aba Localizações

6Aplicar ajuste no estoque

Ao fechar uma auditoria com divergência aprovada, o sistema gera um ajuste pendente (na aba Auditorias, painel "Ajustes de estoque pendentes"). Isso NÃO altera o estoque sozinho.

Quem tem a permissão aplicar_ajuste_estoque vê um botão "Aplicar no estoque" — ao confirmar, o sistema escreve o novo valor direto no Firebird (EST_DISP) e grava um log permanente: produto, usuário, valor antes/depois, data e hora. Quem não tem a permissão simplesmente não vê o botão (não é só desabilitado — some).

Essa é a ÚNICA exceção deliberada à regra de que o Firebird de produção é só-leitura no resto do CotaFácil — decisão consciente pra fechar o ciclo do anti-furto sem depender de outro sistema pra corrigir o estoque.

7Modelo de dados (resumo)

Detalhe técnico completo (todas as colunas, migrações) está em ia/GRUPO-SUBGRUPO-E-CONFERENCIA.md no repositório. Resumo:

Tabela	O que guarda
`conferencia_gancho`	1 linha por auditoria — título, status, escopo
`conferencia_item`	1 linha por produto dentro da auditoria — esperado, contado, se veio da lista ou foi achado avulso
`conferencia_bipagem`	Log de TODA leitura (nunca apagado) — base do corte "por operador"
`conferencia_ajuste`	1 linha por item divergente ao fechar — fila de ajustes pendentes
`conferencia_ajuste_log`	1 linha por aplicação real de ajuste no Firebird — rastro obrigatório
`conferencia_localizacao`	Cadastro das prateleiras físicas
`conferencia_vinculo`	Vínculo orgânico produto↔localização — nasce sozinho na 1ª bipagem, guarda a última contagem

8Regras de negócio

Bipar nunca escreve estoque sozinho. Só o botão "Aplicar no estoque" (com permissão) escreve de verdade — e é sempre logado.

Esperado é uma fotografia do momento da criação (ou da última contagem, no caso de localização) — não recalcula ao vivo durante a contagem.

Toda divergência passa por revisão antes de a auditoria poder fechar. Sem exceção, sem "fechar no automático".

Vínculo orgânico é automático (escopo localização) — o sistema aprende sozinho quais produtos ficam em cada prateleira, sem planograma manual.

Histórico por operador é correlação, nunca acusação. O nome aparece pra rastreabilidade e treino de equipe, não pra punir automaticamente.

Financeiro só com permissão ver_custo. Se o campo não vier na resposta da API, a tela esconde — nunca chuta ou estima um valor.

Não inventar métrica. O sistema não calcula "acurácia %" nem "score de risco" — só mostra dado real (perda, unidades, ocorrências). Interpretação é humana.

9Cálculos

Diferença por item

diferenca = contado - esperado
< 0  → faltou
> 0  → sobrou
= 0  → confere

Valor da perda (só conta falta, sobra não gera perda)

valor_perda = diferenca < 0 ? abs(diferenca) × preco_custo : 0

Perda total de uma auditoria fechada

valor_total = soma(valor_perda) de todos os itens divergentes

Não existe cálculo de "acuracidade %" nem "risco" no sistema — essas métricas foram avaliadas (inspiradas num protótipo externo) e descartadas por inventarem limiares sem lastro real. Só dado bruto e real é mostrado.

10Perguntas frequentes

O operador bipou um código que não existe no catálogo

Aparece "Código não encontrado no catálogo" e nada é adicionado. O código é consultado direto no Firebird (COD_BARRA1/2/3) — se o produto não existir lá, precisa ser cadastrado primeiro em Cadastro de Produtos.

Bipei na prateleira errada (escopo localização)

Toque em "Trocar" na tela de bipagem pra voltar à Prova de Presença e escolher a prateleira certa.

A quantidade contada está errada

Use o ícone de lápis no item pra corrigir manualmente, ou o de lixeira pra remover o item (com confirmação).

Fechei sem querer / preciso bipar mais antes de decidir

Na tela de revisão, existe um "Cancelar revisão" que volta a auditoria pra ABERTA sem fechar — dá pra bipar mais antes de decidir aprovar ou recontar.

Onde ficam os dados?

A contagem em si (auditorias, itens, bipagens, ajustes, vínculos, localizações) fica no SQLite local do servidor CotaFácil. O catálogo de produtos (nome, preço, estoque) e a escrita de ajuste aplicado vêm do Firebird de produção — nada de localStorage do navegador.

Esqueci minha senha

Peça pra um administrador redefinir em Configurações → Usuários — não é autoatendimento.

Manual gerado em 23/07/2026, refletindo o sistema em produção nessa data. Se algo aqui parecer desatualizado, confira a tela real antes de confiar cegamente.