5.1 KiB
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
#scannerInputpermanece 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:
- Se utiliza una señal de cancelación
abortControlleroreader.cancel(). - Se libera el bloqueo con
reader.releaseLock(). - Se cierra el puerto con
await port.close(). - El procesamiento de lectura se ejecuta dentro de un bucle
while (keepReading)asíncrono con bloquetry ... 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
serialBufferhasta 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
-
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 Centralpredeterminado. - 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.jsy binding converifyToken().
-
frontend/public/js/serial-scanner.js(Nuevo módulo):- Encapsula la clase
SerialBarcodeScannercon métodos:isSupported()connect(baudRate)disconnect()autoConnectIfAuthorized()- Eventos:
onCodeScanned,onStatusChanged,onError.
- Encapsula la clase
-
frontend/src/routes/reception.js:- Filtrado estricto de
buildingspresenciales (!is_virtual). - Sede predeterminada
Edificio Central.
- Filtrado estricto de
4. Plan de Pruebas y Validación
- Prueba de Compatibilidad de API:
- En Chrome/Edge: verificar que
navigator.serialesté 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.
- En Chrome/Edge: verificar que
- Prueba de Ingesta y Verificación Asíncrona:
- Simular transmisión de bytes en serie terminados en
\r\ncon código de credencial. - Verificar que
verifyTokense dispare sin que el cursor deba estar en el input de texto.
- Simular transmisión de bytes en serie terminados en
- Prueba de Desconexión Física y Resiliencia:
- Simular evento
disconnecten el puerto serial y validar que el badge retorne a "Desconectado" sin colgar el navegador.
- Simular evento