1. Problema
En Honduras, muchas personas complementan sus ingresos trayendo cajas de productos desde Estados Unidos y revendiéndolos: maquillaje, cuidado de la piel, herramientas para el cabello, carteras, organizadores. Una misma caja mezcla dos formas de compra. Parte llega en lotes surtidos, que se pagan por un precio total sin saber cuánto costó cada cosa, y parte se compra en tiendas físicas, con recibo. Después se paga el flete, la aduana (en lempiras) y otros gastos.
El problema es que el precio de venta se pone a ojo. Casi nadie reparte el flete, la aduana y el costo del lote entre los productos, así que no hay forma de saber si la caja dejó ganancia. Es fácil vender un producto por debajo de lo que costó traerlo sin enterarse nunca. A eso se suma que el dólar cambia de un mes a otro, que el stock se lleva de memoria y que los fiados, lo que las clientas se llevan y pagan después, se anotan en un cuaderno, donde se pierden los abonos.
2. Solución
Cuenta Clara es una aplicación web progresiva (PWA): se abre con un enlace, se instala en la pantalla de inicio del celular sin pasar por una tienda de aplicaciones y guarda los datos en la nube, protegidos por cuenta.
La idea central es calcular el costo real de cada producto. Se registra lo que costó la caja, cada gasto en la moneda en que se pagó, y el tipo de cambio al que se pagó, que queda fijo con la caja para que los precios no cambien todos los días. Lo comprado en tienda conserva su costo exacto en dólares; lo que llegó en lote se reparte según el valor estimado de cada cosa, siempre anclado a lo que de verdad se pagó por el lote. Encima de eso, cada producto se lleva su parte de los gastos de traer la caja.
Con ese costo, la app sugiere a cuánto vender cada producto para ganar el margen que la emprendedora elija, más un colchón por si el dólar está más caro cuando toque reponer, y avisa en rojo cuando un precio queda por debajo del costo. Además lleva el stock con alertas de reposición y los fiados con sus abonos.
3. Funcionalidades
- Cajas con su costo real: lote, compras en tienda, flete, aduana y otros gastos, cada uno en dólares o lempiras. La app muestra cuánto se invirtió, cuánto encarece traer la mercadería y cuánto falta vender para recuperar la inversión.
- Precio sugerido en vivo: mientras se carga un producto, dice cuánto cuesta de verdad y a cuánto conviene venderlo.
- Aviso de pérdida: los productos con un precio por debajo del costo aparecen marcados, con cuánto se pierde en cada uno.
- Stock con fotos y alertas: cada producto con su foto tomada desde el celular, las unidades que quedan y el aviso cuando hay que reponer.
- Fiados y abonos: quién debe, cuánto, y cada abono, sin poder abonar más de lo que se debe.
- Resumen del negocio: lo que falta cobrar, lo que queda por vender y cuánto se recuperó de cada caja.
- A prueba de cortes de conexión: si la señal se cae justo al guardar, reintentar no duplica la venta ni el abono.
- Portal administrativo: quien administra ve todas las cuentas con sus totales (no su contenido), da o quita el rol de administrador y desactiva o reactiva cuentas.
4. Arquitectura
La aplicación no tiene un servidor propio. El sitio es estático y lo sirve Vercel; los datos, el inicio de sesión y las fotos los maneja Supabase. Toda la seguridad vive en la base de datos: cada tabla tiene políticas de seguridad por fila (RLS), así que cada cuenta ve y cambia solo lo suyo, aunque la aplicación hable directo con la base. Las operaciones que tocan varias filas (vender, anotar un fiado, abonar) son funciones de la base que corren en una sola transacción y no se repiten si se reintentan.
Hay dos roles. Cada negocio usa su propia cuenta y ve solo lo suyo. Los administradores tienen además un portal para ver todas las cuentas y cambiar su rol o su estado; ese portal también pasa por funciones de la base que primero verifican el rol, así que ninguna clave secreta sale de Supabase.
Deslizá el diagrama hacia la izquierda para verlo completo.
El detalle, con los diagramas C4 de contexto y de contenedores, está en el documento de arquitectura, y las dos decisiones principales en sus registros de decisión (ADR): Supabase como backend con la seguridad en RLS y escrituras idempotentes con una clave generada por la app.
5. Tecnologías
| Parte | Tecnología | Por qué |
|---|---|---|
| Frontend | HTML, CSS y JavaScript sin compilación; service worker (PWA) | Se usa desde el celular, se instala sin tienda y abre sin internet para consultar. |
| Backend | Supabase (Auth, API REST y Storage) | Sin servidor propio que mantener ni pagar; el plan gratis alcanza. |
| Base de datos | PostgreSQL con RLS, vistas y funciones | Los datos son relacionales y el costo real se calcula en un solo lugar. |
| Acceso | Correo y contraseña, o Google (OAuth 2.0) | Entrar con la cuenta que ya se usa en el celular. |
| Publicación | Vercel, con dominio propio, HTTPS y headers de seguridad | Cada cambio aprobado se publica solo. |
| CI/CD | GitHub Actions y Deployment Checks de Vercel | Solo llega a producción lo que pasó las pruebas. |
| Calidad | node:test, PGlite, Chrome con Puppeteer, cobertura Istanbul y SonarCloud | Pruebas unitarias, de la base y de la interfaz; 0 bugs y 0 code smells. |
6. Manual de uso paso a paso
- Entrá a la app. Abrí www.melvamateo.site y tocá Iniciar sesión. Podés entrar con tu correo y contraseña o con tu cuenta de Google.
- Instalala en el celular. En el menú del navegador elegí Agregar a la pantalla de inicio. Desde ahí se abre como una aplicación más.
- Registrá una caja. En la pestaña Cajas, tocá Registrar caja y completá el nombre, la fecha de llegada, lo que pagaste por el lote, el flete, la aduana y otros gastos, cada uno con su moneda. Poné el tipo de cambio al que pagaste, la ganancia que querés y el colchón por el dólar.
- Cargá los productos. En Stock, tocá Agregar producto: elegí la caja, escribí el nombre, decí si vino en el lote o de una tienda, el valor en dólares y cuántas unidades llegaron. Si querés, tomale una foto. Mientras escribís el precio, la app te dice cuánto te cuesta y a cuánto venderlo; si el precio queda por debajo del costo, te avisa.
- Vendé. Cuando vendas algo, buscá el producto en Stock y tocá Vender. La app descuenta las unidades y suma la venta a la caja, así sabés cuánto llevás recuperado.
- Anotá los fiados. En Fiados, anotá quién se lleva algo, qué se llevó y cuánto debe. Cuando te pague una parte, tocá Registrar abono: el saldo se actualiza y la app no deja abonar más de lo que se debe.
- Revisá el resumen. En Resumen ves cuánto te deben, cuánto tenés por vender, qué productos se están vendiendo con pérdida, qué hay que reponer y cuánto recuperaste de cada caja.
- Si administrás Cuenta Clara. Con una cuenta administradora, arriba aparece Administración. Ahí ves todas las cuentas y cuántos datos tiene cada una, podés darle o quitarle el rol de administrador a otra cuenta, y desactivar o reactivar cuentas: una cuenta desactivada no ve ni carga datos hasta que la reactives. Nadie puede quitarse su propio rol, así que siempre queda alguien que administra.
- Si te quedás sin señal. Podés abrir la app y consultar lo último que se cargó. Para guardar algo nuevo hace falta conexión; si se cortó justo al guardar, volvé a intentarlo: la app no lo registra dos veces.
Las capturas son de la app real, con los datos de muestra de una caja de ejemplo y, en el portal administrativo, cuentas de ejemplo inventadas: no son datos de ninguna persona.
7. Cliente
Cuenta Clara nació para una emprendedora hondureña que trae cajas desde Estados Unidos con productos de belleza y artículos variados, y los revende en su salón y por redes sociales. Trabaja sola, maneja todo desde el celular y no tiene presupuesto para tecnología. Antes ponía los precios a ojo, llevaba los fiados en un cuaderno y no sabía si cada caja le dejaba ganancia.
Por privacidad, en esta presentación pública no uso su nombre. Lo que ella necesitaba, saber el costo real, poner precios con ganancia y llevar el stock y los fiados, lo comparte cualquier persona que importe y revenda, así que la aplicación quedó general: sirve para cualquier emprendedor con el mismo negocio.
8. Autor
Melva Odany Mateo Santos, estudiante de Ingeniería en Informática. Cuenta Clara es mi proyecto capstone de la clase de Ingeniería de Software I: lo diseñé, lo desarrollé, lo probé y lo publiqué de principio a fin, con Claude como asistente de programación.
Código en GitHub: github.com/MelvaMateo/cuenta-clara · Aplicación en vivo: www.melvamateo.site · Código de verificación: LEARN-CAP-FE4FE1D4