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

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 #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.