feat: complete Phase 6 - Hybrid Coexistence testing, PWA kiosk mode, static SPA mount and Pilot manual (v0.6.0-beta)

This commit is contained in:
Carlos Tello
2026-10-13 15:58:47 -03:00
parent 1ba74f7929
commit a99b928bb5
12 changed files with 450 additions and 10 deletions
+105
View File
@@ -0,0 +1,105 @@
# GUÍA TÉCNICA: DESPLIEGUE PILOTO Y CONVIVENCIA HÍBRIDA (Fase 6)
## OnEverControl — Servidor de Puesto de Control Web
Esta guía detalla los pasos de instalación, configuración de red y puesta en marcha del **entorno piloto de OnEverControl** para operar de forma simultánea e híbrida con el sistema de escritorio existente de OnEverAccess.
---
### 1. Principio de Convivencia Híbrida
OnEverControl fue diseñado bajo una **arquitectura desacoplada no disruptiva**:
- **Base de Datos Compartida:** Ambas interfaces (Web y Escritorio) leen y escriben en las mismas tablas transaccionales de SQL Server (`videoman`: `tck`, `tckper`, `tckprx`, `tckhst`, `mvthist`).
- **Hardware Desacoplado:** El cliente web no toma puertos COM ni compite por recursos físicos. Toda apertura se encola en la tabla `pdtmdl`, la cual es leída y despachada por el servicio local `OnEverWPC` hacia las placas ST1660 en menos de 50 ms.
- **Transición Transparente:** Un ingreso registrado desde una tablet en la garita puede ser cerrado desde una PC con el software de escritorio, y viceversa, sin inconsistencias ni bloqueos.
---
### 2. Opciones de Despliegue del Servidor Web
El servidor puede instalarse en el mismo equipo donde corre OnEverAccess o en un nodo auxiliar de la red LAN:
#### Opción A: Windows 10/11 Bare-Metal (Modo Nativo o Servicio NSSM)
1. **Configurar el archivo `.env`:**
```env
DB_SERVER=localhost\SQLEXPRESS
DB_NAME=videoman
DB_USER=sa
DB_PASSWORD=SuPassword
SERVER_PORT=8000
```
2. **Construir el Frontend (si hubo cambios de código):**
```powershell
cd frontend
npm install
npm run build
```
3. **Ejecutar como Servicio de Windows (Permanente y Autoiniciable):**
Ejecute como Administrador:
```cmd
scripts\windows\install_service.bat
```
*El servicio iniciará automáticamente con el sistema operativo y reiniciará ante cualquier fallo.*
4. **Ejecución Directa de Diagnóstico:**
```cmd
scripts\windows\start_native.bat
```
---
#### Opción B: Contenedor LXC en Proxmox VE / Debian (Recomendado para servidores)
El contenedor LXC ofrece un consumo ultra-reducido (< 80 MB de RAM y < 1% CPU):
1. Cree un contenedor LXC Debian 12 en Proxmox con 1 vCPU, 512 MB de RAM y 4 GB de disco.
2. Copie la carpeta `OnEverControl/` al contenedor.
3. Ejecute el script automatizado de aprovisionamiento:
```bash
chmod +x scripts/lxc/setup_lxc.sh
sudo ./scripts/lxc/setup_lxc.sh
```
4. El script configurará las dependencias de FreeTDS, creará el entorno virtual Python y registrará el servicio `systemd` `onevercontrol.service` con reinicio automático.
---
#### Opción C: Docker Compose con Nginx Reverse Proxy
1. Verifique que Docker y Docker Compose estén instalados en el host.
2. Levante el stack productivo:
```bash
docker compose up -d
```
3. El frontend y los WebSockets quedarán disponibles en el puerto estándar `80`.
---
### 3. Configuración de la Tablet en Garita (Samsung Galaxy Tab)
1. **Conexión de Red:** Conecte la tablet a la red Wi-Fi de garitas (debe tener visibilidad TCP hacia la IP del servidor en el puerto 8000 u 80).
2. **IP Fija / DHCP Reserva:** Se recomienda asignar reserva DHCP a la tablet y registrar su nombre en la tabla `wks` de la base de datos (por ejemplo: `TAB_GARITA_1`).
3. **Instalación como PWA Standalone (Kiosco):**
- Abra Chrome o Samsung Internet y navegue a `http://<IP_SERVIDOR>:8000/`.
- Toque los 3 puntos del menú y elija **"Agregar a pantalla de inicio"** (o "Instalar aplicación").
- La aplicación quedará instalada como una app nativa, con ícono de garita, pantalla completa y soporte de orientación táctil.
---
### 4. Checklist de Verificación Pre-Vuelo (Testing Piloto)
Antes de entregar la tablet al guardia de seguridad en el puesto:
| Ítem | Prueba | Criterio de Éxito |
| :--- | :--- | :--- |
| **1. Conectividad** | Navegar a `http://<IP>:8000/health` | Retorna `{"status": "ok", "version": "0.6.0-beta"}` |
| **2. Login** | Iniciar sesión con usuario `guardia` | Ingreso exitoso y emisión de cookie HttpOnly |
| **3. WebSockets** | Observar indicador en cabecera | Badge verde `● Online` activo |
| **4. Hardware** | Toque en "⚡ Abrir Barrera Entrada" | Barrera física levanta y latencia < 100 ms |
| **5. Escaneo DNI** | Escanear DNI con la cámara de la tablet | Datos de documento, apellido y nombre completados |
| **6. Híbrido** | Ingresar un auto desde la web y cerrar desde la PC | El auto desaparece del listado en ambos sistemas |
---
### 5. Plan de Contingencia Durante el Piloto
Si por cualquier motivo la tablet sufriera descarga de batería o pérdida de enlace Wi-Fi durante el turno:
- El guardia puede sentarse en la PC habitual y abrir el sistema de escritorio existente (`pct_view.py`).
- No se pierde ninguna información: todos los vehículos ingresados durante el turno continuarán visibles en el sistema de escritorio para darles salida con normalidad.
+95
View File
@@ -0,0 +1,95 @@
# MANUAL OPERATIVO: PUESTO DE CONTROL WEB (OnEverControl)
## Guía de Uso Rápido para Operadores de Garita y Tablets Samsung Galaxy Tab
Este manual describe el funcionamiento diario de la interfaz web de **OnEverControl**, optimizada para su uso táctil en tablets **Samsung Galaxy Tab A9 / A11** y terminales de escritorio.
---
### 1. Acceso e Inicio de Turno
1. Abra el navegador Chrome o Samsung Internet en la tablet e ingrese a la dirección local asignada (ejemplo: `http://192.168.1.100:8000`).
2. *(Recomendado)* **Modo Kiosco / Pantalla Completa:**
- En el menú del navegador, seleccione **"Agregar a pantalla de inicio"** (o "Instalar aplicación").
- Abra el ícono **OnEverControl** desde la pantalla principal de la tablet; la aplicación se iniciará en pantalla completa sin barras de navegación ni botones que distraigan al operador.
3. **Inicio de Sesión:**
- **Puesto de Control / Workstation:** Seleccione la garita correspondiente (por ejemplo: `CFT-DESK`, `GARITA_PRINCIPAL`).
- **Usuario y Contraseña:** Ingrese sus credenciales habituales de OnEverAccess (ej: `guardia`).
- Presione el botón **"Iniciar Turno"**.
---
### 2. Pantalla Principal (Garita Cockpit)
La interfaz se divide en dos secciones operativas:
```text
┌──────────────────────────────────────────┬──────────────────────────────────────────┐
│ COLUMNA 1: INGRESO RÁPIDO │ COLUMNA 2: PREDIO Y EGRESOS │
│ │ │
│ [ 📷 ESCANEAR DNI CON CÁMARA ] │ [ 🔍 Filtrar por Patente o DNI... ] │
│ │ Badge: [ 14 visitas en predio ] │
│ • Módulo de Entrada: [ ENTRADA VISITAS] │ │
│ • DNI: [ 30123456 ] Sexo: [ M ] │ Lista de Visitas Activas: │
│ • Apellido: [ PEREZ ] Nombre: [JUAN] │ ┌─────────────────────────────────────┐ │
│ • Patente: [ AA123BB ] Lote: [ 142 ] │ │ [ AA123BB ] PEREZ, JUAN (DNI ...) │ │
│ • Motivo: [ VISITA ] Ocupantes: [-2+]│ │ Lote 142 • 14:32 [ DAR SALIDA ] │ │
│ │ └─────────────────────────────────────┘ │
│ [x] Abrir barrera al confirmar │ │
│ │ [⚡ Abrir Barrera Entrada] │
│ [ ✓ REGISTRAR INGRESO Y ABRIR BARRERA ] │ [⚡ Abrir Barrera Salida ] │
└──────────────────────────────────────────┴──────────────────────────────────────────┘
```
---
### 3. Registro de un Ingreso Paso a Paso
#### Opción A: Con Cámara de la Tablet (Recomendada)
1. Toque el botón azul **"📷 ESCANEAR DNI CON CÁMARA"**.
2. Apunte la cámara trasera de la tablet hacia el código de barras (PDF417 o QR) del DNI argentino del visitante.
- Si es de noche o hay poca luz, presione el botón **"💡 Encender Linterna"**.
3. El sistema reconocerá automáticamente el código, cerrará la cámara al instante para ahorrar batería/RAM y autocompletará **Documento, Apellido, Nombre y Sexo**.
4. Ingrese la **Patente** del vehículo (si ingresa a pie, déjela en blanco).
5. Escriba el **Lote / Destino** (ej: `142`). El sistema mostrará sugerencias predictivas táctiles para seleccionar con un toque.
6. Ajuste los **Ocupantes** con los botones grandes `+` y `-`.
7. Presione el botón verde grande **"✓ REGISTRAR INGRESO Y ABRIR"**.
- El sistema validará que la persona no esté adentro (Antipassback).
- Generará el ticket en la base de datos de OnEverAccess.
- Enviará el pulso inmediato de apertura a la barrera.
#### Opción B: Carga Manual Rápida
1. Toque el campo **Documento / DNI** e ingrese el número.
2. Complete el apellido, nombre, patente y lote de destino.
3. Presione **"✓ REGISTRAR INGRESO Y ABRIR"**.
---
### 4. Registro de Salida (Egreso)
1. Cuando un vehículo llega a la barrera de salida, ubíquelo en la columna derecha **Predio y Egresos**.
- Puede escribir los primeros números o letras de la patente en la barra de búsqueda `🔍 Filtrar...`.
2. Presione el botón rojo **"DAR SALIDA"** correspondiente al vehículo.
3. El sistema:
- Registrará el egreso y liberará el ticket activo.
- Accionará la barrera física de salida asignada a la estación.
- Actualizará el contador de visitas dentro del predio en tiempo real.
---
### 5. Aperturas Manuales de Emergencia
En la barra inferior se encuentran disponibles botones de acceso directo para contingencias:
- **⚡ Abrir Barrera Entrada:** Envía un pulso de apertura manual al carril de ingreso asignado.
- **⚡ Abrir Barrera Salida:** Envía un pulso de apertura manual al carril de egreso asignado.
*Nota: Toda apertura manual queda registrada con fecha, hora y usuario del guardia para auditoría de seguridad.*
---
### 6. Preguntas Frecuentes y Solución de Problemas
* **¿Qué significa el cartel "Antipassback detectado"?**
Indica que el visitante o vehículo ya figura con un ingreso activo dentro del predio y no registró su salida previa. Si el vehículo efectivamente salió antes sin ser registrado, diríjase a la lista de visitas y dele salida manual antes de ingresarlo nuevamente.
* **El indicador de estado dice "○ Reconectando..." en rojo:**
Verifique que la tablet continúe conectada a la red Wi-Fi de la garita. La aplicación reintentará conectarse automáticamente cada 3 segundos sin perder los datos que haya escrito en pantalla.
* **La cámara no enfoca el código:**
Asegúrese de mantener el DNI a unos 15-20 centímetros de la lente y evite reflejos directos de tubos fluorescentes o del sol sobre el plástico del documento. Si el código está rayado o ilegible, utilice el teclado numérico para escribir el número de DNI directamente.