6.8 KiB
6.8 KiB
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
#scannerInputpermanece 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:
- Se utiliza una señal de cancelación
abortControlleroreader.cancel(). - Se libera el bloqueo con
reader.releaseLock(). - Se cierra el puerto con
await port.close(). - El procesamiento de lectura se ejecuta dentro de un bucle
while (keepReading)asíncrono con bloquetry ... 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
serialBufferhasta 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.
2.5. Arquitectura Multi-Lector Serial (4 Slots Concurrentes)
- Se diseña la clase
MultiSerialBarcodeScannerque administra un array fijo de 4 slots de escaneo (Slot 1,Slot 2,Slot 3,Slot 4). - Cada slot encapsula su propia instancia de
SerialPort,reader,baudRate(predeterminado 9600) y buffer de línea. - La función
requestAndConnectSlot(slotId, baudRate)permite al operador invocarnavigator.serial.requestPort()para asignar un puerto COM específico al slot deseado. - Al detectarse un código en cualquiera de los slots activos, se despacha el evento
onCodeScanned(code, { slotId, slotName }), emitiendo una alerta visual en el slot específico y ejecutandoverifyToken(code).
2.6. Módulo de Normalización y Parseo de DNI Argentino
- Módulo
backend/app/services/argentine_dni_parser.py:limpiar_numero_documento(doc_raw): Remueve puntos, espacios, y extrae prefijos de género antiguos (F,M) retornando(documento_numerico, sexo).parsear_dni(raw_text): Identifica los formatos oficiales de Renaper:- Formato 2009 (con/sin comilla inicial, posición fija de apellido, nombre, sexo).
- Formatos 2012, 2026 y App Mi Argentina (comienzan con número de trámite >= 8 dígitos, sexo alfabético o numérico 1/2/3, y DNI de 6 a 9 dígitos).
- Entradas directas de tarjetas o códigos de barras 1D.
- Integración en
backend/app/services/qr_security_service.py:- Antes del fallback por string crudo, se invoca
parsear_dni(clean_normalized). - Si retorna un
documentonumérico válido (5 a 9 dígitos), se busca al usuario porUser.document_number == doco coincidencia deusername. - Si el usuario existe en el padrón de UniCABA, se valida su estado (activo, regularidad) y se computan sus clases de hoy.
- Si no existe, se retorna estado
DENEGADOcon detalle amigable: "DNI argentino {doc} ({apellido}, {nombre}) no encontrado en el padrón de UniCABA."
- Antes del fallback por string crudo, se invoca
3. Estructura de Cambios por Archivo
backend/app/services/argentine_dni_parser.py(Nuevo módulo):- Funciones
limpiar_numero_documentoyparsear_dnicon cobertura exhaustiva de los formatos 2009, 2012, 2026 y Mi Argentina.
- Funciones
backend/tests/test_dni_parser.py(Nuevas pruebas unitarias):- Pruebas automatizadas con los 6 ejemplos provistos por el usuario y casos extremos.
backend/app/services/qr_security_service.py:- Integración de
parsear_dniendecode_and_resolve_usercon respuesta enriquecida.
- Integración de
frontend/public/js/serial-scanner.js:- Soporte para
MultiSerialBarcodeScanneradministrando hasta 4 slots concurrentes con reconexión automática.
- Soporte para
frontend/views/reception/scanner.html:- Interfaz visual para los 4 lectores COM (con modal o acordeón de gestión de 4 terminales, badges de estado individuales y notificación de lectura por puerto).
- Parser complementario en cliente para pre-detección de DNI argentino.
4. Plan de Pruebas y Validación
- Pruebas Unitarias del Parser de DNI:
- Validar los 6 ejemplos de lecturas reales provistas por el usuario.
- Pruebas de Verificación de Recepción:
- Validar que al enviar la cadena cruda de un DNI argentino a
/api/v1/reception/verify, se resuelva el estudiante si existe en BD.
- Validar que al enviar la cadena cruda de un DNI argentino a
- Prueba de Multi-Lector Serial en Navegador:
- Verificar la API de 4 slots en
MultiSerialBarcodeScannercon eventos concurrentes.
- Verificar la API de 4 slots en