OnEverControl — Puesto de Control Web

Sistema de Control de Accesos y Gestión de Visitas Web de Alta Disponibilidad para Barrios Cerrados, Countries y Predios Industriales.


📋 Objetivo del Proyecto

Desarrollar una versión reducida solo web en modo cliente (Thin Client) que migra exclusivamente el Login y el Puesto de Control operativo del sistema actual de escritorio (OemspotPySYS / PyQt6).

Su propósito es permitir que el puesto de control sea accesible de forma ágil desde cualquier dispositivo (PC, notebook o tablet) en la red local (LAN) donde ya está en pleno funcionamiento OnEverAccess, sin requerir instalaciones de Python, librerías gráficas PyQt6 ni configuraciones complejas en cada terminal de garita.


🔍 Descripción General

OnEverControl (Modo Cliente Web) se conecta a los servicios existentes de la red local (base de datos SQL Server videoman y servicio de hardware OnEverWPC) y provee:

  • Autenticación Unificada (Login): Validación de operadores y supervisores utilizando los usuarios y contraseñas ya existentes en OnEverAccess.
  • Puesto de Control de Garita (Ingreso y Salida):
    • Registro ágil de ingresos y egresos vehiculares y peatonales en tiempo real.
    • Escaneo óptico de DNI argentino (PDF417 y QR) mediante la cámara de la tablet, reemplazando lectores COM y de teclado.
    • Validación de pólizas (ART, conductor y automotor).
    • Gestión de acompañantes por vehículo (carga rápida y desacople en salida).
    • Control de antipassback con conmutación directa a salida.
    • Consulta y consumo de visitas preautorizadas por lote.
    • Encolado de apertura de barreras y molinetes en pdtmdl (despachado por OnEverAccess/WPC).
    • Padrón en tiempo real de visitas dentro del predio y herramienta de salida masiva.
    • Captura fotográfica de evidencia del visitante y documento con la cámara de la tablet (sin streaming pesado de cámaras fijas por ISAPI para optimizar batería y red Wi-Fi).
  • La Tablet como Workstation: Cada tablet opera bajo su propio identificador de estación registrado en la base de datos de OnEverAccess (ej: TABLET_01, GARITA_SUR_TAB), recibiendo automáticamente los carriles y barreras asignados a dicha workstation de forma idéntica a como el sistema actual lo hace con una PC Windows.

🏛️ Arquitectura General

El sistema implementa una Clean Architecture desacoplada:

[ Navegador Web Operador ]
          │ (HTTPS / WebSockets)
          ▼
    [ Nginx Reverse Proxy ]
          │ (Proxy Pass :8000)
          ▼
   [ Backend FastAPI Core ]
     ├── Routers RESTful (Pydantic v2)
     ├── WebSockets Gateway (Eventos en Vivo)
     ├── Proxy de Cámaras Hikvision (ISAPI Digest)
     └── Reglas de Negocio (DNI Parser, Antipassback, Pólizas)
          │
          ├── (Pool Asíncrono pymssql)
          ▼
  [ Microsoft SQL Server ('videoman') ]
     ├── Tablas de Acceso: tck, tckper, tckprx, tckhst, mvthist
     ├── Tablas de Entidades: Per, Aut, Lot, pre, mdl
     └── Cola de Comandos: pdtmdl
          │
          ▼ (Lectura continua en < 50ms)
   [ Daemon OnEverWPC (Python) ]
          │ (Bus RS-485 / Puertos COM)
          ▼
[ Controladores Físicos ST1660 (Barreras / Molinetes / Tótems) ]

💻 Stack Tecnológico

Capa Tecnología Propósito
Backend FastAPI (Python 3.11+) + Pydantic v2 API REST asíncrona, validación estricta de esquemas, WebSockets y lógica de negocio.
Servidor ASGI Uvicorn Servidor web asíncrono de alto rendimiento.
Frontend React + TypeScript + Vite SPA ultraliviana (~30-50 MB RAM) optimizada para tablets Samsung Galaxy Tab A9/A11 (4GB RAM) y táctiles.
Estilos Vanilla CSS + OnEver Design Tokens Sistema de diseño de alto contraste con temas Dark/Light y layouts para 1360x768.
Base de Datos Microsoft SQL Server Base de datos relacional existente (videoman), compatible con compatibilidad 100+.
Conector BD pymssql Conexión directa y eficiente a SQL Server en Windows y Linux.
Hardware Bridge Tabla pdtmdl + OnEverWPC Cola transaccional desacoplada hacia las placas RS-485.
Web Proxy / SSL Nginx Terminación SSL/TLS, compresión y balanceo de carga.
Contenedores Docker & Docker Compose Entornos reproducibles y despliegue rápido.

