feat(reception): filter virtual buildings, remove camera and add SDD-013 Web Serial COM support (v3.8.50)

This commit is contained in:
2026-10-28 14:04:45 -03:00
parent 4668117c35
commit 9f21442bed
12 changed files with 574 additions and 96 deletions
+12
View File
@@ -11,6 +11,18 @@ El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1
- **Sincronización Continua Moodle (Fase 6):** Automatización de workers persistentes en background para el procesamiento continuo de la cola de Web Services Moodle 4.1.
- **Pruebas de Carga y Hardening (Fase 6):** Pruebas de estrés de concurrencia y validación final de producción.
## [3.8.50] - 2026-10-28
### Added & Changed (Depuración de Sedes Físicas en Recepción, Eliminación de Cámara y Especificación SDD-013 Web Serial COM)
- **Depuración de Sedes en la Consola de Recepción**:
- Se filtró estrictamente el selector de sedes (`/reception/scanner`) para mostrar únicamente sedes físicas/presenciales, excluyendo completamente al Campus Virtual por tratarse de un puesto de control físico.
- Se configuró la sede física **Edificio Central** (`CENTRAL`) como el punto de control predeterminado seleccionado al abrir la consola de acceso.
- **Eliminación Total del Escaneo por Cámara Web**:
- Se removió el lector de cámara, la librería `html5-qrcode` y los botones interactivos asociados, reconvirtiendo la columna de escaneo en un panel dedicado de alta velocidad para pistolas ópticas y lectores por puerto serie.
- **Especificación e Integración SDD-013 (Lector Óptico por Puerto Serie COM)**:
- Creación de la especificación SDD-013 (`specs/013-escaner-qr-puerto-com-serial/` con `spec.md`, `plan.md`, `tasks.md`) bajo sintaxis EARS en español.
- Implementación del módulo frontend `serial-scanner.js` utilizando la **Web Serial API** (`navigator.serial`) para motores Chromium (Google Chrome, Microsoft Edge, Opera, Brave) en entornos Windows.
- Permite la captura directa de lecturas de código de barras y QR desde puertos COM físicos/virtuales sin depender del foco del cursor ni de la emulación de teclado, con reconexión automática y bufferizado por delimitador de línea.
## [3.8.49] - 2026-10-28
### Added & Fixed (Anti-Captura Estricto en QR Dinámico, Corrección de Zona Horaria de Buenos Aires y Registro Óptico)
- **Corrección Integral del Desfasaje Horario en Registros de Ingreso**:
+5 -5
View File
@@ -9,11 +9,11 @@ Memoria del proyecto entre sesiones para la rama `dev`.
- Libro de Calificaciones (*Gradebook*) con actas de regularidad inmutables.
- Autenticación híbrida (Google OAuth 2.0, Moodle SSO, Local) y Modo Impersonación.
- Reinicialización segura del sistema con contraseña de Administrador.
- **Sprint Activo: Anti-Captura Estricto en QR Dinámico y Corrección de Zona Horaria (v3.8.49)**:
- **Corrección Integral del Desfasaje Horario (16:18 vs 13:18)**: Solucionado el desfasaje de 3 horas en la Consola de Recepción (`/reception/scanner`). Se implementó `to_argentina_time` en `reception.py` convirtiendo los timestamps a la zona horaria institucional de Buenos Aires (`America/Argentina/Buenos_Aires`, UTC-3) e inyectando `scanned_time`. Adaptado tanto el render Nunjucks inicial como las actualizaciones periódicas AJAX.
- **Ventana Estricta Anti-Captura en QR Dinámico**: Periodo de validez del JWT reducido a 6 segundos (`valid_seconds = 6`), de modo que capturas de pantalla o fotos del código QR de 10 segundos o más queden categóricamente expiradas y rechazadas con `jwt.ExpiredSignatureError`.
- **Priorización Criptográfica**: `decode_and_resolve_user` evalúa prioritariamente la firma JWT con control de expiración estricto, informando al operador: *"La credencial digital ha expirado (anti-captura activo). Renueve el código en la pantalla del usuario."*
- **Versión Consolidada**: `v3.8.49`.
- **Sprint Activo: Consola de Recepción Presencial y Lector por Puerto Serie (v3.8.50)**:
- **Sede Física Exclusiva y Edificio Central Predeterminado**: Filtrado total de sedes virtuales en `/reception/scanner`. Edificio Central fijado como sede predeterminada de control de acceso.
- **Depuración de Cámara Web**: Removido el visor de cámara y la dependencia de `html5-qrcode`, consolidando la consola en modo lector óptico / pistola de alta velocidad.
- **Especificación e Integración SDD-013 (Web Serial COM en Chromium/Windows)**: Especificación formal completa en `specs/013-escaner-qr-puerto-com-serial/` y módulo `serial-scanner.js` para captura directa asíncrona desde puertos COM (`navigator.serial`) sin requerir foco en el cursor.
- **Versión Consolidada**: `v3.8.50`.
## Decisiones (y por qué)
- **Flujo Secuencial de Bedelía (9 Pasos)**: Estandarizar la carga operativa en: 1) Sede -> 2) Aula -> 3) Ciclo Lectivo -> 4) Carrera -> 5) Materia (vinculada a Carrera) -> 6) Comisión (asociada a Materia, Carrera y Ciclo) -> 7) Profesores -> 8) Alumnos -> 9) Reserva de Espacio. Esto asegura consistencia e integridad relacional.
+1 -1
View File
@@ -7,7 +7,7 @@ from typing import Any
from database import db, get_db, engine, SessionLocal, session
from config.config import Config
__version__ = "3.8.49"
__version__ = "3.8.50"
class DummyContext:
def __enter__(self):
+1 -1
View File
@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
setup(
name="edu-space-admin",
version="3.8.49",
version="3.8.50",
description="Administrative interface for Edu-Space Classroom Management System (FastAPI ASGI Core)",
author="Edu-Space Development Team",
author_email="admin@edu-space.com",
+1 -1
View File
@@ -1,6 +1,6 @@
{
"name": "frontend",
"version": "3.8.49",
"version": "3.8.50",
"description": "",
"main": "index.js",
"scripts": {
+186
View File
@@ -0,0 +1,186 @@
/**
* serial-scanner.js — Módulo de Lector Óptico y Escáner QR por Puerto Serie (COM)
* Específico para navegadores Chromium (Google Chrome, Microsoft Edge, Opera, Brave) en entornos Windows.
* Utiliza la Web Serial API (navigator.serial) para lectura directa y en segundo plano sin requerir foco.
* Espec: specs/013-escaner-qr-puerto-com-serial/
*/
(function(window) {
'use strict';
class SerialBarcodeScanner {
constructor(options = {}) {
this.baudRate = options.baudRate || 9600;
this.port = null;
this.reader = null;
this.readableStreamClosed = null;
this.keepReading = false;
this.buffer = '';
this.onCodeScanned = options.onCodeScanned || null;
this.onStatusChanged = options.onStatusChanged || null;
this.onError = options.onError || null;
this._initDisconnectListener();
}
isSupported() {
return typeof navigator !== 'undefined' && 'serial' in navigator;
}
_initDisconnectListener() {
if (this.isSupported()) {
navigator.serial.addEventListener('disconnect', (event) => {
if (this.port && event.target === this.port) {
this._notifyStatus('DISCONNECTED', 'Puerto serie desconectado físicamente.');
this.disconnect();
}
});
}
}
_notifyStatus(status, message, details = {}) {
if (typeof this.onStatusChanged === 'function') {
this.onStatusChanged({ status, message, ...details });
}
}
async autoConnectIfAuthorized() {
if (!this.isSupported()) return false;
try {
const ports = await navigator.serial.getPorts();
if (ports && ports.length > 0) {
this.port = ports[0];
await this._openPort();
return true;
}
} catch (err) {
console.warn('[SerialScanner] Autoconnect notice:', err.message);
}
return false;
}
async requestAndConnect(baudRate = null) {
if (!this.isSupported()) {
throw new Error('La Web Serial API no está soportada en este navegador. Utiliza Google Chrome o Microsoft Edge.');
}
if (baudRate) {
this.baudRate = parseInt(baudRate, 10) || 9600;
}
// Desconectar puerto previo si estuviera activo
if (this.port) {
await this.disconnect();
}
// Despliega el diálogo nativo de Windows para seleccionar dispositivo COM
this.port = await navigator.serial.requestPort();
await this._openPort();
return this.port;
}
async _openPort() {
if (!this.port) return;
await this.port.open({
baudRate: this.baudRate,
dataBits: 8,
stopBits: 1,
parity: 'none',
bufferSize: 1024
});
this.keepReading = true;
this._notifyStatus('CONNECTED', `Puerto serie conectado a ${this.baudRate} baudios.`, {
baudRate: this.baudRate
});
this._startReadingLoop();
}
async _startReadingLoop() {
while (this.port && this.port.readable && this.keepReading) {
const textDecoder = new TextDecoderStream();
this.readableStreamClosed = this.port.readable.pipeTo(textDecoder.writable);
this.reader = textDecoder.readable.getReader();
try {
while (this.keepReading) {
const { value, done } = await this.reader.read();
if (done) break;
if (value) {
this._handleIncomingText(value);
}
}
} catch (error) {
if (this.keepReading) {
console.error('[SerialScanner] Error en lectura serie:', error);
if (typeof this.onError === 'function') {
this.onError(error);
}
}
} finally {
try {
this.reader.releaseLock();
} catch (e) {}
}
}
}
_handleIncomingText(chunk) {
this.buffer += chunk;
// Detectar delimitadores de fin de línea habituales en pistolas ópticas (\r, \n)
if (this.buffer.includes('\n') || this.buffer.includes('\r')) {
const parts = this.buffer.split(/[\r\n]+/);
for (let i = 0; i < parts.length - 1; i++) {
const rawCode = parts[i].trim();
if (rawCode.length >= 2) {
this._dispatchCode(rawCode);
}
}
this.buffer = parts[parts.length - 1];
}
}
_dispatchCode(code) {
// Normalizar scancodes si fuera necesario
const cleanCode = code.replace(/Ñ/g, ':').replace(/ñ/g, ':');
if (typeof this.onCodeScanned === 'function') {
this.onCodeScanned(cleanCode);
}
}
async disconnect() {
this.keepReading = false;
if (this.reader) {
try {
await this.reader.cancel();
} catch (e) {}
this.reader = null;
}
if (this.readableStreamClosed) {
try {
await this.readableStreamClosed.catch(() => {});
} catch (e) {}
this.readableStreamClosed = null;
}
if (this.port) {
try {
await this.port.close();
} catch (e) {}
this.port = null;
}
this.buffer = '';
this._notifyStatus('DISCONNECTED', 'Puerto serie desconectado.');
}
}
// Exportar al objeto global de ventana
window.SerialBarcodeScanner = SerialBarcodeScanner;
})(window);
+3 -3
View File
@@ -86,9 +86,9 @@ const env = nunjucks.configure(path.join(__dirname, '../views'), {
});
// Versiones institucionales del sistema
const APP_VERSION = '3.8.49';
const FRONTEND_VERSION = '3.8.49';
const BACKEND_VERSION = '3.8.49';
const APP_VERSION = '3.8.50';
const FRONTEND_VERSION = '3.8.50';
const BACKEND_VERSION = '3.8.50';
env.addGlobal('app_version', APP_VERSION);
env.addGlobal('frontend_version', FRONTEND_VERSION);
+30 -3
View File
@@ -26,7 +26,24 @@ router.get('/scanner', async (req, res) => {
req.apiClient.get('/buildings'),
req.apiClient.get('/reception/recent-logs', { params: { limit: 15 } })
]);
buildings = respBld.data?.buildings || respBld.data || [];
const rawBuildings = respBld.data?.buildings || respBld.data || [];
// Filtrar estrictamente solo sedes físicas (excluyendo sedes virtuales)
buildings = rawBuildings.filter(b => {
const code = (b.code || '').toUpperCase();
const name = (b.name || '').toUpperCase();
const isVirt = Boolean(b.is_virtual || code.includes('VIRTUAL') || name.includes('VIRTUAL'));
return !isVirt;
});
// Predeterminar Edificio Central
let defaultBuildingId = null;
const central = buildings.find(b => (b.code || '').toUpperCase().includes('CENTRAL') || (b.name || '').toUpperCase().includes('CENTRAL'));
if (central) {
defaultBuildingId = central.id;
} else if (buildings.length > 0) {
defaultBuildingId = buildings[0].id;
}
recentLogs = (respLogs.data?.items || []).map(l => {
let timeStr = l.scanned_time;
if (!timeStr && l.scanned_at) {
@@ -45,14 +62,24 @@ router.get('/scanner', async (req, res) => {
}
return { ...l, scanned_time: timeStr || '--' };
});
res.render('reception/scanner', {
title: 'Control de Acceso QR — Recepción & Seguridad',
buildings,
defaultBuildingId,
recentLogs,
userRole: role
});
return;
} catch (err) {
console.warn('Reception scanner init notice:', err.message);
}
res.render('reception/scanner', {
title: 'Control de Acceso QR — Recepción & Seguridad',
buildings,
recentLogs,
buildings: [],
defaultBuildingId: null,
recentLogs: [],
userRole: role
});
});
+138 -82
View File
@@ -19,11 +19,12 @@
<div class="d-flex align-items-center gap-3">
<div>
<label class="small text-muted fw-bold d-block">Punto de Control / Sede:</label>
<select class="form-select form-select-sm rounded-pill px-3" id="buildingSelect">
<option value="">Todas las Sedes</option>
<label class="small text-muted fw-bold d-block">Punto de Control / Sede Física:</label>
<select class="form-select form-select-sm rounded-pill px-3 shadow-xs" id="buildingSelect">
{% for b in buildings %}
<option value="{{ b.id }}" {% if loop.first %}selected{% endif %}>{{ b.name }}</option>
<option value="{{ b.id }}" {% if b.id == defaultBuildingId or (not defaultBuildingId and loop.first) %}selected{% endif %}>
{{ b.name }}
</option>
{% endfor %}
</select>
</div>
@@ -31,45 +32,68 @@
</div>
<div class="row g-4">
<!-- Columna Izquierda: Escáner y Entrada Rápida -->
<!-- Columna Izquierda: Escáner Óptico / Pistola USB y Puerto Serial -->
<div class="col-12 col-lg-5">
<div class="card border-0 shadow-sm rounded-4 p-4 mb-4">
<h5 class="fw-bold mb-3 d-flex align-items-center justify-content-between">
<span><i class="bi bi-camera me-2 text-primary"></i>Lector de Cámara</span>
<button type="button" class="btn btn-sm btn-outline-primary rounded-pill px-3" id="toggleCamBtn" onclick="toggleCamera()">
<i class="bi bi-play-circle me-1"></i> Iniciar Cámara
</button>
</h5>
<div class="d-flex align-items-center justify-content-between mb-3">
<h5 class="fw-bold mb-0 text-dark d-flex align-items-center">
<i class="bi bi-upc-scan me-2 text-primary"></i>Lector Óptico de Acceso
</h5>
<span class="small text-success fw-semibold d-flex align-items-center gap-1" id="scannerFocusIndicator" title="El cursor está atrapado permanentemente en este campo para lectura USB directa">
<span class="scanner-active-dot"></span> Lector Listo
</span>
</div>
<!-- Visor de Cámara -->
<div id="reader" class="rounded-4 overflow-hidden bg-dark position-relative d-flex align-items-center justify-content-center text-white"
style="width: 100%; min-height: 280px;">
<div id="cameraPlaceholder" class="text-center p-4">
<i class="bi bi-camera-video display-4 text-secondary mb-2 d-block"></i>
<span class="small text-muted">Cámara en espera. Presiona "Iniciar Cámara" o utiliza un lector óptico USB.</span>
<!-- Banner Informativo de Operación -->
<div class="p-3 bg-light rounded-4 border mb-3 text-start">
<div class="d-flex align-items-start gap-2">
<i class="bi bi-shield-check text-primary fs-5 mt-1"></i>
<div>
<div class="fw-bold small text-dark">Modo Alta Velocidad USB HID / COM</div>
<div class="text-muted small" style="font-size: 0.76rem;">
El cursor se mantiene retenido permanentemente en el campo de escaneo. Dispara la pistola óptica sobre la credencial QR o DNI físico para registrar el acceso en tiempo real.
</div>
</div>
</div>
</div>
<!-- Entrada Manual o Pistola Óptica USB -->
<!-- Entrada de Lectura Óptica USB -->
<form id="manualScanForm" onsubmit="handleManualScan(event)">
<div class="input-group shadow-sm rounded-pill overflow-hidden border border-2 border-primary mb-2">
<input type="text" class="form-control rounded-start-pill ps-3 border-0 py-2 fs-6" id="scannerInput"
placeholder="Escanea con la pistola o escribe el DNI..." autofocus autocomplete="off">
<button class="btn btn-primary rounded-end-pill px-4 fw-semibold border-0" type="submit">
<i class="bi bi-arrow-right-circle me-1"></i> Validar
</button>
</div>
<div class="d-flex align-items-center justify-content-between px-2">
<span class="small text-muted" style="font-size: 0.74rem;">
<i class="bi bi-info-circle me-1"></i>Captura automática al recibir el delimitador Enter
</span>
<button type="button" class="btn btn-link btn-sm text-decoration-none p-0 text-primary small" onclick="focusScannerInput()">
<i class="bi bi-crosshair me-1"></i>Forzar Foco
</button>
</div>
</form>
<!-- Panel de Conexión Serial / Puerto COM (Web Serial API) -->
<div class="mt-4 pt-3 border-top">
<div class="d-flex align-items-center justify-content-between mb-1">
<label class="form-label small fw-bold text-uppercase text-muted mb-0">
<i class="bi bi-upc-scan me-1 text-primary"></i> Pistola Óptica USB o Entrada Manual
</label>
<span class="small text-success fw-semibold d-flex align-items-center gap-1" id="scannerFocusIndicator" title="El cursor está bloqueado en este campo para recibir el escaneo inmediato">
<span class="scanner-active-dot"></span> Lector Listo
<div class="d-flex align-items-center justify-content-between mb-2">
<span class="small fw-bold text-uppercase text-muted">
<i class="bi bi-usb-symbol me-1 text-primary"></i> Puerto Serie (COM)
</span>
<span class="badge bg-secondary-subtle text-secondary rounded-pill px-2 py-1 small" id="serialPortStatusBadge">
<i class="bi bi-circle-fill text-muted me-1" style="font-size: 0.5rem;"></i> Puerto USB-HID Activo
</span>
</div>
<form id="manualScanForm" onsubmit="handleManualScan(event)">
<div class="input-group shadow-sm rounded-pill overflow-hidden border border-2 border-primary">
<input type="text" class="form-control rounded-start-pill ps-3 border-0" id="scannerInput"
placeholder="Escanea con la pistola o escribe el DNI..." autofocus autocomplete="off">
<button class="btn btn-primary rounded-end-pill px-4 fw-semibold border-0" type="submit">
Validar
</button>
</div>
<span class="small text-muted d-block mt-1">El cursor se mantiene siempre activo aquí. La pistola óptica envía la lectura y valida automáticamente.</span>
</form>
<div class="d-flex align-items-center justify-content-between p-2 rounded-3 bg-body-tertiary border">
<small class="text-muted" style="font-size: 0.74rem;">
Dispositivos Seriales COM (Windows / Chromium)
</small>
<button type="button" class="btn btn-xs btn-outline-secondary rounded-pill px-3 py-1 text-nowrap" id="btnConnectSerial" onclick="handleSerialConnectClick()">
<i class="bi bi-link-45deg me-1"></i>Configurar COM
</button>
</div>
</div>
</div>
</div>
@@ -87,9 +111,9 @@
<div class="card-body p-4 d-flex flex-column justify-content-center text-center" id="resultBody">
<div class="py-5 text-muted" id="waitingState">
<i class="bi bi-qr-code-scan display-1 opacity-25 text-primary mb-3 d-block"></i>
<h4 class="fw-bold text-secondary">Apunta el código QR a la cámara</h4>
<h4 class="fw-bold text-secondary">Apunta el lector óptico a la credencial</h4>
<p class="small text-muted max-w-md mx-auto">
Al detectar la credencial del alumno o docente, el sistema mostrará instantáneamente sus datos de ingreso y las aulas donde cursa hoy.
Al detectar la credencial dinámica o física del alumno o docente, el sistema mostrará instantáneamente sus datos de ingreso y las aulas donde cursa hoy.
</p>
</div>
@@ -184,58 +208,89 @@
</div>
</div>
<!-- html5-qrcode Library via CDN -->
<script src="https://cdn.jsdelivr.net/npm/html5-qrcode@2.3.8/html5-qrcode.min.js"></script>
<!-- Módulo de Web Serial API para lectores ópticos y escáneres QR (SDD-013) -->
<script src="/js/serial-scanner.js"></script>
<script>
let html5QrCode = null;
let isCameraRunning = false;
let isScanningLocked = false;
let serialScanner = null;
// Inicializar o alternar cámara
function toggleCamera() {
const btn = document.getElementById('toggleCamBtn');
const placeholder = document.getElementById('cameraPlaceholder');
// Inicializar SerialBarcodeScanner para Chromium / Windows
function initSerialScanner() {
if (typeof SerialBarcodeScanner === 'undefined') return;
if (isCameraRunning) {
if (html5QrCode) {
html5QrCode.stop().then(() => {
isCameraRunning = false;
btn.innerHTML = '<i class="bi bi-play-circle me-1"></i> Iniciar Cámara';
btn.classList.replace('btn-danger', 'btn-outline-primary');
placeholder.classList.remove('d-none');
});
}
} else {
html5QrCode = new Html5Qrcode("reader");
placeholder.classList.add('d-none');
html5QrCode.start(
{ facingMode: "environment" },
{
fps: 10,
qrbox: { width: 250, height: 250 }
},
(decodedText) => {
if (!isScanningLocked) {
isScanningLocked = true;
playBeep(true);
verifyToken(decodedText);
setTimeout(() => { isScanningLocked = false; }, 2500);
}
},
(errorMessage) => {
// Errores normales de lectura frame a frame, se omiten
serialScanner = new SerialBarcodeScanner({
baudRate: 9600,
onCodeScanned: function(code) {
if (!isScanningLocked) {
isScanningLocked = true;
playBeep(true);
verifyToken(code);
setTimeout(() => { isScanningLocked = false; }, 1500);
}
).then(() => {
isCameraRunning = true;
btn.innerHTML = '<i class="bi bi-stop-circle me-1"></i> Detener Cámara';
btn.classList.replace('btn-outline-primary', 'btn-danger');
}).catch(err => {
console.error("Error al iniciar cámara:", err);
placeholder.classList.remove('d-none');
alert("No se pudo acceder a la cámara. Asegúrate de otorgar los permisos en el navegador.");
});
},
onStatusChanged: function(evt) {
const badge = document.getElementById('serialPortStatusBadge');
const btn = document.getElementById('btnConnectSerial');
if (evt.status === 'CONNECTED') {
if (badge) {
badge.className = 'badge bg-success text-white rounded-pill px-2 py-1 small';
badge.innerHTML = '<i class="bi bi-usb-plug-fill me-1"></i> COM Activo (9600 baud)';
}
if (btn) {
btn.className = 'btn btn-xs btn-outline-danger rounded-pill px-3 py-1 text-nowrap';
btn.innerHTML = '<i class="bi bi-x-circle me-1"></i>Desconectar';
}
} else {
if (badge) {
badge.className = 'badge bg-secondary-subtle text-secondary rounded-pill px-2 py-1 small';
badge.innerHTML = '<i class="bi bi-circle-fill text-muted me-1" style="font-size: 0.5rem;"></i> Puerto USB-HID Activo';
}
if (btn) {
btn.className = 'btn btn-xs btn-outline-secondary rounded-pill px-3 py-1 text-nowrap';
btn.innerHTML = '<i class="bi bi-link-45deg me-1"></i>Configurar COM';
}
}
},
onError: function(err) {
console.warn('[SerialScanner UI] Error:', err);
}
});
// Comprobar soporte
if (!serialScanner.isSupported()) {
const badge = document.getElementById('serialPortStatusBadge');
const btn = document.getElementById('btnConnectSerial');
if (badge) {
badge.className = 'badge bg-body-tertiary text-muted rounded-pill px-2 py-1 small border';
badge.textContent = 'Modo USB-HID (Chromium requerido para COM)';
}
if (btn) btn.disabled = true;
} else {
// Intentar auto-conexión a puerto previamente autorizado
serialScanner.autoConnectIfAuthorized();
}
}
async function handleSerialConnectClick() {
if (!serialScanner) initSerialScanner();
if (!serialScanner.isSupported()) {
alert('La Web Serial API no está disponible en este navegador. Utiliza Google Chrome o Microsoft Edge en entornos Windows.');
return;
}
const btn = document.getElementById('btnConnectSerial');
if (serialScanner.port) {
await serialScanner.disconnect();
} else {
try {
await serialScanner.requestAndConnect(9600);
} catch (err) {
if (err.name !== 'NotFoundError') {
console.error('Error al conectar puerto COM:', err);
alert('No se pudo abrir el puerto serie: ' + err.message);
}
}
}
}
@@ -445,6 +500,7 @@
// Eventos globales para forzar el foco permanente en scannerInput
document.addEventListener('DOMContentLoaded', () => {
initSerialScanner();
focusScannerInput();
setInterval(focusScannerInput, 2000);
@@ -0,0 +1,89 @@
# 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.
---
## 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`.
---
## 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.
@@ -0,0 +1,68 @@
# Especificación SDD-013: Compatibilidad de Escáner QR por Puerto Serie (COM) en Entornos Windows
## 1. Resumen Ejecutivo y Motivación
En los puestos de control de acceso físico e ingreso a sedes de UniCABA (particularmente Edificio Central), las pistolas ópticas y escáneres QR industriales operan frecuentemente conectados a través de interfaces RS-232 o conversores USB-a-Serial (puertos COM virtuales, ej. `COM3`, `COM4`), emulando protocolos de puerto serie en lugar de teclados USB HID estándar.
La emulación de teclado tradicional presenta desventajas operativas en puestos de recepción:
- Requiere retención estricta del foco del cursor en un campo de texto específico (`#scannerInput`), el cual puede perderse si el operador hace clic en otra ventana o aplicación.
- Está sujeta a desajustes de disposición de teclado (`US` vs `ES` / `Latam`), provocando sustitución de caracteres (ej. `:` por `Ñ`).
- No provee confirmación bidireccional sobre si el dispositivo físico está conectado, encendido o transmitiendo datos.
Para resolver esto en terminales con sistema operativo **Windows**, esta especificación introduce compatibilidad nativa con la **Web Serial API** de navegadores basados en **Chromium** (Google Chrome, Microsoft Edge, Brave, Opera), permitiendo la captura directa, asíncrona y en segundo plano de las lecturas ópticas directamente desde el puerto COM hacia el flujo de validación académica en tiempo real de Edu-Space.
---
## 2. Alcance y Límites
- **Sistemas Operativos Compatibles (Fase 1)**: Microsoft Windows 10 y Windows 11.
- **Navegadores Compatibles**: Navegadores con soporte nativo de Web Serial API (`navigator.serial` en contextos seguros HTTPS o `localhost`): Google Chrome (v89+), Microsoft Edge (v89+), Opera (v75+), Brave.
- **Entornos Excluidos**: Mozilla Firefox y Apple Safari (no implementan la Web Serial API por políticas de estándar W3C). En dichos navegadores, la consola continuará operando de manera transparente mediante el modo USB HID / Emulación de Teclado convencional.
---
## 3. Actores del Sistema
- **Operador de Recepción / Seguridad**: Personal institucional que supervisa los accesos peatonales en la sede y configura la conexión con el puerto COM de la pistola.
- **Estudiante / Docente**: Persona que presenta su credencial digital (código QR rotativo) o carnet físico en el punto de control.
- **Administrador del Sistema**: Configura parámetros de sede predeterminada, auditoría y tolerancias de lectura.
---
## 4. Requisitos Funcionales en Sintaxis EARS (Español Estricto)
### 4.1. Requisitos Ubicuos (Comportamiento Permanente)
- **RF-01 (Detección de soporte)**: EL SISTEMA detectará de forma permanente la presencia del objeto `navigator.serial` en la ventana del navegador e informará visualmente al operador la disponibilidad del modo Puerto Serie (COM).
- **RF-02 (Aislamiento de entrada)**: EL SISTEMA procesará las lecturas seriales entrantes de manera desacoplada del foco visual del cursor, permitiendo que la recepción valide accesos aun si el operador tiene abierto otro modal o elemento de la interfaz.
- **RF-03 (Registro de auditoría)**: EL SISTEMA registrará en `AuditLog` cada sesión de conexión o desconexión del puerto serie con el identificador del usuario operador y el puerto asignado.
### 4.2. Requisitos Basados en Eventos (Acción ➔ Respuesta)
- **RF-04 (Solicitud y apertura de puerto)**: CUANDO el operador pulse el botón "Configurar COM", EL SISTEMA invocará `navigator.serial.requestPort()` desplegando el cuadro de diálogo nativo de Windows para que el usuario seleccione el puerto COM deseado (ej. COM3, COM4).
- **RF-05 (Configuración de parámetros seriales)**: CUANDO el operador confirme la selección del puerto, EL SISTEMA abrirá la conexión serie (`port.open()`) aplicando una tasa de baudios predeterminada de 9600 baudios, 8 bits de datos, 1 bit de parada y sin paridad (9600 8-N-1), con opción de alternar a 115200 baudios.
- **RF-06 (Bufferizado y corte por delimitador)**: CUANDO el lector serie transmita fragmentos de bytes, EL SISTEMA decodificará el flujo mediante `TextDecoderStream` y acumulará los caracteres en un buffer hasta detectar un delimitador de fin de línea (`\r`, `\n` o `\r\n`).
- **RF-07 (Disparo de verificación automática)**: CUANDO el buffer complete una cadena de escaneo delimitada, EL SISTEMA emitirá un tono sonoro de captura (`playBeep`), normalizará los caracteres (reemplazo tolerante de scancodes si aplica) y despachará la petición HTTP POST a `/reception/verify`.
### 4.3. Requisitos Basados en Estados (Activo mientras se cumpla una condición)
- **RF-08 (Monitoreo de estado de conexión)**: MIENTRAS el puerto serie permanezca abierto y transmitiendo (`port.readable !== null`), EL SISTEMA exhibirá un badge visual con pulso verde activo: `● Puerto COM Conectado (COMx - 9600 baud)`.
- **RF-09 (Reconexión automática persistente)**: MIENTRAS el operador permanezca en la sesión de navegación y haya autorizado previamente un puerto serial, EL SISTEMA intentará reabrir automáticamente el puerto conocido mediante `navigator.serial.getPorts()` sin requerir volver a solicitar el permiso de Windows.
### 4.4. Requisitos de No Deseado / Excepciones (Manejo de Errores)
- **RF-10 (Navegador no compatible)**: SI el navegador web no soporta la Web Serial API (`"serial" in navigator === false`), ENTONCES EL SISTEMA mantendrá deshabilitado el control COM, exhibirá una insignia explicativa `"Modo USB-HID Estándar (Chromium requerido para COM)"` y continuará operando normalmente con el teclado/pistola óptica.
- **RF-11 (Desconexión física o extracción del cable USB)**: SI el cable USB del conversor serie es desconectado físicamente mientras el lector está operando, ENTONCES EL SISTEMA capturará el evento `disconnect` de `navigator.serial`, liberará los bloqueos de stream (`releaseLock`), cerrará el puerto de manera segura, actualizará el badge a `"Puerto COM Desconectado"` y alertará al operador sin interrumpir la ejecución de la aplicación.
- **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.
---
## 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**.
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()`).
---
## 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.
@@ -0,0 +1,40 @@
# Tareas de Implementación SDD-013: Escáner QR por Puerto Serie (COM) en Chromium Windows
## Tarea 1: Depuración de la Consola de Recepción (Sede Física y Eliminación de Cámara)
- **Objetivo**: Asegurar que solo se listen sedes presenciales/físicas, predeterminar Edificio Central y remover totalmente el código y librerías de escáner por cámara web.
- **Archivos**: `frontend/src/routes/reception.js`, `frontend/views/reception/scanner.html`.
- **Hecho cuando**:
- El selector `#buildingSelect` solo contiene sedes físicas (sin Campus Virtual) y tiene seleccionada la sede `Edificio Central` por defecto.
- Se eliminó la librería `html5-qrcode` y el visor de cámara de la interfaz.
## Tarea 2: Módulo Cliente `SerialBarcodeScanner` (Web Serial API)
- **Objetivo**: Crear el módulo JavaScript reutilizable que encapsula la Web Serial API para lectores ópticos y pistolas serie.
- **Archivos**: `frontend/public/js/serial-scanner.js`.
- **Hecho cuando**:
- `SerialBarcodeScanner` detecta la disponibilidad de `navigator.serial`.
- Permite solicitar y abrir un puerto COM con baudRate configurable (9600 predeterminado).
- Lee los bytes entrantes mediante `TextDecoderStream` y emite eventos `onCodeScanned` ante delimitadores `\r` y `\n`.
- Maneja la liberación de recursos (`releaseLock`) y cierre seguro de puertos.
## Tarea 3: Integración de UI de Puerto Serie en la Consola de Recepción
- **Objetivo**: Conectar `SerialBarcodeScanner` con la interfaz de `scanner.html` y el despachador de verificación `/reception/verify`.
- **Archivos**: `frontend/views/reception/scanner.html`.
- **Hecho cuando**:
- El botón "Configurar COM" abre el diálogo de selección de puertos serie de Windows en Chromium.
- El badge refleja visualmente el estado: "COM Conectado (COMx)", "Puerto USB-HID Activo" o "No Soportado".
- Las lecturas entrantes por puerto COM disparan automáticamente `verifyToken()` mostrando el titular y sus clases del día sin requerir foco en el input.
## Tarea 4: Resiliencia ante Desconexión y Reconexión Automática
- **Objetivo**: Manejar desconexiones físicas de cables USB/Serial y reabrir puertos autorizados al recargar la página.
- **Archivos**: `frontend/public/js/serial-scanner.js`, `frontend/views/reception/scanner.html`.
- **Hecho cuando**:
- El evento `navigator.serial.addEventListener('disconnect', ...)` actualiza el estado a "Desconectado" limpiamente.
- Al recargar la página, `navigator.serial.getPorts()` reabre el puerto autorizado automáticamente si sigue conectado.
## Tarea 5: Validación Cruzada, Suite de Pruebas y Despliegue en Producción
- **Objetivo**: Verificar que la suite de pruebas automatizadas del backend se ejecute al 100%, realizar bump semántico de versión, commit, git push a `dev` y despliegue al servidor institucional LXC `10.0.0.217`.
- **Archivos**: `backend/tests/`, `package.json`, `app.js`, `CHANGELOG.md`, `MEMORY.md`.
- **Hecho cuando**:
- `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`.