Controle de Validade
Dashboard + mapa de calor da loja + coletor com leitura de código de barras pela câmera. Substitui a planilha Controle_Validade_v12.xlsx, que continua sendo entrada (importação) e saída (exportação).
Rodar no seu computador
Node 20 ou mais novo.
npm install
npm run import -- "../Controle_Validade_v12.xlsx" # carga inicial (já feita neste PC)
npm start # http://localhost:3000 (o coletor é a aba "Coletor")
npm test # 23 testes contra Postgres
O banco é PostgreSQL nos dois ambientes, com o mesmo SQL:
| Onde | Banco |
|---|
| Seu computador | PGlite (um Postgres que roda dentro do Node, guardado em data/pg; não precisa instalar nada) |
| Vercel | Neon, pela variável DATABASE_URL |
Localmente o login fica desligado (só o localhost acessa). Com npm run lan ou REQUIRE_LOGIN=1 ele passa a ser obrigatório.
Publicar (Git + Vercel + Neon)
- Git — crie um repositório privado vazio no GitHub e, na pasta
validade-app:
git remote add origin https://github.com/SEU-USUARIO/validade-app.git
git push -u origin main
O .gitignore já deixa de fora node_modules, data/ e .env.
- Vercel — Add New → Project, escolha o repositório. Preset Other, sem comando de build.
- Neon — no projeto da Vercel, Storage → Create Database → Neon (ou Marketplace → Neon) e conecte ao projeto. A Vercel cria sozinha a variável
DATABASE_URL; não precisa copiar a senha.
- Segredo da sessão — em Settings → Environment Variables crie
SESSION_SECRET com um texto aleatório de 32+ caracteres:
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
- Redeploy (para as variáveis valerem) e abra o endereço no celular. As tabelas são criadas na primeira chamada.
- Dados e primeiro acesso — no painel da Vercel (Settings → Environment Variables), copie a linha
DATABASE_URL=... e salve num arquivo chamado .env.local dentro da pasta validade-app. O Git ignora esse arquivo e os scripts o leem sozinhos, então a string nunca vai para o chat nem para o repositório. Depois:
npm run import -- "../Controle_Validade_v12.xlsx" # sobe produtos e estoque
npm run usuario -- MICHEL 123456 admin # troque pelo PIN que quiser (6 a 8 números)
npm run usuario -- JOAO 654321 operador # um por pessoa da loja
- Abra o endereço da Vercel, entre com nome + PIN e use Adicionar à tela inicial. O endereço é HTTPS, que é o que libera a câmera.
Na Vercel o login é sempre obrigatório. Depois, novos usuários e PINs se gerenciam em Configurações → Equipe.
Segurança embutida
PIN com hash (scrypt) e bloqueio de 10 min após 5 erros · sessão em cookie HttpOnly/Secure/SameSite=Lax assinado · o nome do operador nos lançamentos vem da sessão, não do que o aparelho manda · cabeçalho obrigatório contra CSRF · Content-Security-Policy restritiva · câmera liberada só para o próprio site · operador não altera regras, planta, equipe nem importa dados.
Endereço
GÔNDOLA-LADO-PRATELEIRA, por exemplo 1-B-3.
| Parte | Valores |
|---|
| Gôndola | 1 a 40 (hoje 1 a 19; sacaria e aquarismo entram depois) |
| Lado | A esquerda · B direita · F ponta da frente · C ponta das costas |
| Prateleira | 1 a 5. Ponta pode vir sem prateleira: 1-F, 1-C |
Endereços antigos fora disso (19, 4-E-1) continuam no estoque, aparecem em Qualidade dos dados e no mapa como “sem endereço válido”, e se corrigem na próxima ronda. Endereço novo fora do padrão é recusado.
Regra de prevenção (Configurações → Regras de desconto)
| Prazo | Desconto |
|---|
| até 30 dias | 50% em tudo |
| até 90 dias | ração (seca e úmida) 20% · demais itens 30% |
| vencido | retirar da loja |
“Ração” vem da categoria do produto; sem categoria, do nome. Não existe mais a faixa de 10%. Perda potencial = valor × desconto (vencido = 100%).
Telas
- Visão geral — valor em risco, validade do estoque (donut), muro de validade por mês, “fazer hoje”, gôndolas que pedem atenção, marcas, qualidade dos dados.
- Mapa da loja — mapa único com zoom e arrasto (roda do mouse, pinça no celular, botões + − e "ver tudo"). Longe, cada gôndola é uma faixa de calor com número, nome, risco e responsáveis; ao clicar, a câmera aproxima e mostra a vista de cima (módulo 1 junto da Frente, nomes dos lados e dos módulos) com um painel por cima (risco, setores, lotes do módulo). Métricas: Risco, Validade, Ocupação, Ronda. Editar planta (posição, proporção real, setas, imagem de fundo, medidas padrão) e Editar gôndolas (lados, módulos, medidas, nomes, novas gôndolas e áreas com pallets) são só para administradores.
- Estoque, Etiquetas (imprimir), Movimentações (com desfazer), Configurações (regras, equipe, importar/exportar).
- Ronda do dia (Coletor → Ronda) — o app escolhe os 5, 10 ou 20 endereços com maior nota (dinheiro que pode se perder ali × dias sem conferir) e os ordena para caminhar: gôndola, depois F → A → C → B. Em cada endereço: "conferem", Corrigir, Não achei, Mover, Etiquetei (registra a etiqueta do desconto) e Retirei da loja (baixa dos vencidos). Lote que vence em até 30 dias só é confirmado com o código lido (há uma saída "sem código", que fica registrada). Ao fim, o resumo mostra a divergência (itens que não bateram) e o painel dos últimos 7 dias sai dos próprios lançamentos.
- Coletor (aba do app, mesmo login;
/coletor só redireciona para ela; operadores já abrem nela) — Entrada (receber soma / contar define), Ronda por endereço, Baixa, Buscar. Atalhos de lado e prateleira por toque, câmera para o EAN e para a etiqueta do endereço, fila offline com reenvio sem duplicar, desfazer do último lançamento, aviso de FEFO.
Câmera
Usa o leitor nativo do Chrome (BarcodeDetector) e, onde ele não existe, o ZXing (public/vendor/zxing.min.js). Para EAN só aceita leitura com dígito verificador correto. Exige HTTPS (ou localhost).
Modelo de dados
produtos · lotes (EAN + lote + validade + endereço) · eventos (toda entrada, contagem, ajuste, baixa e transferência, com quem/quando/saldo) · usuarios · config.
Limites conhecidos
- Não lê vendas do PDV, então o saldo só diminui por baixa ou ronda — por isso a Ronda existe.
- Importar pelo painel aceita arquivos de até ~4 MB (limite da Vercel); a carga grande vai por
npm run import.
- A câmera foi testada com leitura de imagens de código de barras, não com um aparelho real de loja.
- O driver do Neon (
pg) foi testado por rede contra um servidor Postgres local; a conexão com o Neon de verdade só é exercitada no primeiro deploy.
npm audit aponta 2 avisos moderados de uuid dentro do exceljs; o trecho afetado não é usado aqui.
Novas filiais e demonstração
Cada filial é um projeto próprio na Vercel com o seu Neon (mesmo código, dados separados).
- Primeiro acesso sem terminal: crie a variável
ADMIN_INICIAL com NOME:PIN (ex.: JOAO:123456, tipo Sensitive) e faça o redeploy. Ela cria o administrador no primeiro acesso, só se o banco não tiver nenhum usuário; depois pode ser apagada.
- Demonstração:
DEMO=1 PGLITE_DIR=memory:// npm start mostra o sistema com produtos e lotes de exemplo, sem tocar no estoque real. Na Vercel, DEMO_INICIAL=1 carrega os dados de exemplo uma única vez (só em banco sem estoque); apague a variável depois e limpe os dados antes do uso real.
Carregar a lista da nota ou da contagem
Na Conferência de Recebimento ou de Contagem, o botão Carregar a lista aceita planilha (.xlsx), CSV, TXT ou o XML da NF-e. O app acha sozinho a linha do cabeçalho (EAN, código de barras, quantidade, lote, validade…); sem cabeçalho, entende EAN;quantidade em cada linha. Mostra o que entendeu e o que ficou de fora, e só então carrega as quantidades como "esperado": laranja até chegar, verde quando bate, vermelho quando passa. Bipar a chave da nota (44 números do DANFE) anota o número da NF.
Modo avião (sem internet)
Conferências, entrada e contagem funcionam sem rede. Antes de ficar offline, no Coletor ou em Conferências toque em Preparar para o modo avião: o aparelho guarda o catálogo de produtos (para mostrar o nome de cada EAN), a lista de endereços e os endereços da ronda de hoje. Sem internet, o que for lançado fica numa fila no aparelho e sobe sozinho quando a rede voltar (cada lançamento tem um identificador, então reenviar nunca soma duas vezes). Uma conferência criada e finalizada offline guarda o horário real de abertura e de fechamento. O app só precisa estar instalado e ter sido aberto uma vez com internet.
Precisa de internet: gerar a ronda do dia, carregar a lista da nota, imprimir ou exportar a conferência (isso acontece depois que ela sobe) e a auditoria.
