# 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**: ```text [ 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 ```text 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 ```bash cd OnEverControl copy .env.example .env ``` Configurar en `.env` las credenciales de SQL Server: ```ini 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) ```bash 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) ```bash 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: ```cmd 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: ```bash 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: ```bash 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](file:///c:/Workspace/OemspotPySYS/OnEverControl/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](file:///c:/Workspace/OemspotPySYS/OnEverControl/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`](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 - **Fase Actual:** **Fase 0 (Completada).** - **Repositorio:** Sincronizado en [`https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`](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).