feat(reception): filter virtual buildings, remove camera and add SDD-013 Web Serial COM support (v3.8.50)
This commit is contained in:
@@ -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.
|
- **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.
|
- **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
|
## [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)
|
### 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**:
|
- **Corrección Integral del Desfasaje Horario en Registros de Ingreso**:
|
||||||
|
|||||||
@@ -9,11 +9,11 @@ Memoria del proyecto entre sesiones para la rama `dev`.
|
|||||||
- Libro de Calificaciones (*Gradebook*) con actas de regularidad inmutables.
|
- Libro de Calificaciones (*Gradebook*) con actas de regularidad inmutables.
|
||||||
- Autenticación híbrida (Google OAuth 2.0, Moodle SSO, Local) y Modo Impersonación.
|
- 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.
|
- 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)**:
|
- **Sprint Activo: Consola de Recepción Presencial y Lector por Puerto Serie (v3.8.50)**:
|
||||||
- **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.
|
- **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.
|
||||||
- **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`.
|
- **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.
|
||||||
- **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."*
|
- **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.49`.
|
- **Versión Consolidada**: `v3.8.50`.
|
||||||
|
|
||||||
## Decisiones (y por qué)
|
## 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.
|
- **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.
|
||||||
|
|||||||
@@ -7,7 +7,7 @@ from typing import Any
|
|||||||
from database import db, get_db, engine, SessionLocal, session
|
from database import db, get_db, engine, SessionLocal, session
|
||||||
from config.config import Config
|
from config.config import Config
|
||||||
|
|
||||||
__version__ = "3.8.49"
|
__version__ = "3.8.50"
|
||||||
|
|
||||||
class DummyContext:
|
class DummyContext:
|
||||||
def __enter__(self):
|
def __enter__(self):
|
||||||
|
|||||||
+1
-1
@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
|
|||||||
|
|
||||||
setup(
|
setup(
|
||||||
name="edu-space-admin",
|
name="edu-space-admin",
|
||||||
version="3.8.49",
|
version="3.8.50",
|
||||||
description="Administrative interface for Edu-Space Classroom Management System (FastAPI ASGI Core)",
|
description="Administrative interface for Edu-Space Classroom Management System (FastAPI ASGI Core)",
|
||||||
author="Edu-Space Development Team",
|
author="Edu-Space Development Team",
|
||||||
author_email="admin@edu-space.com",
|
author_email="admin@edu-space.com",
|
||||||
|
|||||||
@@ -1,6 +1,6 @@
|
|||||||
{
|
{
|
||||||
"name": "frontend",
|
"name": "frontend",
|
||||||
"version": "3.8.49",
|
"version": "3.8.50",
|
||||||
"description": "",
|
"description": "",
|
||||||
"main": "index.js",
|
"main": "index.js",
|
||||||
"scripts": {
|
"scripts": {
|
||||||
|
|||||||
@@ -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
@@ -86,9 +86,9 @@ const env = nunjucks.configure(path.join(__dirname, '../views'), {
|
|||||||
});
|
});
|
||||||
|
|
||||||
// Versiones institucionales del sistema
|
// Versiones institucionales del sistema
|
||||||
const APP_VERSION = '3.8.49';
|
const APP_VERSION = '3.8.50';
|
||||||
const FRONTEND_VERSION = '3.8.49';
|
const FRONTEND_VERSION = '3.8.50';
|
||||||
const BACKEND_VERSION = '3.8.49';
|
const BACKEND_VERSION = '3.8.50';
|
||||||
|
|
||||||
env.addGlobal('app_version', APP_VERSION);
|
env.addGlobal('app_version', APP_VERSION);
|
||||||
env.addGlobal('frontend_version', FRONTEND_VERSION);
|
env.addGlobal('frontend_version', FRONTEND_VERSION);
|
||||||
|
|||||||
@@ -26,7 +26,24 @@ router.get('/scanner', async (req, res) => {
|
|||||||
req.apiClient.get('/buildings'),
|
req.apiClient.get('/buildings'),
|
||||||
req.apiClient.get('/reception/recent-logs', { params: { limit: 15 } })
|
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 => {
|
recentLogs = (respLogs.data?.items || []).map(l => {
|
||||||
let timeStr = l.scanned_time;
|
let timeStr = l.scanned_time;
|
||||||
if (!timeStr && l.scanned_at) {
|
if (!timeStr && l.scanned_at) {
|
||||||
@@ -45,14 +62,24 @@ router.get('/scanner', async (req, res) => {
|
|||||||
}
|
}
|
||||||
return { ...l, scanned_time: timeStr || '--' };
|
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) {
|
} catch (err) {
|
||||||
console.warn('Reception scanner init notice:', err.message);
|
console.warn('Reception scanner init notice:', err.message);
|
||||||
}
|
}
|
||||||
|
|
||||||
res.render('reception/scanner', {
|
res.render('reception/scanner', {
|
||||||
title: 'Control de Acceso QR — Recepción & Seguridad',
|
title: 'Control de Acceso QR — Recepción & Seguridad',
|
||||||
buildings,
|
buildings: [],
|
||||||
recentLogs,
|
defaultBuildingId: null,
|
||||||
|
recentLogs: [],
|
||||||
userRole: role
|
userRole: role
|
||||||
});
|
});
|
||||||
});
|
});
|
||||||
|
|||||||
@@ -19,11 +19,12 @@
|
|||||||
|
|
||||||
<div class="d-flex align-items-center gap-3">
|
<div class="d-flex align-items-center gap-3">
|
||||||
<div>
|
<div>
|
||||||
<label class="small text-muted fw-bold d-block">Punto de Control / Sede:</label>
|
<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" id="buildingSelect">
|
<select class="form-select form-select-sm rounded-pill px-3 shadow-xs" id="buildingSelect">
|
||||||
<option value="">Todas las Sedes</option>
|
|
||||||
{% for b in buildings %}
|
{% 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 %}
|
{% endfor %}
|
||||||
</select>
|
</select>
|
||||||
</div>
|
</div>
|
||||||
@@ -31,45 +32,68 @@
|
|||||||
</div>
|
</div>
|
||||||
|
|
||||||
<div class="row g-4">
|
<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="col-12 col-lg-5">
|
||||||
<div class="card border-0 shadow-sm rounded-4 p-4 mb-4">
|
<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">
|
<div class="d-flex align-items-center justify-content-between mb-3">
|
||||||
<span><i class="bi bi-camera me-2 text-primary"></i>Lector de Cámara</span>
|
<h5 class="fw-bold mb-0 text-dark d-flex align-items-center">
|
||||||
<button type="button" class="btn btn-sm btn-outline-primary rounded-pill px-3" id="toggleCamBtn" onclick="toggleCamera()">
|
<i class="bi bi-upc-scan me-2 text-primary"></i>Lector Óptico de Acceso
|
||||||
<i class="bi bi-play-circle me-1"></i> Iniciar Cámara
|
</h5>
|
||||||
</button>
|
<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">
|
||||||
</h5>
|
<span class="scanner-active-dot"></span> Lector Listo
|
||||||
|
</span>
|
||||||
|
</div>
|
||||||
|
|
||||||
<!-- Visor de Cámara -->
|
<!-- Banner Informativo de Operación -->
|
||||||
<div id="reader" class="rounded-4 overflow-hidden bg-dark position-relative d-flex align-items-center justify-content-center text-white"
|
<div class="p-3 bg-light rounded-4 border mb-3 text-start">
|
||||||
style="width: 100%; min-height: 280px;">
|
<div class="d-flex align-items-start gap-2">
|
||||||
<div id="cameraPlaceholder" class="text-center p-4">
|
<i class="bi bi-shield-check text-primary fs-5 mt-1"></i>
|
||||||
<i class="bi bi-camera-video display-4 text-secondary mb-2 d-block"></i>
|
<div>
|
||||||
<span class="small text-muted">Cámara en espera. Presiona "Iniciar Cámara" o utiliza un lector óptico USB.</span>
|
<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>
|
||||||
</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="mt-4 pt-3 border-top">
|
||||||
<div class="d-flex align-items-center justify-content-between mb-1">
|
<div class="d-flex align-items-center justify-content-between mb-2">
|
||||||
<label class="form-label small fw-bold text-uppercase text-muted mb-0">
|
<span class="small fw-bold text-uppercase text-muted">
|
||||||
<i class="bi bi-upc-scan me-1 text-primary"></i> Pistola Óptica USB o Entrada Manual
|
<i class="bi bi-usb-symbol me-1 text-primary"></i> Puerto Serie (COM)
|
||||||
</label>
|
</span>
|
||||||
<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="badge bg-secondary-subtle text-secondary rounded-pill px-2 py-1 small" id="serialPortStatusBadge">
|
||||||
<span class="scanner-active-dot"></span> Lector Listo
|
<i class="bi bi-circle-fill text-muted me-1" style="font-size: 0.5rem;"></i> Puerto USB-HID Activo
|
||||||
</span>
|
</span>
|
||||||
</div>
|
</div>
|
||||||
<form id="manualScanForm" onsubmit="handleManualScan(event)">
|
<div class="d-flex align-items-center justify-content-between p-2 rounded-3 bg-body-tertiary border">
|
||||||
<div class="input-group shadow-sm rounded-pill overflow-hidden border border-2 border-primary">
|
<small class="text-muted" style="font-size: 0.74rem;">
|
||||||
<input type="text" class="form-control rounded-start-pill ps-3 border-0" id="scannerInput"
|
Dispositivos Seriales COM (Windows / Chromium)
|
||||||
placeholder="Escanea con la pistola o escribe el DNI..." autofocus autocomplete="off">
|
</small>
|
||||||
<button class="btn btn-primary rounded-end-pill px-4 fw-semibold border-0" type="submit">
|
<button type="button" class="btn btn-xs btn-outline-secondary rounded-pill px-3 py-1 text-nowrap" id="btnConnectSerial" onclick="handleSerialConnectClick()">
|
||||||
Validar
|
<i class="bi bi-link-45deg me-1"></i>Configurar COM
|
||||||
</button>
|
</button>
|
||||||
</div>
|
</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>
|
</div>
|
||||||
</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="card-body p-4 d-flex flex-column justify-content-center text-center" id="resultBody">
|
||||||
<div class="py-5 text-muted" id="waitingState">
|
<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>
|
<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">
|
<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>
|
</p>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
@@ -184,58 +208,89 @@
|
|||||||
</div>
|
</div>
|
||||||
</div>
|
</div>
|
||||||
|
|
||||||
<!-- html5-qrcode Library via CDN -->
|
<!-- Módulo de Web Serial API para lectores ópticos y escáneres QR (SDD-013) -->
|
||||||
<script src="https://cdn.jsdelivr.net/npm/html5-qrcode@2.3.8/html5-qrcode.min.js"></script>
|
<script src="/js/serial-scanner.js"></script>
|
||||||
|
|
||||||
<script>
|
<script>
|
||||||
let html5QrCode = null;
|
|
||||||
let isCameraRunning = false;
|
|
||||||
let isScanningLocked = false;
|
let isScanningLocked = false;
|
||||||
|
let serialScanner = null;
|
||||||
|
|
||||||
// Inicializar o alternar cámara
|
// Inicializar SerialBarcodeScanner para Chromium / Windows
|
||||||
function toggleCamera() {
|
function initSerialScanner() {
|
||||||
const btn = document.getElementById('toggleCamBtn');
|
if (typeof SerialBarcodeScanner === 'undefined') return;
|
||||||
const placeholder = document.getElementById('cameraPlaceholder');
|
|
||||||
|
|
||||||
if (isCameraRunning) {
|
serialScanner = new SerialBarcodeScanner({
|
||||||
if (html5QrCode) {
|
baudRate: 9600,
|
||||||
html5QrCode.stop().then(() => {
|
onCodeScanned: function(code) {
|
||||||
isCameraRunning = false;
|
if (!isScanningLocked) {
|
||||||
btn.innerHTML = '<i class="bi bi-play-circle me-1"></i> Iniciar Cámara';
|
isScanningLocked = true;
|
||||||
btn.classList.replace('btn-danger', 'btn-outline-primary');
|
playBeep(true);
|
||||||
placeholder.classList.remove('d-none');
|
verifyToken(code);
|
||||||
});
|
setTimeout(() => { isScanningLocked = false; }, 1500);
|
||||||
}
|
|
||||||
} 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
|
|
||||||
}
|
}
|
||||||
).then(() => {
|
},
|
||||||
isCameraRunning = true;
|
onStatusChanged: function(evt) {
|
||||||
btn.innerHTML = '<i class="bi bi-stop-circle me-1"></i> Detener Cámara';
|
const badge = document.getElementById('serialPortStatusBadge');
|
||||||
btn.classList.replace('btn-outline-primary', 'btn-danger');
|
const btn = document.getElementById('btnConnectSerial');
|
||||||
}).catch(err => {
|
if (evt.status === 'CONNECTED') {
|
||||||
console.error("Error al iniciar cámara:", err);
|
if (badge) {
|
||||||
placeholder.classList.remove('d-none');
|
badge.className = 'badge bg-success text-white rounded-pill px-2 py-1 small';
|
||||||
alert("No se pudo acceder a la cámara. Asegúrate de otorgar los permisos en el navegador.");
|
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
|
// Eventos globales para forzar el foco permanente en scannerInput
|
||||||
document.addEventListener('DOMContentLoaded', () => {
|
document.addEventListener('DOMContentLoaded', () => {
|
||||||
|
initSerialScanner();
|
||||||
focusScannerInput();
|
focusScannerInput();
|
||||||
setInterval(focusScannerInput, 2000);
|
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`.
|
||||||
Reference in New Issue
Block a user