# 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`](https://gitea.oemspot.com.ar/carlostellocba/OnEverControl). --- ### Resumen Visual de Fases ```text [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. * **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 `videoman` y documentación de placas ST1660. * **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 (ESTADO: COMPLETADA) * **Objetivos:** - Crear la estructura completa de carpetas y configuración inicial en `OnEverControl/backend` y `OnEverControl/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`) usando `pymssql` compatible 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). * **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 `/health` y 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 en `CHANGELOG.md` y subido al repositorio oficial de Gitea (`https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`). * **Dependencias:** - Conectividad a la instancia de SQL Server `videoman`. * **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 (ESTADO: COMPLETADA) * **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). - Desarrollar los endpoints RESTful para: - `/api/v1/control-posts`: Validación de `workstation_name` para tablets y PCs (`es_puesto_de_control` y `listar_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 relaciones `peraut`. - `/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 en `tck`, `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. * **Entregables:** - Routers, esquemas Pydantic v2 y repositorios SQL implementados en el backend. - Tests unitarios y de integración con `pytest` para 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. --- ### Fase 3: Desarrollo del Frontend (Interfaz Web Touch-First para Tablets y Garitas) (ESTADO: COMPLETADA) * **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 `100dvh` que 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. - 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. * **Entregables:** - SPA PWA completamente funcional en React + TypeScript + Vite, testeada y optimizada para tablets Samsung Galaxy Tab A9 y A11 (4GB RAM). - 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 (ESTADO: COMPLETADA) * **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 modal optimizado para decodificar DNI (PDF417/QR) en tiempo real con la cámara de la tablet, con liberación inmediata de hardware. - **WebSockets en Tiempo Real:** Implementar endpoint WebSocket nativo en FastAPI y hook `useWebSocket` en React para sincronizar eventos instantáneos (apertura completada, alertas de antipassback, nuevas preautorizaciones). * **Entregables:** - Módulos `hardware_service.py` y componentes de escáner óptico operativos y probados. - Despacho de órdenes de apertura verificado en la tabla `pdtmdl` y recibido por `OnEverWPC`. * **Dependencias:** - Servicio `OnEverWPC` escuchando `pdtmdl` en la red local. * **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 (ESTADO: COMPLETADA) * **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 (ESTADO: COMPLETADA) * **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.py` en 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.