Files
admin-edu-space/specs/013-escaner-qr-puerto-com-serial/plan.md
T

90 lines
5.1 KiB
Markdown

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