CubexaCubexaDocumentação
Voltar ao siteDownloadsBaixar Cubexa
Versão 1.2.0atual

Manual do usuário e referência técnica da versão atual.

Guiav1.2.0

Visão geral da documentação

A documentação do Cubexa 1.2.0 reúne o guia operacional e a referência técnica da versão atual.

MANUALOperação diária

Instalação, estoque, compras, vendas, PDV, caixa, crediário, manufatura, transformações, backup e administração.

TÉCNICAArquitetura e manutenção

Arquitetura, banco, licenciamento, impressão, PDV, caixa, manufatura, crediário, transformações, testes e release.

Arquivos originais

Os documentos fonte da versão 1.2.0 também podem ser baixados para consulta offline.

Versões

A documentação atual corresponde à versão 1.2.0. A versão 1.1.1 permanece disponível no seletor por compatibilidade com clientes que ainda utilizam aquela linha.

Manualv1.2.0

Como usar este manual

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.

SímboloSignificado
ImportanteRegra que evita perda de dados ou inconsistência.
Boa práticaRecomendação operacional para reduzir risco.
Resultado esperadoComo confirmar que o procedimento funcionou.
Manualv1.2.0

Destaques da versão 1 2 0

Os procedimentos da versão 1.0.0 continuam válidos. A versão 1.2.0 acrescenta novas formas de instalar, vender, imprimir, controlar caixa, produzir e receber.

RecursoO que o usuário pode fazer
InstalaçãoEscolher os modos Normal ou Portátil e aceitar os Termos de Licença e Uso.
LicençaConsultar plano, validade, limites e dispositivo em Configurações.
ComprasVisualizar, imprimir e salvar pedidos de compra em PDF.
VendasUsar o PDV, dividir pagamentos, calcular troco e emitir comprovantes.
CaixaAbrir e encerrar caixa, registrar suprimentos e sangrias e gerar o fechamento diário.
ProduçãoCadastrar receitas e concluir ordens com custos, perdas e lotes.
CrediárioCriar parcelas, acompanhar contas a receber e registrar recebimentos.
TransformaçõesConverter produtos e unidades com fator, perdas, custos e genealogia.
AtalhosUsar F2 para a ação contextual e Esc para fechar janelas e prévias.
Manualv1.2.0

1 Primeira configuração

  1. Abra a Cubexa pelo atalho da área de trabalho ou menu Iniciar.
  2. Na tela Configure seu espaço, informe o nome da empresa e o nome do administrador.
  3. O sistema gera o usuário a partir do nome do administrador informado.
  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.
Boa prática: Crie um segundo Administrador para contingência e use contas Operador no trabalho diário. Não compartilhe a conta administrativa.
Manualv1.2.0

2 Entrar, sair e navegar

  1. Informe usuário e senha na tela de acesso e selecione Entrar.
  2. Use o menu lateral para Dashboard, Produtos, Movimentações, Vendas, Compras, Inventário, Lotes e reposição, Relatórios e Configurações.
  3. Use Ctrl+K para localizar telas e ações. As opções visíveis recebem atalhos Ctrl+1, Ctrl+2 e seguintes. Use Esc para fechar buscas, modais, painéis e prévias.
  4. Use F2 para executar a ação principal da tela atual, quando seu perfil e sua licença permitirem.
  5. Ao terminar, selecione Sair no menu lateral.
Segurança: Sempre encerre a sessão em computadores compartilhados. Fechar somente a janela pode executar backup “Ao sair”, mas não substitui o hábito de sair da conta.
Manualv1.2.0

3 Perfis de acesso

PerfilUso recomendadoRestrições
AdministradorResponsável pelo sistema e dados mestres.Nenhuma restrição funcional; ações críticas exigem confirmação.
OperadorEquipe de estoque, compras e vendas.Não administra empresa, usuários, backup nem estrutura do catálogo.
ConsultaGestão, auditoria ou conferência.Somente leitura; não registra operações.
Manualv1.2.0

4 Configurar empresa

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

5 Categorias e produtos

5 1 Criar uma categoria

  1. Acesse Produtos e selecione Categorias.
  2. Selecione Nova categoria.
  3. Informe nome, descrição e cor; escolha a categoria-pai se desejar hierarquia.
  4. Salve e feche o gerenciador.

