[jevillanueva]

---

name: feat: add self-service registration components and styles
about: Abre un Pull Request para contribuir con código, documentación o pruebas
title: "feat: implementar autoservicio de acreditación, participación y canjes"
labels: enhancement
assignees: "AASG2003"

✨ Descripción

Implementa el autoservicio de PyDay La Paz para que los participantes puedan acreditarse, descargar su credencial QR, registrar su participación en charlas y talleres, consultar puntos y canjear productos o un regalo especial desde el navegador.

Agrega una página principal con accesos a los distintos flujos y preguntas frecuentes. Integra los endpoints de autoservicio del backend, comparte la lectura del QR y adapta la navegación de las rutas /self sin sustituir el menú administrativo del resto de la aplicación.

Descripción basada en el commit 8c2a90eab6fc1e48f3e996231c0a372da251f2df de la rama feat/self-service: 15 archivos modificados, 1324 inserciones y 10 eliminaciones.

🔄 Tipo de cambio

• 🐛 Bug fix - corrección de un problema existente
• 🚀 Nueva funcionalidad - agrega algo nuevo sin romper lo existente
• 💥 Breaking change - modifica comportamiento existente
• 📄 Documentación - cambios solo en docs, README o comentarios
• 🎨 Estilo / Refactor - mejoras de código sin cambiar funcionalidad
• 🧪 Tests - agrega o corrige pruebas
• 🔧 Infraestructura - cambios en CI/CD, Docker o configuración

🔗 Issue relacionado

No se proporcionó un issue relacionado. Añadir Closes #N cuando corresponda.

🧩 ¿Qué cambiaste?

• Agrega /self con accesos a acreditación, participación, canje de puntos y canje de regalos; incorpora un banner y preguntas frecuentes con el contacto hello@pylapaz.org.
• Implementa /self/acreditation con carnet de identidad y fecha de nacimiento, bloqueo de envíos simultáneos y descarga de la credencial QR como PNG con efecto holográfico.
• Integra vanilla-tilt para la inclinación de la tarjeta y html-to-image para exportarla; agrega los estilos en styles/hologram.module.css.
• Añade lib/qr.ts para leer imágenes QR con jsqr, probar distintas resoluciones y colores invertidos, y extraer el código de control como texto o desde JSON.
• Implementa /self/check/[code]: verifica el código por GET, permite subir el QR y registra la participación por POST; muestra el resultado y redirige a /self al cerrar el diálogo de error de validación.
• Agrega /self/redeem/reward con consulta de puntos, selector de productos con stock, carnet obligatorio, bloqueo por saldo insuficiente y actualización de saldo y catálogo después del canje.
• Agrega /self/redeem/gift con comprobación inicial de disponibilidad, lectura QR y canje con carnet, sin exigir puntos ni selección de producto.
• Muestra los mensajes del canje y, cuando existen, los códigos de descuento y enlaces de descarga. Los enlaces de descarga se restringen a HTTP o HTTPS.
• Comparte el diálogo de participación entre la página principal y el menú de autoservicio; valida códigos no vacíos y codifica el valor al navegar a /self/check/[code].
• Adapta el enlace del título y las opciones del menú a /self y sus subrutas, conservando las opciones administrativas fuera de esas rutas.
• Añade tipos de autoservicio, clientes HTTP y las dependencias necesarias; conserva el texto de las respuestas de error del API y desactiva controles durante las operaciones pendientes.

🧪 ¿Cómo probarlo?

Preparación

Se necesita un backend compatible con los endpoints /api/v1/self-service, un participante de prueba con carnet y fecha de nacimiento válidos, un código de actividad vigente y productos con stock. Realizar los canjes únicamente en un entorno de pruebas, porque modifican puntos y existencias.

Configurar NEXT_PUBLIC_API_URL con la URL base del backend. Next.js redirige /api/v1/:path* a esa URL mediante la configuración existente.

npm ci
$env:NEXT_PUBLIC_API_URL = "http://localhost:8000"
npm run dev

En otra terminal, con la misma variable configurada, ejecutar las comprobaciones del proyecto:

npx tsc --noEmit
npm run lint
npm run build

Estos comandos son instrucciones para el revisor; no se certifica su ejecución ni su resultado en este documento.

Recorrido manual

