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

86 lines
11 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)
### 4.6. Requisitos de Multi-Lector Serial (Hasta 4 Lectores COM Concurrentes)
- **RF-14 (Gestión de Múltiples Lectores Serie)**: EL SISTEMA permitirá la conexión, configuración y escucha simultánea de hasta **4 lectores QR / código de barras por puerto serie (COM)** concurrentes en una misma terminal o puesto de control de recepción.
- **RF-15 (Slots de Lectura Independientes)**: EL SISTEMA proveerá 4 slots identificables (ej: "Lector 1 / Entrada", "Lector 2", "Lector 3", "Lector 4"), cada uno con su propio estado de conexión (`CONNECTED`, `DISCONNECTED`), configuración de baudios y control independiente para abrir o liberar el puerto.
- **RF-16 (Multiplexación y canalización de escaneos)**: CUANDO cualquiera de los 4 lectores seriales transmita una lectura, EL SISTEMA procesará el código de inmediato de forma no bloqueante, notificando en la interfaz el slot emisor y disparando la verificación académica sin interferir con los otros lectores.
- **RF-17 (Reconexión automática multi-puerto)**: MIENTRAS existan puertos seriales previamente autorizados en el navegador (`navigator.serial.getPorts()`), EL SISTEMA intentará reabrir y asignar automáticamente hasta 4 puertos conocidos a los slots disponibles al iniciar o recargar la consola.
### 4.7. Requisitos de Reconocimiento de Documento Nacional de Identidad (DNI Argentino)
- **RF-18 (Detección de DNI Físico / QR / PDF417 de Renaper)**: EL SISTEMA detectará automáticamente si una cadena leída (vía lector COM, pistola USB-HID o ingreso manual) corresponde a un Documento Nacional de Identidad argentino en sus distintos formatos oficiales:
1. *Formato 2009 con comilla inicial*: `"34247025"A"1"TELLO"CARLOS FACUNDO"...` o `"f5592570 "A"1"SAUCEDO"TERESA DE JESUS"...`
2. *Formato 2009 sin comilla inicial*: `34247025"A"1"TELLO"CARLOS FACUNDO"...`
3. *Formato 2012*: `00225303383"RIO"MARTINA"F"46585482"A"...` (número de trámite, apellido, nombre, sexo M/F/X, DNI).
4. *Formato App Mi Argentina*: `305336518"CIRILLI"GEORGINA SUSANA"2"28988082"A"...` (sexo numérico 1=M, 2=F, 3=X, DNI).
5. *Formato 2026*: `00749743816"TELLO"CARLOS FACUNDO"34247025"G"...` (DNI en posición 3 con ejemplar alfabético).
6. *Entrada 1D / directa*: Con o sin prefijos de género antiguos (ej: `F5592570` ➔ `5592570`).
- **RF-19 (Normalización y Búsqueda Académica por DNI)**: CUANDO se reconozca un DNI argentino, EL SISTEMA normalizará el número de documento numérico y realizará la búsqueda directa en el padrón institucional (`User.document_number` o username).
- **RF-20 (Respuesta Contextual de DNI)**: SI el DNI pertenece a un estudiante o docente registrado, EL SISTEMA retornará su validación académica completa (aulas y horarios de hoy). SI el DNI no se encuentra en la base de datos de UniCABA, EL SISTEMA responderá informando claramente el documento y nombres extraídos del plástico físico (ej. `"DNI 34247025 (TELLO, CARLOS FACUNDO) no se encuentra registrado en el padrón de UniCABA"`).
---
## 5. Requisitos No Funcionales (NFR)
1. **Latencia de Captura**: El tiempo transcurrido entre la recepción del último byte del escáner en cualquiera de los 4 puertos 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()`).
4. **Tolerancia a Separadores en DNI**: El parser de DNI debe soportar indistintamente separadores de comillas dobles (`"`) y arrobas (`@`), así como terminadores `\r`, `\n` o espacios en blanco residuales.
---
## 6. Criterios de Aceptación y Validación
- [ ] La consola de recepción permite conectar hasta 4 lectores seriales COM independientes con indicadores individuales de estado.
- [ ] Al escanear desde cualquiera de los 4 lectores COM, el sistema captura y valida el código inmediatamente.
- [ ] Al escanear cualquiera de los 6 formatos de ejemplo de DNI argentino (2009, 2012, 2026, Mi Argentina, prefijos F/M), el sistema extrae el número de documento y datos de identidad con 100% de precisión.
- [ ] Si el titular del DNI está registrado en UniCABA, el sistema muestra sus clases de hoy y su estado regular/activo.
- [ ] Si el titular del DNI no está registrado, el sistema notifica el DNI y nombre leídos sin error de sintaxis ni bloqueo.
- [ ] Al desconectar físicamente cualquiera de los lectores serie, el slot correspondiente pasa a desconectado sin afectar a los otros lectores.