5 2 Cadastrar um produto

  1. Acesse Produtos → Novo produto.
  2. Preencha nome, descrição, categoria, unidade, preço de venda, estoque mínimo, estoque ideal e localização física.
  3. Ative controle por lote e/ou validade somente quando o produto exigir rastreabilidade.
  4. Adicione uma ou mais variações. Para cada uma, informe nome, SKU e código de barras quando disponíveis.
  5. Se houver estoque inicial, informe quantidade e custo. O sistema registrará uma entrada INITIAL_STOCK, preservando o histórico.
  6. Adicione imagem local se necessário, revise e salve.
Importante: SKU e código de barras devem ser únicos. Depois de registrar operações, não “corrija” saldo editando o cadastro: use Movimentações ou Inventário.

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

6 Movimentações de estoque

6 1 Registrar entrada ou saída

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

6 2 Estornar uma movimentação

  1. Abra a movimentação no histórico.
  2. Confirme produto, quantidade, lote, custo e origem.
  3. Selecione Registrar estorno.
  4. Confirme. O sistema cria um lançamento inverso; o original continua visível.
Importante: Movimentações não são editadas nem apagadas. Use estorno para manter rastreabilidade.
Manualv1.2.0

7 Fornecedores e compras

7 1 Cadastrar fornecedor

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

7 2 Criar pedido de compra

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

7 3 Receber compra total ou parcialmente

  1. Abra a compra com status apto a receber.
  2. Selecione Receber itens.
  3. Informe a quantidade efetivamente recebida de cada item; não ultrapasse o pedido.
  4. Para itens controlados, informe lote, fabricação e validade.
  5. Confirme o recebimento. O estoque e o custo médio serão atualizados somente agora.
  6. Repita em outro momento se o recebimento foi parcial.
Manualv1.2.0

8 Clientes e vendas

8 1 Cadastrar cliente

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

8 2 Criar e finalizar venda

  1. Acesse Vendas → Nova venda.
  2. Selecione o cliente ou mantenha Consumidor não identificado.
  3. Informe data/hora e forma de pagamento.
  4. Adicione produtos, quantidades, preços e descontos por item.
  5. Informe desconto geral, acréscimo e observações.
  6. Selecione Salvar rascunho para continuar depois, ou Finalizar venda para validar e baixar o estoque.
  7. Confirme o status Finalizada e o total.

8 3 Cancelar venda

  1. Abra a venda.
  2. Selecione Cancelar venda e confirme.
  3. Se ela já estava finalizada, confira as movimentações de estorno que devolveram o estoque.
Lotes: Em produtos rastreados, a finalização consome automaticamente os lotes pelo critério FEFO: primeiro os que vencem antes.
Manualv1.2.0

9 Inventário físico

  1. Evite compras, vendas e movimentações durante a contagem.
  2. Acesse Inventário → Novo inventário.
  3. Escolha o escopo: geral, categoria ou localização. Adicione observações e inicie.
  4. Conte cada item fisicamente e registre a quantidade. Use busca por produto, SKU ou código de barras.
  5. Em diferença positiva de produto rastreado, informe lote e validade exigidos.
  6. Revise progresso, pendências e divergências.
  7. Selecione Concluir inventário. O sistema cria entradas/saídas de ajuste.
  8. Se o saldo tiver mudado desde o início, o sistema bloqueará a conclusão; revise o movimento e reinicie a contagem.
Boa prática: Faça inventários por localização ou categoria em ciclos menores. Isso reduz o tempo de paralisação e facilita investigar divergências.
Manualv1.2.0

10 Lotes, validade e reposição

  • 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.
Manualv1.2.0

11 Relatórios e exportações

  1. Acesse Relatórios e selecione o relatório desejado.
  2. Aplique filtros de período, categoria, produto, fornecedor e usuário conforme disponíveis.
  3. Confira indicadores e linhas na tela.
  4. Selecione PDF para documento paginado, XLSX para análise em planilha ou CSV para integração.
  5. Abra o arquivo exportado e confirme título, período, totais e quantidade de registros.
Boa prática: Guarde relatórios gerenciais fora da pasta de backup do banco. Relatório exportado não substitui backup, pois não contém todas as relações e o histórico necessários à restauração.
Manualv1.2.0

12 Importar produtos por planilha

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

