Nebluna Inventario y Ventas
Sistema de inventario y ventas para una microtostadora de café de especialidad en Ciudad de México. Cubre el ciclo completo: café verde, tueste, granel, empaque, venta, envío y reportes. Next.js 16 y TypeScript sobre Supabase.
Aplicación de operación multi-rol sobre PostgreSQL, donde las reglas de negocio se imponen en la base de datos y no en los formularios: constraints y triggers impiden el stock negativo, cada venta referencia un lote concreto y la merma de tueste se mide por batch. 99 migraciones versionadas, Row Level Security en todas las tablas y un CI que reconstruye la base desde cero en cada pull request.
Galería
Descripción del Proyecto
Nebluna es el sistema de inventario y ventas de una microtostadora de café de especialidad en Ciudad de México. Cubre el ciclo completo del producto: entrada de café verde, tueste, inventario a granel, empaque, venta por cuatro canales, envío y reportes. Está construido con Next.js 16 (App Router) y TypeScript sobre Supabase, y sustituye a la hoja de cálculo con la que operaba el negocio.
Implementación Técnica
Modelo de Datos e Integridad
99 migraciones versionadas definen el esquema en PostgreSQL. Las reglas de negocio se imponen en la base y no en los formularios: constraints y triggers impiden que el stock quede en negativo, cada venta referencia una fila concreta de inventario empacado, y una mezcla descuenta de sus lotes de origen por una sola vía canónica. Las fechas de negocio se guardan como DATE y no como TIMESTAMPTZ, y las relaciones van siempre por clave foránea, nunca por coincidencia de texto.
Roles y Seguridad
Dos roles con productos distintos: administración ve finanzas, costos y ajustes; cada promotor ve el catálogo, sus propias ventas y sus propias comisiones, y nada de lo que corresponde a los demás. La separación la imponen políticas de Row Level Security en cada tabla, así que se sostiene aunque falle un guard de ruta.
Interfaz
React Query para el estado de servidor, react-hook-form con Zod para los formularios, y shadcn/ui sobre Tailwind CSS 4. Tres grupos de rutas: autenticación, dashboard, y un grupo de impresión que genera el ticket de venta en tamaño carta con su propia hoja de estilos. Mobile first, con las pantallas densas, reportes y conciliación, pensadas para escritorio.
Pruebas y CI
86 tests unitarios y 9 suites de integración que cubren políticas de RLS, ciclo de venta, comisiones, re-empaque, conciliación de inventario, manejo de fechas y stock por SKU. Cuatro workflows de GitHub Actions: lint bloqueante a cero errores, integración contra un stack de Supabase levantado desde cero en el runner, auditoría de Lighthouse en cada despliegue a producción, y un guardia que compara las migraciones contra el registro remoto.
Funcionalidades
- Ventas: alta guiada en cuatro pasos, cuatro canales (directo, promotor, WhatsApp e Instagram), precios de menudeo y mayoreo, cálculo de envío y ticket imprimible.
- Inventario: stock empacado y a granel desglosado por lote, con indicador de frescura a 60 días y asignación de bolsas a promotores.
- Producción: registro de tuestes con kg verde, kg tostado, merma y costo por kilo calculado, más mezclas construidas a partir de varios lotes de origen.
- Comisiones: tasa sobre subtotal, solo en el canal promotor, con historial de liquidaciones por periodo.
- Conciliación: conteo físico de inventario y solicitudes de conteo a promotores.
- Reportes: por canal, producto, cliente, frescura, rentabilidad, cobranza, precios y promotores.
El Reto
- El stock no puede quedar en negativo, y una hoja de cálculo no tiene forma de impedirlo
- El tueste pierde entre el 12 y el 20% del peso verde, así que el costo por kilo depende de medir la merma en cada lote
- Administración y promotores comparten los mismos datos con necesidades opuestas: unos trabajan con costos y márgenes, los otros no deben verlos, ni entre ellos
- Aplicar 99 migraciones sobre una base ya en uso sin que los archivos y el registro remoto se desincronicen
El Enfoque
- Constraints y triggers en PostgreSQL: la base rechaza la escritura en vez de que la valide el formulario
- La merma se registra por tueste como peso verde menos peso tostado, y el costo por kilo se calcula a partir de ahí
- Row Level Security en todas las tablas, con el permiso aplicado en la base y no en la interfaz
- Un único camino documentado para aplicar migraciones, con un guardia automatizado que compara los archivos contra el registro remoto
Resultados
- 99 migraciones versionadas y un guardia de deriva que corre en CI
- 86 tests unitarios y 9 suites de integración contra una base efímera construida desde cero en cada pull request
- Gates de Lighthouse en cada despliegue a producción: accesibilidad y buenas prácticas en 0.95, rendimiento en 0.60
- Página de login reducida de 6,2 MB a unos 760 KB autohospedando la fuente de iconos y optimizando los logos
Impacto
Trazabilidad por lote, costo real por kilo con la merma incluida y comisiones calculadas por el sistema, en lugar de reconstruirse a mano sobre una hoja de cálculo.
Detalles del Proyecto
Objetivo
Llevar la operación de una hoja de cálculo a un sistema donde las reglas del negocio las imponga la base de datos, y donde el equipo de venta trabaje con el catálogo y sus propias comisiones sin acceso a los datos financieros.
Tema
Software de operación e inventario para producción de café de especialidad.
Fecha
20 de agosto de 2026