Files
OnEverControl/ROADMAP.md
T

14 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 y Estado

[Fase 0: ✔ COMPLETADA] ➔ [Fase 1: ✔ COMPLETADA] ➔ [Fase 2: ✔ COMPLETADA] 
                                                                 │
[Fase 5: ✔ COMPLETADA]  [Fase 4: ✔ COMPLETADA]  [Fase 3: ✔ COMPLETADA]
          │
          ▼
[Fase 6: ✔ COMPLETADA] ➔ [Fase 7: ⏳ PENDIENTE] ➔ [Fase 8: ⏳ PENDIENTE]

Tabla de Progreso de Fases

Fase Título / Alcance Estado Versión Hitos Clave
Fase 0 Análisis, Diseño y Arquitectura COMPLETADA - Informe maestro, constitución, arnés de IA, especificaciones SDD.
Fase 1 Arquitectura y Setup Base COMPLETADA v0.1.0-alpha Backend FastAPI (/health), React Vite SPA, Docker, LXC, Windows NSSM.
Fase 2 Backend Core y Control de Accesos COMPLETADA v0.5.0-beta JWT, passwords legacy VB6, DNI parser multiformato, antipassback, TicketID.
Fase 3 Frontend Web Cockpit Touch-First COMPLETADA v0.5.0-beta SPA React TS para tablets Galaxy Tab A9/A11 (4GB RAM), autocompletado lotes.
Fase 4 Hardware, Escaneo Óptico y WebSockets COMPLETADA v0.5.0-beta Encolado en pdtmdl, cámara tablet (BarcodeDetector), WebSockets live.
Fase 5 Pruebas Integrales, QA y Stress Testing COMPLETADA v0.5.0-beta 28 tests pytest aprobados, latencia hardware 72ms, build Vite < 55KB gzip.
Fase 6 Despliegue Piloto y Convivencia Híbrida COMPLETADA v0.6.0-beta Compatibilidad Desktop/Web validada, PWA Kiosco, manuales garita y piloto.
Fase 7 Puesta en Producción y Migración Total PENDIENTE v1.0.0 Habilitación en todas las garitas, retiro gradual de desktop, monitoreo.
Fase 8 Mejoras Posteriores y Analítica PENDIENTE v1.1.0+ Reconocimiento LPR embebido, analítica de flujo en carriles.

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.