13 Usuários e auditoria

13 1 Criar ou alterar usuário

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

13 2 Consultar auditoria

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

14 Backup manual

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

15 Configurar backup automático em drive externo

  1. Conecte o HD externo ou pendrive e confirme no Explorador de Arquivos que ele está acessível e possui espaço livre.
  2. Crie uma pasta exclusiva, por exemplo E:\Backups-Cubexa. Evite usar a raiz da unidade.
  3. Na Cubexa, entre como Administrador e acesse Configurações → Backups.
  4. Selecione Escolher pasta e indique a pasta do drive externo.
  5. 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.
  6. Defina retenção. Recomendação inicial: 14 cópias diárias ou 8 semanais, ajustando ao volume e ao espaço.
  7. Selecione Salvar configuração.
  8. Crie um backup manual de teste e confirme o histórico e o arquivo no drive.
  9. Ejete o drive com segurança somente depois de o backup terminar.
Atenção: A letra da unidade pode mudar ao reconectar. Se isso ocorrer, selecione novamente a pasta. Backups automáticos falharão se o drive estiver desconectado, sem espaço ou sem permissão de gravação.
Manualv1.2.0

16 Estratégia de backup recomendada 3 2 1

  • 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.
Manualv1.2.0

17 Restaurar um backup

  1. Pare vendas, compras, recebimentos e movimentações. Avise todos os usuários da janela de restauração.
  2. Confirme que o arquivo é .sqlite3, provém da Cubexa e corresponde ao ponto desejado. Preserve uma cópia dele.
  3. Entre como Administrador e acesse Configurações → Backups.
  4. Selecione Restaurar backup, leia o aviso e confirme Selecionar e restaurar.
  5. Escolha o arquivo. A Cubexa valida integridade e estrutura e cria automaticamente um PRE_RESTORE do estado atual.
  6. Aguarde a conclusão. A sessão será encerrada. Entre novamente.
  7. Confira empresa, usuários, produtos, saldo de amostra, últimas vendas/compras e auditoria.
  8. Se algo estiver incorreto, pare as operações e contate o suporte informando o caminho do PRE_RESTORE.
Nunca faça: Não renomeie qualquer banco para “parecer” backup, não substitua o arquivo ativo manualmente e não restaure com usuários trabalhando.
Manualv1.2.0

18 Teste periódico de restauração

  • 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.
Manualv1.2.0

19 Recuperar senha do administrador

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

20 Rotina operacional sugerida

FrequênciaVerificações
DiáriaAlertas do Dashboard; compras a receber; vendas pendentes; lotes vencendo; último backup concluído.
SemanalEstoque baixo; sugestões de reposição; itens sem giro; falhas de backup; usuários ativos.
MensalInventário cíclico; divergências; relatórios de margem e giro; espaço livre do computador e drive.
TrimestralTeste de restauração; revisão de acessos; cópia externa/off-site; atualização do manual.
Manualv1.2.0

21 Solução de problemas

SituaçãoAção segura
Saída bloqueadaConfira saldo e lotes. Não habilite estoque negativo apenas para contornar o erro.
Inventário não concluiPreencha contagens pendentes; se houve movimento durante a contagem, investigue e reinicie.
Backup falhouReconecte a unidade, confirme pasta, espaço e permissão; execute novo backup manual.
Arquivo não restauraUse um .sqlite3 original da Cubexa; não force a importação.
Produto duplicado na importaçãoRevise SKU/código de barras e mapeamento antes de repetir.
Tela sem ação de ediçãoConfirme se o perfil é Operador/Administrador e se a ação exige Administrador.
Saldo incorretoConsulte movimentos, estornos e auditoria; faça ajuste documentado ou inventário.
Manualv1.2.0

22 Checklist de encerramento diário

  • 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.
Manualv1.2.0

23 Instalar e atualizar a versão 1 2 0

  1. Execute Cubexa-Setup-1.2.0.exe.
  2. Leia as boas-vindas e os Termos de Licença e Uso. Marque o aceite para habilitar o botão Próximo.
  3. Escolha o usuário do Windows e a pasta de instalação.
  4. Selecione Normal para manter os dados no perfil do Windows ou Portátil para manter os dados comerciais em CubexaData junto do programa.
  5. Conclua a instalação. Em uma atualização, abra Configurações e Sobre e confirme a versão 1.2.0.
