Manual Profesional Completo

Este manual explica el por qué y el cómo internos. Para la guía de uso paso a paso, ver el Manual de Usuario.

1. Arquitectura general

Ledyvas es una aplicación de escritorio construida sobre Electron. Corre 100 % en la máquina del cliente — no hay servidor de aplicación ni base de datos en la nube. Lo único que Ledyvas consulta por internet es un servidor de licencias (un Cloudflare Worker), y solo cada tanto.

• Proceso principal: arranca la app, valida la licencia, abre la base de datos y conecta todos los módulos antes de mostrar la interfaz.
• Interfaz: HTML/CSS/JavaScript sin framework. Cada pantalla es una vista que se carga bajo demanda al navegar.
• Puente único: la interfaz nunca toca la base de datos directamente. Todo pasa por una capa de servicios con validación, transacciones y cálculos.
• Modo portátil: la base de datos vive en una carpeta Data al lado del ejecutable. Puede copiar la carpeta entera a otra computadora o a un disco externo.

2. Licencia y cifrado

Ledyvas se activa con un código de licencia contra el servidor de licencias. La validación usa firma criptográfica asimétrica (Ed25519): la clave privada vive solo en el servidor, así que la app no podría falsificar una licencia aunque alguien la descompilara.

• Margen offline: tras activar, Ledyvas funciona varios días sin conexión. Revalida sola en segundo plano cada vez que hay internet. Solo si el margen vence y no hay conexión, la app pide reconectarse.
• Transferencia: la licencia se puede mover a otra máquina. El servidor exige una sola máquina activa a la vez (huella de hardware); al activar en una PC nueva, la anterior queda desactivada.
• Base de datos cifrada: el archivo opshield.db está cifrado. La clave se deriva del código de licencia mediante PBKDF2 con 210.000 iteraciones (estándar OWASP). Si roban la laptop, nadie abre la base sin la licencia. Como la clave viaja con la licencia y no con el hardware, la misma licencia reactivada en otra PC vuelve a abrir el mismo archivo — por eso puede mover la carpeta entre computadoras.

3. Base de datos y migraciones

Ledyvas usa un único archivo SQLite. El esquema evoluciona por migraciones numeradas y ordenadas: cada actualización de la app trae migraciones nuevas que se aplican solas, una vez, en el primer arranque, dentro de su propia transacción. Nunca se modifica una migración ya aplicada; se agrega una nueva.

Al arrancar, Ledyvas también hace un punto de control del registro de escritura (WAL) y lo repite en segundo plano cada tanto — esto evita que el archivo de trabajo crezca sin control en sesiones largas.

4. Catálogo y relaciones

El catálogo es la base de todo. Se carga una vez y se referencia en cada operación posterior por su identificador interno estable, nunca por su nombre — por eso puede renombrar un producto, un destino o una categoría en cualquier momento sin romper el historial.

Entidad	Rol	Se relaciona con
Producto	Artículo que se compra, vende o produce. Tiene categoría, subcategoría, unidad, costo, código de barras.	Compras, Ventas, Recetas, Fórmula, Inventario
Categoría / Subcategoría	Clasifican el producto. Definen agrupación en Compra/Inventario y a qué "familia" pertenece (Alimentos, Bebidas, Mono Uso, Combustible…).	Producto, Fórmula, Consolidados
Proveedor	A quién se le compra. Puede tener una lista de productos que suministra con su costo (referencia).	Compra
Cliente	A quién se le vende. Si es "revendedor", tiene stock propio.	Venta a Consumidor, Destino
Destino	Punto de distribución. Puede tener un cliente-revendedor vinculado y un precio de venta por PAX.	Fórmula, Centro Logístico, Margen por Destino
Equipo	Vehículo o embarcación. Tipo (barco/terrestre) y grupo (compañía/alquilado).	Combustible, Consolidado de Flotas

5. El motor de Fórmula por PAX

Solo con Modo Excursión activo. La Fórmula traduce "cuánta gente va a atender" en "cuánto comprar y despachar".

