Flujo de Login por QR

Canal: Socket.IO
Funcionalidad: Permite al frontend integrar el servicio de inicio de sesión mediante código QR.

---

1. Conexión WebSocket

• URL: ws://<HOST>/socket (mismo endpoint que el resto de la aplicación)
• Protocolo: Socket.IO

El frontend debe abrir la conexión antes de iniciar el flujo de QR.

---

2. Unirse a la sala QR

Evento: join-qr-room
El cliente solicita unirse a una sala identificada por el qrToken recibido del backend.

socket.emit('join-qr-room', { qrToken: '<tokenRecibido>' });

---

3. Eventos de respuesta

3.1 joined

• Descripción: Confirmación de unión satisfactoria a la sala.

• Uso:

  socket.on('joined', () => {
    // Mostrar spinner o indicador "Esperando escaneo".
  });

---

3.2 error

• Descripción: Fallo en la unión o validación.

• Payload: { code: number, message: string }

• Uso:

  socket.on('error', ({ code, message }) => {
    // Mostrar alerta con message y detener flujo.
  });

• Códigos de error:

  • 4006: Token inválido o expirado.
  • 4010: IP no autorizada.
  • 4012: Intento duplicado (QR invalidado).

---

3.3 qr-approved

• Descripción: El usuario escaneó y aprobó el QR.

• Payload: { jwt: string }

• Uso:

  socket.on('qr-approved', ({ jwt }) => {
    // Guardar JWT y redirigir a área privada.
  });

---

3.4 qr-invalid

• Descripción: QR invalidado por intento duplicado.

• Payload: { code: 4012, message: string }

• Uso:

  socket.on('qr-invalid', ({ code, message }) => {
    // Mostrar mensaje "QR inválido" y limpiar estado.
  });

---

3.5 qr-expired

• Descripción: El QR expiró sin ser aprobado.

• Payload: { code: 4008, message: string }

• Uso:

  socket.on('qr-expired', ({ code, message }) => {
    // Mostrar "QR expirado" y ofrecer reintentar.
  });

---

4. Recomendaciones para el frontend

1. Control de estado: Mantener estados claros: esperando, aprobado, error, expirado.
2. Tiempo de vida (TTL): Mostrar un contador regresivo según la duración del QR.
3. Seguridad: No exponer logs de IP ni detalles internos.

---