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.