1. Se configura una matriz de Valor: por cada combinación producto × destino, cuánto consume una persona (ej. 0,25 kg de arroz por PAX en el destino X).
2. Cada día se carga el PAX por destino.
3. La corrida calcula, por línea (destino × producto): Requerida = Valor × PAX.
4. De la Requerida se restan tres ajustes que se cargan por destino: Existencia (lo que el destino ya tiene), Devolución (lo que devolvió) e Inventario en Playa (conteo físico en el punto). El resultado es el Despacho de esa línea (nunca negativo).
5. Para saber cuánto comprar en total, se suma el Despacho de todos los destinos de cada producto (redondeando cada línea hacia arriba, porque no se entrega una fracción a un restaurante) y se resta una sola vez el Inventario de Almacén (stock compartido que ya hay en el Centro Logístico).

Compra Asistida A (Alimentos) y B (Bebidas) solo ejecutan este cálculo — son una propuesta. No generan ninguna compra real ni tocan el inventario. La pantalla Compra es la única que confirma.

6. Compra: cómo entra el stock

La pantalla Compra es el único punto del sistema que genera una compra real. Al confirmar, dentro de una única transacción atómica:

1. Se inserta el documento de compra (proveedor, fecha, líneas).
2. Se suma la cantidad a current_stock de cada producto, de forma síncrona.
3. Se registra un movimiento en el historial (stock_movements) con producto, cantidad, costo, fecha y usuario — trazabilidad completa.
4. Se sincroniza el módulo Control Diario para ese día/categoría.
5. Si el producto es de Bebidas, Mono Uso o Combustible, se transfiere solo al seguimiento interno de esas categorías dentro de Centro Logístico.

Anular o modificar una compra revierte todo lo anterior sobre la fecha original del documento, no sobre la fecha de hoy. Ledyvas no bloquea la anulación aunque el stock quede negativo (ver sección 16).

7. Centro Logístico y las Ventas

Centro Logístico es el único almacén del sistema. Desde ahí se vende/despacha a los destinos. Cada sección de venta (Venta a Restaurantes = Alimentos + Mono Uso; Venta a Embarcaciones = Bebidas) tiene su propio PAX, independiente del PAX de Compra — el PAX de Compra y el de Venta no se pisan entre sí (comprar y vender son procesos separados).

Al confirmar una venta, por cada destino con algo calculado se genera una transferencia real: descuenta current_stock, acredita el stock del cliente-revendedor de ese destino, y registra el movimiento — todo dentro de una sola transacción (si falla un destino, se revierte todo). El despacho por destino usa la misma fórmula ajustada por Existencia/Devolución/Inventario en Playa que la Compra.

La venta valida el stock y avisa qué falta, pero no impide confirmar — la operación no se interrumpe.

8. Venta a Consumidor y stock del revendedor

Cada cliente marcado como "revendedor" tiene un balance de stock propio (reseller_stock). Se acredita cuando el Centro Logístico le despacha, y se descuenta cuando ese revendedor vende al consumidor final en la pantalla Venta a Consumidor.

• Al confirmar una venta desde Centro Logístico se crea automáticamente un borrador de Venta a Consumidor por destino. El borrador existe, se puede editar, pero no descuenta stock hasta que se confirma explícitamente.
• Las líneas de Bebidas de embarcaciones no llevan precio de venta propio (el cobro del paquete por PAX se registra una sola vez del lado de Alimentos, para no contar el ingreso dos veces). Se muestran como registro de costo, no como pérdida.
• Reventa es solo un reporte de lo ya despachado — no genera movimientos.

9. Bebidas, Mono Uso y Combustible

Estas tres familias no tienen almacén ni pantalla aparte. Viven dentro de Centro Logístico con un seguimiento de stock propio:

• Se transfieren solas a ese seguimiento al confirmar una Compra (en vez de sumarse al stock general de productos).
• Desde Centro Logístico se registran sus ventas, ajustes, salidas/consumo y devoluciones, cada una con su tipo de movimiento y su historial.
• Bebidas se subdivide en Alcohólicas / No Alcohólicas.
• La vista "Devolución del Día" consolida todas las devoluciones (Bebidas por subgrupo, Consumibles, Combustible) en un solo lugar, y ese stock devuelto reduce automáticamente la sugerencia de compra del día siguiente.

