Manual Profissional Completo

Este manual explica o porquê e o como internos. Para o guia de uso passo a passo, veja o Manual do Usuário.

1. Arquitetura geral

O Ledyvas é uma aplicação de desktop construída sobre Electron. Roda 100 % na máquina do cliente — não há servidor de aplicação nem banco de dados na nuvem. A única coisa que o Ledyvas consulta pela internet é um servidor de licenças (um Cloudflare Worker), e só de vez em quando.

• Processo principal: inicia o app, valida a licença, abre o banco de dados e conecta todos os módulos antes de mostrar a interface.
• Interface: HTML/CSS/JavaScript sem framework. Cada tela é uma view carregada sob demanda ao navegar.
• Ponte única: a interface nunca toca no banco de dados diretamente. Tudo passa por uma camada de serviços com validação, transações e cálculos.
• Modo portátil: o banco de dados vive numa pasta Data ao lado do executável. Você pode copiar a pasta inteira para outro computador ou um disco externo.

2. Licença e criptografia

O Ledyvas é ativado com um código de licença contra o servidor de licenças. A validação usa assinatura criptográfica assimétrica (Ed25519): a chave privada vive apenas no servidor, então o app não conseguiria falsificar uma licença mesmo que alguém o descompilasse.

• Margem offline: após ativar, o Ledyvas funciona vários dias sem conexão. Revalida sozinho em segundo plano sempre que há internet. Só se a margem vencer e não houver conexão, o app pede para reconectar.
• Transferência: a licença pode ser movida para outra máquina. O servidor exige uma só máquina ativa por vez (impressão digital de hardware); ao ativar num PC novo, o anterior fica desativado.
• Banco de dados criptografado: o arquivo opshield.db está criptografado. A chave é derivada do código de licença por PBKDF2 com 210.000 iterações (padrão OWASP). Se roubarem o notebook, ninguém abre o banco sem a licença. Como a chave viaja com a licença e não com o hardware, a mesma licença reativada em outro PC volta a abrir o mesmo arquivo — por isso você pode mover a pasta entre computadores.

3. Banco de dados e migrações

O Ledyvas usa um único arquivo SQLite. O esquema evolui por migrações numeradas e ordenadas: cada atualização do app traz migrações novas que se aplicam sozinhas, uma vez, no primeiro início, dentro da própria transação. Uma migração já aplicada nunca é modificada; adiciona-se uma nova.

Ao iniciar, o Ledyvas também faz um ponto de verificação do registro de escrita (WAL) e o repete em segundo plano de tempos em tempos — isso evita que o arquivo de trabalho cresça sem controle em sessões longas.

4. Catálogo e relações

O catálogo é a base de tudo. Carrega-se uma vez e é referenciado em cada operação posterior pelo seu identificador interno estável, nunca pelo nome — por isso você pode renomear um produto, um destino ou uma categoria a qualquer momento sem quebrar o histórico.

Entidade	Papel	Relaciona-se com
Produto	Item que se compra, vende ou produz. Tem categoria, subcategoria, unidade, custo, código de barras.	Compras, Vendas, Receitas, Fórmula, Estoque
Categoria / Subcategoria	Classificam o produto. Definem o agrupamento em Compra/Estoque e a que "família" pertence (Alimentos, Bebidas, Uso Único, Combustível…).	Produto, Fórmula, Consolidados
Fornecedor	De quem se compra. Pode ter uma lista de produtos que fornece com o custo (referência).	Compra
Cliente	Para quem se vende. Se for "revendedor", tem estoque próprio.	Venda ao Consumidor, Destino
Destino	Ponto de distribuição. Pode ter um cliente-revendedor vinculado e um preço de venda por PAX.	Fórmula, Centro Logístico, Margem por Destino
Equipamento	Veículo ou embarcação. Tipo (barco/terrestre) e grupo (empresa/alugado).	Combustível, Consolidado de Frotas

5. O motor de Fórmula por PAX

Só com o Modo Excursão ativo. A Fórmula traduz "quantas pessoas você vai atender" em "quanto comprar e enviar".

