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

101 lines
6.8 KiB
Markdown

# 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 `#scannerInput` permanece 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:
1. Se utiliza una señal de cancelación `abortController` o `reader.cancel()`.
2. Se libera el bloqueo con `reader.releaseLock()`.
3. Se cierra el puerto con `await port.close()`.
4. El procesamiento de lectura se ejecuta dentro de un bucle `while (keepReading)` asíncrono con bloque `try ... 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 `serialBuffer` hasta 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 `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. **`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. **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.