📂 Estructura del Repositorio

OnEverControl/
├── README.md                           # Este documento
├── ROADMAP.md                          # Plan de desarrollo detallado por fases
├── INFORME_TECNICO_PUESTO_DE_CONTROL_WEB.md # Informe técnico maestro y arquitectura
├── docker-compose.yml                  # Configuración de contenedores
├── .env.example                        # Variables de entorno modelo
├── backend/                            # Código fuente del Backend FastAPI + Pydantic v2
│   ├── app/
│   │   ├── api/v1/                     # Endpoints REST y WebSockets
│   │   ├── core/                       # Seguridad, base de datos y configuración
│   │   ├── schemas/                    # Modelos Pydantic v2
│   │   ├── services/                   # Lógica de negocio
│   │   └── repositories/               # Consultas SQL Server
│   └── tests/                          # Suite de pruebas automatizadas
├── frontend/                           # Código fuente del Frontend (React + TypeScript + Vite)
│   ├── src/
│   │   ├── api/                        # Clientes HTTP hacia FastAPI
│   │   ├── components/                 # Componentes táctiles modulares (>= 48px)
│   │   ├── context/                    # Contextos globales de autenticación y estación
│   │   ├── hooks/                      # Custom hooks (escáner de cámara, WebSockets)
│   │   ├── views/                      # Pantallas principales (Login, Puesto de Control)
│   │   └── styles/                     # OnEver Design Tokens en Vanilla CSS
│   ├── vite.config.ts                  # Configuración Vite
│   └── package.json
├── docs/                               # Diagramas, contratos de API y constitución del proyecto
└── scripts/                            # Scripts de verificación y despliegue

⚙️ Requisitos del Sistema

  • Servidor (Entornos Soportados):
    • Windows 10/11 / Windows Server 2016+: Bare-metal o ejecutado como servicio de Windows (vía NSSM / Task Scheduler).
    • LXC (Linux Containers en Proxmox VE / Debian 12 / Ubuntu 22.04): Despliegue ultraliviano (< 80 MB RAM de overhead) administrado por systemd.
    • Docker / Docker Compose: Contenedores estandarizados Linux/Windows con multi-stage build.
    • Dependencias de Servidor: Python 3.11+, Node.js 20+ (para build de Vite), FreeTDS (en Linux/LXC).
    • Base de Datos & Hardware: Conectividad TCP a Microsoft SQL Server (videoman) y servicio OnEverWPC ejecutándose en la red local para el despacho físico hacia las placas RS-485.
  • Cliente (Garita / Puesto Móvil en Tablets Táctiles):
    • Dispositivos Soportados:
      • Tablets Android (Objetivo Principal): Samsung Galaxy Tab A9 y A11 de 4GB de RAM (Google Chrome / Samsung Internet) con huella de memoria optimizada.
      • iPad / iPadOS: iPad 9ª/10ª gen, iPad Air, iPad Pro (Safari / Chrome).
      • Tablets y All-in-One Windows: Microsoft Surface, terminales táctiles de garita (Edge / Chrome).
      • PCs de Escritorio / Laptops: Cualquier navegador moderno para puestos fijos.
    • Diseño Táctil (Touch-First): Botones de tamaño generoso (>= 48px), layouts adaptables 100dvh que evitan que el teclado virtual tape las acciones, y soporte PWA para ejecución a pantalla completa sin barras de navegación.
    • Periféricos: Cámara integrada de la tablet (trasera/frontal) con escaneo en tiempo real de DNI (PDF417 y QR) y captura de evidencia fotográfica (sin necesidad de lectores físicos externos).

🚀 Entorno de Desarrollo Local

1. Clonar y configurar variables de entorno

cd OnEverControl
copy .env.example .env

Configurar en .env las credenciales de SQL Server:

DB_SERVER=192.168.1.50\SQLEXPRESS   # o IP del servidor SQL en la LAN
DB_DATABASE=videoman
DB_USERNAME=sa
DB_PASSWORD=tu_password
SECRET_KEY=clave_super_secreta_jwt_de_32_caracteres_o_mas

2. Backend (FastAPI + Pydantic v2)

cd backend
python -m venv venv
venv\Scripts\activate   # En Windows (o 'source venv/bin/activate' en Linux)
pip install -r requirements.txt
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

La documentación interactiva Swagger estará disponible en: http://localhost:8000/docs.

3. Frontend (React + TypeScript + Vite)

cd frontend
npm install
npm run dev -- --host

La aplicación web estará disponible en: http://localhost:5173.


🚢 Despliegue Multiplataforma (Windows 10/11, LXC, Docker)

