8.1 KiB
Especificación SDD-013: Compatibilidad de Escáner QR por Puerto Serie (COM) en Entornos Windows
1. Resumen Ejecutivo y Motivación
En los puestos de control de acceso físico e ingreso a sedes de UniCABA (particularmente Edificio Central), las pistolas ópticas y escáneres QR industriales operan frecuentemente conectados a través de interfaces RS-232 o conversores USB-a-Serial (puertos COM virtuales, ej. COM3, COM4), emulando protocolos de puerto serie en lugar de teclados USB HID estándar.
La emulación de teclado tradicional presenta desventajas operativas en puestos de recepción:
- Requiere retención estricta del foco del cursor en un campo de texto específico (
#scannerInput), el cual puede perderse si el operador hace clic en otra ventana o aplicación. - Está sujeta a desajustes de disposición de teclado (
USvsES/Latam), provocando sustitución de caracteres (ej.:porÑ). - No provee confirmación bidireccional sobre si el dispositivo físico está conectado, encendido o transmitiendo datos.
Para resolver esto en terminales con sistema operativo Windows, esta especificación introduce compatibilidad nativa con la Web Serial API de navegadores basados en Chromium (Google Chrome, Microsoft Edge, Brave, Opera), permitiendo la captura directa, asíncrona y en segundo plano de las lecturas ópticas directamente desde el puerto COM hacia el flujo de validación académica en tiempo real de Edu-Space.
2. Alcance y Límites
- Sistemas Operativos Compatibles (Fase 1): Microsoft Windows 10 y Windows 11.
- Navegadores Compatibles: Navegadores con soporte nativo de Web Serial API (
navigator.serialen contextos seguros HTTPS olocalhost): Google Chrome (v89+), Microsoft Edge (v89+), Opera (v75+), Brave. - Entornos Excluidos: Mozilla Firefox y Apple Safari (no implementan la Web Serial API por políticas de estándar W3C). En dichos navegadores, la consola continuará operando de manera transparente mediante el modo USB HID / Emulación de Teclado convencional.
3. Actores del Sistema
- Operador de Recepción / Seguridad: Personal institucional que supervisa los accesos peatonales en la sede y configura la conexión con el puerto COM de la pistola.
- Estudiante / Docente: Persona que presenta su credencial digital (código QR rotativo) o carnet físico en el punto de control.
- Administrador del Sistema: Configura parámetros de sede predeterminada, auditoría y tolerancias de lectura.
4. Requisitos Funcionales en Sintaxis EARS (Español Estricto)
4.1. Requisitos Ubicuos (Comportamiento Permanente)
- RF-01 (Detección de soporte): EL SISTEMA detectará de forma permanente la presencia del objeto
navigator.serialen la ventana del navegador e informará visualmente al operador la disponibilidad del modo Puerto Serie (COM). - RF-02 (Aislamiento de entrada): EL SISTEMA procesará las lecturas seriales entrantes de manera desacoplada del foco visual del cursor, permitiendo que la recepción valide accesos aun si el operador tiene abierto otro modal o elemento de la interfaz.
- RF-03 (Registro de auditoría): EL SISTEMA registrará en
AuditLogcada sesión de conexión o desconexión del puerto serie con el identificador del usuario operador y el puerto asignado.
4.2. Requisitos Basados en Eventos (Acción ➔ Respuesta)
- RF-04 (Solicitud y apertura de puerto): CUANDO el operador pulse el botón "Configurar COM", EL SISTEMA invocará
navigator.serial.requestPort()desplegando el cuadro de diálogo nativo de Windows para que el usuario seleccione el puerto COM deseado (ej. COM3, COM4). - RF-05 (Configuración de parámetros seriales): CUANDO el operador confirme la selección del puerto, EL SISTEMA abrirá la conexión serie (
port.open()) aplicando una tasa de baudios predeterminada de 9600 baudios, 8 bits de datos, 1 bit de parada y sin paridad (9600 8-N-1), con opción de alternar a 115200 baudios. - RF-06 (Bufferizado y corte por delimitador): CUANDO el lector serie transmita fragmentos de bytes, EL SISTEMA decodificará el flujo mediante
TextDecoderStreamy acumulará los caracteres en un buffer hasta detectar un delimitador de fin de línea (\r,\no\r\n). - RF-07 (Disparo de verificación automática): CUANDO el buffer complete una cadena de escaneo delimitada, EL SISTEMA emitirá un tono sonoro de captura (
playBeep), normalizará los caracteres (reemplazo tolerante de scancodes si aplica) y despachará la petición HTTP POST a/reception/verify.
4.3. Requisitos Basados en Estados (Activo mientras se cumpla una condición)
- RF-08 (Monitoreo de estado de conexión): MIENTRAS el puerto serie permanezca abierto y transmitiendo (
port.readable !== null), EL SISTEMA exhibirá un badge visual con pulso verde activo:● Puerto COM Conectado (COMx - 9600 baud). - RF-09 (Reconexión automática persistente): MIENTRAS el operador permanezca en la sesión de navegación y haya autorizado previamente un puerto serial, EL SISTEMA intentará reabrir automáticamente el puerto conocido mediante
navigator.serial.getPorts()sin requerir volver a solicitar el permiso de Windows.
4.4. Requisitos de No Deseado / Excepciones (Manejo de Errores)
- RF-10 (Navegador no compatible): SI el navegador web no soporta la Web Serial API (
"serial" in navigator === false), ENTONCES EL SISTEMA mantendrá deshabilitado el control COM, exhibirá una insignia explicativa"Modo USB-HID Estándar (Chromium requerido para COM)"y continuará operando normalmente con el teclado/pistola óptica. - RF-11 (Desconexión física o extracción del cable USB): SI el cable USB del conversor serie es desconectado físicamente mientras el lector está operando, ENTONCES EL SISTEMA capturará el evento
disconnectdenavigator.serial, liberará los bloqueos de stream (releaseLock), cerrará el puerto de manera segura, actualizará el badge a"Puerto COM Desconectado"y alertará al operador sin interrumpir la ejecución de la aplicación. - RF-12 (Error de apertura o puerto ocupado): SI el puerto COM seleccionado ya se encuentra abierto por otra aplicación de Windows o falla la comunicación, ENTONCES EL SISTEMA mostrará un mensaje de advertencia:
"No se pudo acceder al puerto COM. Verifique que no esté en uso por otra terminal o software de escáner".
4.5. Requisitos Opcionales (Configuración y Preferencias)
- RF-13 (Ajuste de velocidad de baudios): DONDE el modelo de escáner industrial requiera una tasa de transferencia diferente a 9600 baudios, EL SISTEMA permitirá al operador seleccionar entre 9600, 19200, 38400 y 115200 baudios mediante un menú desplegable de configuración rápida.
5. Requisitos No Funcionales (NFR)
- Latencia de Captura: El tiempo transcurrido entre la recepción del último byte del escáner en el puerto serie y el despacho de la solicitud
/reception/verifydebe ser inferior a 50 milisegundos. - Seguridad y Permisos: La comunicación serie solo se ejecuta en contextos de origen seguro (
HTTPSolocalhost), respetando estrictamente el modelo de permisos explícitos de usuario de la Web Serial API de Chromium. - Resiliencia ante Streams Abruptos: El lector de stream serial no debe colgar el hilo principal de renderizado de la UI; debe implementarse con
ReadableStreamDefaultReaderasíncrono y controltry...finallypara liberar el bloqueo (releaseLock()).
6. Criterios de Aceptación y Validación
- En Google Chrome o Edge en Windows, el botón "Configurar COM" abre el selector de dispositivos nativo del sistema operativo.
- Al seleccionar un lector o conversor USB-Serial (ej. Prolific, FTDI, CH340, Honeywell, Zebra), el badge cambia a "COM Conectado" con pulso verde.
- Al escanear una credencial QR con la pistola conectada al puerto serie, la consola registra el ingreso inmediatamente sin necesidad de tener el cursor en el input de texto.
- Al desconectar físicamente el cable USB, el sistema no lanza excepciones no controladas y vuelve al estado USB-HID.
- En navegadores no Chromium (Firefox), la aplicación no presenta errores de consola y mantiene el funcionamiento por emulación de teclado USB HID.