From 6859b89262738b918dc3be9f1dfec18356f65b57 Mon Sep 17 00:00:00 2001 From: Valentin Romero Date: Tue, 30 Jun 2026 22:04:13 -0300 Subject: [PATCH] first commit --- .gitignore | 1 + README.md | 554 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 555 insertions(+) create mode 100644 .gitignore create mode 100644 README.md diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..2eea525 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.env \ No newline at end of file diff --git a/README.md b/README.md new file mode 100644 index 0000000..17e7984 --- /dev/null +++ b/README.md @@ -0,0 +1,554 @@ +# Urban Dance + +Urban Dance es un sistema de gestión para academias de baile que centraliza alumnos, clases, asistencias, facturación y pagos, integrando una experiencia simple para alumnos mediante WhatsApp y RFID. + +El proyecto está compuesto por un backend desarrollado con **NestJS**, un frontend desarrollado con **NextJS** y una base de datos **PostgreSQL**. +La estructura está pensada para permitir tanto un despliegue completo mediante `docker-compose`, como la ejecución individual de cada servicio en modo desarrollo. + +--- + +## Descripción funcional del sistema + +El sistema está pensado para la administración integral de alumnos en una academia de baile. + +Su filosofía principal es mantener una experiencia simple para el usuario final. El alumno no necesita acceder a una aplicación web ni gestionar credenciales tradicionales, sino que interactúa con el sistema a través de un bot de WhatsApp. + +Desde el bot, el alumno puede: + +* Consultar las clases en las que se encuentra inscripto. +* Inscribirse a nuevas clases disponibles. +* Consultar facturas generadas. +* Obtener links de pago. +* Ver el estado de su deuda. +* Gestionar su asistencia mediante un llavero RFID entregado por la academia. + +El sistema prioriza la confianza y la identificación unívoca del alumno bajo el criterio: + +```text +1 usuario = 1 número telefónico +``` + +Esto permite centralizar la comunicación, autenticación y operación del alumno desde WhatsApp. + +--- + +## Roles del sistema + +El sistema contempla los siguientes roles principales: + +* Alumno +* Profesor +* Administrador +* Administrador global + +Los alumnos interactúan con el sistema únicamente mediante el bot de WhatsApp y el llavero RFID. +Los usuarios administrativos acceden a la aplicación web mediante un link generado desde el bot de WhatsApp. + +--- + +## Usuarios administrativos + +Los usuarios administrativos, como profesores y administradores, cuentan con acceso a la aplicación web. + +El acceso a la web se realiza desde el bot de WhatsApp mediante un token único de sesión y usuario. Este token permite identificar al usuario que está ingresando y transportar la información necesaria para operar dentro del sistema web. + +Desde la aplicación web, los usuarios administrativos pueden gestionar: + +* Asistencias. +* Alta, baja y modificación de clases. +* Alta, baja y modificación de usuarios. +* Generación de facturas. +* Gestión de pagos. +* Administración general del sistema. + +--- + +## Autenticación web + +El sistema utiliza tokens únicos de sesión para permitir el acceso web de usuarios administrativos. + +El flujo de autenticación es el siguiente: + +1. El usuario administrativo solicita acceso desde el bot de WhatsApp. +2. El bot genera un token único. +3. El bot envía un link al frontend con ese token. +4. El frontend verifica el token contra el endpoint `/auth/verify`. +5. Si el token es válido, se inicia la sesión web. + +Características del token: + +* Tiene vencimiento de 30 minutos. +* Es de un solo uso. +* Se envía al frontend mediante query param. +* Se almacena en memoria y cookie durante la sesión. + +Endpoint relacionado: + +```http +GET http://localhost:3001/auth/verify +``` + +Este endpoint público se utiliza para verificar el token de inicio de sesión. + +--- + +## Gestión de clases + +El sistema permite administrar clases con distintas modalidades. + +Las clases pueden ser: + +### Clases puntuales + +Clases creadas para una fecha específica, por ejemplo: + +```text +Clase especial de salsa - Viernes 10/05 de 19:00 a 21:00 +``` + +### Clases recurrentes + +Clases que se repiten en el tiempo bajo una regla definida, por ejemplo: + +```text +Todos los lunes de 18:00 a 20:00 durante 6 meses +``` + +Esta funcionalidad permite contemplar la lógica habitual de una academia de baile, donde existen cursos regulares, clases especiales, talleres y eventos puntuales. + +--- + +## Asistencia mediante RFID + +A cada alumno se le entrega un llavero RFID que permite registrar su asistencia a clases. + +Este mecanismo simplifica el control de presencia y evita que el alumno tenga que realizar acciones manuales desde una aplicación web. + +El sistema permite asociar cada llavero RFID a un usuario determinado y registrar sus ingresos o asistencias dentro de las clases correspondientes. + +Además, una vez inicializado el sistema, se permite un flujo de registro de usuario a través de un nuevo llavero RFID, simplificando el alta de nuevos alumnos. + +--- + +## Integración RFID con ESP32 + +El proyecto cuenta con un sketch disponible en: + +```bash +/bot-wsp/sketchesp32.txt +``` + +Este sketch está pensado para desplegarse en un **ESP32** con lector RFID. + +El código contempla: + +* Portal cautivo para configuración inicial. +* Configuración de acceso a red WiFi. +* Configuración de la URL del backend. +* Envío de información del llavero RFID al backend. +* Vinculación del llavero con un usuario. +* Registro de asistencia si el llavero ya está registrado. +* Inicio de flujo de registro si el llavero aún no está asociado a un usuario. + +Endpoint utilizado por el dispositivo: + +```http +POST http://localhost:3001/rfid/ping +``` + +Este endpoint recibe la información enviada por el lector RFID y permite resolver si corresponde registrar asistencia o iniciar un flujo de vinculación con un usuario. + +### Requisitos de hardware + +Para utilizar la funcionalidad RFID se requiere: + +* ESP32. +* Lector RFID compatible. +* Llavero RFID. +* Adaptador USB a micro USB. +* Fuente 5V 1A. +* Red WiFi disponible. + +--- + +## Facturación y pagos + +El sistema contempla integración con: + +* Mercado Pago, para generación de links de pago. +* Odoo, para facturación electrónica. + +Desde el sistema se pueden generar facturas, consultar estados de deuda y obtener links de pago para que el alumno pueda operar desde WhatsApp. + +--- + +## Flujo inicial del sistema + +El backend cuenta con endpoints públicos para iniciar la configuración del sistema y obtener tokens de acceso. + +### Obtener token inicial + +```http +GET http://localhost:3001/auth/getToken +``` + +Este endpoint permite obtener un token de acceso. + +En caso de no existir usuarios registrados en el sistema, se crea automáticamente un usuario administrador global y se retorna un token de login para dicho usuario. + +Este flujo permite realizar la primera configuración del sistema luego del despliegue inicial. + +--- + +### Inicializar sistema + +```http +GET http://localhost:3001/auth/init +``` + +Este endpoint retorna y redirige a la primera URL pública del frontend para realizar la configuración inicial del sistema. + +Se recomienda registrar en primer lugar un usuario de tipo administrador con un número de teléfono válido. + +El número debe ingresarse con el siguiente criterio: + +```text +Código de área + número, sin el prefijo 15 +``` + +Ejemplo: + +```text +343XXXXXXX +``` + +Este número será utilizado posteriormente para el inicio de sesión y la vinculación con el bot de WhatsApp. + +--- + +## Estructura del proyecto + +```bash +/ +├── bot-wsp/ # Backend NestJS +├── front-urban/ # Frontend NextJS +├── .env # Variables de entorno generales +└── docker-compose.yml # Compose principal para despliegue completo +``` + +--- + +## Servicios principales + +El proyecto cuenta con los siguientes servicios principales: + +| Servicio | Tecnología | Puerto | +| ---------------------- | ---------- | ------ | +| Base de datos | PostgreSQL | `5431` | +| Backend API | NestJS | `3001` | +| Servicio QR / WhatsApp | Backend | `3008` | +| Frontend | NextJS | `3000` | + +El archivo `docker-compose.yml` define los servicios necesarios junto con sus respectivos `Dockerfile`, permitiendo un despliegue rápido con variables de entorno configurables para ambientes de desarrollo o producción. + +--- + +## Despliegue en producción con Docker Compose + +Desde la raíz del proyecto, completar correctamente las variables de entorno en el archivo `.env`. + +Luego ejecutar: + +```bash +docker compose build +docker compose up -d +``` + +Este comando construye y levanta los servicios principales: + +* PostgreSQL +* Backend NestJS +* Servicio QR / WhatsApp +* Frontend NextJS +* Odoo ERP + +Verificar que los puertos requeridos estén disponibles antes de iniciar el despliegue. + +--- + +# Backend - NestJS + +Ubicación: + +```bash +/bot-wsp +``` + +Versión utilizada: + +```bash +NestJS v10.3.0 +``` + +## Requisitos + +Se requiere contar con una versión mínima de Node: + +```bash +Node v20.20.2 +``` + +Antes de iniciar el backend, revisar las variables de entorno. +Se puede tomar como referencia el archivo: + +```bash +.env.example +``` + +Es muy importante contar con la variable: + +```bash +DATABASE_URL +``` + +El schema de la base de datos se encuentra en: + +```bash +/bot-wsp/prisma/schema.prisma +``` + +--- + +## Base de datos para desarrollo + +Dentro de `/bot-wsp` se cuenta con un `docker-compose.yml` propio para levantar una instancia de PostgreSQL y utilizarla como base de datos local. + +Desde la carpeta del backend: + +```bash +cd bot-wsp +``` + +Levantar PostgreSQL: + +```bash +docker compose up -d +``` + +--- + +## Iniciar backend en modo desarrollo + +Desde la carpeta `/bot-wsp`, ejecutar: + +```bash +npm i +npm run build +npm run generar +npm run start:dev +``` + +En caso de iniciar correctamente, el backend levantará un controller `GET` disponible en: + +```bash +http://localhost:3008 +``` + +Este endpoint retorna un código QR para realizar la vinculación con WhatsApp Web. + +También se puede encontrar el QR generado en: + +```bash +/bot-wsp/bot.qr.png +``` + +--- + +## Vinculación de WhatsApp + +Luego de escanear el código QR y completar la vinculación, se recomienda utilizar **WhatsApp Business**. + +Si la conexión fue exitosa, en consola se visualizará un log similar a: + +```bash +LOG [WhatsappService] ✅ WhatsApp conectado exitosamente! +``` + +--- + +# Frontend - NextJS + +Ubicación: + +```bash +/front-urban +``` + +Versión utilizada: + +```bash +NextJS v14.2.30 +``` + +## Variables de entorno + +El frontend cuenta con un archivo de ejemplo: + +```bash +.env.example +``` + +Antes de iniciar el servicio, revisar y completar las variables de entorno necesarias. + +--- + +## Iniciar frontend en modo desarrollo + +Desde la carpeta `/front-urban`, ejecutar: + +```bash +npm i +npm run build +npm run dev +``` + +El servicio queda disponible en: + +```bash +http://localhost:3000 +``` + +--- + +# Odoo ERP + +Ubicación: + +```bash +./ +``` + +Versión utilizada: + +```bash +Odoo 18.0 CE +``` + +## Variables de entorno + +El Odoo cuenta con un archivo .env para su configuracion de despliegue en el docker-compose: + +```bash +.env +``` + +Antes de iniciar el servicio, revisar y completar las variables de entorno necesarias. + +## Despliegue y configuracion del entorno Odoo ERP: + +### Crear la base: +1) localhost:8069/web/database/manager. +2) Completá: nombre de la base, email y contraseña del admin. +3) Elegí el idioma Español (AR). +4) País: Argentina (esto activa sugerencias de localización más adelante). +5) Presionar boton Crear instancia + +### Configurar la localización argentina +1) En aplicaciones instalar la aplicacion l10n_ar +2) Configurá los datos fiscales de tu compañía: Ajustes → Empresas → tu compañía → completá CUIT, condición ante IVA, y los puntos de venta (Responsable Inscripto, Monotributo, etc.). +3) Si vas a facturar electrónicamente, necesitás cargar el certificado AFIP en Contabilidad → Configuración → Diarios (configuración del punto de venta electrónico). + +### Instalar aplicacion de Mercado Pago +1) En aplicaciones, buscá "Mercado Pago" e instalarlo. +2) En Ajustes → Sitio Web → Pagos (o Contabilidad/Ventas → Configuración → Proveedores de pago). Abrí "Mercado Pago", poné tus credenciales (Access Token y Public Key, que sacás desde tu cuenta de desarrollador de Mercado Pago). +3) Activalo (pasarlo de "Deshabilitado" a "Habilitado" o "Modo prueba" primero para testear). + +### Configuracion de API +1) En aplicaciones instalar la aplicacion account_api +2) Ingresa a "Ajustes -> Tecnico -> Parametros del sistema", buscar el registro "account.api.invoice.state.webhook" y proceder a establecer en el valor la URL del frontend. Su data de ejm actual es: https://libraries-exclusive-vernon-device.trycloudflare.com/odoo/webhook + + +--- + +# Resumen rápido + +## Levantar todo el proyecto en producción + +Desde la raíz: + +```bash +docker compose build +docker compose up -d +``` + +## Levantar backend en desarrollo + +```bash +cd bot-wsp +docker compose up -d +npm i +npm run build +npm run generar +npm run start:dev +``` + +## Levantar frontend en desarrollo + +```bash +cd front-urban +npm i +npm run build +npm run dev +``` + +--- + +## Comandos útiles con Docker + +Ver contenedores activos: + +```bash +docker compose ps +``` + +Ver logs de todos los servicios: + +```bash +docker compose logs -f +``` + +Ver logs del backend: + +```bash +docker compose logs -f backend +``` + +Ver logs del frontend: + +```bash +docker compose logs -f frontend +``` + +Reiniciar servicios: + +```bash +docker compose restart +``` + +Detener servicios: + +```bash +docker compose down +``` + +--- + +## Notas importantes + +* Revisar siempre las variables de entorno antes de iniciar los servicios. +* El backend requiere una variable `DATABASE_URL` válida. +* El proyecto completo debe construirse y levantarse desde el `docker-compose.yml` principal. +* Para desarrollo local del backend, `/bot-wsp` incluye su propio `docker-compose.yml` para levantar PostgreSQL. +* La vinculación de WhatsApp se realiza mediante el código QR generado por el backend. +* El servicio expuesto en el puerto `3008` corresponde a un servicio dentro del ámbito backend utilizado para la vinculación de WhatsApp. +* La integración RFID requiere un ESP32 configurado con WiFi y con la URL del backend correctamente establecida.