OnEverControl está desacoplado del hardware físico mediante la tabla pdtmdl de SQL Server, permitiendo correr de forma idéntica en tres infraestructuras:

Opción A: Bare-metal en Windows 10/11 (Puesto de Garita o Servidor Local)

  1. Instalar Python 3.11 y compilar la SPA de React (npm run build).
  2. Configurar el backend como servicio de Windows mediante NSSM:
    nssm install OnEverControl "C:\OnEverControl\backend\venv\Scripts\uvicorn.exe" "app.main:app --host 0.0.0.0 --port 8000"
    nssm set OnEverControl AppDirectory "C:\OnEverControl\backend"
    nssm start OnEverControl
    

Opción B: Contenedor LXC en Proxmox / Debian / Ubuntu (Recomendado para servidores)

  1. Crear un contenedor LXC unprivileged con Debian 12 (mínimo 512 MB RAM / 1 vCPU asignada).
  2. Ejecutar el script automatizado:
    chmod +x scripts/lxc/setup_lxc.sh && ./scripts/lxc/setup_lxc.sh
    
  3. El servicio correrá gestionado por systemd (systemctl status onevercontrol), consumiendo menos de 80 MB de memoria RAM.

Opción C: Docker & Docker Compose

  1. Levantar el stack completo (FastAPI + Nginx reverse proxy + estáticos de React) con un solo comando:
    docker compose up -d
    
  2. Acceso inmediato en el puerto 80 o 443 con certificados SSL locales.

🛣️ Roadmap del Proyecto

El desarrollo se estructura en 9 fases consecutivas (ver detalle exhaustivo en ROADMAP.md):

  • Fase 0: Análisis, Diseño y Definición de Arquitectura (Completada)
  • Fase 1: Arquitectura y Base del Proyecto
  • Fase 2: Backend / API Core con FastAPI
  • Fase 3: Desarrollo del Frontend Web
  • Fase 4: Integración con Hardware, Cámaras y Tiempo Real
  • Fase 5: Pruebas Integrales y Stress Testing
  • Fase 6: Despliegue Piloto y Convivencia Híbrida
  • Fase 7: Puesta en Producción Total
  • Fase 8: Mejoras Posteriores (LPR nativo, analítica)

📐 Convenciones de Código y Diseño

  • Backend:
    • Código en Python 3.11+ respetando PEP 8 y tipos estrictos (type hints).
    • Modelos y validaciones únicamente con Pydantic v2.
    • Rutas versionadas (/api/v1/...).
  • Frontend:
    • Nombres de componentes en formato PascalCase (AccessFormPanel.tsx).
    • Lógica encapsulada en Custom Hooks (useCameraScanner.ts, etc.) y componentes funcionales tipados de React.
    • Estilos centralizados en variables CSS semánticas para garantizar consistencia con OnEver Design System.
  • Operatividad:
    • Enfoque Keyboard-First: toda acción principal debe ser ejecutable sin ratón para garantizar la velocidad de atención requerida en garita.
  • Control de Versiones y Release:
    • Versionado Semántico independiente y sincronizado para backend/ (backend/app/__version__.py) y frontend/ (frontend/package.json).
    • Todo cambio y actualización de versión se documenta en CHANGELOG.md antes de cada commit/push.

📦 Repositorio Oficial y Publicación

El código fuente centralizado del proyecto se aloja en el servidor Gitea de la organización:

  • URL Remota: https://gitea.oemspot.com.ar/carlostellocba/OnEverControl
  • Rama Principal: main
  • Flujo de Publicación:
    1. Incrementar versión en backend y frontend.
    2. Registrar notas de versión en CHANGELOG.md.
    3. Ejecutar pruebas automatizadas (pytest y npm run build).
    4. Realizar commit semántico y push: git push origin main.

⚠️ Consideraciones Importantes

  1. Desacople de Hardware: El navegador web nunca intenta abrir sockets o puertos COM directos hacia las placas ST1660. Toda apertura se canaliza insertando en la tabla pdtmdl.
  2. Convivencia con Desktop: La base de datos es compartida. Se garantiza que un ingreso registrado desde la web puede cerrarse desde el sistema de escritorio existente y viceversa sin colisiones.
  3. Seguridad en Cámaras: Las credenciales de las cámaras Hikvision se resguardan en el servidor; el cliente web solo recibe snapshots procesados a través del proxy interno.

📌 Estado Actual del Proyecto

S
Description
No description provided
Readme
29 MiB
Languages
TypeScript 57.7%
Python 35.5%
CSS 5.1%
Batchfile 0.5%
Java 0.3%
Other 0.9%