En los Consolidados, estas familias no se reparten por destino: se llevan como costo general (excepto Mono Uso, que sí se despacha por destino — ver sección 5).

10. Garrafones de combustible

Para negocios que además del inventario en galones manejan combustible/aceite en garrafones físicos (5, 7, 9, 10 y 18 GL). Es un inventario paralelo que sincroniza solo con el inventario en galones — nunca hay que cargar nada dos veces.

Operación	Efecto
Compra	Suma garrafones (por capacidad y cantidad exacta, o con una sugerencia de reparto óptimo dados los galones que necesita) y suma los galones equivalentes al inventario general.
Venta / despacho	Resta garrafones asignándolos a un equipo, y resta los galones del inventario.
Devolución	Llena (suma completo), parcial (suma los galones reales que trae) o vacía (no suma combustible, solo devuelve el envase).
Ajuste	Corrige el conteo tras un inventario físico. Pide el valor correcto por capacidad/estado y un motivo, y queda auditado.

Tiene su propio Cierre de Día (Inicial + Compras − Vendido + Devuelto = Final) e Historial completo. La visualización se puede alternar entre Galones y Litros; lo guardado en la base nunca cambia de unidad.

11. Control Diario

Es una capa de reconciliación, separada del stock real. Registra, por día/categoría/producto: inicial, compras, despachos (por equipo/destino), devoluciones y el conteo físico.

Final calculado = Inicial + Compras − (Despachado − Devuelto). Si hay conteo físico cargado, ese es el número verificado y se usa como inicial del día siguiente — así una diferencia entre lo teórico y lo real se corrige sola y no se arrastra.

Las compras y despachos reales sincronizan Control Diario automáticamente; también se puede editar a mano.

12. Cómo se calcula cada Consolidado

Resumen Diario / Consolidado Operacional

El costo operativo total del negocio en el período: la Compra real confirmada (por categoría, con los buckets Gasolina/Aceite separados) más los costos manuales configurables por rubro (alquiler, sueldos, comisiones, etc. — se administran en Configuración, no son un listado fijo). Muestra además: PAX del período, total de gasto, costo por PAX, y una tabla estadística PAX Promedio por Destino (promedio de PAX vendido por día a cada destino, contando solo los días con venta real). Esa tabla es puramente informativa — no entra en ningún cálculo de costo.

Margen por Destino

Solo con Modo Excursión. Costo, venta y margen por cada destino, únicamente para lo que pasó por Centro Logístico (transferencias reales). El costo está congelado en cada transferencia; la venta usa el precio guardado en la transferencia. Bebidas y Combustible no aparecen por destino (se muestran aparte como "otros costos del período").

Consolidado de Flotas

Consumo de combustible por equipo. En modo semanal usa promedio ponderado por cantidad (un día de mucho consumo pesa más que uno de poco). Montos en moneda local o dólares según la tasa configurada.

13. Recetas y Producción

Una receta define, para un producto terminado, cuánto lleva de cada ingrediente. El ingrediente puede estar en una unidad distinta a la del producto en el catálogo (gramos en la receta, kilos en Productos) — Ledyvas convierte automáticamente por familia de unidad (peso, volumen) antes de calcular costo y consumo.

Al producir, dentro de una transacción:

1. Se descuenta cada ingrediente del stock según la cantidad convertida × lotes.
2. Se suma el producto terminado (porciones × lotes).
3. Se recalcula el costo del producto terminado como promedio ponderado entre el stock que ya había (a su costo anterior) y lo recién producido (al costo por porción de la receta). Si la receta no tiene ingredientes costeados, no se pisa el costo real anterior.

Así el producto terminado tiene siempre un costo real: vale lo correcto en Inventario y se puede vender sin que la validación lo bloquee por costo cero.

14. Equipos y Consolidado de Flotas

Equipos es el padrón de vehículos/embarcaciones. Cada uno con código automático, tipo (barco/terrestre) y grupo (de la compañía / alquilados). Se usan para atribuir despachos de combustible y ventas por unidad, que después alimentan el Consolidado de Flotas (ver sección 12).

15. Multiusuario, roles y acceso

