Files
OnEverControl/INFORME_TECNICO_PUESTO_DE_CONTROL_WEB.md
T

588 lines
50 KiB
Markdown

# INFORME TÉCNICO Y PROPUESTA DE ARQUITECTURA
## Sistema "Puesto de Control" — Versión Web (OnEverControl)
**Proyecto:** Migración y Modernización de Puesto de Control a Arquitectura Web (Backend: FastAPI + Pydantic v2 | Frontend: React + TypeScript + Vite)
**Autor:** Antigravity (Advanced Agentic AI Assistant)
**Fecha:** Octubre 2026
**Ubicación de Documentación:** `OnEverControl/`
**Estado:** Fase 0 — Análisis, Diseño y Definición de Arquitectura
---
## 1. Análisis del Sistema Actual
### 1.1. Contexto, Propósito y Alcance Reducido ("Modo Cliente Web")
**OnEverControl** se concibe estrictamente como un **Modo Cliente Web Ligero (Thin Client)**. No tiene por objetivo migrar ni duplicar los módulos administrativos centrales de la suite completa `OemspotPySYS` / `OnEverAccess` (como altas maestras de socios, liquidaciones, configuración de infraestructura de bajo nivel o reportes contables).
Su alcance está específicamente acotado y enfocado a dos módulos clave:
1. **Módulo de Login / Autenticación:** Inicio y cierre de sesión del operador/guardia validando credenciales y privilegios existentes en la base de datos `videoman`.
2. **Módulo de Puesto de Control:** La operativa de garita en tiempo real para autorizar ingresos y egresos (peatonales y vehiculares), lectura de DNI, validación de pólizas, gestión de acompañantes, control de antipassback y encolado de comandos de apertura de barrera (`pdtmdl`).
**Objetivo de Despliegue en Red Local:**
El sistema está diseñado para ser desplegado dentro de la **red local (LAN) donde ya se encuentra en funcionamiento operativo OnEverAccess** (junto a su base de datos SQL Server y su daemon de hardware `OnEverWPC`). Esto permite que cualquier terminal de garita, notebook de guardia, tablet perimetral o PC secundaria de la intranet acceda instantáneamente al puesto de control mediante un navegador web, eliminando la necesidad de instalar dependencias de Python, entornos gráficos PyQt6 o librerías locales en cada puesto físico.
### 1.2. Mapeo de Funcionalidades Actuales
A partir de la inspección exhaustiva de los módulos de escritorio (`puestocontrol/pct_view.py`, `pct_repository.py`, `pct_dialogs.py`, `pct_integrantes_dialog.py`, `pct_salida_integrantes_dialog.py`, `pct_session_manager.py` y `pct_threads.py`), se identifican las siguientes funcionalidades operativas:
1. **Gestión de Carriles Multi-Pestaña y Workstations:**
- La aplicación detecta el nombre de la máquina física (`get_workstation_name()`), consulta en la base de datos si es un puesto de control válido (`es_puesto_de_control`) y recupera los módulos/carriles asignados a dicha estación (`listar_modulos_por_workstation`).
- Cada carril opera en una pestaña independiente que puede estar configurada en sentido **Entrada** o **Salida**.
2. **Lectura y Decodificación de Documentos de Identidad (DNI):**
- Recepción de cadenas crudas desde escáneres de código de barras/QR (PDF417 de DNI argentino y QR de Renaper / Mi Argentina).
- Parsing automático de documento, apellido, nombre y sexo mediante `herramientas/parser_dni.py` (soportando formatos 2009, 2012, 2026 y digital).
3. **Búsqueda Avanzada y Predictiva de Personas:**
- Búsqueda por documento, por coincidencia fonética/parcial de apellido y nombre (`buscar_personas_avanzado`), o selección directa desde el padrón general (`Per`).
4. **Búsqueda y Asociación Vehicular por Patente:**
- Búsqueda predictiva por dominio/patente (`buscar_vehiculos_coincidencias`).
- Autocompletado del conductor habitual asociado a la patente (`peraut`).
- Asociación dinámica de vehículos a personas al momento del ingreso.
5. **Gestión de Preautorizaciones:**
- Consulta de visitas o proveedores autorizados previamente por propietarios de lotes (`obtener_preautorizados_activos`).
- Verificación de fechas de vigencia y consumo automático de la preautorización al registrar el ingreso (`consumir_preautorizacion`).
6. **Selección y Validación de Destino (Lote / Unidad Funcional):**
- Búsqueda interactiva de lotes por número o calle (`Lot`).
- Validación reactiva del estado del lote (al día, restringido, obras suspendidas, etc. vía `obtener_permiso_lote`).
- Consulta de residentes del lote (`obtener_residentes_lote`).
7. **Control de Documentación y Pólizas de Seguro:**
- Registro de Conducir: número, entidad emisora, vigencia desde/hasta.
- Póliza de Seguro ART (obligatoria para proveedores y trabajadores de obra).
- Póliza de Seguro Automotor: aseguradora, póliza, vigencias.
- Notificación visual de campos obligatorios o vencidos con validación reactiva de fechas.
8. **Gestión Integral de Acompañantes / Integrantes Vehiculares:**
- Diferenciación de roles: Conductor vs. Peatón/Acompañante.
- Selector numérico de ocupantes (adultos y menores).
- Diálogo de registro rápido de acompañantes (`DialogoRegistroIntegrantes`) que permite escanear secuencialmente los DNI de cada pasajero.
- Desacople y control en salida: Al egresar un vehículo con acompañantes, el sistema permite marcar quiénes salen en el coche, quiénes egresan a pie y quiénes permanecen en el predio (convirtiéndose de forma atómica en peatones dentro del barrio para evitar alertas de seguridad o evasiones).
9. **Control de Antipassback:**
- Verificación previa si la persona ya posee un ticket activo adentro (`verificar_antipassback`).
- Si se detecta violación de antipassback, el sistema muestra un banner de alerta destacado y un botón de un clic ("🚪 Ir a Salida") que traslada el contexto directamente al carril de egreso.
10. **Generación y Registro del Ticket de Ingreso:**
- Inserción atómica del ticket principal (`tck`), personas asociadas (`tckper`), metadatos dinámicos (`tckprx`) y registro histórico de movimientos (`mvthist`).
- Encolado de la orden de apertura física de barrera/molinete en la tabla `pdtmdl`.
- Encolado opcional de orden de impresión de comprobante/ticket con código de barras (`T9`) para tótems expendedores.
11. **Registro y Validación de Salida:**
- Localización rápida del ingreso activo por documento, patente o selección desde el padrón de ingresados (`DialogoTicketActivoSalida`).
- Cálculo del tiempo de permanencia transcurrido.
- Checkbox de cacheo a la salida y verificación de baúl inspeccionado.
- Cierre del ticket activo, archivado a histórico (`tckhst`) y apertura de la barrera de egreso.
12. **Padrón de Visitas Ingresadas (En Tiempo Real):**
- Grilla de todas las personas y vehículos actualmente dentro del predio (`obtener_ingresados`).
- Filtros multicriterio por nombre, DNI, lote y patente.
13. **Herramienta de Salida Masiva:**
- Diálogo administrativo (`DlgSalidaMasiva`) para desalojar en bloque a obreros o visitas ante fin de jornada laboral o toque de queda nocturno.
14. **Streaming de Video y Captura de Evidencia Fotográfica:**
- Conexión vía HTTP Digest ISAPI con cámaras IP Hikvision (`VideoStreamThread`) para monitorear el carril vehicular y el rostro del ingresante a ~15 FPS.
- Captura manual o automática de fotos de carril / rostro / DNI asociadas al evento de acceso.
- Soporte para captura mediante webcam USB local (`LocalCameraThread`).
15. **Persistencia de Sesiones de Carril Pendientes:**
- Mecanismo en memoria y archivo JSON temporal (`CarrilProcessSessionManager`) para pausar la carga de un vehículo con múltiples integrantes si el guardia debe atender una emergencia en otro carril, evitando perder lo escaneado.
---
### 1.3. Matriz de Clasificación de Funcionalidades
| Funcionalidad | Clasificación | Justificación y Estrategia en la Versión Web |
| :--- | :---: | :--- |
| **Ingreso y Salida de Visitas/Proveedores** | **Mantener y Mejorar** | Es el núcleo del negocio. Debe mantenerse 100% equivalente en reglas de validación pero con una UI más fluida, reactiva y táctil/keyboard-first. |
| **Parsing de DNI (Formatos 2009/2012/2026/App)** | **Mantener** | La lógica matemática y de expresiones regulares actual de `parser_dni.py` es excelente y debe trasladarse al backend FastAPI, con validación espejo en frontend para respuesta instantánea. |
| **Gestión de Integrantes y Desacople en Salida** | **Mantener y Modernizar** | El flujo actual requiere múltiples diálogos emergentes modales de PyQt. En web, se modernizará mediante un drawer lateral o wizard interactivo dentro de la misma pantalla del carril, reduciendo clics. |
| **Consulta de Preautorizados y Consumo** | **Mantener y Potenciar** | En web se integrará con actualización en tiempo real (WebSockets), de modo que si un vecino autoriza una visita desde su app móvil, el puesto de control lo vea de inmediato sin presionar "refrescar". |
| **Encolado de Comandos de Hardware (`pdtmdl`)** | **Mantener** | La tabla `pdtmdl` es el estándar probado y seguro que desacopla la aplicación de las placas ST1660. El backend FastAPI insertará en `pdtmdl` de forma asíncrona garantizando tiempos de respuesta menores a 10 ms. |
| **Padrón de Ingresados y Salida Masiva** | **Mantener y Modernizar** | Grilla web reactiva con filtros rápidos, paginación virtualizada y selección masiva con confirmación segura. |
| **Streaming de Cámaras Hikvision por ISAPI** | **Eliminar en Versión Web** | No se utiliza en la versión cliente web. Elimina sobrecarga de red Wi-Fi y consumo de batería en las tablets de garita. El monitoreo de video perimetral continuo permanece donde corresponde: en el sistema CCTV/NVR de la garita o en la estación central OnEverAccess. La tablet se enfoca exclusivamente en su propia cámara integrada para escanear DNI y capturar fotos de evidencia. |
| **Acceso a Puerto Serial COM y Emulación de Teclado** | **Reemplazar por Cámara de Tablet** | Se eliminan por completo los lectores físicos externos de código de barras/QR (puerto COM y USB teclado). La lectura de DNI (PDF417 y QR) se realiza directamente con la cámara integrada de la tablet mediante la Barcode Detection API nativa y ZXing Wasm/JS en el frontend, capturando al mismo tiempo la foto de evidencia del documento. |
| **Ventanas Modales Anidadas de PyQt6** | **Eliminar** | Múltiples modales apilados (ej: ventana sobre ventana para fecha, lote, integrantes) degradan la UX web. Se reemplazan por componentes modales modernos tipo Dialog, Drawers y Popovers fluidos. |
| **Dependencia de la variable `COMPUTERNAME` del SO** | **Reemplazar por Workstation Registrada** | Cada tablet se da de alta en la base de datos de OnEverAccess como una Workstation formal (ej: `TABLET_01`), persistida de forma segura en la tablet y validada con las mismas funciones y reglas que una PC Windows. |
| **Nueva: Monitoreo en Tiempo Real Multi-Puesto (WebSocket)** | **Nueva** | Sincronización instantánea de estados entre múltiples garitas o puestos simultáneos (ej: garita principal, garita secundaria, administración central). |
| **Nueva: Modo Operativo Offline Resiliente** | **Nueva** | Cache de operaciones críticas con Service Workers / PWA si ocurre micro-cortes en la red interna de la garita. |
| **Nueva: Telemetría y Métricas en Tiempo Real** | **Nueva** | Dashboard de tiempos de atención por guardia, picos de flujo vehicular y demoras de barrera. |
---
### 1.4. Dependencias con Hardware, Red y Servicios Externos
```mermaid
graph TD
subgraph Puesto_Fisico_Garita [Puesto Físico / Garita de Seguridad]
PC[PC / Terminal Operador]
Lector[Lector Código Barras / QR USB o Serie]
Webcam[Webcam USB Operador]
Lector -->|Teclado HID o RS-232| PC
Webcam -->|Video USB UVC| PC
end
subgraph Dispositivos_Infraestructura [Infraestructura de Campo]
CamHik[Cámaras Hikvision IP LPR/Rostro]
Placa[Controladores ST1660 PASS/PARK]
Barrera[Barreras / Molinetes / Puertas]
Placa -->|Relé / Pulso| Barrera
end
subgraph Servidores_Red_Local [Red Local / Servidor OnEver]
ServerWPC[Servicio OnEverWPC / Python Daemon]
FastAPI[Backend FastAPI OnEverControl]
SQLServer[(Base de Datos SQL Server 'videoman')]
end
PC -->|HTTPS / WebSocket| FastAPI
CamHik -->|RTSP / ISAPI Digest| FastAPI
FastAPI -->|pymssql / Async Pool| SQLServer
FastAPI -->|INSERT comando| SQLServer
SQLServer -.->|pdtmdl| ServerWPC
ServerWPC -->|RS-485 / COM| Placa
```
1. **Controladores de Hardware (ST1660 Pass & Park):**
- Protocolo serial propietario binario (tramas con `STX`, dirección 01-99, comando `O3`/`O5`/`V3`/`V6`, checksum).
- Conexión física mediante bus RS-485 multipunto conectado a puerto COM físico o adaptador USB-Serial (FTDI/CH340).
- Actualmente despachado por el servicio de fondo `OemspotPyWPC` mediante la tabla de cola `pdtmdl`.
2. **Lectores de Documentos / QR:**
- Lectores Honeywell, Datalogic o genéricos conectados por USB (modo Teclado HID) o puerto RS-232 / Virtual COM.
3. **Cámaras IP Hikvision:**
- Protocolo ISAPI HTTP Digest (`/ISAPI/Streaming/channels/{ch}/picture`) y RTSP H.264 para video continuo. Requieren credenciales Digest y acceso a la subred de seguridad.
4. **Base de Datos Microsoft SQL Server:**
- Base de datos relacional `videoman`. Motor SQL Server 2008 / 2012 / 2016+ con nivel de compatibilidad 100+, collation `Modern_Spanish_CI_AS`.
---
### 1.5. Limitaciones Identificadas para la Transición Web y Soluciones
1. **Reemplazo del Lector Físico por la Cámara Integrada de la Tablet:**
- *Comportamiento actual en desktop:* El sistema dependía de lectores físicos de código de barras/QR conectados a puertos serie COM (`SerialQRReaderThread`) o mediante cables USB emulando teclado.
- *Solución adoptada en OnEverControl:* Se **eliminan por completo los escáneres físicos externos** (tanto por puerto COM como por emulación de teclado). La tablet utiliza su propia cámara integrada (trasera/frontal) mediante la **Barcode Detection API nativa** del navegador y fallback con **ZXing (WebAssembly/JS)** en el frontend. Al enfocar el documento de identidad, el navegador detecta y decodifica el código PDF417 o QR en tiempo real en menos de 50 ms, ejecuta el parser de DNI y captura simultáneamente el fotograma del documento como evidencia visual. Esto reduce costos a cero en lectores, elimina cables y otorga máxima movilidad al guardia en el carril.
2. **Descarte de la función de Streaming de Cámaras Hikvision por ISAPI:**
- *Comportamiento actual en desktop:* La aplicación de escritorio ejecutaba hilos continuos `VideoStreamThread` con solicitudes HTTP Digest cada 60 ms para mostrar el video del carril en pantalla.
- *Definición adoptada en OnEverControl:* La versión web cliente para tablets **prescinde del streaming de cámaras Hikvision por ISAPI**. Esta decisión elimina la saturación de ancho de banda sobre la red Wi-Fi de garitas, erradica el drenaje de batería y recalentamiento en las tablets, y simplifica la arquitectura al no requerir proxies de video complejos. El monitoreo perimetral permanente continúa en el sistema de CCTV/NVR de la garita o en OnEverAccess central, mientras que la tablet se enfoca en su objetivo operativo: lectura rápida de DNI con su propia cámara, validaciones de acceso y apertura de paso.
3. **La Tablet como una Workstation oficial de OnEverAccess:**
- *Comportamiento en PC Windows:* En la aplicación de escritorio PyQt6, el sistema invoca `get_workstation_name()` leyendo `os.environ["COMPUTERNAME"]` y valida en base de datos `es_puesto_de_control(workstation_name)` y `listar_modulos_por_workstation(workstation_name)`.
- *Mecanismo para Tablets (Android, iPadOS, Windows):*
Cada tablet se da de alta en la base de datos `videoman` de OnEverAccess como una **Workstation formal** (ejemplo: `TABLET_GARITA_1`, `TABLET_ACCESO_PROV`, `TABLET_PATRULLA`).
En el navegador de la tablet, el `workstation_name` se vincula durante el primer inicio o configuración inicial de la garita y queda persistido de manera inmutable en el almacenamiento seguro de la tablet (`localStorage` y Cookie HttpOnly firmada).
Al iniciar sesión el guardia, el backend FastAPI ejecuta **exactamente las mismas consultas T-SQL que el sistema de escritorio actual**:
- Verifica si la estación es un puesto de control activo (`es_puesto_de_control`).
- Recupera los módulos y carriles físicos/virtuales asignados a esa estación (`listar_modulos_por_workstation`).
- Si la tablet no está autorizada, renderiza la pantalla de bloqueo y advertencia equivalente a `_crear_vista_no_autorizada`.
- Todos los tickets, eventos y auditorías registran el nombre de la Workstation asignada a la tablet, garantizando trazabilidad idéntica a una PC Windows física.
---
## 2. Propuesta de Arquitectura para la Versión Web
### 2.1. Arquitectura General del Sistema
Se adopta una arquitectura desacoplada basada en **Microservicios Híbridos y Clean Architecture**, garantizando alta disponibilidad, aislamiento de fallos y rendimiento en tiempo real:
```mermaid
graph LR
subgraph Cliente_Web [Frontend SPA / PWA Tablets 4GB RAM]
UI[React + TS + Vite SPA]
SW[Service Worker Cache PWA]
WS_Client[WebSocket Client React Hook / Context]
end
subgraph Gateway_Proxy [Reverse Proxy & Edge]
Nginx[Nginx / Caddy SSL & Static Server]
end
subgraph Backend_Core [Backend FastAPI OnEverControl]
API_GW[FastAPI Router & Auth Middleware]
Access_Ctrl[Control de Acceso & Validaciones]
Tck_Service[Servicio de Tickets & Movimientos]
Hardware_Hub[Hardware Hub & Camera Proxy]
WS_Manager[WebSocket Real-time Manager]
DB_Adapter[Async Database Pool pymssql/SQLAlchemy]
end
subgraph Capa_Datos [Persistencia & Hardware Daemon]
MSSQL[(SQL Server 'videoman')]
WPC_Daemon[OnEverWPC Hardware Daemon]
end
UI <-->|HTTPS REST| Nginx
WS_Client <-->|WSS WebSockets| Nginx
Nginx <--> API_GW
API_GW --> Access_Ctrl
API_GW --> Tck_Service
API_GW --> Hardware_Hub
API_GW --> WS_Manager
Access_Ctrl --> DB_Adapter
Tck_Service --> DB_Adapter
DB_Adapter <--> MSSQL
Tck_Service -->|INSERT pdtmdl| MSSQL
MSSQL -.->|POLL pdtmdl| WPC_Daemon
```
### 2.2. Frontend (Diseño Táctil "Touch-First" para Tablets Android, Windows e iPad)
El frontend web está diseñado prioritariamente para **dispositivos de interfaz táctil**, específicamente tablets comerciales y de grado industrial (**Android, Microsoft Windows táctil / Surface, e iPad / iPadOS**), permitiendo a los guardias operar tanto desde soportes fijos en el mostrador de garita como desplazándose directamente hasta la ventanilla del vehículo:
1. **Diseño de Interfaz "Touch-First" & Ergonomía:**
- **Objetivos Táctiles Generosos (Touch Targets):** Todos los botones primarios, selectores y campos de entrada poseen una altura mínima de **48 x 48 píxeles** (cumpliendo los estándares WCAG y Apple Human Interface Guidelines), facilitando la pulsación rápida incluso con guantes o en condiciones de movimiento.
- **Diseño Híbrido "Touch + Keyboard":** La interfaz combina amplias zonas táctiles para tablets con atajos de teclado físicos (`F2`, `F4`, `Enter`, `Esc`) para puestos que cuenten con teclados físicos o lectores de código de barras.
2. **Adaptabilidad a Teclados Virtuales en Pantalla (On-Screen Keyboard):**
- **Viewport Dinámico Resiliente (`dvh`):** Layouts diseñados con unidades de viewport dinámicas (`100dvh`), con scroll interno suave que garantiza que, al desplegarse el teclado virtual de la tablet, los botones críticos de acción (**Confirmar Ingreso** y **Cancelar**) permanezcan visibles o rápidamente accesibles sin desbordar la pantalla.
- **Teclados Numéricos Contextuales:** Uso de atributos HTML5 específicos (`inputmode="numeric"`, `pattern="[0-9]*"`) en campos de DNI, teléfono, código de lote y selector de ocupantes, forzando a iPadOS y Android a desplegar el teclado numérico de dígitos grandes en lugar del teclado alfanumérico completo.
3. **Aprovechamiento de las Cámaras Integradas de la Tablet:**
- En lugar de requerir webcams USB externas, la interfaz web utiliza directamente la **cámara trasera y frontal de la tablet** mediante la API `navigator.mediaDevices.getUserMedia({ video: { facingMode: "environment" } })`. Esto permite al guardia apuntar la tablet hacia el DNI o el rostro del conductor y tomar la fotografía de evidencia con un toque en pantalla.
4. **Modo PWA (Progressive Web App) y Modo Kiosco:**
- Capacidad de **"Agregar a la pantalla de inicio"** en iPad (Safari), tablets Android (Chrome) y Windows (Edge), ejecutándose en modo **pantalla completa (Standalone / Kiosk)** sin barras de URL ni botones del navegador.
- Prevención de gestos indeseados: desactivación de zoom por doble toque accidental (`touch-action: manipulation`) y bloqueo de recargas accidentales por arrastre (`overscroll-behavior-y: contain`).
5. **Orientación Dual (Landscape y Portrait):**
- Soporte fluido para orientación horizontal (**Landscape**, estándar en bases/soportes fijos de garita) y vertical (**Portrait**, ergonómico cuando el guardia sostiene la tablet con una mano en el exterior).
### 2.3. Backend / API (FastAPI)
- **Framework:** **FastAPI (Python 3.11+)**.
- **Ventajas Arquitectónicas:**
- Ejecución asíncrona de alto rendimiento (`asyncio` con servidor `uvicorn`).
- Validación de esquemas y contratos estricta con **Pydantic v2**.
- Documentación interactiva autogenerada lista para auditoría (OpenAPI / Swagger en `/docs`).
- Soporte nativo para WebSockets y Server-Sent Events (SSE) sin extensiones pesadas.
- Reutilización total del código de negocio Python existente (`parser_dni.py`, validaciones de pólizas y cálculo de antipassback).
### 2.4. Base de Datos y Persistencia
- **Motor:** Microsoft SQL Server (base de datos existente `videoman`).
- **Acceso a Datos:** Pool de conexiones asíncrono para operaciones de lectura/escritura críticas, compatible con el collation actual `Modern_Spanish_CI_AS` y compatibilidad SQL Server 2008+.
- **Garantía Transaccional:** Transacciones ACID atómicas en la creación de tickets de ingreso/salida: la inserción de `tck`, la asignación de personas `tckper`, las propiedades dinámicas `tckprx`, el histórico `mvthist` y el encolado de hardware `pdtmdl` se confirman en una única transacción. Si cualquier paso falla, se realiza rollback completo.
### 2.5. Comunicación con Dispositivos y Controladores (Resolución del Desacople)
- **Principio de Diseño:** *El navegador jamás interactúa directamente con los buses industriales RS-485 ni con las placas ST1660.*
- **Flujo de Ejecución de Comandos:**
1. El guardia presiona "Confirmar Ingreso" o pulsa `Enter` en la interfaz web.
2. El frontend envía `POST /api/v1/access/entry` al backend FastAPI con el payload validado.
3. FastAPI procesa la lógica de negocio, registra el ticket y ejecuta `INSERT INTO pdtmdl` con el comando correspondiente (`O3` barrera, `V5` molinete, `T9` ticket).
4. El daemon de hardware `OnEverWPC` (que corre de forma independiente en el servidor o PC concentradora) toma el comando en menos de 50 ms y lo transmite al puerto COM físico.
5. FastAPI responde con código `200 OK` y emite un evento WebSocket al frontend indicando "Acceso Permitido y Barrera Abierta".
- **Comandos Manuales de Emergencia:**
- Endpoint dedicado `POST /api/v1/hardware/modules/{id}/open` para aperturas manuales de cortesía o emergencia desde la interfaz web, con auditoría obligatoria de usuario y motivo.
### 2.6. Comunicación en Tiempo Real y Manejo de Eventos
- **Tecnología:** **WebSockets nativos de FastAPI**.
- **Canales de Eventos:**
- `/ws/station/{station_id}`: Eventos específicos del carril (escaneo de DNI, cambio de estado de cámara, resultado de validación).
- `/ws/global/events`: Alertas perimetrales, avisos de antipassback, nuevas preautorizaciones cargadas por vecinos y estado de salud de los controladores de hardware.
### 2.7. Logs, Auditoría y Trazabilidad
- Toda acción operativa sensible (apertura manual de barrera, anulación de ticket, modificación de póliza, salida forzada de acompañante) se registra en una tabla de auditoría inmutable (`aud_log`) que almacena: `UsuarioID`, `WorkstationID`, `ModuloID`, `FechaHora`, `Accion`, `DetalleJSON` e `IP_Cliente`.
- Logs de aplicación estructurados en formato JSON (usando `structlog` o `loguru`) con rotación automática diaria.
### 2.8. Escalabilidad, Seguridad y Entornos de Ejecución Servidor
- **Entornos de Ejecución Soportados para el Servidor Web / API:**
- **Bare-metal Windows 10/11:** Ejecución nativa en PCs de garita o servidores Windows como servicio del sistema (mediante NSSM o Windows Task Scheduler), ideal para despliegues locales directos.
- **LXC (Linux Containers en Proxmox / Debian / Ubuntu):** Despliegue ultraliviano con overhead de CPU y RAM casi nulo (< 80 MB RAM), administrado por `systemd`. Utiliza FreeTDS y `pymssql` nativo de Linux para comunicarse por red con SQL Server `videoman`.
- **Docker & Docker Compose:** Empaquetado inmutable en contenedores estandarizados multiplataforma (Linux o Windows Docker Host), facilitando actualizaciones rápidas y réplicas.
- **Factor Clave de Portabilidad:** Al estar la capa de hardware físico desacoplada mediante la tabla `pdtmdl` (escuchada por `OnEverWPC` en la máquina Windows donde residen los puertos COM físicos), el servidor de `OnEverControl` **no requiere drivers Win32 ni acceso serial local**, permitiendo que corra de manera 100% nativa y transparente tanto en Linux (LXC/Docker) como en Windows.
- **Alta Disponibilidad:** Posibilidad de ejecutar múltiples réplicas del backend FastAPI detrás de un Reverse Proxy Nginx con balanceo de carga.
- **Monitoreo:** Endpoint de salud `/health` y `/metrics` compatible con Prometheus y dashboards de monitoreo en Grafana.
---
## 3. Tecnologías Recomendadas y Justificación de Decisiones
### 3.1. Cuadro Comparativo del Stack Tecnológico
| Capa / Componente | Tecnología Seleccionada | Alternativas Evaluadas | Justificación de la Elección |
| :--- | :--- | :--- | :--- |
| **Backend Framework** | **FastAPI (Python 3.11+)** | Flask, Django REST, Node.js (Express/NestJS) | **FastAPI** es un requerimiento explícito del proyecto y la mejor opción técnica: ofrece rendimiento asíncrono con `asyncio`/`uvloop`, validación estricta con Pydantic v2, generación automática de OpenAPI y compatibilidad directa con las bibliotecas existentes en Python del proyecto (`parser_dni`, cálculos de hardware, etc.). Flask carece de tipado asíncrono robusto nativo; Django es excesivamente monolítico; Node.js obligaría a reescribir toda la lógica de Python. |
| **Frontend Framework & Build** | **React + TypeScript + Vite** | Next.js, Angular, Vue, NestJS BFF | **React + TypeScript + Vite** produce una Single Page Application (SPA) estática de altísimo rendimiento y huella de memoria ultraliviana (~30-50 MB en navegador). A diferencia de arquitecturas basadas en servidores Node.js/BFF pesados, los activos estáticos compilados con Vite se sirven de forma directa por Nginx o el backend FastAPI. Esta ligereza es determinante para garantizar fluidez sin cierres de pestaña ni retrasos en **tablets Samsung Galaxy Tab A9 y A11 de 4 GB de RAM**, donde el sistema operativo Android y los procesos en segundo plano dejan un margen operativo ajustado de memoria libre. |
| **Diseño / Estilos** | **CSS Puro / Vanilla CSS con Sistema de Tokens (OnEver DS)** | TailwindCSS, Bootstrap, Material UI | **Vanilla CSS estructurado con Design Tokens** (Variables CSS semánticas) respeta las directrices del proyecto y el Design System ya concebido en `styles/design_system.py`. Ofrece control milimétrico de contraste, temas Dark/Light de alto contraste para garitas, máxima velocidad de carga sin dependencias pesadas y layouts compactos optimizados para pantallas de 1360x768 píxeles comunes en puestos de seguridad. |
| **Motor de Base de Datos** | **Microsoft SQL Server (videoman)** | PostgreSQL, MySQL, SQLite | Se mantiene **SQL Server** existente para preservar la compatibilidad total e inmediata con el ecosistema de producción (`videoman`), las tablas de hardware `pdtmdl`, la base histórica de personas y los stored procedures optimizados. |
| **Acceso a Base de Datos** | **pymssql + Pool Asíncrono / SQLAlchemy Core** | pyodbc, Tortoise-ORM, Peewee | **pymssql** ya está implementado y validado en el repositorio actual (`db_config.py`). Funciona de manera nativa tanto en Windows como en Linux sin requerir controladores ODBC externos complicados, admitiendo el nivel de compatibilidad 100 de SQL Server 2008. |
| **Comunicación Real-Time** | **WebSockets (FastAPI WebSocket Endpoint)** | Server-Sent Events (SSE), Long Polling | **WebSockets** proporciona comunicación bidireccional de bajísima latencia (< 5 ms). Permite tanto enviar alertas e imágenes desde el servidor al navegador como recibir comandos inmediatos del operador. |
| **Autenticación & Sesión** | **JWT (JSON Web Token) en Cookies HttpOnly con Refresh Tokens** | Sesiones por BD, OAuth2 externo | Seguridad sólida en contexto web: protección contra robo de tokens (XSS) mediante flags `HttpOnly` y `SameSite=Strict`, con expiración corta de access token (15-30 min) y refresh tokens persistentes para no interrumpir el turno del operador. |
| **Reverse Proxy & Web Server** | **Nginx** | Apache, Traefik, Caddy | **Nginx** es el estándar indiscutido para servir estáticos con máxima velocidad, manejar terminación TLS/SSL (HTTPS) y proxificar peticiones HTTP y WebSockets hacia Uvicorn con balanceo de carga. |
| **Entornos de Servidor & Despliegue** | **Windows 10/11, LXC (Linux Containers) & Docker** | Máquinas virtuales pesadas (KVM/ESXi monolíticas) | OnEverControl está diseñado para máxima versatilidad operativa: (1) **Windows 10/11** bare-metal ejecutándose como servicio de sistema para puestos fijos de garita; (2) **LXC (Linux Containers)** en Proxmox/Debian consumiendo recursos mínimos (< 80 MB RAM de overhead) y gestionado por systemd; y (3) **Docker / Docker Compose** para despliegues estandarizados e inmutables. El desacople de puertos físicos mediante la tabla SQL Server `pdtmdl` hace posible que el backend corra en Linux/LXC/Docker sin requerir passthrough serial ni drivers propietarios. |
| **Herramientas de Testing** | **pytest + HTTPX (Backend) / Vitest + React Testing Library + Playwright (Frontend)** | Selenium, Cypress, unittest | `pytest` con `pytest-asyncio` y `httpx` permite pruebas de integración de API asíncronas ultraveloces. `Vitest` y `React Testing Library` ejecutan pruebas unitarias veloces en frontend, y `Playwright` permite simular escaneos de código de barras y flujos completos de carril en navegadores headless. |
---
## 4. Estructura del Proyecto
Se propone la siguiente estructura para el repositorio `OnEverControl`, manteniendo un desacoplamiento limpio entre frontend, backend, documentación y utilidades de automatización:
```text
OnEverControl/
├── README.md # Documentación principal de inicio rápido
├── ROADMAP.md # Hoja de ruta de desarrollo y fases
├── INFORME_TECNICO_PUESTO_DE_CONTROL_WEB.md # Este informe técnico maestro
├── docker-compose.yml # Orquestación de servicios (API, Web, Proxy)
├── .env.example # Plantilla de variables de entorno
│
├── backend/ # Núcleo API FastAPI
│ ├── Dockerfile
│ ├── pyproject.toml / requirements.txt
│ ├── app/
│ │ ├── main.py # Punto de entrada FastAPI y middlewares
│ │ ├── core/ # Configuraciones y seguridad central
│ │ │ ├── config.py # Settings basados en Pydantic
│ │ │ ├── security.py # Hasheo de claves, JWT y auth helpers
│ │ │ ├── database.py # Pool de conexiones pymssql
│ │ │ └── logging.py # Configuración de logs estructurados
│ │ ├── api/ # Routers de endpoints (v1)
│ │ │ ├── v1/
│ │ │ │ ├── router.py # Agregador de rutas v1
│ │ │ │ ├── auth.py # Login, logout, refresh, usuario actual
│ │ │ │ ├── control_posts.py # Gestión de puestos y carriles asignados
│ │ │ │ ├── access.py # Ingresos, salidas, validaciones, antipassback
│ │ │ │ ├── people.py # Personas, búsqueda predictiva, DNI parsing
│ │ │ │ ├── vehicles.py # Patentes, seguros, autos asociados
│ │ │ │ ├── lots.py # Lotes, propietarios, permisos de lote
│ │ │ │ ├── preauthorizations.py# Visitas preautorizadas y consumo
│ │ │ │ ├── hardware.py # Apertura remota de módulos, cola pdtmdl
│ │ │ │ ├── cameras.py # Proxy ISAPI Hikvision y snapshots
│ │ │ │ └── websockets.py # Gateway WebSocket de eventos en vivo
│ │ ├── schemas/ # Modelos Pydantic (Request / Response DTOs)
│ │ │ ├── auth_schema.py
│ │ │ ├── access_schema.py
│ │ │ ├── person_schema.py
│ │ │ ├── vehicle_schema.py
│ │ │ ├── hardware_schema.py
│ │ │ └── lot_schema.py
│ │ ├── services/ # Lógica de negocio desacoplada
│ │ │ ├── access_service.py # Orquestación de ingreso y salida
│ │ │ ├── antipassback_service.py # Reglas de antipassback y bypass
│ │ │ ├── dni_parser_service.py # Adaptación de parser_dni.py
│ │ │ ├── hardware_service.py # Inserción y formato en pdtmdl
│ │ │ └── camera_service.py # Cliente Digest HTTP persistente Hikvision
│ │ ├── repositories/ # Capa de acceso a SQL Server (T-SQL)
│ │ │ ├── access_repository.py # Consultas tck, tckper, tckprx, mvthist
│ │ │ ├── person_repository.py # Consultas Per, PerDocCatVal
│ │ │ ├── vehicle_repository.py # Consultas Aut, peraut
│ │ │ ├── lot_repository.py # Consultas Lot, permisos
│ │ │ └── hardware_repository.py # Consultas mdl, pdtmdl
│ │ └── utils/ # Funciones auxiliares y formateadores
│ └── tests/ # Suite de pruebas unitarias y de integración
│ ├── conftest.py
│ ├── test_auth.py
│ ├── test_dni_parser.py
│ ├── test_access_flow.py
│ └── test_hardware_commands.py
│
├── frontend/ # Aplicación Web SPA (React + TypeScript + Vite)
│ ├── index.html # Entrypoint HTML5 PWA táctil
│ ├── package.json # Dependencias React 18+, TypeScript, Vite
│ ├── tsconfig.json # Configuración de compilación TypeScript estricta
│ ├── vite.config.ts # Configuración de Vite (pwa plugin, proxy dev)
│ ├── public/ # Favicons, manifest PWA, assets estáticos
│ └── src/
│ ├── main.tsx # Punto de entrada de React (mount en #root)
│ ├── App.tsx # Enrutador principal y layout general
│ ├── api/ # Clientes HTTP hacia backend FastAPI
│ │ ├── client.ts # Instancia base con interceptores de cookies JWT
│ │ ├── authApi.ts # Endpoints /api/v1/auth
│ │ ├── accessApi.ts # Endpoints /api/v1/access
│ │ └── workstationApi.ts # Endpoints /api/v1/control-posts
│ ├── components/ # Componentes modulares de interfaz táctil
│ │ ├── common/ # Botones Touch (>= 48px), Modales, Badges
│ │ ├── scanner/ # Visor de cámara para DNI (PDF417 / QR)
│ │ ├── access/ # Panel de ingreso, carriles, acompañantes
│ │ └── workstation/ # Selector y estado de estación de trabajo
│ ├── context/ # Contextos globales de estado liviano
│ │ ├── AuthContext.tsx # Sesión activa de guardia
│ │ └── WorkstationContext.tsx # Workstation actual y carriles vinculados
│ ├── hooks/ # Custom hooks reutilizables
│ │ ├── useCameraScanner.ts # Control de cámara y decodificación con BarcodeDetector
│ │ ├── useWebSocket.ts # Conexión persistente con /ws/station/{name}
│ │ └── useKeyboardShortcuts.ts # Soporte para atajos de teclado (F2, F4, Esc)
│ ├── views/ # Pantallas principales
│ │ ├── LoginView.tsx # Pantalla de login táctil y selección de workstation
│ │ └── ControlPostView.tsx # Pantalla operativa de Puesto de Control
│ └── styles/ # OnEver Design Tokens en Vanilla CSS
│ ├── tokens.css # Variables de color (Dark/Light), fuentes, sombras
│ ├── base.css # Reset, touch-action: manipulation, 100dvh
│ └── components.css # Estilos modulares para botones y formularios
│ └── tests/ # Pruebas unitarias de componentes con Vitest
│
├── docs/ # Documentación técnica adicional y diagramas
│ ├── architecture_diagrams.png
│ ├── hardware_protocol_spec.md
│ └── api_contracts.md
│
└── scripts/ # Scripts de verificación y despliegue multiplataforma
├── test_sql_connection.py # Test agnóstico de conexión SQL Server (Windows/Linux)
├── windows/ # Despliegue en Windows 10/11
│ ├── install_service.bat # Instalación como servicio de Windows (NSSM)
│ └── start_native.bat # Inicio bare-metal rápido en garita
├── lxc/ # Despliegue en Proxmox / Debian LXC
│ ├── setup_lxc.sh # Instalación de dependencias Linux (FreeTDS, Python, Nginx)
│ └── onevercontrol.service # Unit file para administración con systemd
└── docker/ # Despliegue en Docker / Docker Compose
└── nginx.conf # Configuración de proxy y compresión
```
---
## 5. Modelo de Datos y Entidades
Para soportar la versión web manteniendo total interoperabilidad con la base de datos SQL Server `videoman`, se identifican las entidades clave, sus relaciones y esquemas:
```mermaid
erDiagram
Per ||--o{ PerDocCatVal : "posee documentos"
Per ||--o{ peraut : "conduce / asocia"
Aut ||--o{ peraut : "asociado a"
Lot ||--o{ pre : "preautoriza visitas a"
Lot ||--o{ tckprx : "destino de"
tck ||--o{ tckper : "incluye personas"
Per ||--o{ tckper : "participa en"
tck ||--o{ tckprx : "metadatos extendidos"
tck ||--o| tckhst : "se archiva al salir"
mdl ||--o{ pdtmdl : "recibe comandos para"
usr ||--o{ usrcatval : "privilegios y roles"
Per {
int PersonaID PK
string Apellido
string Nombre
string NroSocio
int Blacklist
datetime CreationDate
}
Aut {
int AutoID PK
string Patente
string Aseguradora
string PolizaNro
date PolizaVigenciaDesde
date PolizaVigenciaHasta
}
Lot {
int LoteID PK
string Lote
string Calle
int EstadoValID
}
tck {
int TicketID PK
datetime FechaHoraIngreso
int ModuloIngresoID FK
}
tckper {
int TicketID FK
int PersonaID FK
int RolID
int EsMenor
}
pdtmdl {
int PdtMdlID PK
int ModuloID FK
string Comando
int Inmediato
string Extra
}
```
### 5.1. Entidades Principales
1. **Persona (`Per`):**
- Identificador único (`PersonaID`), Apellido, Nombre, Número de Socio, Estado de Lista Negra (`Blacklist`), Observaciones.
2. **Documento de Identidad (`PerDocCatVal`):**
- Vínculo a `PersonaID`, Tipo de Documento (`DocumentoTipoID`: 1=DNI, 2=Pasaporte, etc.), Número de documento (`Documento`).
3. **Vehículo (`Aut`):**
- `AutoID`, Dominio/Patente, Datos de seguro (Aseguradora, PolizaNro, PolizaVigenciaDesde, PolizaVigenciaHasta).
4. **Relación Persona-Vehículo (`peraut`):**
- `PersonaID`, `AutoID`. Permite sugerir automáticamente la patente al escanear la persona o viceversa.
5. **Lote / Destino (`Lot`):**
- `LoteID`, Código de Lote (`Lote`), Calle, Estado de habilitación (`EstadoValID`).
6. **Ticket Activo de Ingreso (`tck`):**
- `TicketID`, `FechaHoraIngreso`, `ModuloIngresoID` (carril de entrada). Un registro aquí representa una persona o vehículo dentro del predio.
7. **Personas en Ticket (`tckper`):**
- `TicketID`, `PersonaID`, `RolID` (1 = Conductor, 2 = Peatón/Acompañante), `EsMenor` (0 o 1).
8. **Propiedades Dinámicas de Ticket (`tckprx`):**
- `TicketID`, `PropiedadID` (ej: 4=Patente, 13=LoteID, 5=Entidad/Empresa, 6=Motivo), `Valor`.
9. **Histórico de Movimientos (`tckhst` y `mvthist`):**
- Datos consolidados del ingreso y egreso con estampas de tiempo, módulos de paso, duración y operador interviniente.
10. **Preautorizaciones (`pre`):**
- `PreautorizadoID`, `LoteID`, Apellido, Nombre, Documento, Entidad, Fechas de vigencia (`FechaInicio`, `FechaFin`), Estado de consumo.
11. **Módulos de Hardware (`mdl`):**
- `ModuloID`, Nombre, Dirección física (`Address`), Tipo de acceso (1=Puerta, 2=Molinete, 3/5=Barrera), Configuración de cámara asociada (`HikID`).
12. **Cola de Comandos de Hardware (`pdtmdl`):**
- `PdtMdlID`, `ModuloID`, `Comando` (trama formateada), `Inmediato` (1), `Extra` (TicketID).
13. **Usuarios y Permisos (`usr`, `usrcatval`):**
- `UsuarioID`, Nombre, Password (actualmente MD5 o compatible, a actualizar a bcrypt/argon2), Privilegios de acceso asignados.
---
## 6. Consideraciones de Seguridad
### 6.1. Autenticación y Gestión de Sesión
- **Tokens de Acceso:** Uso de tokens JWT emitidos con algoritmo asimétrico o HMAC-SHA256 con secret de alta entropía.
- **Protección de Almacenamiento:** El token se almacena en **Cookies HTTP con atributos `HttpOnly`, `Secure` y `SameSite=Strict`**, impidiendo que scripts maliciosos puedan extraer el token mediante vulnerabilidades XSS.
- **Cierre de Turno e Inactividad:** Detección de inactividad configurable (ej: bloqueo automático tras 15 minutos sin interacción para proteger garitas en relevos de guardia).
### 6.2. Autorización Basada en Roles (RBAC)
- Permisos granulares asociados a la tabla `UsrCatVal` actual:
- `OPERADOR_GUARDIA`: Registro de ingresos y salidas, escaneo de DNI, apertura por evento.
- `SUPERVISOR`: Apertura manual extraordinaria, anulación de tickets pendientes, gestión de listas negras y bypass de antipassback con clave.
- `ADMINISTRADOR`: Configuración de carriles, módulos de hardware, altas de usuarios y auditoría completa.
### 6.3. Protección de APIs
- **Rate Limiting:** Protección contra ataques de fuerza bruta en `/api/v1/auth/login` y endpoints de búsqueda masiva.
- **Validación Estricta:** Filtrado y saneamiento de todos los inputs en FastAPI mediante Pydantic, previniendo inyección SQL en consultas T-SQL.
- **CORS:** Configuración estricta de Cross-Origin Resource Sharing restringida únicamente al origen del frontend de la intranet.
### 6.4. Seguridad en la Comunicación con Dispositivos
- La red de cámaras Hikvision y los controladores ST1660 deben residir en una **VLAN de Seguridad / Dispositivos aislada**, accesible únicamente por el servidor FastAPI y el servicio OnEverWPC. Ningún dispositivo del carril expone puertos hacia el navegador cliente.
---
## 7. Plan de Migración y Coexistencia con el Sistema Desktop
### 7.1. Estrategia de Convivencia Transparente
Dado que un predio de seguridad no puede detener su operación ni un solo minuto, la versión web debe ser capaz de convivir en paralelo con el sistema de escritorio actual durante todo el período de transición.
```mermaid
graph TD
Garita1[Garita Principal: Puesto Desktop PyQt6]
Garita2[Garita Secundaria: Puesto Web OnEverControl]
BD[(SQL Server 'videoman')]
WPC[Daemon OnEverWPC Hardware]
Placas[Placas ST1660 & Barreras]
Garita1 -->|Lectura / Escritura tck, tckper| BD
Garita1 -->|Encola apertura| BD
Garita2 -->|Lectura / Escritura tck, tckper vía FastAPI| BD
Garita2 -->|Encola apertura vía FastAPI| BD
BD -->|pdtmdl| WPC
WPC -->|RS-485| Placas
```
- **Compatibilidad Total de Base de Datos:** Tanto la aplicación de escritorio como la versión web leen y escriben en las mismas tablas (`tck`, `tckper`, `tckprx`, `pdtmdl`, `mvthist`).
- **Escenario Real de Convivencia:** Una persona puede registrar su ingreso vehicular en la Garita Principal utilizando la aplicación actual de escritorio, y luego egresar por la Garita Secundaria atendida con la nueva versión web. Ambos sistemas verán el mismo ticket activo en tiempo real.
### 7.2. Fases de Migración Progresiva
1. **Fase Piloto en Carril Test / Secundario:** Despliegue de la versión web en un carril de baja carga (ej: acceso de proveedores o salida peatonal).
2. **Operación Espejo:** Monitoreo de latencia, estabilidad del escáner y verificación de que los tickets creados en la web cierran correctamente en escritorio y viceversa.
3. **Reemplazo Progresivo:** Migración terminal por terminal sin impacto en el personal ni en el flujo vehicular.
---
## 8. Decisiones Técnicas Pendientes y Recomendaciones
Durante el análisis del código fuente y los requerimientos, se identificaron las siguientes definiciones clave que requieren alineación con el equipo de infraestructura:
1. **Modalidad de Lectura de Documentos de Identidad (DNI):**
- *Definición adoptada:* **Lectura directa mediante la cámara integrada de la tablet.** Se reemplazan por completo los lectores físicos externos por puerto COM y emulación de teclado. El frontend en React + TypeScript implementa la Barcode Detection API nativa y la biblioteca ZXing (Wasm/JS), decodificando el código PDF417 o QR del DNI en tiempo real con la cámara trasera de la tablet y capturando simultáneamente la foto del documento como evidencia visual. Esto garantiza movilidad total para el guardia en el carril y costo cero en periféricos.
2. **Exclusión del Streaming de Cámaras Hikvision por ISAPI en la Versión Web:**
- *Definición adoptada:* **No se utilizará streaming de cámaras Hikvision por ISAPI.** Se descarta por completo la reemisión de video continuo hacia las tablets para evitar consumo excesivo de batería, recalentamiento y congestión en la red Wi-Fi de garitas. El monitoreo de video de seguridad fijo perimetral continúa en el circuito cerrado de TV (CCTV/NVR) o en el puesto central de OnEverAccess, dejando a la tablet libre y ágil para el control de accesos.
3. **Modernización de Almacenamiento de Contraseñas:**
- *Situación:* La base histórica utiliza esquemas heredados de autenticación.
- *Recomendación:* Implementar actualización automática transparente al iniciar sesión (*hash re-encoding*): cuando un usuario se loguea con éxito con su clave actual, el backend re-hashea la contraseña con **bcrypt / argon2id**, asegurando la base de datos sin obligar a resetear las contraseñas a todos los operadores.
4. **Persistencia Temporal de Sesiones de Carril Pendientes:**
- *Situación:* En escritorio se usa un archivo JSON local en `%TEMP%` (`CarrilProcessSessionManager`).
- *Recomendación:* Implementar persistencia de sesiones en el backend en una tabla ligera `pct_carril_sesion` o Redis/SQLite en memoria del backend, replicando el estado hacia el navegador mediante `localStorage`. De este modo, si el operador recarga el navegador o se traslada a otra PC, puede reanudar el ingreso exactamente donde quedó.
5. **Despliegue Multiplataforma Agnóstico (Windows 10/11, LXC y Docker):**
- *Definición adoptada:* El servidor de OnEverControl se diseña para operar sin acoplamiento a ningún sistema operativo en particular, soportando tres modalidades de despliegue:
- **Windows 10/11 (Bare-metal):** Ejecución directa con Python venv y servicio de Windows mediante NSSM. Ideal para instalaciones en la misma PC de garita donde ya corre Windows.
- **LXC (Linux Containers en Proxmox / Debian):** Opción de máxima eficiencia para virtualización en servidor central o micro-servidores de predio. Overhead de CPU y memoria casi nulo (< 80 MB RAM), arranque en milisegundos y administración estándar mediante unidades de `systemd`.
- **Docker / Docker Compose:** Empaquetado estandarizado en contenedores inmutables con imagen base `python:3.11-slim` y Nginx para servir la SPA de React compilada y proxificar la API FastAPI.
- *Garantía de Portabilidad:* Al desacoplar el hardware mediante la tabla SQL Server `pdtmdl` (leída por el daemon `OnEverWPC` en la máquina Windows conectada al bus RS-485), el backend FastAPI no requiere drivers propietarios ni puertos COM directos. Se garantiza el uso exclusivo de `pathlib.Path` para rutas de archivos y configuración de FreeTDS para interoperabilidad de collations con SQL Server (`Modern_Spanish_CI_AS`).
6. **Gestión de Versiones y Repositorio Oficial Gitea:**
- *Definición adoptada:* El código fuente oficial de OnEverControl se aloja y versiona en el repositorio central de Gitea: [`https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`](https://gitea.oemspot.com.ar/carlostellocba/OnEverControl).
- *Procedimiento de Publicación:* Todo commit a la rama principal `main` o cierre de fase debe cumplir obligatoriamente con:
1. Actualización sincronizada de versión semántica en el backend (`backend/app/__version__.py` o `pyproject.toml`).
2. Actualización sincronizada de versión semántica en el frontend (`frontend/package.json`).
3. Asiento cronológico de cambios en `CHANGELOG.md`.
4. Aprobación completa de la suite de pruebas automatizadas (`pytest` y `npm run build`) antes del push a Gitea.