Importante. No modo Portátil, não remova a unidade nem renomeie CubexaData com a Cubexa aberta. Use a remoção segura e mantenha uma cópia de backup separada.
Manualv1.2.0

24 Consultar e administrar a licença

  1. Acesse Configurações e Licença.
  2. Confira plano, estado, validade, consumo de produtos e usuários e dispositivo atual.
  3. Para ativar uma licença paga, informe a chave fornecida e conclua a ativação com internet disponível.
  4. Use Revalidar quando orientado pelo suporte. Uma licença local válida continua operando offline.
  5. Use Desativar dispositivo somente quando precisar transferir a licença ou liberar a vaga. Confirme a ação.

Se a licença não permitir escrita, a Cubexa mantém consultas, relatórios, exportações e backups. Regularize a licença para voltar a registrar operações.

Manualv1.2.0

25 Gerar pedido de compra e configurar impressão

  1. Abra Compras e selecione um pedido.
  2. Revise fornecedor, situação, itens, recebimentos, valores e observações.
  3. Abra a prévia do pedido A4 e use Salvar PDF ou Imprimir. Cancelar a impressão não altera a compra.
  4. Para calibrar o dispositivo, acesse Configurações e Impressão. Escolha A4, 58 mm, 80 mm ou Personalizado, impressora, margens, escala, fonte, logo e compatibilidade de caracteres.
  5. Faça uma impressão de teste e salve o perfil local.
Manualv1.2.0

26 Operar o PDV e emitir comprovante

  1. Acesse Vendas e abra o PDV. Se não houver caixa aberto, siga o direcionamento para abrir uma sessão.
  2. Busque por nome, SKU ou código de barras. Para várias unidades, use quantidade*código, como 5*7890000000000.
  3. Revise quantidade, preço, desconto e avisos de falta de estoque.
  4. Identifique o cliente quando necessário e selecione uma ou mais formas de pagamento.
  5. Em dinheiro, informe o valor recebido e confira o troco.
  6. Selecione Finalizar. O sistema revalida estoque, lotes, pagamentos e caixa na transação.
  7. No pop-up pós-venda, imprima, salve o comprovante ou saia. Falha de impressão não desfaz a venda concluída.
Manualv1.2.0

27 Controlar caixa e fechamento diário

  1. Acesse Vendas e Caixa e fechamento.
  2. Abra o caixa e informe o saldo inicial. A sessão pertence ao operador neste computador.
  3. Registre Suprimento para entrada avulsa ou Sangria para retirada de dinheiro, sempre com motivo.
  4. Use o PDV. Vendas e cancelamentos em dinheiro atualizam o caixa na mesma transação.
  5. No encerramento, informe a contagem física e justifique qualquer diferença.
  6. Revise o histórico e gere o fechamento da competência. Administradores podem revisar ou reabrir com registro de auditoria.
  7. Salve o PDF gerencial e, se configurado, acompanhe o envio por e-mail.
Manualv1.2.0

28 Configurar o envio de fechamento por e mail

  1. Entre como Administrador e acesse Configurações e E-mail.
  2. Informe servidor SMTP, porta, TLS, usuário, senha, remetente e destinatários.
  3. Teste a conexão e salve. A senha fica protegida pelo armazenamento seguro do Windows.
  4. No fechamento diário, solicite o envio. Falhas temporárias entram na fila de nova tentativa sem repetir mensagens confirmadas.
Manualv1.2.0

29 Cadastrar receita e concluir produção

  1. Acesse Manufatura e cadastre uma receita com produto de saída, rendimento, vigência e insumos.
  2. Crie uma ordem em Rascunho e revise a necessidade calculada.
  3. Emita a ordem. A emissão valida os dados, mas não reserva estoque.
  4. Na conclusão, informe produção efetiva, perdas, custos adicionais e lote do produto acabado quando exigido.
  5. Revise a prévia e confirme. O sistema consome insumos por FEFO e calcula o custo real na mesma transação.
  6. Consulte o histórico e a exportação JSON. Correções usam estorno integral quando permitido.
Manualv1.2.0

