Os nomes de menus e botões aparecem em negrito no texto. As etapas partem da barra lateral do sistema. Quando uma ação não estiver visível, confirme o perfil do usuário: algumas funções são exclusivas do Administrador e o perfil Consulta não pode alterar dados.

1. Abra a Cubexa pelo atalho da área de trabalho ou menu Iniciar.
2. Na tela “Vamos preparar seu estoque”, selecione Iniciar configuração.
3. Informe os dados da empresa e do primeiro administrador. Use um nome de acesso individual.
4. Crie uma senha exclusiva com pelo menos 8 caracteres e guarde-a em local seguro.
5. Conclua a configuração. O sistema abrirá o catálogo para o primeiro cadastro.

6. Informe usuário e senha na tela de acesso e selecione Entrar.
7. Use o menu lateral para Dashboard, Produtos, Movimentações, Vendas, Compras, Inventário, Lotes e reposição, Relatórios e Configurações.
8. Use Ctrl+K para localizar telas e ações. Use Esc para fechar a busca.
9. Use Ctrl+N para iniciar a ação principal da tela atual, quando seu perfil permitir.
10. Ao terminar, selecione Sair no menu lateral.

11. Acesse Configurações → Empresa.
12. Revise nome, razão social, CPF/CNPJ, endereço, telefone e e-mail.
13. Opcionalmente selecione logotipo PNG, JPG ou WebP de até 5 MB.
14. Defina moeda, casas decimais e formato de data.
15. Mantenha “Permitir estoque negativo” desativado, salvo decisão formal da empresa.
16. Selecione Salvar e confirme a mensagem de atualização.

5.1 Criar uma categoria

17. Acesse Produtos e selecione Categorias.
18. Selecione Nova categoria.
19. Informe nome, descrição e cor; escolha a categoria-pai se desejar hierarquia.
20. Salve e feche o gerenciador.

5.2 Cadastrar um produto

21. Acesse Produtos → Novo produto.
22. Preencha nome, descrição, categoria, unidade, preço de venda, estoque mínimo, estoque ideal e localização física.
23. Ative controle por lote e/ou validade somente quando o produto exigir rastreabilidade.
24. Adicione uma ou mais variações. Para cada uma, informe nome, SKU e código de barras quando disponíveis.
25. Se houver estoque inicial, informe quantidade e custo. O sistema registrará uma entrada INITIAL_STOCK, preservando o histórico.
26. Adicione imagem local se necessário, revise e salve.

5.3 Localizar, editar e arquivar

• Busque por nome, SKU ou código de barras.
• Filtre por categoria e situação do estoque; ordene por atualização, nome, saldo ou preço.
• Abra o produto ou use o ícone Editar.
• Arquive produtos fora de uso; o histórico permanece preservado.

6.1 Registrar entrada ou saída

27. Acesse Movimentações → Nova movimentação.
28. Escolha Entrada para adicionar saldo ou Saída para retirar.
29. Selecione o produto/variação, informe quantidade e motivo.
30. Em entradas, revise o custo unitário; informe data/hora se o lançamento não for imediato.
31. Quando houver controle por lote, selecione o lote ou informe código, fabricação e validade.
32. Registre uma nota com documento, responsável ou justificativa.
33. Selecione Registrar entrada ou Registrar saída e confirme o novo saldo no histórico.

6.2 Estornar uma movimentação

34. Abra a movimentação no histórico.
35. Confirme produto, quantidade, lote, custo e origem.
36. Selecione Registrar estorno.
37. Confirme. O sistema cria um lançamento inverso; o original continua visível.

7.1 Cadastrar fornecedor

38. Acesse Compras → aba Fornecedores → Novo fornecedor.
39. Preencha nome/razão social, documento, contatos, endereço, prazo e observações.
40. Associe produtos, códigos do fornecedor, preço, prazo e quantidade mínima quando aplicável.
41. Salve.

7.2 Criar pedido de compra

42. Acesse Compras → Nova compra.
43. Selecione fornecedor, data, previsão e situação inicial: Rascunho ou Pedido.
44. Adicione itens; selecione a variação e informe quantidade, custo unitário e desconto.
45. Informe desconto geral, frete e observações.
46. Revise o total e selecione Salvar compra.

7.3 Receber compra total ou parcialmente

