12 KiB
12 KiB
ROADMAP DEL PROYECTO: PUESTO DE CONTROL WEB (OnEverControl)
Hoja de Ruta de Desarrollo y Despliegue por Etapas (Modo Cliente Web Reducido)
Este documento define el roadmap estructurado para el desarrollo, integración, validación y puesta en marcha de la versión reducida solo web en modo cliente (Thin Client) de OnEverControl. Su alcance se enfoca exclusivamente en la migración del Login y del Puesto de Control operativo para operar a través de la red local (LAN) donde ya funciona OnEverAccess, utilizando FastAPI + Pydantic v2 (Python) en el backend y React + TypeScript + Vite en el frontend, bajo control de versiones publicado en Gitea: https://gitea.oemspot.com.ar/carlostellocba/OnEverControl.
Resumen Visual de Fases
[Fase 0: Análisis & Diseño] ➔ [Fase 1: Arquitectura & Setup Base] ➔ [Fase 2: Backend Core & APIs]
│
[Fase 5: Pruebas & QA] [Fase 4: Integración Hardware/Cámaras] [Fase 3: Frontend Web SPA]
│
▼
[Fase 6: Piloto & Migración] ➔ [Fase 7: Puesta en Producción] ➔ [Fase 8: Mejoras Posteriores]
Detalle de Fases de Ejecución
Fase 0: Análisis, Diseño y Definición de Arquitectura (ESTADO: COMPLETADA)
- Objetivos:
- Auditar exhaustivamente la lógica del sistema actual de escritorio (
OemspotPySYS/puestocontrol/). - Identificar todas las dependencias con bases de datos, hardware industrial, protocolos seriales y cámaras.
- Diseñar la arquitectura desacoplada para la versión web con FastAPI y definir el stack tecnológico óptimo.
- Elaborar el informe técnico maestro y el modelo de datos para guiar el desarrollo.
- Auditar exhaustivamente la lógica del sistema actual de escritorio (
- Entregables:
OnEverControl/INFORME_TECNICO_PUESTO_DE_CONTROL_WEB.md(Informe Técnico y Arquitectura).OnEverControl/ROADMAP.md(Este documento).OnEverControl/README.md(Guía inicial del proyecto).
- Dependencias:
- Acceso al repositorio actual, esquemas de tablas SQL Server
videomany documentación de placas ST1660.
- Acceso al repositorio actual, esquemas de tablas SQL Server
- Riesgos y Mitigación:
- Riesgo: Desalineación en cómo resolver los puertos COM locales en web.
- Mitigación: Se definió el estándar USB HID (teclado) y Web Serial API, manteniendo el encolado en
pdtmdl.
Fase 1: Arquitectura y Base del Proyecto
- Objetivos:
- Crear la estructura completa de carpetas y configuración inicial en
OnEverControl/backendyOnEverControl/frontend. - Configurar los entornos de despliegue agnósticos: Docker Compose, script de instalación LXC (systemd / FreeTDS) y servicio para Windows 10/11 (NSSM).
- Establecer el pool de conexiones asíncrono hacia Microsoft SQL Server (
videoman) usandopymssqlcompatible con Linux y Windows. - Configurar middlewares de seguridad (CORS, compresión gzip, logging estructurado, manejo centralizado de excepciones).
- Inicializar el proyecto frontend en React + TypeScript + Vite con arquitectura modular por componentes, estado liviano y servicio de UI táctil (OnEver Design System).
- Crear la estructura completa de carpetas y configuración inicial en
- Entregables:
- Archivos de configuración
.env.example,docker-compose.yml, scripts de despliegue para Windows (scripts/windows/) y LXC (scripts/lxc/). - Esqueleto del backend FastAPI con endpoint
/healthy documentación Swagger activa en/docs. - Esqueleto del frontend en React + TypeScript + Vite con layout táctil base responsive (100dvh) optimizado para tablets Samsung Galaxy Tab A9/A11 (4GB RAM).
- Script automatizado de verificación de conectividad con la base de datos SQL Server (
test_sql_connection.py) ejecutable en Windows y Linux. - Control de versión inicial (
v0.1.0) configurado en backend y frontend, registrado enCHANGELOG.mdy subido al repositorio oficial de Gitea (https://gitea.oemspot.com.ar/carlostellocba/OnEverControl).
- Archivos de configuración
- Dependencias:
- Conectividad a la instancia de SQL Server
videoman.
- Conectividad a la instancia de SQL Server
- Riesgos y Mitigación:
- Riesgo: Latencias o fallos de conexión en Windows/Linux con pymssql.
- Mitigación: Reutilizar los patrones de conexión y timeouts probados en
db_config.py.
Fase 2: Backend / API Core con FastAPI
- Objetivos:
- Implementar el módulo de autenticación con JWT (Cookies HttpOnly) y control de roles basado en
UsrCatVal. - Migrar y adaptar la lógica pura de negocio de Python:
- Parser de DNI argentino (
herramientas/parser_dni.py). - Lógica de validación de antipassback (
verificar_antipassback). - Validación y vigencia de pólizas (ART, Conductor, Seguro Automotor).
- Parser de DNI argentino (
- Desarrollar los endpoints RESTful para:
/api/v1/control-posts: Validación deworkstation_namepara tablets y PCs (es_puesto_de_controlylistar_modulos_por_workstation)./api/v1/people: Búsqueda de personas por DNI, búsqueda predictiva por texto, altas y consultas./api/v1/vehicles: Búsqueda de vehículos por patente y relacionesperaut./api/v1/lots: Búsqueda de lotes y validación de estados de permiso./api/v1/preauthorizations: Búsqueda y consumo atómico de preautorizaciones./api/v1/access/entry: Registro de ingreso vehicular y peatonal (atómico entck,tckper,tckprx,mvthist)./api/v1/access/exit: Consulta de ticket activo y registro de egreso (con desacople de acompañantes)./api/v1/access/inside: Consulta del padrón de visitas dentro del predio./api/v1/access/mass-exit: Salida masiva de personal con auditoría.
- Implementar el módulo de autenticación con JWT (Cookies HttpOnly) y control de roles basado en
- Entregables:
- Routers, esquemas Pydantic v2 y repositorios SQL implementados en el backend.
- Tests unitarios y de integración con
pytestpara cada flujo de negocio crítico.
- Dependencias:
- Finalización de Fase 1.
- Riesgos y Mitigación:
- Riesgo: Inconsistencias al replicar transacciones complejas de
pct_repository.py. - Mitigación: Pruebas cruzadas validando que los registros generados por FastAPI sean idénticos a los de PyQt.
- Riesgo: Inconsistencias al replicar transacciones complejas de
Fase 3: Desarrollo del Frontend (Interfaz Web Touch-First para Tablets y Garitas)
- Objetivos:
- Construir la interfaz de usuario con diseño táctil prioritario (Touch-First) para tablets (Android, Windows e iPad):
- Touch targets generosos (mínimo 48 x 48 px) para operación ágil táctil.
- Layout adaptativo con
100dvhque impide que el teclado virtual en pantalla tape los botones de acción (Confirmar Ingreso,Cancelar). - Atributos
inputmode="numeric"para desplegar teclado numérico automático en DNI y cantidades. - Soporte de orientación horizontal (Landscape) y vertical (Portrait).
- Modo PWA Standalone (instalable sin barras de navegación del navegador).
- Acceso a las cámaras integradas de la tablet (trasera y frontal) con Barcode Detection API y ZXing Wasm/JS para escanear DNI (PDF417 y QR) en tiempo real, reemplazando totalmente lectores físicos COM o emuladores de teclado.
- Implementar la experiencia híbrida "Touch + Keyboard":
- Atajos de teclado físico para puestos con teclado (
F2,F4,Enter,Esc). - Búsqueda manual rápida por número de documento o nombre.
- Atajos de teclado físico para puestos con teclado (
- Desarrollar los drawers y diálogos táctiles interactivos:
- Búsqueda predictiva de personas y vehículos.
- Selector táctil de lotes con indicación visual de permisos.
- Búsqueda y consumo de preautorizados.
- Diálogo interactivo de acompañantes (
DialogoRegistroIntegrantes). - Diálogo de verificación y desacople de acompañantes en salida.
- Padrón de ingresados con filtros rápidos táctiles y salida masiva.
- Implementar persistencia de sesiones de carril interrumpidas.
- Construir la interfaz de usuario con diseño táctil prioritario (Touch-First) para tablets (Android, Windows e iPad):
- Entregables:
- SPA PWA completamente funcional en Node.js, testeada y optimizada para tablets táctiles (Android, Windows, iPad).
- Suite de pruebas de componentes y validación de formularios en frontend.
- Dependencias:
- Disponibilidad de los endpoints de Fase 2.
- Riesgos y Mitigación:
- Riesgo: Iluminación deficiente o reflejos al escanear el DNI con la cámara de la tablet en el carril.
- Mitigación: Visor de cámara con guía visual de encuadre, selector de cámara trasera con autofoco continuo y fallback inmediato para tipeo manual rápido del número de DNI.
Fase 4: Integración con Hardware, Escaneo Óptico y Tiempo Real
- Objetivos:
- Encolado de Hardware: Implementar en el backend FastAPI la inserción formateada de tramas de apertura y comandos de tickets en la tabla
pdtmdl(O3,O5,O1,V3,V6,T9). - Escaneo Óptico y Captura con Cámara de la Tablet: Integración en el frontend de la Barcode Detection API y ZXing (Wasm/JS) para decodificar DNI (PDF417/QR) en tiempo real con la cámara de la tablet, capturando simultáneamente la foto de evidencia.
- WebSockets en Tiempo Real: Implementar endpoint WebSocket nativo en FastAPI y hook
useWebSocketen React para sincronizar eventos instantáneos (apertura completada, alertas de antipassback, nuevas preautorizaciones).
- Encolado de Hardware: Implementar en el backend FastAPI la inserción formateada de tramas de apertura y comandos de tickets en la tabla
- Entregables:
- Módulos
hardware_service.pyy componentes de escáner óptico operativos y probados. - Despacho de órdenes de apertura verificado en la tabla
pdtmdly recibido porOnEverWPC.
- Módulos
- Dependencias:
- Servicio
OnEverWPCescuchandopdtmdlen la red local.
- Servicio
- Riesgos y Mitigación:
- Riesgo: Desconexión temporal de la tablet de la red Wi-Fi durante el envío de apertura.
- Mitigación: Reintento automático con feedback háptico en pantalla indicando estado de conexión con el servidor.
Fase 5: Pruebas Integrales, QA y Stress Testing
- Objetivos:
- Realizar pruebas integrales de punta a punta (E2E) simulando el flujo real de guardias en horas pico.
- Pruebas de estrés y latencia:
- Tiempo de respuesta de búsqueda de persona < 100 ms.
- Tiempo de encolado de apertura de barrera en
pdtmdl< 20 ms. - Tiempo de renderizado de la UI tras escaneo de DNI < 50 ms.
- Verificación de casos extremos y ergonomía táctil:
- Validación en tablets reales (iPadOS / Safari, Android / Chrome, Windows Surface / Edge).
- Despliegue de teclado virtual sin oclusión de botones de confirmación.
- Escaneo con DNI dañado o caracteres especiales.
- Vehículo con 5 acompañantes donde 2 salen a pie y 1 se queda en el lote.
- Desconexión temporal de red y recuperación automática de WebSockets.
- Entregables:
- Reporte de aseguramiento de calidad (QA Test Matrix).
- Suite de pruebas E2E automatizadas con Playwright.
- Dependencias:
- Fase 3 y Fase 4 completadas.
- Riesgos y Mitigación:
- Riesgo: Descubrimiento de discrepancias con el sistema legado VB6 o PyQt.
- Mitigación: Comparación directa de transacciones en la base de datos contra el entorno de pruebas.
Fase 6: Despliegue Piloto y Convivencia Híbrida
- Objetivos:
- Desplegar la versión web en una garita piloto en el entorno elegido (Windows 10/11 bare-metal, LXC en Proxmox o Docker Compose).
- Validar la convivencia híbrida en producción: ingresos registrados en la web cerrados en el sistema de escritorio, y viceversa.
- Capacitar a los guardias en la nueva interfaz web y recolectar feedback de usabilidad en el puesto de trabajo.
- Entregables:
- Servidor web productivo desplegado en red local con Nginx y FastAPI (Windows Service, contenedor LXC o contenedor Docker).
- Manual de usuario y guía rápida de atajos de teclado para guardias de seguridad.
- Dependencias:
- Aprobación de Fase 5 y validación por supervisores de seguridad.
- Riesgos y Mitigación:
- Riesgo: Resistencia al cambio o dudas operativas de los guardias.
- Mitigación: Interfaz visualmente idéntica en colores y lógica a la versión PyQt para curva de aprendizaje cero.
Fase 7: Puesta en Producción y Migración Total
- Objetivos:
- Habilitar la versión web en todos los puestos de control del predio (Garitas Principales, Secundarias y Peatonales).
- Retirar gradualmente la aplicación de escritorio
pct_view.pyen los puestos operativos, conservándola como respaldo. - Establecer monitoreo continuo de métricas y rendimiento.
- Entregables:
- Puesta en producción completa (100% web).
- Backup programado y procedimiento de contingencia ante fallos.
- Dependencias:
- Fase 6 exitosa sin incidentes durante 14 días continuos.
- Riesgos y Mitigación:
- Riesgo: Caída del servidor web.
- Mitigación: Configuración de reinicio automático con systemd/Docker y switch inmediato de contingencia al cliente de escritorio si fuera necesario.