30 Vender e receber pelo crediário

  1. Cadastre ou abra um cliente ativo e configure o limite quando necessário.
  2. No PDV, identifique o cliente e informe entrada, quantidade de parcelas e primeiro vencimento.
  3. Revise vencimentos e valores. O sistema distribui os centavos entre as primeiras parcelas.
  4. Se o saldo ultrapassar o limite, um Administrador deve autorizar e justificar.
  5. Finalize a venda e abra o crediário do cliente para consultar parcelas abertas, parciais, pagas, vencidas ou canceladas.
  6. Registre o recebimento. Dinheiro exige caixa aberto; PIX e cartões não alteram o caixa físico.
  7. Para corrigir um recebimento, estorne o lançamento integral e registre o valor correto.
Manualv1.2.0

31 Transformar produtos e unidades

  1. Acesse Transformações e escolha um perfil ou crie uma nova versão.
  2. Selecione variantes de origem e destino diferentes.
  3. Informe quantidade de origem, fator, perda técnica, baixa explícita de valor e custo adicional quando houver.
  4. Revise a quantidade líquida e o custo transferido. Custo zero exige confirmação explícita.
  5. Confira os lotes consumidos por FEFO e a validade herdada. O sistema não estende a validade silenciosamente.
  6. Confirme. Saldo insuficiente bloqueia a operação mesmo quando o estoque negativo estiver habilitado.
  7. Consulte o documento, a genealogia e a exportação JSON. O estorno integral depende da ausência de operações posteriores.
Manualv1.2.0

32 Boas práticas da versão 1 2 0

  • Crie e teste um backup antes de atualizar. Depois, confirme a versão em Sobre e faça uma operação de amostra.
  • No modo Portátil, use uma unidade confiável e remoção segura. Portabilidade não substitui backup.
  • Abra um caixa por operador e computador. Não compartilhe sessões e justifique suprimentos, sangrias e diferenças.
  • Calibre os comprovantes em cada computador e mantenha um perfil A4 para contingência.
  • Revise receitas e perfis de transformação antes de emitir documentos. Alterações futuras criam uma nova versão sem apagar o histórico.
  • Concilie contas a receber e parcelas vencidas diariamente. Devoluções externas devem ocorrer no meio de pagamento original.
  • Confira a ação exibida antes de usar F2.
Técnicav1.2.0

Controle do documento

CampoValor
ProdutoCubexa (identificadores internos legados “NexoStock”)
Versão1.2.0
PlataformaWindows 10/11 x64, aplicação desktop com instalação Normal ou Portátil
Base documentalCódigo-fonte, migrações, contratos IPC, serviços, testes e README da versão
EscopoEstoque, operação comercial, licenciamento, documentos, PDV, caixa, manufatura, crediário e transformações
Nota de identidade: O nome comercial é Cubexa. O arquivo nexostock.sqlite3, a bridge window.nexostock e o App ID com.nexostock.desktop foram preservados por compatibilidade; não devem ser renomeados em manutenção corretiva sem plano de migração.
Técnicav1.2.0

Destaques da versão 1 2 0

A versão 1.2.0 mantém o catálogo, o estoque, as compras, as vendas, os inventários, os relatórios e a administração da versão 1.0.0. A atualização amplia a operação com os recursos abaixo e executa as migrações 009 a 016 após um backup verificado.

ÁreaMudança incorporada
Instalação e dadosModos Normal e Portátil, preservação de dados, bloqueio concorrente da pasta e validação da unidade.
LicenciamentoDemo, Básico e Profissional, certificados Ed25519, operação offline e modo somente leitura.
DocumentosPedido de compra A4 com histórico, prévia, PDF e impressão; perfis A4, 58 mm, 80 mm e personalizado.
VendasPDV, pagamentos divididos, troco e comprovantes não fiscais com proteção contra finalização repetida.
CaixaCaixa por operador e computador, suprimento, sangria, encerramento contado, fechamento diário, PDF e SMTP.
Novos módulosManufatura, crediário e transformação rastreável entre produtos e unidades.
QualidadeAtalho F2 contextual, Esc nas janelas, correções de foco e sessão; 307 testes aprovados em 38 arquivos.
Técnicav1.2.0

Sumário executivo

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.
Técnicav1.2.0

1 Arquitetura e tecnologias