1. Configura-se uma matriz de Valor: para cada combinação produto × destino, quanto uma pessoa consome (ex. 0,25 kg de arroz por PAX no destino X).
2. Todo dia carrega-se o PAX por destino.
3. A execução calcula, por linha (destino × produto): Necessária = Valor × PAX.
4. Da Necessária subtraem-se três ajustes carregados por destino: Estoque Existente (o que o destino já tem), Devolução (o que devolveu) e Inventário na Praia (contagem física no ponto). O resultado é o Envio dessa linha (nunca negativo).
5. Para saber quanto comprar no total, soma-se o Envio de todos os destinos de cada produto (arredondando cada linha para cima, porque não se entrega uma fração a um restaurante) e subtrai-se uma única vez o Inventário de Armazém (estoque compartilhado que já existe no Centro Logístico).

Compra Assistida A (Alimentos) e B (Bebidas) só executam esse cálculo — são uma proposta. Não geram nenhuma compra real nem tocam no estoque. A tela Compra é a única que confirma.

6. Compra: como o estoque entra

A tela Compra é o único ponto do sistema que gera uma compra real. Ao confirmar, dentro de uma única transação atômica:

1. Insere-se o documento de compra (fornecedor, data, linhas).
2. Soma-se a quantidade ao current_stock de cada produto, de forma síncrona.
3. Registra-se um movimento no histórico (stock_movements) com produto, quantidade, custo, data e usuário — rastreabilidade completa.
4. Sincroniza-se o módulo Controle Diário para aquele dia/categoria.
5. Se o produto for de Bebidas, Uso Único ou Combustível, transfere-se sozinho para o acompanhamento interno dessas categorias dentro do Centro Logístico.

Cancelar ou modificar uma compra reverte tudo isso sobre a data original do documento, não sobre a data de hoje. O Ledyvas não bloqueia o cancelamento mesmo que o estoque fique negativo (ver seção 16).

7. Centro Logístico e as Vendas

Centro Logístico é o único armazém do sistema. Dali se vende/envia aos destinos. Cada seção de venda (Venda a Restaurantes = Alimentos + Uso Único; Venda a Embarcações = Bebidas) tem o próprio PAX, independente do PAX de Compra — o PAX de Compra e o de Venda não interferem entre si (comprar e vender são processos separados).

Ao confirmar uma venda, para cada destino com algo calculado gera-se uma transferência real: desconta o current_stock, credita o estoque do cliente-revendedor daquele destino, e registra o movimento — tudo dentro de uma única transação (se um destino falha, tudo é revertido). O envio por destino usa a mesma fórmula ajustada por Estoque Existente/Devolução/Inventário na Praia da Compra.

A venda valida o estoque e avisa o que falta, mas não impede confirmar — a operação não é interrompida.

8. Venda ao Consumidor e o estoque do revendedor

Cada cliente marcado como "revendedor" tem um saldo de estoque próprio (reseller_stock). É creditado quando o Centro Logístico lhe envia, e descontado quando esse revendedor vende ao consumidor final na tela Venda ao Consumidor.

• Ao confirmar uma venda a partir do Centro Logístico cria-se automaticamente um rascunho de Venda ao Consumidor por destino. O rascunho existe, pode ser editado, mas não desconta estoque até ser confirmado explicitamente.
• As linhas de Bebidas de embarcações não têm preço de venda próprio (a cobrança do pacote por PAX é registrada uma única vez do lado dos Alimentos, para não contar a receita duas vezes). São mostradas como registro de custo, não como prejuízo.
• Revenda é apenas um relatório do que já foi enviado — não gera movimentos.

9. Bebidas, Uso Único e Combustível

Essas três famílias não têm armazém nem tela à parte. Vivem dentro do Centro Logístico com um acompanhamento de estoque próprio:

• Transferem-se sozinhas para esse acompanhamento ao confirmar uma Compra (em vez de somar ao estoque geral de produtos).
• A partir do Centro Logístico registram-se suas vendas, ajustes, saídas/consumo e devoluções, cada uma com o próprio tipo de movimento e histórico.
• Bebidas subdivide-se em Alcoólicas / Não Alcoólicas.
• A visão "Devolução do Dia" consolida todas as devoluções (Bebidas por subgrupo, Consumíveis, Combustível) num só lugar, e esse estoque devolvido reduz automaticamente a sugestão de compra do dia seguinte.

