Files
OnEverControl/ROADMAP.md
T

205 lines
14 KiB
Markdown

# 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 y Estado
```text
[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.