Files
admin-edu-space/specs/013-escaner-qr-puerto-com-serial/plan.md
T

5.1 KiB

Plan Técnico SDD-013: Integración de Escáner QR por Puerto Serie (COM) con Web Serial API

1. Arquitectura Técnica y Componentes

1.1. Contexto de Ejecución

La solución se implementa en la capa frontend de la Consola de Recepción (frontend/views/reception/scanner.html y módulo complementario frontend/public/js/serial-scanner.js), aprovechando la Web Serial API estandarizada para motores Chromium en entornos Windows.

+-------------------------------------------------------------+
|                     Pistola Óptica / QR                     |
|           (Conexión USB-Serial / COM3 en Windows)           |
+-------------------------------------------------------------+
                              | RS-232 / USB Serial Stream
                              v
+-------------------------------------------------------------+
|                 Navegador Chromium (Edge/Chrome)             |
|  - Web Serial API: navigator.serial.requestPort()           |
|  - Stream Reader: port.readable.pipeTo(TextDecoderStream)   |
|  - Buffer de Línea: Regex /[\r\n]+/ delimitador de código   |
|  - Dispatcher: verifyToken(code) desacoplado del foco visual|
+-------------------------------------------------------------+
                              | HTTP POST JSON
                              v
+-------------------------------------------------------------+
|                      Backend REST API                       |
|  - /reception/verify ➔ QRSecurityService.decode_and_resolve |
|  - Registro de auditoría y AccessLogQR con hora Buenos Aires|
+-------------------------------------------------------------+

2. Decisiones de Diseño y Patrones Clave

2.1. Detección y Degradación Elegante

  • Si ("serial" in navigator) es falso (Firefox, Safari o contextos no seguros HTTP), la interfaz oculta o desactiva el botón de puerto COM y muestra un badge informativo: "Modo USB-HID (Emulación de Teclado)".
  • El flujo original con cursor retenido en #scannerInput permanece 100% operativo como respaldo transparente.

2.2. Manejo de Streams y Bloqueos (Locking)

En la Web Serial API, el flujo readable queda bloqueado por el lector (ReadableStreamDefaultReader). Para garantizar que el puerto pueda cerrarse limpiamente o reconectarse:

  1. Se utiliza una señal de cancelación abortController o reader.cancel().
  2. Se libera el bloqueo con reader.releaseLock().
  3. Se cierra el puerto con await port.close().
  4. El procesamiento de lectura se ejecuta dentro de un bucle while (keepReading) asíncrono con bloque try ... finally.

2.3. Bufferizado y Normalización de Scancodes

Las pistolas ópticas envían los caracteres leídos en pequeños fragmentos (chunks) seguidos de un carácter de retorno de carro (\r = CR, ASCII 13) o salto de línea (\n = LF, ASCII 10).

  • Se acumula el serialBuffer hasta encontrar un delimitador.
  • Se extrae el código completo, se descarta el buffer procesado y se invoca verifyToken(code.trim()).
  • Se aplica la normalización de scancodes (reemplazo tolerante de Ñ a : si el escáner serie viniera mapeado con tablas de teclado).

2.4. Reconexión Automática (Auto-Reconnect)

  • Al recargar la página o volver a la pestaña, se consulta navigator.serial.getPorts().
  • Si el navegador ya concedió permiso para un puerto serie en esta sesión, se reabre automáticamente sin solicitar nuevamente permiso interactivo al usuario.

3. Estructura de Cambios por Archivo

  1. frontend/views/reception/scanner.html:

    • Reemplazo definitivo del visor de cámara por el panel de Lector Óptico y Control de Puerto Serie.
    • Selector de sedes filtrado exclusivamente por sedes físicas con Edificio Central predeterminado.
    • Controles de UI para el puerto COM: Badge de estado (COM Activo, Desconectado, No Soportado), botón de conexión rápida, selector de baud rate (9600 predeterminado).
    • Inclusión del módulo serial-scanner.js y binding con verifyToken().
  2. frontend/public/js/serial-scanner.js (Nuevo módulo):

    • Encapsula la clase SerialBarcodeScanner con métodos:
      • isSupported()
      • connect(baudRate)
      • disconnect()
      • autoConnectIfAuthorized()
      • Eventos: onCodeScanned, onStatusChanged, onError.
  3. frontend/src/routes/reception.js:

    • Filtrado estricto de buildings presenciales (!is_virtual).
    • Sede predeterminada Edificio Central.

4. Plan de Pruebas y Validación

  1. Prueba de Compatibilidad de API:
    • En Chrome/Edge: verificar que navigator.serial esté disponible y que al pulsar "Configurar COM" se abra el diálogo del sistema operativo Windows.
    • En Firefox: verificar que la interfaz no lance errores y explique amigablemente el uso de USB HID.
  2. Prueba de Ingesta y Verificación Asíncrona:
    • Simular transmisión de bytes en serie terminados en \r\n con código de credencial.
    • Verificar que verifyToken se dispare sin que el cursor deba estar en el input de texto.
  3. Prueba de Desconexión Física y Resiliencia:
    • Simular evento disconnect en el puerto serial y validar que el badge retorne a "Desconectado" sin colgar el navegador.