Saltar al contenido
Punto de venta e inventario de escritorio← Todos los proyectos

Kairos

Un comercio llevaba ventas, stock, caja y fiado en procesos manuales y planillas sueltas, sin control por rol ni trazabilidad. Construí un sistema POS que corre en la PC del local, sin depender de internet, y reúne ventas, inventario con kardex, arqueo de caja, créditos a clientes y reportes en una sola herramienta que se instala como app de Windows.

Sistema de punto de venta e inventario para un local físico. Funciona en local y sin conexión, con backend Flask organizado en capas (routes, services, repositories), base SQLite con migraciones versionadas y distribución como ejecutable de escritorio con instalador, backups automáticos y clave de seguridad propia en cada instalación.

PropósitoProyecto estrella: software en producción para un negocio real, desde el modelado del dominio hasta el instalador.
Resultado claveUnifica en un solo sistema ventas, inventario, arqueo de caja, cuentas por cobrar y reportes, que antes vivían en procesos separados.
Stack
PythonFlaskSQLAlchemyAlembicSQLiteChart.jsPyInstallerpytest
(01)Problema

Llevar la operación diaria a un sistema confiable que funcione sin internet.

El negocio necesitaba registrar ventas rápido, controlar stock y caja, y dar seguimiento al fiado de clientes, todo en una PC común del mostrador y sin servidores externos.

  1. Ventas, stock y caja se llevaban por separado, sin una fuente única de verdad ni historial de movimientos.
  2. El cierre de caja por turno era manual y propenso a errores (efectivo, transferencias por banco, diferencias).
  3. Las ventas a crédito y los pagos parciales de clientes no tenían seguimiento formal.
  4. Hacía falta restringir acciones sensibles por rol sin frenar la operación en el mostrador.
(02)Solución

Un POS modular, instalable y pensado para el uso real del mostrador.

Una aplicación Flask que corre en local y se abre en el navegador, con módulos independientes para cada área del negocio y un empaquetado que la hace instalable y actualizable como cualquier programa de Windows.

  1. Ventas por código de barras o búsqueda, pago en efectivo o transferencia por banco, descuentos por ítem y total en letras (guaraníes).
  2. Inventario con niveles de stock, kardex por producto y carga masiva de stock.
  3. Arqueo de caja con apertura y cierre por turno, movimientos de entrada y salida, conteo por denominación, cálculo automático de diferencias y reporte PDF.
  4. Créditos a clientes con cuentas por cobrar y registro de pagos parciales.
  5. Dashboard con estadísticas diarias y generales, comparación con el período anterior, gráficos de tendencia, productos más vendidos y exportación a CSV y Excel.
(03)Arquitectura

Capas bien separadas dentro de un monolito liviano y portable.

La lógica sensible del negocio está aislada de las vistas y del acceso a datos, así el sistema crece por módulos y se testea sin levantar la interfaz.

Presentación

Plantillas Jinja2 con macros reutilizables, Bootstrap 5, un design system propio en CSS y módulos JS vanilla por pantalla (tablas paginadas por AJAX, gráficos con Chart.js).

Rutas y seguridad

Blueprints por área (ventas, productos, inventario, arqueo, créditos, registros y admin), con autorización por rol, CSRF y rate limiting.

Servicios

Reglas de negocio y validaciones: cálculo de ventas y descuentos, cierre de caja, pagos de crédito, reportes y generación de PDF.

Repositorios y persistencia

Acceso a datos con SQLAlchemy sobre SQLite, índices de rendimiento, migraciones Alembic y backups automáticos de la base.

Distribución

Ejecutable PyInstaller con icono en la bandeja del sistema, instancia única, puerto libre automático e instalador NSIS versionado.

Fig. 01Una venta, de la ruta a la base
Recorrido de una venta por las capas de KairosLa ruta exige sesión, token CSRF y una caja abierta; el servicio valida el formulario; el repositorio, dentro de una transacción, bloquea los productos, guarda la venta con sus líneas, descuenta el stock a través del kardex y, si es a crédito, crea la deuda del cliente. Si algo falla se hace rollback; si no, commit, y recién después se registra el movimiento de caja.Rutaventas_routes.pyServicioventas_service.pyRepositoriorepositories/venta.pySQLiteSQLAlchemy · AlembicTransacciónsi algo falladespués del commitSesión + CSRFlogin_required¿Caja abierta?si no, no vendeValidar datospago y cantidadBloquear filasen orden por idVenta y líneascon descuentosKardexsalida por líneaDeuda clientesolo a créditoRollbackno queda nadaCommittodo o nadaCajasegún el pago

Antes de tocar datos, la venta pasa dos controles: sesión con CSRF y una caja abierta. Después, todo ocurre en una sola transacción: los productos se bloquean en orden de id (así dos cajas no se esperan entre sí), el stock solo se mueve con un asiento de kardex y, si cualquier paso falla, no queda nada a medias.

Camino de la ventaCondicionalTransacción
(04)Stack y decisiones

Elegí el stack para una operación local y offline: Flask y SQLite no necesitan infraestructura, se empaquetan en un solo ejecutable y permiten avanzar rápido sobre el dominio. La suite de tests y la CI mantienen el sistema estable mientras se agregan módulos.

PythonFlaskSQLAlchemyAlembicSQLiteChart.jsPyInstallerpytest
  1. Arquitectura en capas (routes → services → repositories) para que las reglas de negocio no dependan de las vistas y puedan testearse aisladas.
  2. Enfoque local y sin conexión: Flask + SQLite empaquetados con PyInstaller, con icono en la bandeja del sistema, una sola instancia por PC y datos persistentes en %APPDATA% entre actualizaciones.
  3. Frontend sin framework ni build step: módulos JS desacoplados que se comunican por eventos (búsqueda → tabla → resumen) para mantener ágil el flujo de venta con lector de código de barras.
  4. Integridad de datos con kardex de movimientos por producto y migraciones Alembic versionadas para cambiar el esquema sin perder datos.
  5. Seguridad adaptada a la app local: roles y autenticación, protección CSRF, rate limiting en el login y una SECRET_KEY única que se genera en cada instalación.
(05)Resultados
Suite de tests
277pytest
01

Unifica en un solo sistema ventas, inventario, arqueo de caja, cuentas por cobrar y reportes, que antes vivían en procesos separados.

02

277 tests automatizados con pytest que cubren flujos completos (ventas, créditos, arqueo, kardex, migraciones), ejecutados en CI con GitHub Actions sobre Python 3.9, 3.10 y 3.11.

03

Distribución lista para el usuario final: un instalador NSIS con versionado, backups automáticos al iniciar y actualización sin tocar los datos.

(06)Siguiente paso

¿Hablamos sobre una oportunidad similar?