47. Abra a compra com status apto a receber.
48. Selecione Receber itens.
49. Informe a quantidade efetivamente recebida de cada item; não ultrapasse o pedido.
50. Para itens controlados, informe lote, fabricação e validade.
51. Confirme o recebimento. O estoque e o custo médio serão atualizados somente agora.
52. Repita em outro momento se o recebimento foi parcial.

8.1 Cadastrar cliente

53. Acesse Vendas → Clientes → Novo cliente.
54. Informe nome e, se disponíveis, CPF/CNPJ, telefone, WhatsApp, e-mail e observações.
55. Mantenha Cliente ativo marcado e salve.

8.2 Criar e finalizar venda

56. Acesse Vendas → Nova venda.
57. Selecione o cliente ou mantenha Consumidor não identificado.
58. Informe data/hora e forma de pagamento.
59. Adicione produtos, quantidades, preços e descontos por item.
60. Informe desconto geral, acréscimo e observações.
61. Selecione Salvar rascunho para continuar depois, ou Finalizar venda para validar e baixar o estoque.
62. Confirme o status Finalizada e o total.

8.3 Cancelar venda

63. Abra a venda.
64. Selecione Cancelar venda e confirme.
65. Se ela já estava finalizada, confira as movimentações de estorno que devolveram o estoque.

66. Evite compras, vendas e movimentações durante a contagem.
67. Acesse Inventário → Novo inventário.
68. Escolha o escopo: geral, categoria ou localização. Adicione observações e inicie.
69. Conte cada item fisicamente e registre a quantidade. Use busca por produto, SKU ou código de barras.
70. Em diferença positiva de produto rastreado, informe lote e validade exigidos.
71. Revise progresso, pendências e divergências.
72. Selecione Concluir inventário. O sistema cria entradas/saídas de ajuste.
73. Se o saldo tiver mudado desde o início, o sistema bloqueará a conclusão; revise o movimento e reinicie a contagem.

• Acesse Lotes e reposição para consultar lote, fornecedor, compra, fabricação, validade, saldo e histórico.
• Priorize lotes vencidos, a vencer em 7 dias e a vencer em 30 dias. Não realize venda de item vencido sem política formal e avaliação aplicável.
• Use a visão de integridade para comparar saldo dos lotes com o saldo total.
• Revise sugestões quando o estoque cair abaixo do mínimo; a sugestão busca completar o nível ideal.
• Agrupe sugestões por fornecedor e crie uma compra em rascunho; revise preço, prazo e quantidade antes de enviar.
• Consulte produtos sem giro em 30, 60, 90 ou 180 dias para reduzir capital imobilizado.

74. Acesse Relatórios e selecione o relatório desejado.
75. Aplique filtros de período, categoria, produto, fornecedor e usuário conforme disponíveis.
76. Confira indicadores e linhas na tela.
77. Selecione PDF para documento paginado, XLSX para análise em planilha ou CSV para integração.
78. Abra o arquivo exportado e confirme título, período, totais e quantidade de registros.

79. Acesse Relatórios e abra a importação de produtos. A ação requer Administrador.
80. Selecione um arquivo XLSX ou CSV.
81. Mapeie cada coluna do arquivo para o campo correspondente.
82. Revise a prévia e corrija cabeçalhos ou valores inválidos.
83. Escolha criar/atualizar conforme o identificador disponível (SKU ou código de barras).
84. Execute a importação e leia o resumo de criados, atualizados, ignorados e erros.
85. Revise uma amostra no catálogo antes de importar o próximo lote.

13.1 Criar ou alterar usuário

86. Acesse Configurações → Usuários.
87. Selecione Novo usuário ou Editar.
88. Informe nome, usuário, perfil, situação e senha. Nova senha deve ter ao menos 8 caracteres.
89. Salve. O sistema não permite desativar a própria conta nem o último administrador ativo.

13.2 Consultar auditoria

90. Acesse Configurações → Auditoria.
91. Pesquise por ação, módulo, registro ou usuário; use os filtros disponíveis.
92. Compare valores anteriores e novos quando exibidos.
93. Registre externamente o identificador, usuário e horário ao abrir um chamado.

94. Acesse Configurações → Backups.
95. Revise a pasta de destino. Se necessário, selecione Escolher pasta e aponte para uma pasta dedicada.
96. Selecione Criar backup agora.
97. Aguarde a mensagem “Backup criado” e confirme no histórico o status Concluído, horário e tamanho.
98. Abra a pasta no Windows e verifique se existe um arquivo Cubexa-backup-...-manual.sqlite3 com tamanho maior que zero.