Nos Consolidados, essas famílias não são distribuídas por destino: são levadas como custo geral (exceto Uso Único, que é sim enviado por destino — ver seção 5).

10. Galões de combustível

Para negócios que, além do inventário em galões, gerenciam combustível/óleo em galões físicos (5, 7, 9, 10 e 18 GL). É um inventário paralelo que sincroniza sozinho com o inventário em galões — nunca é preciso lançar nada duas vezes.

Operação	Efeito
Compra	Soma galões (por capacidade e quantidade exata, ou com uma sugestão de distribuição ótima dados os galões que você precisa) e soma os galões equivalentes ao inventário geral.
Venda / envio	Subtrai galões atribuindo-os a um equipamento, e subtrai os galões do inventário.
Devolução	Cheio (soma completo), parcial (soma os galões reais que traz) ou vazio (não soma combustível, só devolve o recipiente).
Ajuste	Corrige a contagem após um inventário físico. Pede o valor correto por capacidade/estado e um motivo, e fica auditado.

Tem o próprio Fechamento de Dia (Inicial + Compras − Vendido + Devolvido = Final) e Histórico completo. A visualização pode alternar entre Galões e Litros; o que está salvo no banco nunca muda de unidade.

11. Controle Diário

É uma camada de reconciliação, separada do estoque real. Registra, por dia/categoria/produto: inicial, compras, envios (por equipamento/destino), devoluções e a contagem física.

Final calculado = Inicial + Compras − (Enviado − Devolvido). Se houver contagem física carregada, esse é o número verificado e é usado como inicial do dia seguinte — assim uma diferença entre o teórico e o real se corrige sozinha e não é arrastada.

As compras e envios reais sincronizam o Controle Diário automaticamente; também é possível editar na mão.

12. Como se calcula cada Consolidado

Resumo Diário / Consolidado Operacional

O custo operacional total do negócio no período: a Compra real confirmada (por categoria, com os buckets Gasolina/Óleo separados) mais os custos manuais configuráveis por rubrica (aluguel, salários, comissões, etc. — gerenciados em Configuração, não são uma lista fixa). Mostra ainda: PAX do período, gasto total, custo por PAX, e uma tabela estatística PAX Médio por Destino (média de PAX vendido por dia a cada destino, contando apenas os dias com venda real). Essa tabela é puramente informativa — não entra em nenhum cálculo de custo.

Margem por Destino

Só com o Modo Excursão. Custo, venda e margem por cada destino, unicamente para o que passou pelo Centro Logístico (transferências reais). O custo está congelado em cada transferência; a venda usa o preço salvo na transferência. Bebidas e Combustível não aparecem por destino (são mostrados à parte como "outros custos do período").

Consolidado de Frotas

Consumo de combustível por equipamento. No modo semanal usa média ponderada por quantidade (um dia de muito consumo pesa mais que um de pouco). Valores na moeda local ou em dólares conforme a taxa configurada.

13. Receitas e Produção

Uma receita define, para um produto acabado, quanto leva de cada ingrediente. O ingrediente pode estar numa unidade diferente da do produto no catálogo (gramas na receita, quilos em Produtos) — o Ledyvas converte automaticamente por família de unidade (peso, volume) antes de calcular custo e consumo.

Ao produzir, dentro de uma transação:

1. Desconta-se cada ingrediente do estoque conforme a quantidade convertida × lotes.
2. Soma-se o produto acabado (porções × lotes).
3. Recalcula-se o custo do produto acabado como média ponderada entre o estoque que já havia (ao custo anterior) e o recém-produzido (ao custo por porção da receita). Se a receita não tiver ingredientes custeados, o custo real anterior não é sobrescrito.

Assim o produto acabado sempre tem um custo real: vale o valor certo em Estoque e pode ser vendido sem que a validação o bloqueie por custo zero.

14. Equipamentos e Consolidado de Frotas

Equipamentos é o cadastro de veículos/embarcações. Cada um com código automático, tipo (barco/terrestre) e grupo (da empresa / alugados). São usados para atribuir envios de combustível e vendas por unidade, que depois alimentam o Consolidado de Frotas (ver seção 12).