ComponenteTecnologia / responsabilidade
RendererReact 19 + TypeScript strict; UI, acessibilidade e estado de tela.
DesktopElectron 37; janela, ciclo de vida, diálogos e empacotamento.
BridgePreload com contextIsolation e API mínima window.nexostock.
AplicaçãoServiços TypeScript; autorização, validações e limite transacional.
PersistênciaSQLite via better-sqlite3; migrações versionadas.
BuildVite 7 e Electron Builder/NSIS.
ExportaçãoExcelJS para XLSX; geradores locais para PDF e CSV.
TestesVitest com 307 testes aprovados em 38 arquivos na liberação 1.2.0.

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.

Técnicav1.2.0

2 Estrutura do repositório

DiretórioConteúdo
src/Aplicação React, componentes, estilos e features.
electron/Main, preload, IPC, contratos, serviços, banco e migrações.
tests/Testes automatizados de catálogo, estoque, compras, vendas, inventário, relatórios, administração e erros.
docs/Arquitetura e checklist de release.
resources/Ícones e recursos de empacotamento.
release/Instaladores e artefatos gerados.
Técnicav1.2.0

3 Banco de dados e integridade

  • 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 versão 1.2.0 inclui as migrações 001 a 016 e cria um backup verificado antes de migrar uma base existente.
  • 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.
Técnicav1.2.0

4 Modelo de dados essencial

GrupoEntidades e função
Organizaçãocompanies, users, settings e audit_logs.
Catálogocategories, products, product_variants e product_suppliers.
Estoquestock_balances, stock_movements e lots.
Comprassuppliers, purchases e purchase_items.
Vendascustomers, sales e sale_items.
Inventárioinventories e inventory_items.
Continuidadebackup_history e schema_migrations.
Invariante crítica: A engine de movimentação é a única autoridade para alterar stock_balances e saldos de lotes. Compras alteram estoque somente no recebimento; vendas, somente na finalização; inventários, somente na conclusão.
Técnicav1.2.0

5 Regras de negócio críticas

  • 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.
Técnicav1.2.0

6 Segurança e perfis

PerfilCapacidade principal
AdministradorConfigura empresa e política de estoque; gerencia catálogo, usuários, auditoria, importação e backups; também opera os demais módulos.
OperadorRegistra movimentos, compras, vendas, recebimentos e inventários; não altera configurações administrativas nem o catálogo estrutural.
ConsultaAcesso somente leitura a telas e registros; ações de escrita são ocultadas e bloqueadas no processo principal.
  • 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.
Técnicav1.2.0

7 Backup e restauração implementação

ItemComportamento
FrequênciasDiário, semanal ou ao sair; habilitação configurável.
DestinoPasta selecionada pelo administrador; se ausente, subpasta backups do userData.
ArquivoCubexa-backup-<data-hora>-<tipo>.sqlite3.
ValidaçãoExtensão .sqlite3, integrity_check e presença de companies, users e schema_migrations.
EvidênciaHistórico com status, caminho, tamanho, horário e checksum SHA-256.
Retenção1 a 100 cópias; arquivos antigos do mesmo diretório são removidos, exceto PRE_RESTORE.
RestauraçãoCria PRE_RESTORE, encerra sessão, fecha banco, substitui arquivo, reabre, configura e executa migrações.
FalhaTenta repor o PRE_RESTORE e informa seu caminho ao operador.
Limite operacional: A rotina integrada grava em um único diretório configurado. A estratégia 3-2-1 deve ser completada com uma segunda cópia automatizada ou procedimento externo, sem manipular o banco em uso.
Técnicav1.2.0

8 Instalação, build e release

  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.
Técnicav1.2.0

9 Operação de desenvolvimento

ComandoUso
npm run devAplicativo desktop com banco local e runtime de licença.
$env:CUBEXA_DEMO_DATA='1'; npm run devDados demonstrativos, somente desenvolvimento e apenas se não houver empresa.
npm run dev:webPrévia no navegador com snapshot em memória e sem banco.
npm run checkTypecheck seguido dos testes.
npm run dist:winInstalador Windows NSIS.
Técnicav1.2.0

10 Testes e critérios de aceite

  • 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.
Técnicav1.2.0

11 Diagnóstico e suporte

