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

69 lines
8.1 KiB
Markdown

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