99. Conecte o HD externo ou pendrive e confirme no Explorador de Arquivos que ele está acessível e possui espaço livre.
100. Crie uma pasta exclusiva, por exemplo E:\Backups-Cubexa. Evite usar a raiz da unidade.
101. Na Cubexa, entre como Administrador e acesse Configurações → Backups.
102. Selecione Escolher pasta e indique a pasta do drive externo.
103. Ative a rotina e escolha Diário para operação frequente, Semanal para baixa movimentação, ou Ao sair se o drive permanece conectado no encerramento.
104. Defina retenção. Recomendação inicial: 14 cópias diárias ou 8 semanais, ajustando ao volume e ao espaço.
105. Selecione Salvar configuração.
106. Crie um backup manual de teste e confirme o histórico e o arquivo no drive.
107. Ejete o drive com segurança somente depois de o backup terminar.

• Mantenha pelo menos 3 cópias dos dados: o banco ativo e duas cópias de backup.
• Use 2 mídias ou locais distintos: por exemplo, drive externo e armazenamento corporativo sincronizado.
• Mantenha 1 cópia fora do local físico. Se usar nuvem/Drive, sincronize a pasta de backups concluídos, nunca a pasta do banco ativo.
• Não trabalhe diretamente sobre um arquivo .sqlite3 em pasta sincronizada; sincronizadores podem copiar enquanto o arquivo está em uso.
• Criptografe a unidade externa quando ela sair da empresa e controle quem possui a chave.
• Registre o responsável e confira o histórico ao menos semanalmente.

108. Pare vendas, compras, recebimentos e movimentações. Avise todos os usuários da janela de restauração.
109. Confirme que o arquivo é .sqlite3, provém da Cubexa e corresponde ao ponto desejado. Preserve uma cópia dele.
110. Entre como Administrador e acesse Configurações → Backups.
111. Selecione Restaurar backup, leia o aviso e confirme Selecionar e restaurar.
112. Escolha o arquivo. A Cubexa valida integridade e estrutura e cria automaticamente um PRE_RESTORE do estado atual.
113. Aguarde a conclusão. A sessão será encerrada. Entre novamente.
114. Confira empresa, usuários, produtos, saldo de amostra, últimas vendas/compras e auditoria.
115. Se algo estiver incorreto, pare as operações e contate o suporte informando o caminho do PRE_RESTORE.

• Frequência recomendada: trimestral e sempre antes de atualização relevante.
• Faça o teste em ambiente controlado ou computador de homologação; não use produção apenas para “ver se funciona”.
• Escolha uma cópia recente e registre data, arquivo, tamanho e responsável.
• Após restaurar, valide login, contagens de cadastros, saldos de amostra, movimentações e um relatório.
• Registre o resultado e corrija imediatamente falhas de rotina, destino ou retenção.

116. Na tela de acesso, selecione a opção de recuperação de senha.
117. Confirme os dados solicitados da empresa.
118. Informe a nova senha seguindo o mínimo de 8 caracteres.
119. Conclua. O sistema cria um backup preventivo antes de alterar a credencial.
120. Entre com a nova senha. Se ocorrer bloqueio por tentativas repetidas, aguarde o período informado antes de tentar novamente.

• Rascunhos importantes salvos e documentos recebidos/finalizados corretamente.
• Nenhum inventário iniciado por engano ou deixado sem responsável.
• Alertas críticos revisados.
• Backup automático concluído ou backup manual criado.
• Drive externo mantido conectado até o fim da cópia e depois ejetado com segurança, quando aplicável.
• Sessão encerrada.

A Cubexa é um sistema de controle de estoque para microempresas, distribuído como aplicativo Electron e projetado para funcionar integralmente no computador do cliente. A interface React não acessa o sistema de arquivos nem o banco diretamente. Todas as operações atravessam uma bridge tipada do preload, controladores IPC e serviços de aplicação que aplicam autorização e transações SQLite.

• Catálogo com categorias, produtos, variações, SKU, código de barras, preços, níveis de estoque, imagens, lote e validade.
• Movimentação central e imutável, compras e recebimentos, vendas e cancelamentos, inventários, lotes, reposição e relatórios.
• Administração local com usuários e perfis, auditoria, configurações, backup/restauração e recuperação de senha.
• Sem dependência de internet para a operação normal; os dados permanecem no perfil local do Windows.

