14 KiB
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 servicioOnEverWPCejecutá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
100dvhque 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).
- Dispositivos Soportados:
🚀 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)
- Instalar Python 3.11 y compilar la SPA de React (
npm run build). - 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)
- Crear un contenedor LXC unprivileged con Debian 12 (mínimo 512 MB RAM / 1 vCPU asignada).
- Ejecutar el script automatizado:
chmod +x scripts/lxc/setup_lxc.sh && ./scripts/lxc/setup_lxc.sh - El servicio correrá gestionado por
systemd(systemctl status onevercontrol), consumiendo menos de 80 MB de memoria RAM.
Opción C: Docker & Docker Compose
- Levantar el stack completo (FastAPI + Nginx reverse proxy + estáticos de React) con un solo comando:
docker compose up -d - Acceso inmediato en el puerto
80o443con 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/...).
- Código en Python 3.11+ respetando PEP 8 y tipos estrictos (
- 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.
- Nombres de componentes en formato PascalCase (
- 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) yfrontend/(frontend/package.json). - Todo cambio y actualización de versión se documenta en CHANGELOG.md antes de cada commit/push.
- Versionado Semántico independiente y sincronizado para
📦 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:
- Incrementar versión en backend y frontend.
- Registrar notas de versión en
CHANGELOG.md. - Ejecutar pruebas automatizadas (
pytestynpm run build). - Realizar commit semántico y push:
git push origin main.
⚠️ Consideraciones Importantes
- 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. - 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.
- 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
- Fase Actual: Fase 0 (Completada).
- Repositorio: Sincronizado en
https://gitea.oemspot.com.ar/carlostellocba/OnEverControl. - Próximo Paso: Aprobación del informe técnico y comienzo de la Fase 1 (creación del esqueleto funcional de Backend FastAPI v0.1.0 y Frontend Vite v0.1.0).