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)

1. 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.
2. Vercel — Add New → Project, escolha o repositório. Preset Other, sem comando de build.
3. 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.
4. 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'))"
   

5. Redeploy (para as variáveis valerem) e abra o endereço no celular. As tabelas são criadas na primeira chamada.
6. 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
   

7. 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.