SintomaVerificação inicial
Aplicativo não iniciaIntegridade do SQLite, permissões no userData e logs de inicialização.
Banco ocupadoOutra instância/processo, antivirus ou sincronizador operando no arquivo ativo; aguardar busy_timeout.
Saldo inesperadoHistórico de movimentos, estornos, lotes e auditoria; nunca editar o SQLite manualmente.
Backup falhaExistência/permissão da pasta, espaço livre, disponibilidade da unidade externa e histórico de backup.
Restauração recusadaExtensão, integrity_check e tabelas mínimas esperadas.
Usuário bloqueadoAguardar bloqueio temporário ou usar recuperação local do administrador conforme procedimento autorizado.
Técnicav1.2.0

12 Manutenção e evolução

  • 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.
Técnicav1.2.0

Apêndice A Checklist de release 1 2 0

  • 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.
Técnicav1.2.0

13 Licenciamento e capacidades comerciais

  • A Demo tem 90 dias. O estado local pode ser sincronizado sem ampliar o prazo por reinstalação ou conexão tardia.
  • Os planos Demo e Básico aplicam limites de produtos e usuários. O Profissional libera capacidades adicionais, incluindo crediário e e-mail de fechamento.
  • O certificado é assinado com Ed25519, vinculado ao hash do dispositivo e validado antes da persistência. A chave privada não acompanha o desktop.
  • Expiração, suspensão ou revogação preservam login, consultas, relatórios, exportações e backups. Os serviços de aplicação bloqueiam novas gravações.
  • O banco de licença fica separado do banco comercial e não é transportado por backups de estoque.
Técnicav1.2.0

14 Instalação e armazenamento

  • No modo Normal, os dados comerciais ficam no perfil do Windows. No modo Portátil, ficam em CubexaData junto do aplicativo.
  • Licença e perfis locais de dispositivo permanecem no Windows nos dois modos.
  • O marcador portátil, a sentinela de dados e o bloqueio de pasta impedem criação silenciosa de outra base e uso simultâneo da mesma pasta.
  • Antes de aplicar migrações, a API SQLite cria um snapshot que inclui transações confirmadas no WAL, executa integrity_check e grava um manifesto SHA-256.
  • Atualização e desinstalação preservam dados. A remoção de um dispositivo portátil durante a operação interrompe o acesso e exige reconexão antes de reabrir.
Técnicav1.2.0

15 Documentos impressão PDV e caixa

  • Pedidos e comprovantes usam snapshots versionados para preservar o conteúdo histórico depois de alterações cadastrais.
  • O PDV finaliza venda, estoque, lotes, pagamentos, caixa, comprovante e auditoria na mesma transação. request_id impede repetição da operação.
  • Pagamentos podem ser divididos. O troco considera o valor recebido em dinheiro e requer caixa aberto no computador do operador.
  • Perfis de impressão são locais ao dispositivo. PDF funciona offline e sem impressora; a impressão depende do driver e da confirmação do usuário.
  • O fechamento diário usa competência explícita, revisão auditada, PDF gerencial e fila SMTP com retry e proteção contra duplicação.
Técnicav1.2.0

16 Manufatura crediário e transformações

  • Manufatura usa receitas versionadas e ordens em Rascunho, Emitida, Concluída ou Cancelada. A conclusão consome insumos por FEFO e calcula o custo real.
  • Crediário exige cliente ativo, registra entrada, parcelas, vencimentos, recebimentos e estornos. Operações de escrita dependem do plano Profissional.
  • Transformações convertem uma variante em outra com fator, perda técnica, baixa explícita de valor e custo adicional.
  • Produção e transformação bloqueiam saldo insuficiente mesmo quando a política geral permite estoque negativo.
  • Os módulos preservam movimentos, lotes, custos e genealogia para auditoria e estorno integral.
Técnicav1.2.0

Apêndice B Validação da versão 1 2 0

  • TypeScript Desktop e Worker, renderer, main e preload compilados no pacote final.
  • 307 testes aprovados em 38 arquivos.
  • Migração de base 1.1.1 das versões 008 a 016 validada nos modos Normal e Portátil, com dados, imagens, saldos e chaves estrangeiras preservados.
  • Fluxo do instalador, aceite obrigatório dos termos, reinstalação e desinstalação validados em dados isolados.
  • Instalador Windows x64, checksum SHA-256 e relatório de validação gerados em release.
  • Impressão física e variedade de hardware permanecem como itens de homologação no ambiente de destino.