🔧 Fiados Ferrefacil

En la ferretería, una parte importante de las ventas se hace al fiado: el cliente se lleva el material y paga después. Hasta ahora ese control se llevaba en un cuaderno físico o en hojas sueltas, lo que trae tres problemas concretos:

• No hay forma rápida de saber cuánto debe cada cliente en un momento dado.
• Nadie calcula la mora (los días de atraso) de forma consistente: cada quien lo hace a ojo.
• Si el cuaderno se moja, se pierde o se traspapela, se pierde el registro de la deuda — dinero real que la ferretería deja de cobrar.

Fiados Ferrefacil es una aplicación web con base de datos real donde el encargado del mostrador registra cada fiado con su fecha de vencimiento. El sistema calcula automáticamente cuántos días de mora tiene cada fiado pendiente, sin que nadie tenga que hacer la cuenta a mano, y mantiene el historial de pagos parciales hasta que la deuda queda saldada.

Funciona como aplicación instalable (PWA): se puede agregar a la pantalla de inicio del celular del encargado y la interfaz carga incluso sin internet, aunque registrar un fiado nuevo sí requiere conexión (por diseño, para no arriesgar datos de dinero real en un estado incierto).

La decisión de construir solo esta feature, en vez de reconstruir todo el sistema de inventario y facturación del proyecto anterior, fue intencional: un capstone individual necesita demostrar dominio completo de una pieza real de software (backend, base de datos, pruebas automatizadas, seguridad y despliegue), y eso se logra mejor con un alcance acotado y bien hecho que con un sistema grande a medio terminar.

Un detalle que separa esta app de un simple formulario es el manejo cuidadoso de operaciones repetidas: si el vendedor hace doble clic en "Abonar" por error, o si la conexión falla y el navegador reintenta la petición, el sistema detecta que es la misma operación (usando una clave de idempotencia) y no registra el pago dos veces. Esto importa porque en un negocio real, un bug que duplique un pago o un fiado no es solo un error técnico: es dinero real mal contado.

Arquitectura monolítica simple: un servicio Express sirve tanto la API como el frontend estático, y guarda los datos en PostgreSQL gestionado.

El detalle completo, con diagrama C4 y las decisiones de arquitectura justificadas, está en docs/arquitectura.md y en los ADR del repositorio.

• Backend: Node.js, Express, PostgreSQL (node-postgres)
• Seguridad: Helmet (headers, CSP), bcryptjs (hash de contraseñas), sesiones por cookie httpOnly
• Frontend: HTML, CSS y JavaScript nativo (sin framework)
• PWA: Web App Manifest + Service Worker (cache-first / network-first)
• Tests: Jest + Supertest
• CI/CD: GitHub Actions + SonarCloud
• Autenticación: contraseña local (bcrypt) e inicio de sesión con Google vía Supabase Auth (PKCE en el servidor)
• Hosting: Vercel (funciones serverless, HTTPS automático) + Supabase (PostgreSQL gestionado)

Cada pieza se eligió por simplicidad y por ser suficiente para el problema real, no por moda: no hay ningún framework de frontend porque la interfaz es pequeña y no lo necesita. La base de datos sí es gestionada, y por una razón concreta: el hosting serverless no conserva el sistema de archivos entre invocaciones, así que un SQLite embebido perdía los fiados en cada arranque en frío.

La elección de Supabase como proveedor de PostgreSQL, en vez de administrar un servidor de base de datos propio, responde al mismo criterio de simplicidad que guía el resto del proyecto: como estudiante trabajando solo, no tiene sentido invertir tiempo en tareas de administración de infraestructura (parches de seguridad, backups manuales, monitoreo del servidor) cuando un proveedor gestionado ya resuelve eso de forma confiable y gratuita para un proyecto de este tamaño.

1. Entrá a la URL del producto y esperá la pantalla de inicio de sesión.
2. Iniciá sesión con el usuario demo (demo@ferrefacil.com / Demo2026!).
3. En "Nuevo cliente", escribí el nombre y teléfono, y presioná "Agregar cliente".
4. En "Registrar fiado", elegí el cliente, describí lo que se llevó, el monto y la fecha en que debe pagar.
5. La tabla de "Fiados" muestra el saldo pendiente y, si ya se venció, los días de mora en rojo.
6. Cuando el cliente paga (todo o en parte), presioná "Abonar" en su fiado y escribí el monto pagado.
7. El estado cambia solo: pendiente → parcial → pagado, sin que nadie tenga que calcularlo.

Este producto se construyó a partir de la relación real con Marco Tulio Chávez, dueño de la Ferretería Isaac, en la Col. Asentamientos Humanos de San Pedro Sula. La ferretería fue contactada originalmente en el proyecto de Ingeniería de Software I (trabajo en pareja). Para este capstone, la feature de control de fiados con mora automática se diseñó, desarrolló y desplegó de forma individual, resolviendo un problema que el cliente describió directamente en la entrevista original: llevaba todo en un cuaderno físico, sin control de a quién le debía y desde cuándo, lo que generaba desconfianza y pérdida de dinero real cuando el cuaderno se dañaba o el registro quedaba incompleto.

Nombre: José Roberto Figueroa Hernández
Carrera: Ingeniería en Informática
Curso: Ingeniería de Software II — Capstone

Código de verificación de autoría del proyecto: