# 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.