Files

11 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 (US vs ES / 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.serial en contextos seguros HTTPS o localhost): 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.serial en 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 AuditLog cada 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 TextDecoderStream y acumulará los caracteres en un buffer hasta detectar un delimitador de fin de línea (\r, \n o \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 disconnect de navigator.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)

4.6. Requisitos de Multi-Lector Serial (Hasta 4 Lectores COM Concurrentes)

  • RF-14 (Gestión de Múltiples Lectores Serie): EL SISTEMA permitirá la conexión, configuración y escucha simultánea de hasta 4 lectores QR / código de barras por puerto serie (COM) concurrentes en una misma terminal o puesto de control de recepción.
  • RF-15 (Slots de Lectura Independientes): EL SISTEMA proveerá 4 slots identificables (ej: "Lector 1 / Entrada", "Lector 2", "Lector 3", "Lector 4"), cada uno con su propio estado de conexión (CONNECTED, DISCONNECTED), configuración de baudios y control independiente para abrir o liberar el puerto.
  • RF-16 (Multiplexación y canalización de escaneos): CUANDO cualquiera de los 4 lectores seriales transmita una lectura, EL SISTEMA procesará el código de inmediato de forma no bloqueante, notificando en la interfaz el slot emisor y disparando la verificación académica sin interferir con los otros lectores.
  • RF-17 (Reconexión automática multi-puerto): MIENTRAS existan puertos seriales previamente autorizados en el navegador (navigator.serial.getPorts()), EL SISTEMA intentará reabrir y asignar automáticamente hasta 4 puertos conocidos a los slots disponibles al iniciar o recargar la consola.

4.7. Requisitos de Reconocimiento de Documento Nacional de Identidad (DNI Argentino)

  • RF-18 (Detección de DNI Físico / QR / PDF417 de Renaper): EL SISTEMA detectará automáticamente si una cadena leída (vía lector COM, pistola USB-HID o ingreso manual) corresponde a un Documento Nacional de Identidad argentino en sus distintos formatos oficiales:
    1. Formato 2009 con comilla inicial: "34247025"A"1"TELLO"CARLOS FACUNDO"... o "f5592570 "A"1"SAUCEDO"TERESA DE JESUS"...
    2. Formato 2009 sin comilla inicial: 34247025"A"1"TELLO"CARLOS FACUNDO"...
    3. Formato 2012: 00225303383"RIO"MARTINA"F"46585482"A"... (número de trámite, apellido, nombre, sexo M/F/X, DNI).
    4. Formato App Mi Argentina: 305336518"CIRILLI"GEORGINA SUSANA"2"28988082"A"... (sexo numérico 1=M, 2=F, 3=X, DNI).
    5. Formato 2026: 00749743816"TELLO"CARLOS FACUNDO"34247025"G"... (DNI en posición 3 con ejemplar alfabético).
    6. Entrada 1D / directa: Con o sin prefijos de género antiguos (ej: F5592570 ➔ 5592570).
  • RF-19 (Normalización y Búsqueda Académica por DNI): CUANDO se reconozca un DNI argentino, EL SISTEMA normalizará el número de documento numérico y realizará la búsqueda directa en el padrón institucional (User.document_number o username).
  • RF-20 (Respuesta Contextual de DNI): SI el DNI pertenece a un estudiante o docente registrado, EL SISTEMA retornará su validación académica completa (aulas y horarios de hoy). SI el DNI no se encuentra en la base de datos de UniCABA, EL SISTEMA responderá informando claramente el documento y nombres extraídos del plástico físico (ej. "DNI 34247025 (TELLO, CARLOS FACUNDO) no se encuentra registrado en el padrón de UniCABA").

5. Requisitos No Funcionales (NFR)

  1. Latencia de Captura: El tiempo transcurrido entre la recepción del último byte del escáner en cualquiera de los 4 puertos serie y el despacho de la solicitud /reception/verify debe ser inferior a 50 milisegundos.
  2. Seguridad y Permisos: La comunicación serie solo se ejecuta en contextos de origen seguro (HTTPS o localhost), respetando estrictamente el modelo de permisos explícitos de usuario de la Web Serial API de Chromium.
  3. Resiliencia ante Streams Abruptos: El lector de stream serial no debe colgar el hilo principal de renderizado de la UI; debe implementarse con ReadableStreamDefaultReader asíncrono y control try...finally para liberar el bloqueo (releaseLock()).
  4. Tolerancia a Separadores en DNI: El parser de DNI debe soportar indistintamente separadores de comillas dobles (") y arrobas (@), así como terminadores \r, \n o espacios en blanco residuales.

6. Criterios de Aceptación y Validación

  • La consola de recepción permite conectar hasta 4 lectores seriales COM independientes con indicadores individuales de estado.
  • Al escanear desde cualquiera de los 4 lectores COM, el sistema captura y valida el código inmediatamente.
  • Al escanear cualquiera de los 6 formatos de ejemplo de DNI argentino (2009, 2012, 2026, Mi Argentina, prefijos F/M), el sistema extrae el número de documento y datos de identidad con 100% de precisión.
  • Si el titular del DNI está registrado en UniCABA, el sistema muestra sus clases de hoy y su estado regular/activo.
  • Si el titular del DNI no está registrado, el sistema notifica el DNI y nombre leídos sin error de sintaxis ni bloqueo.
  • Al desconectar físicamente cualquiera de los lectores serie, el slot correspondiente pasa a desconectado sin afectar a los otros lectores.