Files
OnEverControl/README.md
T

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).