252 lines
14 KiB
Markdown
252 lines
14 KiB
Markdown
# 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).
|