feat(reception): add multi-serial scanner for up to 4 COM ports and universal Argentine DNI parser (v3.8.52)

This commit is contained in:
2026-10-28 14:47:54 -03:00
parent 1477780df0
commit 19495e96b4
14 changed files with 806 additions and 183 deletions
+36 -25
View File
@@ -53,37 +53,48 @@ Las pistolas ópticas envían los caracteres leídos en pequeños fragmentos (ch
- 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 `MultiSerialBarcodeScanner` que 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 invocar `navigator.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 ejecutando `verifyToken(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 `documento` numérico válido (5 a 9 dígitos), se busca al usuario por `User.document_number == doc` o coincidencia de `username`.
- 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 `DENEGADO` con detalle amigable: *"DNI argentino {doc} ({apellido}, {nombre}) no encontrado en el padrón de UniCABA."*
---
## 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`.
1. **`backend/app/services/argentine_dni_parser.py`** (Nuevo módulo):
- Funciones `limpiar_numero_documento` y `parsear_dni` con cobertura exhaustiva de los formatos 2009, 2012, 2026 y Mi Argentina.
2. **`backend/tests/test_dni_parser.py`** (Nuevas pruebas unitarias):
- Pruebas automatizadas con los 6 ejemplos provistos por el usuario y casos extremos.
3. **`backend/app/services/qr_security_service.py`**:
- Integración de `parsear_dni` en `decode_and_resolve_user` con respuesta enriquecida.
4. **`frontend/public/js/serial-scanner.js`**:
- Soporte para `MultiSerialBarcodeScanner` administrando hasta 4 slots concurrentes con reconexión automática.
5. **`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
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.
1. **Pruebas Unitarias del Parser de DNI**:
- Validar los 6 ejemplos de lecturas reales provistas por el usuario.
2. **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.
3. **Prueba de Multi-Lector Serial en Navegador**:
- Verificar la API de 4 slots en `MultiSerialBarcodeScanner` con eventos concurrentes.
+24 -7
View File
@@ -49,20 +49,37 @@ Para resolver esto en terminales con sistema operativo **Windows**, esta especif
- **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.
### 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 el puerto serie y el despacho de la solicitud `/reception/verify` debe ser inferior a **50 milisegundos**.
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
- [ ] 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.
- [ ] 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.
@@ -38,3 +38,20 @@
- `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`.
## Tarea 6: Módulo y Pruebas de DNI Argentino (Formatos 2009, 2012, 2026 y Mi Argentina)
- **Objetivo**: Implementar `argentine_dni_parser.py` e integrarlo en `qr_security_service.py` con pruebas unitarias en `test_dni_parser.py` para todos los ejemplos provistos.
- **Archivos**: `backend/app/services/argentine_dni_parser.py`, `backend/app/services/qr_security_service.py`, `backend/tests/test_dni_parser.py`.
- **Hecho cuando**:
- Todos los formatos de ejemplo son procesados y extraen correctamente DNI numérico, apellido, nombre y sexo.
- Al escanear un DNI de alumno/docente existente en base de datos, `decode_and_resolve_user` resuelve el usuario y sus clases.
- `pytest tests/test_dni_parser.py` pasa al 100% (verde).
## Tarea 7: Soporte Multi-Lector Serial COM (Hasta 4 Lectores Simultáneos)
- **Objetivo**: Extender `serial-scanner.js` con `MultiSerialBarcodeScanner` y diseñar la UI de gestión de 4 terminales en `scanner.html`.
- **Archivos**: `frontend/public/js/serial-scanner.js`, `frontend/views/reception/scanner.html`.
- **Hecho cuando**:
- Se pueden conectar y monitorear hasta 4 lectores seriales COM en paralelo.
- Cada ranura muestra su estado individual (Conectado / Desconectado) y baudrate.
- Los escaneos desde cualquiera de los 4 lectores se canalizan automáticamente hacia la verificación sin bloquear la interfaz.