1. Abrir http://localhost:3000/self y comprobar los cuatro accesos, el banner, las preguntas frecuentes y el menú de autoservicio. Verificar también que el menú administrativo se conserve fuera de /self.
2. Entrar en /self/acreditation, ingresar el carnet y la fecha de nacimiento del participante de prueba y completar la acreditación. Comprobar el bloqueo durante la consulta y descargar la credencial QR holográfica.
3. Abrir Participación desde la página principal y desde el menú. Confirmar que un código vacío o compuesto solo por espacios no habilite el envío y que un código válido navegue a /self/check/[code], tanto con Aceptar como con Enter.
4. En la participación, subir la credencial PNG y registrar el participante. Verificar el código de control, el mensaje y los puntos devueltos por el API.
5. Probar un código de participación inexistente o no disponible. Confirmar el diálogo de error y el regreso a /self al cerrarlo. Probar también respuestas no exitosas con texto y un fallo de conexión.
6. Entrar en /self/redeem/reward, subir el QR y verificar el saldo. Seleccionar un producto cuyo costo supere los puntos disponibles y comprobar que no permita canjearlo.
7. Elegir un producto asequible, ingresar el carnet y realizar el canje. Verificar la actualización de puntos y stock, los resultados conservados y la posibilidad de realizar otro canje cuando corresponda. Comprobar productos agotados y productos con multiple: false.
8. Entrar en /self/redeem/gift con disponibilidad y completar el canje usando QR y carnet, sin consultar ni exigir puntos. Repetir con el regalo agotado o no disponible y verificar el diálogo y la redirección.
9. Comprobar los códigos de descuento y enlaces de descarga cuando el API los incluya; probar también respuestas que no contengan ninguno de esos campos.
10. Probar una imagen sin QR, un QR con JSON que incluya control_code, un archivo ilegible y clics repetidos durante una consulta. Revisar la interfaz en móvil y escritorio y confirmar que no se solicite acceso a la cámara para cargar imágenes.

🖼️ Capturas de pantalla (si aplica)

Pendientes de adjuntar. Incluir capturas de la página principal, la credencial, el diálogo de participación y los resultados de canje en escritorio y móvil. No publicar credenciales, códigos de descuento ni datos personales reales.

✅ Checklist

• Mi código sigue los estándares del proyecto (TypeScript, React y Next.js; PEP 8 no aplica)
• Probé los cambios localmente y funcionan
• Agregué o actualicé tests para cubrir los cambios (si aplica)
• Actualicé la documentación relevante (README, documentación técnica o comentarios)
• No hay conflictos con la rama main
• El título del PR sigue el formato: tipo: descripción breve
• Vinculé el issue relacionado con Closes #N

💬 Notas para el revisor

• El commit no incorpora pruebas automatizadas. El checklist de pruebas, estándares y conflictos queda pendiente de verificación; las instrucciones anteriores no constituyen evidencia de ejecución.
• Confirmar el contrato del canje de regalo: en este commit el POST envía { control_code, ci, gift: null }. Validar que el backend acepte null; si exige una cadena vacía, será necesario ajustar el cliente antes del merge.
• Las reglas de stock, saldo suficiente, canje único por participante y autorización del carnet deben verificarse en el backend. El bloqueo de productos no múltiples en la interfaz solo conserva los canjes registrados durante la sesión de esa vista.
• Probar con la credencial holográfica real: los efectos visuales pueden reducir el contraste del QR y su legibilidad debe comprobarse en la imagen exportada, no solo con un QR de prueba.
• El giroscopio de VanillaTilt depende del navegador, del dispositivo y de los permisos disponibles. No se añade una solicitud explícita de permisos de sensores.
• Los resultados de canje se conservan en el estado de la página, no como un historial persistente. Los enlaces de descarga se abren en otra pestaña y su comportamiento depende del servidor que los proporciona.
• Si una consulta de canje pierde la conexión, comprobar en el backend si la operación se completó antes de reintentar, para evitar un canje duplicado.

[AASG2003]

En el combo box de los premios ("rewards") no salen los ilimitados (en el modelo de la API dice que los productos en none son ilimitados) la API los devuelve pero el front no los muestra.

[AASG2003]

En /self/acreditation no se tiene trim en la busqueda por carnet, asi que los espacios evitan que se encuentra un CI (el carnet "1000" pasaria pero el "1000 " no), otras paginas si lo tienen no si fue a proposito o no pero es una diferencia entre mismos buscadores entre distintas paginas.

[AASG2003]

Tal vez se podrian colocar mensajes explicitos en lugar de usar los genericos de la API en ingles, solo por no causar confusión.

[AASG2003]

Habria que mejorar la colorimetria entre los botones y campos activados y desactivados, la confusion se nota mejor en /self/redeem/gift el CI todavia no esta activado hasta que subas el qr, pero todos estan con el mismo color, dando a entender que todo estuviera desactivado o bloqueado.

[AASG2003]

Ahora las charlas y talleres tendran checkpoints, al ingresar el codigo a una se crea el "ingreso" registrando que esta en esta charla hasta usar el codigo checkpoint de "salida", pero si se va durante eso a un taller u otra charla sale lo de la foto, internamente la API devolvio 200 haciendo que el mensaje se vea en verde, honestamente muchos solo veran el verde y pensaran que todo esta bien xD, recomendaria cambiar el mensaje, e indicar explicitamente que esta pasando, tal vez en la seccion de preguntas, ya que si alguno mira rapidamente vera 0 y pensara que no funciona porque no le dio puntos.

[AASG2003]

Todo bien