Integração Arica — portal del alumno — Caso
Portal completo para el dojo de jiu-jitsu Integração Arica: asistencia con QR dinámico, progreso de cinturón en vivo y pagos con comprobante.
Por Ricardo Huiscaleo — 04 oct 2026 · 5 min ── deporte · arica ──
── el desafío ──
El dojo manejaba la asistencia en papel, con riesgo de marcaje fraudulento (un alumno marcando por otro) y el progreso de cinturón calculado a mano al final de cada mes. Los pagos llegaban por transferencia sin trazabilidad y el profesor pasaba horas consolidando todo antes de cada graduación.
── lo que construimos ──
Construimos un portal del alumno con asistencia por QR dinámico TOTP —tokens SHA-256 que rotan cada 60 segundos, imposibles de compartir—, progreso de cinturón calculado en tiempo real por WebSocket (cada clase suma y el alumno lo ve al instante), pagos con subida de comprobante y graduación automatizada según el total de clases.
- ✓ QR dinámico TOTP (SHA-256, rotación 60s)
- ✓ Progreso realtime por WebSocket
- ✓ Graduación automatizada
- ✓ Pagos con comprobante
- ✓ Notificaciones automáticas
── ingeniería ──
Los obstáculos técnicos reales del proyecto y cómo los resolvimos.
- 01
Asistencia imposible de falsificar
El problema no era registrar la asistencia, sino que un alumno marcara por otro. Diseñamos un QR dinámico que rota cada 60 segundos: el token se genera con la firma del servidor, la ventana de tiempo y el tenant, y solo vive unos minutos. Compartir una captura de pantalla no sirve —el token ya expiró—, y el escaneo valida la ventana antes de registrar.
- 02
Un sistema heredado con conteos inconsistentes
El progreso de cinturón dependía de un ajuste manual que podía congelar las clases y ocultar asistencias reales. Cambiamos la regla a un piso aditivo: el ajuste manual nunca esconde lo registrado en vivo, el total siempre refleja lo máximo entre lo manual y lo real, y cada edición queda auditada con usuario, IP y diferencia. Además agregamos un comando de salud que detecta alumnos con conteo congelado.
- 03
Progreso y asistencia en vivo sin recargar
El alumno quería ver su cinturón y sus clases sumar al instante. Conectamos los eventos del backend a un canal en tiempo real (WebSocket), de modo que cada asistencia marcada actualiza la vista del alumno y del profesor sin refrescar la página.
- 04
Graduación que ya no depende de cuentas a mano
Antes el profesor sumaba clases a mano antes de cada graduación. El sistema ahora calcula la elegibilidad desde el total real de clases y dispara la promoción cuando corresponde, eliminando el error del conteo manual en papel.
- 05
Pagos sin trazabilidad
Las transferencias llegaban sin comprobante y el estado de cuenta era difuso. Incorporamos subida de comprobante y un flujo de estados claro (pendiente, confirmado, pagado, liquidado) para que la deuda de cada alumno fuera consultable y no dependiera de la memoria del dojo.
── devops ──
Infraestructura, despliegue y operación del sistema.
- 01
Dominio propio y subdominio de academia
El portal vive en integracaoarica.com, con un subdominio de marca (bjj.) para el acceso de alumnos, además de una URL interna de administración. Cada superficie declara su propio contenido y sus sitemaps para no mezclarse con la plataforma base.
- 02
CORS estricto por origen autorizado
La app del portal consume un backend compartido entre varios clientes. En lugar de abrir el CORS con comodín, se usa una allowlist explícita y patrones acotados: el dominio principal, el de marca y los subdominios del dojo. Cada nuevo origen se agrega de forma trazable.
- 03
SEO de servidor con sitemap y robots propios
Como la infraestructura es compartida, el dojo declara su propio sitemap y robots, con el bloque de imágenes del establecimiento y su horario. Sin esto, las URLs del dojo quedarían bajo el sitemap de la plataforma y perderían identidad propia en buscadores.
- 04
Notificaciones automáticas y monitoreo
Los avisos al alumno (asistencia, recordatorios, pagos) se envían solos desde el backend. Detectamos y corregimos un tipo de dato que silenciaba notificaciones (un enum que descartaba valores nuevos) y quedó un reporte periódico que verifica que los procesos programados realmente se ejecuten.
- 05
Assets e identidad del portal
Optimizamos imágenes con formatos modernos, generamos favicons y assets de marca propios del dojo, y limpiamos código muerto de terceros que cargaba peso innecesario, para que el portal cargue rápido tanto en la sala de entrenamiento como en el teléfono del profesor.
── seo & geo ──
Cómo el sitio se hace encontrar por buscadores y por asistentes de IA.
- 01
Visibilidad local para la academia
El dojo compite por búsquedas locales de jiu-jitsu en Arica. Optimizamos el texto, el título y las imágenes del establecimiento alrededor de esas consultas, con contenido en español y una estructura clara que responde a lo que buscan alumnos y apoderados.
- 02
GEO: negocio, coach e imágenes en schema
Publicamos datos estructurados legibles por máquinas: el negocio (SportsActivityLocation) con ubicación, horarios, precios y rating agregado; el profesor como Person; el sitio como WebSite; un FAQ; y cada foto como ImageObject con caption. Esto permite que buscadores y asistentes de IA identifiquen la academia, su oferta y al instructor.
- 03
Reseñas reales que alimentan la confianza
Integramos las reseñas de Google del dojo (más de 20) en el sitio y en el rating estructurado, con promedio 5,0★. Son trazables a su origen y refuerzan tanto la conversión del visitante como la credibilidad ante buscadores.
── marca ──
Identidad visual y de marca del negocio.
- 01
Identidad propia del dojo, no genérica
El portal lleva la marca Integração y el subdominio bjj. con assets propios, favicons del dojo e imágenes optimizadas, para que se sienta una academia real y no una plantilla de plataforma.
- 02
Experiencia del alumno cuidada
Rediseñamos la vista del alumno con un cinturón realista, un loader con el logo del dojo y una paleta coherente con la academia, además de un CTA móvil fijo para coordinar la clase de prueba. La marca se mantiene consistente en cada pantalla.
- 03
Palmarés y respaldo del instructor
Destacamos al Profesor Chicão (cinturón negro 3er dan Carlson Gracie, con palmarés deportivo) como parte central de la identidad: es el activo de confianza que diferencia a esta academia de cualquier otra en la ciudad.
── resultado ──
El caso técnico está publicado con DOI en Zenodo, con el sistema en producción diario del dojo desde 2025. La asistencia es infalsificable y el profesor no administra nada a mano.
Caso técnico publicado: DOI 10.5281/zenodo.22785108