Punto de venta, inventario y caja para una piñatería
Sistema web hecho a la medida para una piñatería real en Bogotá. En producción desde el 14 de octubre de 2026.
- pruebas automáticas
- 1.000+
- endpoints
- 77
- requisitos funcionales
- 75
- pasos en la guía de aceptación
- 114
- Tipo
- Aplicación web progresiva (PWA)
- Cliente
- Una piñatería en Bogotá
- Usuarios
- 3 personas, con roles de administrador, vendedor y propietario
- Desarrollo
- Del 25 de agosto al 25 de octubre de 2026
- En producción
- Desde el 14 de octubre de 2026
Este caso muestra cómo trabajo un problema de punta a punta: entender, diseñar, construir, poner en producción y acompañar. El método no se limita a ventas e inventario.
Contexto
El cliente es una piñatería de Bogotá que vende productos por unidad, por paquete y en anchetas con receta, y que recibe pagos en efectivo, tarjeta, Nequi y Daviplata.
El sistema reúne en un solo lugar la venta, el inventario, las compras, los gastos y la caja, con tres roles de acceso: administrador, vendedor y propietario.
Alcance
| Área | Funciones |
|---|---|
| Venta |
|
| Inventario y compras |
|
| Clientes |
|
| Caja y gastos |
|
| Operación |
|
Decisiones técnicas
| Tema | Decisión |
|---|---|
| Ventas sin conexión | Idempotencia con UUID generado en el cliente, para que un reenvío no duplique la venta. |
| Permisos | Permisos por rol y por dueño, validados en el servidor. |
| Caja abierta | Una sola caja abierta, garantizada con un índice único parcial. |
| Reloj | Un reloj único, now() de PostgreSQL, para las operaciones de caja. |
| Corte de caja | Foto inmutable del corte de caja. |
| Migraciones | Migraciones que no transforman datos, con aprobación manual previa. |
| Datos personales | No se guardan datos de clientes en el navegador. |
| Impresión | El agente de impresión actúa en la medida de lo posible (best-effort) y nunca bloquea una venta. |
Arquitectura
Vista por capas del sistema, de lo que usa el negocio a lo que lo mantiene en marcha.
-
En el negocio
- PWA en celular o computador
- Cola sin conexión en IndexedDB
- Agente local de impresión ESC/POS
-
En el servidor
- Nginx
- API FastAPI
- Celery y Redis
- PostgreSQL 15
-
Operación
- Docker Compose
- Cloudflare Tunnel
- Uptime Kuma
- Respaldos diarios automáticos
- GitHub Actions
Resultado
El sistema está en producción desde el 14 de octubre de 2026 y lo usan tres personas, cada una con su rol.
Se entrega con respaldos diarios automáticos, monitoreo y despliegue continuo con aprobación manual de las migraciones.
Tecnología
| Capa | Tecnologías |
|---|---|
| Backend | Python, FastAPI, SQLAlchemy 2, Alembic, JWT por roles |
| Datos y tareas | PostgreSQL 15, Celery, Redis |
| Frontend | React 18, Vite, Tailwind v4, PWA |
| Infraestructura | Docker Compose, Nginx, Cloudflare Tunnel, Uptime Kuma |
| CI/CD | GitHub Actions con runner propio y aprobación manual de migraciones |
| Respaldos | Diarios y automáticos |
| Pruebas | pytest y vitest |
Cifras verificadas
| Medida | Valor |
|---|---|
| Pruebas automáticas | Más de 1.000 (580+ backend, ~400 frontend, 45 del agente) |
| Endpoints | 77 |
| Modelos de datos | 20 |
| Migraciones | 9 |
| Componentes de interfaz | 42 |
| Requisitos funcionales | 75 |
| Historias de usuario | 13 |
| Documentos técnicos | 12 |
| Guía de aceptación | 114 pasos |
| Tablero de trabajo | 148 tarjetas |
Autoría y uso de IA
El sistema se desarrolló con asistencia de IA (Claude Code). Los requisitos, la arquitectura, las pruebas y la validación con el cliente están a cargo de Santiago Chávez López.
Cotiza tu problema
Cuéntame qué necesita tu negocio. Te respondo con una propuesta y una cotización.