Ledyvas tiene un sistema de usuarios con 5 roles: Gerencia, Compra, Venta, Almacén, Contabilidad. Las contraseñas se guardan solo como hash (scrypt), nunca en texto plano.

16. Stock negativo: decisión de diseño

Ledyvas nunca bloquea confirmar una venta, un despacho, una producción o la anulación de una compra por falta de stock. Es una decisión explícita: no interrumpir la operación del negocio. Un stock negativo no es un error del programa — se corrige con el botón Ajustar Stock de esa fila (en Productos o Inventario), que pide el valor correcto y un motivo y lo deja auditado.

Única excepción: la Devolución de mercadería de un revendedor sí valida que no devuelva más de lo que recibió (físicamente no tiene sentido).

17. Copia de seguridad y Borrado Maestro

Copia de Seguridad (en Inicio): guarda una copia completa del archivo de base de datos con un clic.

Borrado Maestro (en Inicio, "Modo de Prueba"): borra Compras, Ventas y Transferencias desde una fecha elegida en adelante — nunca antes de esa fecha, y nunca el catálogo (Productos, Clientes, Proveedores, Destinos). Pide escribir "BORRAR TODO". Cada documento se borra usando el mismo mecanismo que la anulación individual, así que las reversiones de stock quedan consistentes. Sirve para limpiar datos de prueba antes de operar en serio.

18. Idiomas y moneda

Ledyvas está traducido a español, italiano, inglés, francés y portugués. El idioma se cambia en caliente con las banderas, sin reiniciar. La moneda del negocio se define en Configuración y gobierna todos los montos; la tasa de cambio a dólares (configurable) se usa en los reportes de flota.

19. Asistente de IA

El asistente dentro de la app responde preguntas de uso. Arquitectura:

• La app envía la pregunta (y el historial reciente) junto con su licencia y huella de hardware al servidor de licencias.
• El servidor valida la licencia, aplica un límite de 40 preguntas por día por licencia (red de seguridad de costo), y recién entonces llama al modelo de lenguaje.
• La clave del proveedor de IA nunca está en la app ni en el instalador — vive solo como secret del servidor.
• El asistente responde siempre en el idioma en que se le escribe, entre los 5 idiomas soportados.

20. Reglas de negocio clave

• Comprar ≠ vender. La Compra solo suma stock. El reparto a destinos es independiente.
• Un solo almacén. Centro Logístico. No existe ningún depósito ni "almacén satélite" separado.
• Compra Asistida solo calcula. Nunca genera una compra real.
• Identificadores estables. Todo se referencia por id interno; los nombres se pueden cambiar sin romper nada.
• Todo movimiento de stock queda auditado en el historial, con fecha real del documento (no la de hoy).
• El stock nunca frena la operación (salvo la Devolución de revendedor).
• El conteo físico manda. En Control Diario, el conteo real corrige el teórico y se arrastra como inicial del día siguiente.

21. Preguntas técnicas frecuentes

¿Puedo mover la instalación a otra computadora?

Sí. Copiá la carpeta entera (programa + carpeta Data) y active la licencia en la máquina nueva. La licencia se transfiere sola (la anterior queda desactivada). Como la clave de cifrado deriva de la licencia, la base se abre en la PC nueva.

¿Los datos están en la nube?

No. Todo está en su máquina, en un archivo cifrado. Haga copias de seguridad seguido.

¿Por qué un producto producido valía cero y ahora no?

Producir ahora calcula el costo real del producto terminado (promedio ponderado). Antes había que cargarlo a mano.

¿Por qué la Venta a Restaurantes ahora ofrece Mono Uso?

Los Desechables/Mono Uso se despachan por destino como los Alimentos. Necesitan tener su Valor cargado en la Fórmula (Compra Asistida A) y su costo en Productos.

¿Qué pasa si borro un producto que está en una receta?

Ledyvas le avisa antes de confirmar en cuántas recetas y líneas de Fórmula se usa. Si lo borra, se quita de ahí y esas recetas recalculan su costo. Si el producto tiene compras/ventas reales, no se borra: se desactiva.

Si algo no está cubierto acá

Escriba a info@ledyvas.com.