15. Multiusuário, perfis e acesso

O Ledyvas tem um sistema de usuários com 5 perfis: Gerência, Compras, Vendas, Estoque, Contabilidade. As senhas são guardadas apenas como hash (scrypt), nunca em texto puro.

16. Estoque negativo: decisão de projeto

O Ledyvas nunca bloqueia confirmar uma venda, um envio, uma produção ou o cancelamento de uma compra por falta de estoque. É uma decisão explícita: não interromper a operação do negócio. Um estoque negativo não é um erro do programa — corrige-se com o botão Ajustar Estoque daquela linha (em Produtos ou Estoque), que pede o valor correto e um motivo e o deixa auditado.

Única exceção: a Devolução de mercadoria de um revendedor valida sim que ele não devolva mais do que recebeu (fisicamente não faz sentido).

17. Backup e Exclusão Mestra

Backup (em Início): salva uma cópia completa do arquivo de banco de dados com um clique.

Exclusão Mestra (em Início, "Modo de Teste"): exclui Compras, Vendas e Transferências a partir de uma data escolhida, para a frente — nunca antes dessa data, e nunca o catálogo (Produtos, Clientes, Fornecedores, Destinos). Pede para digitar "EXCLUIR TUDO". Cada documento é excluído usando o mesmo mecanismo do cancelamento individual, então as reversões de estoque ficam consistentes. Serve para limpar dados de teste antes de operar pra valer.

18. Idiomas e moeda

O Ledyvas está traduzido para espanhol, italiano, inglês, francês e português. O idioma muda ao vivo com as bandeiras, sem reiniciar. A moeda do negócio define-se em Configuração e governa todos os valores; a taxa de câmbio para dólares (configurável) é usada nos relatórios de frota.

19. Assistente de IA

O assistente dentro do app responde perguntas de uso. Arquitetura:

• O app envia a pergunta (e o histórico recente) junto com a licença e a impressão digital de hardware ao servidor de licenças.
• O servidor valida a licença, aplica um limite de 40 perguntas por dia por licença (rede de segurança de custo), e só então chama o modelo de linguagem.
• A chave do provedor de IA nunca está no app nem no instalador — vive apenas como secret do servidor.
• O assistente responde sempre no idioma em que se escreve a ele, entre os 5 idiomas suportados.

20. Regras de negócio-chave

• Comprar ≠ vender. A Compra só soma estoque. A distribuição aos destinos é independente.
• Um único armazém. Centro Logístico. Não existe nenhum depósito nem "armazém satélite" separado.
• A Compra Assistida só calcula. Nunca gera uma compra real.
• Identificadores estáveis. Tudo é referenciado pelo id interno; os nomes podem ser trocados sem quebrar nada.
• Todo movimento de estoque fica auditado no histórico, com a data real do documento (não a de hoje).
• O estoque nunca trava a operação (exceto a Devolução de revendedor).
• A contagem física manda. No Controle Diário, a contagem real corrige a teórica e é arrastada como inicial do dia seguinte.

21. Perguntas técnicas frequentes

Posso mover a instalação para outro computador?

Sim. Copie a pasta inteira (programa + pasta Data) e ative a licença na máquina nova. A licença transfere-se sozinha (a anterior fica desativada). Como a chave de criptografia deriva da licença, o banco abre no PC novo.

Os dados estão na nuvem?

Não. Tudo está na sua máquina, num arquivo criptografado. Faça backups com frequência.

Por que um produto produzido valia zero e agora não?

Produzir agora calcula o custo real do produto acabado (média ponderada). Antes era preciso lançá-lo na mão.

Por que a Venda a Restaurantes agora oferece Uso Único?

Os Descartáveis/Uso Único são enviados por destino como os Alimentos. Precisam ter o Valor carregado na Fórmula (Compra Assistida A) e o custo em Produtos.

O que acontece se eu excluir um produto que está numa receita?

O Ledyvas avisa antes de confirmar em quantas receitas e linhas de Fórmula ele é usado. Se você excluir, ele é removido dali e essas receitas recalculam o custo. Se o produto tiver compras/vendas reais, não é excluído: é desativado.

Se algo não estiver coberto aqui

Escreva para info@ledyvas.com.