EstoqueLentes

App desktop pessoal (Electron) para gerenciar o estoque físico de blocos de lentes de uma ótica. A funcionalidade central é uma matriz de dois eixos — esférico × cilindro — mostrando a quantidade de cada lente em estoque, com adição/remoção manual e auto-save.

Tech stack

• TypeScript
• Electron + electron-vite (processos main / preload / renderer)
• React 19 + Tailwind CSS v4
• Componentes estilo shadcn/ui sobre primitivos Radix
• better-sqlite3 + Drizzle ORM (SQLite local, migrations versionadas)
• Vitest para testes unitários

Pré-requisitos

Só para quem vai rodar o código-fonte (desenvolvimento). Quem só quer usar o app já empacotado (instalador .exe/.dmg/.AppImage) não precisa de nada disso.

• Node.js 20+ e npm 10+ (desenvolvido com Node v22.18.0 / npm 10.9.3)
• Visual Studio Build Tools (workload "Desktop development with C++") no Windows, ou Xcode Command Line Tools no macOS / build-essential no Linux, e Python 3 — o better-sqlite3 v13 já vem com binários pré-compilados e não precisa ser recompilado em uso normal, mas o npm install pode disparar uma recompilação nativa dele mesmo assim por uma peculiaridade conhecida do npm com pacotes que têm um binding.gyp no pacote (npm/cli#5234). Ter a toolchain instalada evita que isso quebre a instalação.

Instalação

npm install

Configuração

Não há .env nem chaves de API — o app é 100% local. O único "estado de configuração" é o próprio banco de dados: um arquivo SQLite criado automaticamente em app.getPath('userData') na primeira execução (no Windows, algo como %APPDATA%\estoquelentes\estoquelentes.db), com as migrations em drizzle/ aplicadas automaticamente no startup — nenhum passo manual necessário.

Scripts

Script	Descrição
npm run dev	Roda o app em modo desenvolvimento, com HMR no renderer
npm run build	Typecheck + build de produção
npm start	Executa um build de produção (electron-vite preview)
npm run build:win / build:mac / build:linux	Build + empacotamento via electron-builder para a plataforma alvo
npm run typecheck	tsc --noEmit para as configs de main/preload e renderer
npm run lint	ESLint
npm run format	Prettier (--write)
npm test	Roda a suíte de testes (Vitest)
npm run db:generate	Gera uma nova migration a partir de src/main/db/schema.ts — rodar sempre que o schema mudar, e commitar o SQL gerado em drizzle/
npm run db:studio	Abre o Drizzle Studio para inspecionar o banco

Estrutura do projeto

Split padrão de três processos do Electron, mais uma pasta compartilhada:

src/
  main/       # único lugar onde better-sqlite3/Drizzle roda (schema, queries, migrations, IPC)
  preload/    # ponte contextBridge — expõe window.api ao renderer
  renderer/   # UI React (matriz, diálogos, componentes)
  shared/     # contrato de IPC (canais + tipos) usado pelos três processos

Detalhes de arquitetura, modelo de domínio (esférico/cilindro, formato do código de barras) e decisões de design estão documentados em CLAUDE.md.

Status atual

Implementado: navegação lateral com quatro seções completas.

• Inventário — matriz esférico×cilindro com visualização/edição, grade completa sempre visível (mesmo sem estoque), toggle de categoria positivo/negativo, status colorido por célula contra uma meta de estoque ajustável, leitura de código de barras (adicionar ou remover) com atalho de teclado F2, cadastro manual de nova lente, crescimento dinâmico de linhas/colunas, auto-save imediato.
• Relatório — métricas de movimentações de estoque (vendas e entradas) com seletor de data no padrão dd/mm/aaaa (dia específico ou intervalo), ranking com barras visuais das lentes mais vendidas no período e exportação de lista de compras (texto ou JSON) para itens abaixo da meta de estoque, com ajuste direto da meta na própria seção.
• Registro de auditoria — toda alteração de estoque fica registrada com a origem (manual, barcode, import), agrupada por dia, com busca flexível por dia/mês (por digitação de data, nome do mês por extenso ou seletor nativo de calendário) e rollback por dia (reversível só com confirmação).
• Configurações — alternância de tema claro/escuro, importação de estoque (JSON ou SQL nos modos Mesclar ou Substituir), exportação de estoque completo (JSON ou SQL), criação e restauração de cópias de segurança (backup online) do banco de dados SQLite e atalho direto para abrir a pasta local de dados no explorador de arquivos do sistema operacional.
• Testes & Confiabilidade — 100% dos testes unitários e de componentes passando (108 testes em 14 suítes), além de testes de fumaça (smoke tests) que executam o binário real do Electron e SQLite nativo.

Ainda fora do escopo: desfazer um rollback (por especificação original, o rollback desfaz e remove os registros do dia). Veja EstoqueLentes.md para o spec original completo.

Distribuição e Instalação

O aplicativo é empacotado profissionalmente para Linux e Windows, seguindo padrão ouro de distribuição com esteira automatizada no GitHub Actions (.github/workflows/build_releases.yml):

Windows

• Instalador NSIS (EstoqueLentes-Windows-Setup-x64.exe): assistente de instalação com escolha de diretório, atalhos na Área de Trabalho e Menu Iniciar, sem privilégios de administrador obrigatórios (perMachine: false) e proteção de dados que nunca apaga o banco SQLite ao atualizar ou desinstalar (deleteAppDataOnUninstall: false).
• Portátil (EstoqueLentes-Windows-Portable-x64.exe): executável independente pronto para rodar direto sem instalação.
• Arquivo Portátil ZIP (EstoqueLentes-Windows-Portable-x64.zip): pasta compactada para extração imediata sem overhead temporário.

Linux

• AppImage (EstoqueLentes-Linux-x86_64.AppImage): executável universal portátil que roda em qualquer distribuição Linux sem necessidade de root.
• Pacote DEB (EstoqueLentes-Linux-amd64.deb): integrado para Ubuntu, Debian, Linux Mint e Pop!_OS, com atalho no menu de aplicativos (Office) e ícones do sistema.
• Tarball Portátil (EstoqueLentes-Linux-x86_64.tar.xz): arquivo ultra-compactado com LZMA para uso em distribuições sem dependência de FUSE.

Integridade e Checksums

Toda release pública acompanha o arquivo SHA256SUMS.txt na raiz, permitindo validação direta com:

sha256sum -c SHA256SUMS.txt

Compilação Local

npm run build:linux   # Gera .AppImage, .deb e .tar.xz na pasta dist/
npm run build:win     # Gera instalador NSIS e executável portátil na pasta dist/

Licença

MIT