~/diego-viscarra
$ man tienda-colonial.md
~/proyectos/tienda-colonial/case-study.md
Retail ERP / Transactional POS / Financial Ledger
Full Stack Engineer & Software Architect

Tienda Colonial — ERP & POS Transaccional

Sistema de Punto de Venta con motor FIFO estricto, modelo contable origen → destino y modo contingencia offline.

CLIENTETienda Familiar de Abarrotes (El Salvador)
TIEMPO2025 — En Producción
ESTADODesplegado en producción local & Docker
// Métricas & Invariantes Clave
FIFO Estricto
Trazabilidad por lotes
Costo unitario congelado por venta para cálculo de utilidad bruta sin sesgos
FOR UPDATE
Bloqueo pesimista
Transacciones ACID protegidas contra concurrencia y sobreventa de stock
3 Rutas
Clasificación de retiros
Separación contable estricta entre Gasto Operativo, Bóveda y Devolución
Offline Ready
Modo contingencia
Operación ininterrumpida ante fallas eléctricas o caídas de internet
$cat pantallas_clave.preview
[5 PANTALLAS DOCUMENTADAS]
tienda ~ GET /dashboard/pos
Caché + BarcodeGET /dashboard/pos
Punto de Venta (POS) Operativo
Clic para pantalla completa ⤢

Cuadrícula de productos con lector de códigos de barra, carrito reactivo, atajos de teclado y cálculo inmediato de cambio.

⚠Aviso: Los datos, cifras y registros mostrados son ficticios y corresponden a pruebas simuladas (mock data); no pertenecen a la empresa ni exponen información real.
// Contexto de Negocio & El Reto Real

Diseñado para una tienda de abarrotes de alta rotación en El Salvador con ventas 100% en efectivo, compras por fardo y venta fraccionada, operando bajo fallas eléctricas recurrentes. La dueña no sabía si ganaba o perdía dinero por la fluctuación constante de precios de proveedores.

⚠Distorsión de margen por costo promedio

Comprar un fardo a $12 y al mes siguiente a $14 hacía que calcular márgenes sobre promedios mostrara ganancias ficticias.

⚠Caos en la 'sangría' de caja

Sacar dinero para pagar el pan, guardar en la caja fuerte o gastos personales se registraba como un egreso plano, destruyendo el cálculo contable.

⚠Cortes de turno descuadrados

Diferencias por cambio mal dado o pérdidas no se auditaban sistemáticamente contra el saldo real esperado.

⚠Cortes de energía eléctrica

La tienda no podía detener ventas durante apagones; requería un POS táctil resiliente que no perdiera tickets en cola.

// Decisiones de Arquitectura e Ingeniería

Motor de Inventario FIFO con Bloqueo Pesimista

Consistencia de Datos

Cada compra ingresa como un lote con fecha y costo. Al vender, se descuenta de los lotes más antiguos y se congela el COGS exacto.

  • ›Consultas `SELECT ... FOR UPDATE` para serializar transacciones en lotes activos.
  • ›Cálculo del P&L basado en el costo histórico real del lote vendido.
  • ›Soporte para fraccionamiento de unidades (caja a unidades individuales) sin duplicar ítems.

Modelo Financiero Origen → Destino

Partida Doble Simplificada

Se eliminaron las tablas de saldo estático en caja; todo saldo se deriva del libro mayor de transacciones.

  • ›Catálogo cerrado de cuentas: GAVETA, BOVEDA, DUEÑOS, GASTO, PROVEEDOR.
  • ›Retiros clasificados obligatoriamente en 3 vías contables.
  • ›Conciliación de arqueo con margen de tolerancia inteligente configurada.
// Desglose del Catálogo de Pantallas
01.Punto de Venta (POS) Operativo

Cuadrícula de productos con lector de códigos de barra, carrito reactivo, atajos de teclado y cálculo inmediato de cambio.

GET /dashboard/pos[01-pos-operativo.png]
02.Modal 'Sacar Dinero' (Decisión de Negocio)

Separación contable estricta entre Gasto Operativo (proveedor/factura), Traslado a Bóveda (caja fuerte) o Retiro de Dueños.

POST /caja/retiro[02-modal-sacar-dinero.png]
03.Dashboard Financiero y Estado de Resultados (P&L)

Métricas de ingresos, costo de mercancía vendida calculado con capas FIFO reales, margen bruto y desglose por categorías.

GET /dashboard/stats[03-dashboard-pl.png]
04.Gestor de Inventario con Trazabilidad por Lotes

Vista de capas de stock con fecha de vencimiento, alertas preventivas y desglose de costo unitario por cada lote registrado.

GET /dashboard/inventario[04-inventario-fifo.png]
05.Corte de Caja (Cierre Z) con Reconciliación

Comparativa entre saldo esperado por sistema vs efectivo contado, tolerancia automática y registro en libro contable inmutable.

POST /dashboard/caja/cierre-z[05-cierre-caja-z.png]
// Ficha Técnica Completa
BACKEND
• NestJS 11
• TypeScript
• Prisma 7 (@prisma/adapter-pg)
• PostgreSQL
• Passport + JWT
FRONTEND
• Next.js 16 (App Router)
• React 19
• Tailwind CSS
• Zustand
• Recharts
• shadcn/ui
BASE DE DATOS
• PostgreSQL (Supabase / Docker)
• Bloqueo pesimista FOR UPDATE
• pg_advisory_xact_lock