Fluxo lógico: Renderer → preload tipado → handlers IPC → serviços de aplicação → regras de domínio → repositórios/SQLite. Erros técnicos são convertidos em códigos estáveis e mensagens compreensíveis antes de retornar à interface.

• Arquivo: data/nexostock.sqlite3 dentro do userData do Electron. Em instalações novas no Windows, o diretório base é %APPDATA%\Cubexa.
• Ao detectar a identidade anterior, dados e imagens de %APPDATA%\NexoStock são copiados para o novo local sem apagar a origem.
• PRAGMAs: foreign_keys habilitado, journal_mode WAL, synchronous NORMAL e busy_timeout de 5 segundos.
• Migrações são transacionais e registradas em schema_migrations; a inicialização verifica a integridade do SQLite.
• Valores monetários são inteiros em centavos; quantidades são inteiros em milionésimos da unidade; datas são ISO 8601 UTC.
• Movimentos lançados possuem proteção contra UPDATE e DELETE. Correções criam um movimento inverso relacionado.

• Saídas acima do saldo são bloqueadas, exceto quando a política administrativa de estoque negativo está habilitada.
• O custo médio ponderado é recalculado em entradas com custo e congelado nos itens de vendas concluídas.
• Produtos rastreados por lote exigem lote nas operações aplicáveis; baixas automáticas utilizam FEFO, priorizando a menor validade.
• Pedidos podem ser recebidos parcialmente, mas não acima do pedido. Documentos recebidos não são reeditados como se fossem rascunhos.
• Vendas em rascunho não afetam o saldo. O cancelamento de venda concluída devolve estoque por estornos vinculados.
• O inventário captura uma fotografia do saldo; sua conclusão falha se houver itens sem contagem ou se o saldo mudar durante a contagem.

• Senhas usam hash scrypt; comparações são resistentes a timing.
• Sessão autenticada é mantida somente em memória.
• Tentativas repetidas de login causam bloqueio temporário.
• nodeIntegration desativado; contextIsolation e sandbox ativados.
• Navegação externa é bloqueada; somente HTTPS pode ser aberto pelo sistema.
• É proibido desativar o próprio usuário autenticado ou remover o último administrador ativo.

1. Instale Windows 10/11, Node.js 22+, npm 10+ e ferramentas C++ quando o módulo nativo não tiver binário compatível.
2. Execute npm install. O postinstall reconstrói better-sqlite3 para a versão do Electron.
3. Execute npm run typecheck e npm run test.
4. Execute npm run build:renderer para validar a interface, ou npm run build para gerar o diretório empacotado.
5. Execute npm run dist:win para gerar o instalador NSIS em release/.
6. Distribua Cubexa-Setup-1.0.0.exe. Não distribua somente release/win-unpacked/Cubexa.exe, pois ele depende dos demais recursos do diretório.

• Executar as suites de database, errors, catalog, movements, purchasing, sales, inventory, stock-control, reporting, administration e branding.
• Validar migração de uma base anterior em cópia descartável.
• Testar backup manual, backup agendado e restauração com arquivo válido e inválido.
• Confirmar permissões nas duas camadas: visibilidade da UI e recusa no IPC/serviço.
• Realizar smoke test de criação de produto → compra/recebimento → venda → inventário → relatório.
• Gerar e conferir PDF, XLSX e CSV com os mesmos filtros exibidos na tela.

• Preservar compatibilidade com nomes internos legados até existir migração formal e testada.
• Toda alteração de schema deve ser uma nova migração idempotente e transacional; nunca editar uma migração já publicada.
• Novos fluxos de estoque devem chamar a engine central, não atualizar saldos diretamente.
• Novos canais IPC devem ser mínimos, tipados, validados e autorizados no processo principal.
• Antes de atualizar um cliente, criar backup, registrar a versão e manter o instalador anterior durante a janela de validação.

• Versão de package.json e nome do artefato conferidos.
• Typecheck e testes aprovados.
• Migração e primeira inicialização validadas.
• Perfis e recuperação de senha testados.
• Backup/restauração testados em diretório local e unidade externa.
• Instalador assinado/verificado conforme processo da organização.
• Manual de uso e documentação técnica entregues junto ao instalador.