feat(reception): filter virtual buildings, remove camera and add SDD-013 Web Serial COM support (v3.8.50)
This commit is contained in:
@@ -0,0 +1,89 @@
|
||||
# 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.
|
||||
@@ -0,0 +1,68 @@
|
||||
# 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)
|
||||
- **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)
|
||||
1. **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/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()`).
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
@@ -0,0 +1,40 @@
|
||||
# Tareas de Implementación SDD-013: Escáner QR por Puerto Serie (COM) en Chromium Windows
|
||||
|
||||
## Tarea 1: Depuración de la Consola de Recepción (Sede Física y Eliminación de Cámara)
|
||||
- **Objetivo**: Asegurar que solo se listen sedes presenciales/físicas, predeterminar Edificio Central y remover totalmente el código y librerías de escáner por cámara web.
|
||||
- **Archivos**: `frontend/src/routes/reception.js`, `frontend/views/reception/scanner.html`.
|
||||
- **Hecho cuando**:
|
||||
- El selector `#buildingSelect` solo contiene sedes físicas (sin Campus Virtual) y tiene seleccionada la sede `Edificio Central` por defecto.
|
||||
- Se eliminó la librería `html5-qrcode` y el visor de cámara de la interfaz.
|
||||
|
||||
## Tarea 2: Módulo Cliente `SerialBarcodeScanner` (Web Serial API)
|
||||
- **Objetivo**: Crear el módulo JavaScript reutilizable que encapsula la Web Serial API para lectores ópticos y pistolas serie.
|
||||
- **Archivos**: `frontend/public/js/serial-scanner.js`.
|
||||
- **Hecho cuando**:
|
||||
- `SerialBarcodeScanner` detecta la disponibilidad de `navigator.serial`.
|
||||
- Permite solicitar y abrir un puerto COM con baudRate configurable (9600 predeterminado).
|
||||
- Lee los bytes entrantes mediante `TextDecoderStream` y emite eventos `onCodeScanned` ante delimitadores `\r` y `\n`.
|
||||
- Maneja la liberación de recursos (`releaseLock`) y cierre seguro de puertos.
|
||||
|
||||
## Tarea 3: Integración de UI de Puerto Serie en la Consola de Recepción
|
||||
- **Objetivo**: Conectar `SerialBarcodeScanner` con la interfaz de `scanner.html` y el despachador de verificación `/reception/verify`.
|
||||
- **Archivos**: `frontend/views/reception/scanner.html`.
|
||||
- **Hecho cuando**:
|
||||
- El botón "Configurar COM" abre el diálogo de selección de puertos serie de Windows en Chromium.
|
||||
- El badge refleja visualmente el estado: "COM Conectado (COMx)", "Puerto USB-HID Activo" o "No Soportado".
|
||||
- Las lecturas entrantes por puerto COM disparan automáticamente `verifyToken()` mostrando el titular y sus clases del día sin requerir foco en el input.
|
||||
|
||||
## Tarea 4: Resiliencia ante Desconexión y Reconexión Automática
|
||||
- **Objetivo**: Manejar desconexiones físicas de cables USB/Serial y reabrir puertos autorizados al recargar la página.
|
||||
- **Archivos**: `frontend/public/js/serial-scanner.js`, `frontend/views/reception/scanner.html`.
|
||||
- **Hecho cuando**:
|
||||
- El evento `navigator.serial.addEventListener('disconnect', ...)` actualiza el estado a "Desconectado" limpiamente.
|
||||
- Al recargar la página, `navigator.serial.getPorts()` reabre el puerto autorizado automáticamente si sigue conectado.
|
||||
|
||||
## Tarea 5: Validación Cruzada, Suite de Pruebas y Despliegue en Producción
|
||||
- **Objetivo**: Verificar que la suite de pruebas automatizadas del backend se ejecute al 100%, realizar bump semántico de versión, commit, git push a `dev` y despliegue al servidor institucional LXC `10.0.0.217`.
|
||||
- **Archivos**: `backend/tests/`, `package.json`, `app.js`, `CHANGELOG.md`, `MEMORY.md`.
|
||||
- **Hecho cuando**:
|
||||
- `pytest tests/` pasa exitosamente con 0 fallos.
|
||||
- La versión se incrementa a `3.8.50`.
|
||||
- El despliegue en `10.0.0.217` devuelve HTTP 200 en `/version`.
|
||||
Reference in New Issue
Block a user