Primer push Fase 0 de planificacion

This commit is contained in:
Carlos Tello
2026-10-13 15:01:04 -03:00
parent e2a5f1c1cd
commit 12c5649427
15 changed files with 1350 additions and 0 deletions
+50
View File
@@ -0,0 +1,50 @@
---
name: sdd
description: Úsala siempre que trabajes con Spec-Driven Development en OnEverControl (docs/constitution.md o cualquier archivo dentro de specs/) - redactar, revisar o cambiar specs, planes y tareas, o implementar y validar tareas de una spec.
---
# Spec-Driven Development (SDD) — OnEverControl
## Flujo
Constitución → Spec → Clarificación → Plan → Tareas → Implementación → Validación → Cambio.
- **Nunca pases a la siguiente fase sin la aprobación explícita del usuario.**
- **La spec manda:** si algo no está en la spec activa, no se implementa. Si falta una decisión, para y pregunta.
- **Un cambio de requisitos** se hace primero en la spec, luego en el plan y las tareas, y por último en el código.
- Cada spec vive en su carpeta: `specs/NNN-nombre/` con `spec.md`, `plan.md` y `tasks.md`.
- Al terminar cada fase o tarea, actualiza `MEMORY.md`.
## Estructura de la Spec (`spec.md`)
- **Contexto y objetivo:** Qué problema resuelve y por qué.
- **Usuarios / actores:** Quién lo usa (Operador de garita, Supervisor, etc.).
- **Historias de usuario:** `Como <rol>, quiero <acción> para <beneficio>`.
- **Requisitos funcionales en EARS (en español):**
- Ubicuo: `EL SISTEMA <comportamiento permanente>`.
- Con evento: `CUANDO <evento>, EL SISTEMA <respuesta>`.
- Con condición no deseada: `SI <condición de error/excepción>, ENTONCES EL SISTEMA <respuesta>`.
- Con estado: `MIENTRAS <estado>, EL SISTEMA <respuesta>`.
- **Requisitos no funcionales:** Rendimiento, diseño Touch-First, plataformas táctiles.
- **Casos límite:** Datos vacíos, desconexiones, terminal no autorizada, credenciales inválidas.
- **Fuera de alcance:** Lo que explícitamente no se implementa en esta iteración.
- **Criterios de finalización:** Tests en verde + demo verificable.
## Estructura del Plan (`plan.md`)
- Archivos y responsabilidades (Backend FastAPI + Frontend Node.js).
- Contratos de datos (Pydantic schemas y TypeScript interfaces).
- Decisiones técnicas justificadas con alternativas descartadas.
- Estrategia de tests (pytest para backend, vitest/playwright para frontend).
## Estructura de Tareas (`tasks.md`)
- Tareas pequeñas (máximo 20-30 minutos cada una), en orden de dependencia estricta.
- Formato:
```markdown
- [ ] **Tn. <Descripción de la tarea>.** RF-x, RF-y
- Hecho cuando: <comprobación verificable>.
```
## Implementación de Tareas
- **Una sola tarea cada vez:**
1. Escribir primero los tests y verificar que fallan (en rojo).
2. Escribir el código hasta que los tests pasen (en verde).
3. Ejecutar la suite de pruebas.
4. Marcar la tarea en `tasks.md`, actualizar `MEMORY.md` y parar.
+57
View File
@@ -0,0 +1,57 @@
# AGENTS.md — OnEverControl
Cliente web reducido para Puesto de Control y Login en la red local de OnEverAccess, optimizado para tablets táctiles (Android, Windows, iPad) y terminales de garita.
## Stack y estructura
- **Backend:** FastAPI (Python 3.11+), Pydantic v2, pymssql, Uvicorn en `backend/`.
- **Frontend:** React + TypeScript + Vite (Node.js v20+), Vanilla CSS tokens en `frontend/`.
- **Hardware Objetivo:** Tablets Samsung Galaxy Tab A9 y A11 (4 GB RAM, Android).
- **Entornos de Ejecución Servidor:** Windows 10/11 (bare-metal / servicio), LXC (Linux Containers en Proxmox/Debian) y Docker / Docker Compose.
- **Base de Datos & Hardware:** SQL Server `videoman` (compat 100+) y cola `pdtmdl` en red local.
- **Repositorio Git Remoto:** Gitea en `https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`.
- **Especificaciones:** `specs/NNN-nombre/` con `spec.md`, `plan.md` y `tasks.md`.
## Comandos
- Backend dev: `cd backend && uvicorn app.main:app --reload --port 8000`
- Backend tests: `cd backend && pytest`
- Frontend dev: `cd frontend && npm run dev`
- Frontend tests/build: `cd frontend && npm run test && npm run build`
- Git push a Gitea: `git push origin main`
## Convenciones
- Código en inglés; interfaz de usuario y documentación en español.
- Diseño **Touch-First para 4GB RAM:** Touch targets >= 48px, layout `100dvh`, `inputmode="numeric"`.
- Rendimiento y memoria: React memoization (`useCallback`, `React.memo`), liberación estricta de streams de cámara (`MediaStream.getTracks().forEach(t => t.stop())`), cero dependencias infladas.
- Portabilidad estricta: Usar siempre `pathlib.Path` y variables `.env`; nada de rutas con `C:\...` ni llamadas exclusivas a Win32 en el backend.
- Modelos Pydantic v2 estrictos en el backend.
- **Versionado Semántico (SemVer):** El backend (`backend/app/__version__.py` / `pyproject.toml`) y frontend (`frontend/package.json`) deben mantener sus versiones actualizadas y sincronizadas en cada hito o release, registrándolas en `CHANGELOG.md` antes de subir al repositorio Gitea.
## Reglas de dominio / trampas conocidas
- **Modo Cliente Reducido:** No implementar módulos de administración general ni ERP de OnEverAccess.
- **Hardware Desacoplado:** El frontend NUNCA toca puertos COM; encola órdenes en la tabla `pdtmdl`. Al no requerir COM directo en el backend, permite despliegue nativo en LXC y Docker sin passthrough de hardware.
- **Tablet = Workstation:** Toda tablet opera bajo un `workstation_name` registrado en SQL Server.
- **Lectura de Documento por Cámara de la Tablet:** La lectura de DNI (PDF417 y QR) se realiza directamente con la cámara de la tablet (Barcode Detection API / ZXing), reemplazando por completo lectores físicos por puerto COM o emuladores de teclado.
- **Sin Streaming de Cámaras Hikvision:** No se implementa streaming de cámaras fijas por ISAPI en la versión web (ahorro de batería y ancho de banda en tablets); la tablet solo utiliza su propia cámara integrada para escanear DNI y capturar fotos de evidencia.
- **DNI Argentino:** Usar lógica validada de `herramientas/parser_dni.py` (formatos 2009, 2012, 2026 y App).
- **FreeTDS & Collation en Linux/LXC:** Asegurar configuración de charset UTF-8 hacia SQL Server con collation `Modern_Spanish_CI_AS`.
## Forma de trabajar (Spec-Driven Development)
- Respetar `docs/constitution.md` y la spec activa en `specs/` antes de tocar código.
- Implementar **UNA sola tarea a la vez** de `tasks.md`: tests en rojo primero, luego código, tests en verde, marcar y parar.
- **Flujo de Versionado y Push a Gitea:** Al completar una fase o release:
1. Actualizar número de versión en `backend/` y `frontend/`.
2. Registrar cambios en `CHANGELOG.md`.
3. Ejecutar suite de validación (pytest + build).
4. Realizar commit semántico y push a `https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`.
- No saltarse la aprobación del usuario antes de pasar a la siguiente fase o tarea.
## Límites
- ✅ **Siempre:** Mantener `MEMORY.md` y `CHANGELOG.md` actualizados. Incrementar versiones de backend y frontend antes de subir a Gitea. Respetar principios de `docs/constitution.md`.
- ⚠️ **Pregunta antes:** Cambios en el modelo de base de datos, nuevas dependencias npm/pip, o divergencias con la spec.
- 🚫 **Nunca:** Subir a Gitea con tests fallando o sin actualizar la versión en backend/frontend. Modificar tablas maestras de OnEverAccess fuera de alcance.
## Verificación
- Backend: `pytest` sin advertencias.
- Frontend: `npm run build` sin errores de TypeScript y comprobación de interacción táctil.
- Versiones: Versiones sincronizadas en `backend/` y `frontend/` registradas en `CHANGELOG.md`.
- Consultar `MEMORY.md` para conocer el estado y decisiones entre sesiones.
+24
View File
@@ -0,0 +1,24 @@
# Changelog — OnEverControl
Todas las modificaciones, adiciones y decisiones de arquitectura notables de este proyecto serán documentadas en este archivo.
## [Fase 0: Análisis y Arquitectura] - 2026-10-13
### Agregado
- **Informe Técnico Maestro:** Análisis exhaustivo del sistema de puesto de control actual (`OemspotPySYS`), arquitectura desacoplada, modelo transaccional y propuesta de cliente web en [INFORME_TECNICO_PUESTO_DE_CONTROL_WEB.md](file:///c:/Workspace/OemspotPySYS/OnEverControl/INFORME_TECNICO_PUESTO_DE_CONTROL_WEB.md).
- **Constitución del Proyecto:** 9 principios innegociables (Thin Client, SDD, Hardware vía `pdtmdl`, Touch-First, Tablet como Workstation, TDD, Atomicidad SQL Server, Convenciones de Idioma, Portabilidad Multiplataforma Windows/LXC/Docker) en [docs/constitution.md](file:///c:/Workspace/OemspotPySYS/OnEverControl/docs/constitution.md).
- **Arnés de Agentes de IA:** Reglas operativas, convenciones y trampas de dominio en [AGENTS.md](file:///c:/Workspace/OemspotPySYS/OnEverControl/AGENTS.md) y memoria de contexto en [MEMORY.md](file:///c:/Workspace/OemspotPySYS/OnEverControl/MEMORY.md).
- **Skill SDD:** Habilidad reutilizable de desarrollo guiado por especificaciones en [.agents/skills/sdd/SKILL.md](file:///c:/Workspace/OemspotPySYS/OnEverControl/.agents/skills/sdd/SKILL.md).
- **Especificaciones EARS Iniciales:**
- `specs/001-login-workstation/`: Autenticación de operadores y resolución de estación de trabajo / carril.
- `specs/002-access-control-camera-scanner/`: Escaneo óptico de DNI argentino (PDF417 y QR) mediante la cámara de la tablet.
- **Documentación y Hoja de Ruta:** [README.md](file:///c:/Workspace/OemspotPySYS/OnEverControl/README.md) y [ROADMAP.md](file:///c:/Workspace/OemspotPySYS/OnEverControl/ROADMAP.md) con fases 0 a 8.
### Definiciones de Arquitectura
- **Backend:** FastAPI (Python 3.11+) + Pydantic v2.
- **Frontend:** React + TypeScript + Vite (SPA estática optimizada para tablets Samsung Galaxy Tab A9 y A11 de 4 GB RAM).
- **Soporte de Servidor Multiplataforma:** Capacidad de ejecución agnóstica en **Windows 10/11** (bare-metal / servicio NSSM), contenedores **LXC** (Proxmox VE / Debian con systemd y FreeTDS, < 80 MB RAM overhead) y **Docker / Docker Compose**.
- **Desacople de Hardware:** Toda orden física hacia barreras y molinetes ST1660 se encola en la tabla `pdtmdl` de SQL Server `videoman`, sin requerir puertos COM ni drivers Win32 en el servidor web.
- **Escaneo Óptico y Cámara:** Reemplazo total de escáneres físicos COM o emulación de teclado por la cámara integrada de la tablet (Barcode Detection API / ZXing).
- **Sin Streaming Hikvision ISAPI:** Exclusión de transmisión de video continuo en cliente web para proteger batería y ancho de banda en garitas.
- **Repositorio Oficial Gitea & Versionado:** Repositorio oficial en [`https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`](https://gitea.oemspot.com.ar/carlostellocba/OnEverControl). Requisito formal de incrementar y sincronizar versiones de backend y frontend con registro en este changelog antes de cada push.
+587
View File
@@ -0,0 +1,587 @@
# INFORME TÉCNICO Y PROPUESTA DE ARQUITECTURA
## Sistema "Puesto de Control" — Versión Web (OnEverControl)
**Proyecto:** Migración y Modernización de Puesto de Control a Arquitectura Web (Backend: FastAPI + Pydantic v2 | Frontend: React + TypeScript + Vite)
**Autor:** Antigravity (Advanced Agentic AI Assistant)
**Fecha:** Octubre 2026
**Ubicación de Documentación:** `OnEverControl/`
**Estado:** Fase 0 — Análisis, Diseño y Definición de Arquitectura
---
## 1. Análisis del Sistema Actual
### 1.1. Contexto, Propósito y Alcance Reducido ("Modo Cliente Web")
**OnEverControl** se concibe estrictamente como un **Modo Cliente Web Ligero (Thin Client)**. No tiene por objetivo migrar ni duplicar los módulos administrativos centrales de la suite completa `OemspotPySYS` / `OnEverAccess` (como altas maestras de socios, liquidaciones, configuración de infraestructura de bajo nivel o reportes contables).
Su alcance está específicamente acotado y enfocado a dos módulos clave:
1. **Módulo de Login / Autenticación:** Inicio y cierre de sesión del operador/guardia validando credenciales y privilegios existentes en la base de datos `videoman`.
2. **Módulo de Puesto de Control:** La operativa de garita en tiempo real para autorizar ingresos y egresos (peatonales y vehiculares), lectura de DNI, validación de pólizas, gestión de acompañantes, control de antipassback y encolado de comandos de apertura de barrera (`pdtmdl`).
**Objetivo de Despliegue en Red Local:**
El sistema está diseñado para ser desplegado dentro de la **red local (LAN) donde ya se encuentra en funcionamiento operativo OnEverAccess** (junto a su base de datos SQL Server y su daemon de hardware `OnEverWPC`). Esto permite que cualquier terminal de garita, notebook de guardia, tablet perimetral o PC secundaria de la intranet acceda instantáneamente al puesto de control mediante un navegador web, eliminando la necesidad de instalar dependencias de Python, entornos gráficos PyQt6 o librerías locales en cada puesto físico.
### 1.2. Mapeo de Funcionalidades Actuales
A partir de la inspección exhaustiva de los módulos de escritorio (`puestocontrol/pct_view.py`, `pct_repository.py`, `pct_dialogs.py`, `pct_integrantes_dialog.py`, `pct_salida_integrantes_dialog.py`, `pct_session_manager.py` y `pct_threads.py`), se identifican las siguientes funcionalidades operativas:
1. **Gestión de Carriles Multi-Pestaña y Workstations:**
- La aplicación detecta el nombre de la máquina física (`get_workstation_name()`), consulta en la base de datos si es un puesto de control válido (`es_puesto_de_control`) y recupera los módulos/carriles asignados a dicha estación (`listar_modulos_por_workstation`).
- Cada carril opera en una pestaña independiente que puede estar configurada en sentido **Entrada** o **Salida**.
2. **Lectura y Decodificación de Documentos de Identidad (DNI):**
- Recepción de cadenas crudas desde escáneres de código de barras/QR (PDF417 de DNI argentino y QR de Renaper / Mi Argentina).
- Parsing automático de documento, apellido, nombre y sexo mediante `herramientas/parser_dni.py` (soportando formatos 2009, 2012, 2026 y digital).
3. **Búsqueda Avanzada y Predictiva de Personas:**
- Búsqueda por documento, por coincidencia fonética/parcial de apellido y nombre (`buscar_personas_avanzado`), o selección directa desde el padrón general (`Per`).
4. **Búsqueda y Asociación Vehicular por Patente:**
- Búsqueda predictiva por dominio/patente (`buscar_vehiculos_coincidencias`).
- Autocompletado del conductor habitual asociado a la patente (`peraut`).
- Asociación dinámica de vehículos a personas al momento del ingreso.
5. **Gestión de Preautorizaciones:**
- Consulta de visitas o proveedores autorizados previamente por propietarios de lotes (`obtener_preautorizados_activos`).
- Verificación de fechas de vigencia y consumo automático de la preautorización al registrar el ingreso (`consumir_preautorizacion`).
6. **Selección y Validación de Destino (Lote / Unidad Funcional):**
- Búsqueda interactiva de lotes por número o calle (`Lot`).
- Validación reactiva del estado del lote (al día, restringido, obras suspendidas, etc. vía `obtener_permiso_lote`).
- Consulta de residentes del lote (`obtener_residentes_lote`).
7. **Control de Documentación y Pólizas de Seguro:**
- Registro de Conducir: número, entidad emisora, vigencia desde/hasta.
- Póliza de Seguro ART (obligatoria para proveedores y trabajadores de obra).
- Póliza de Seguro Automotor: aseguradora, póliza, vigencias.
- Notificación visual de campos obligatorios o vencidos con validación reactiva de fechas.
8. **Gestión Integral de Acompañantes / Integrantes Vehiculares:**
- Diferenciación de roles: Conductor vs. Peatón/Acompañante.
- Selector numérico de ocupantes (adultos y menores).
- Diálogo de registro rápido de acompañantes (`DialogoRegistroIntegrantes`) que permite escanear secuencialmente los DNI de cada pasajero.
- Desacople y control en salida: Al egresar un vehículo con acompañantes, el sistema permite marcar quiénes salen en el coche, quiénes egresan a pie y quiénes permanecen en el predio (convirtiéndose de forma atómica en peatones dentro del barrio para evitar alertas de seguridad o evasiones).
9. **Control de Antipassback:**
- Verificación previa si la persona ya posee un ticket activo adentro (`verificar_antipassback`).
- Si se detecta violación de antipassback, el sistema muestra un banner de alerta destacado y un botón de un clic ("🚪 Ir a Salida") que traslada el contexto directamente al carril de egreso.
10. **Generación y Registro del Ticket de Ingreso:**
- Inserción atómica del ticket principal (`tck`), personas asociadas (`tckper`), metadatos dinámicos (`tckprx`) y registro histórico de movimientos (`mvthist`).
- Encolado de la orden de apertura física de barrera/molinete en la tabla `pdtmdl`.
- Encolado opcional de orden de impresión de comprobante/ticket con código de barras (`T9`) para tótems expendedores.
11. **Registro y Validación de Salida:**
- Localización rápida del ingreso activo por documento, patente o selección desde el padrón de ingresados (`DialogoTicketActivoSalida`).
- Cálculo del tiempo de permanencia transcurrido.
- Checkbox de cacheo a la salida y verificación de baúl inspeccionado.
- Cierre del ticket activo, archivado a histórico (`tckhst`) y apertura de la barrera de egreso.
12. **Padrón de Visitas Ingresadas (En Tiempo Real):**
- Grilla de todas las personas y vehículos actualmente dentro del predio (`obtener_ingresados`).
- Filtros multicriterio por nombre, DNI, lote y patente.
13. **Herramienta de Salida Masiva:**
- Diálogo administrativo (`DlgSalidaMasiva`) para desalojar en bloque a obreros o visitas ante fin de jornada laboral o toque de queda nocturno.
14. **Streaming de Video y Captura de Evidencia Fotográfica:**
- Conexión vía HTTP Digest ISAPI con cámaras IP Hikvision (`VideoStreamThread`) para monitorear el carril vehicular y el rostro del ingresante a ~15 FPS.
- Captura manual o automática de fotos de carril / rostro / DNI asociadas al evento de acceso.
- Soporte para captura mediante webcam USB local (`LocalCameraThread`).
15. **Persistencia de Sesiones de Carril Pendientes:**
- Mecanismo en memoria y archivo JSON temporal (`CarrilProcessSessionManager`) para pausar la carga de un vehículo con múltiples integrantes si el guardia debe atender una emergencia en otro carril, evitando perder lo escaneado.
---
### 1.3. Matriz de Clasificación de Funcionalidades
| Funcionalidad | Clasificación | Justificación y Estrategia en la Versión Web |
| :--- | :---: | :--- |
| **Ingreso y Salida de Visitas/Proveedores** | **Mantener y Mejorar** | Es el núcleo del negocio. Debe mantenerse 100% equivalente en reglas de validación pero con una UI más fluida, reactiva y táctil/keyboard-first. |
| **Parsing de DNI (Formatos 2009/2012/2026/App)** | **Mantener** | La lógica matemática y de expresiones regulares actual de `parser_dni.py` es excelente y debe trasladarse al backend FastAPI, con validación espejo en frontend para respuesta instantánea. |
| **Gestión de Integrantes y Desacople en Salida** | **Mantener y Modernizar** | El flujo actual requiere múltiples diálogos emergentes modales de PyQt. En web, se modernizará mediante un drawer lateral o wizard interactivo dentro de la misma pantalla del carril, reduciendo clics. |
| **Consulta de Preautorizados y Consumo** | **Mantener y Potenciar** | En web se integrará con actualización en tiempo real (WebSockets), de modo que si un vecino autoriza una visita desde su app móvil, el puesto de control lo vea de inmediato sin presionar "refrescar". |
| **Encolado de Comandos de Hardware (`pdtmdl`)** | **Mantener** | La tabla `pdtmdl` es el estándar probado y seguro que desacopla la aplicación de las placas ST1660. El backend FastAPI insertará en `pdtmdl` de forma asíncrona garantizando tiempos de respuesta menores a 10 ms. |
| **Padrón de Ingresados y Salida Masiva** | **Mantener y Modernizar** | Grilla web reactiva con filtros rápidos, paginación virtualizada y selección masiva con confirmación segura. |
| **Streaming de Cámaras Hikvision por ISAPI** | **Eliminar en Versión Web** | No se utiliza en la versión cliente web. Elimina sobrecarga de red Wi-Fi y consumo de batería en las tablets de garita. El monitoreo de video perimetral continuo permanece donde corresponde: en el sistema CCTV/NVR de la garita o en la estación central OnEverAccess. La tablet se enfoca exclusivamente en su propia cámara integrada para escanear DNI y capturar fotos de evidencia. |
| **Acceso a Puerto Serial COM y Emulación de Teclado** | **Reemplazar por Cámara de Tablet** | Se eliminan por completo los lectores físicos externos de código de barras/QR (puerto COM y USB teclado). La lectura de DNI (PDF417 y QR) se realiza directamente con la cámara integrada de la tablet mediante la Barcode Detection API nativa y ZXing Wasm/JS en el frontend, capturando al mismo tiempo la foto de evidencia del documento. |
| **Ventanas Modales Anidadas de PyQt6** | **Eliminar** | Múltiples modales apilados (ej: ventana sobre ventana para fecha, lote, integrantes) degradan la UX web. Se reemplazan por componentes modales modernos tipo Dialog, Drawers y Popovers fluidos. |
| **Dependencia de la variable `COMPUTERNAME` del SO** | **Reemplazar por Workstation Registrada** | Cada tablet se da de alta en la base de datos de OnEverAccess como una Workstation formal (ej: `TABLET_01`), persistida de forma segura en la tablet y validada con las mismas funciones y reglas que una PC Windows. |
| **Nueva: Monitoreo en Tiempo Real Multi-Puesto (WebSocket)** | **Nueva** | Sincronización instantánea de estados entre múltiples garitas o puestos simultáneos (ej: garita principal, garita secundaria, administración central). |
| **Nueva: Modo Operativo Offline Resiliente** | **Nueva** | Cache de operaciones críticas con Service Workers / PWA si ocurre micro-cortes en la red interna de la garita. |
| **Nueva: Telemetría y Métricas en Tiempo Real** | **Nueva** | Dashboard de tiempos de atención por guardia, picos de flujo vehicular y demoras de barrera. |
---
### 1.4. Dependencias con Hardware, Red y Servicios Externos
```mermaid
graph TD
subgraph Puesto_Fisico_Garita [Puesto Físico / Garita de Seguridad]
PC[PC / Terminal Operador]
Lector[Lector Código Barras / QR USB o Serie]
Webcam[Webcam USB Operador]
Lector -->|Teclado HID o RS-232| PC
Webcam -->|Video USB UVC| PC
end
subgraph Dispositivos_Infraestructura [Infraestructura de Campo]
CamHik[Cámaras Hikvision IP LPR/Rostro]
Placa[Controladores ST1660 PASS/PARK]
Barrera[Barreras / Molinetes / Puertas]
Placa -->|Relé / Pulso| Barrera
end
subgraph Servidores_Red_Local [Red Local / Servidor OnEver]
ServerWPC[Servicio OnEverWPC / Python Daemon]
FastAPI[Backend FastAPI OnEverControl]
SQLServer[(Base de Datos SQL Server 'videoman')]
end
PC -->|HTTPS / WebSocket| FastAPI
CamHik -->|RTSP / ISAPI Digest| FastAPI
FastAPI -->|pymssql / Async Pool| SQLServer
FastAPI -->|INSERT comando| SQLServer
SQLServer -.->|pdtmdl| ServerWPC
ServerWPC -->|RS-485 / COM| Placa
```
1. **Controladores de Hardware (ST1660 Pass & Park):**
- Protocolo serial propietario binario (tramas con `STX`, dirección 01-99, comando `O3`/`O5`/`V3`/`V6`, checksum).
- Conexión física mediante bus RS-485 multipunto conectado a puerto COM físico o adaptador USB-Serial (FTDI/CH340).
- Actualmente despachado por el servicio de fondo `OemspotPyWPC` mediante la tabla de cola `pdtmdl`.
2. **Lectores de Documentos / QR:**
- Lectores Honeywell, Datalogic o genéricos conectados por USB (modo Teclado HID) o puerto RS-232 / Virtual COM.
3. **Cámaras IP Hikvision:**
- Protocolo ISAPI HTTP Digest (`/ISAPI/Streaming/channels/{ch}/picture`) y RTSP H.264 para video continuo. Requieren credenciales Digest y acceso a la subred de seguridad.
4. **Base de Datos Microsoft SQL Server:**
- Base de datos relacional `videoman`. Motor SQL Server 2008 / 2012 / 2016+ con nivel de compatibilidad 100+, collation `Modern_Spanish_CI_AS`.
---
### 1.5. Limitaciones Identificadas para la Transición Web y Soluciones
1. **Reemplazo del Lector Físico por la Cámara Integrada de la Tablet:**
- *Comportamiento actual en desktop:* El sistema dependía de lectores físicos de código de barras/QR conectados a puertos serie COM (`SerialQRReaderThread`) o mediante cables USB emulando teclado.
- *Solución adoptada en OnEverControl:* Se **eliminan por completo los escáneres físicos externos** (tanto por puerto COM como por emulación de teclado). La tablet utiliza su propia cámara integrada (trasera/frontal) mediante la **Barcode Detection API nativa** del navegador y fallback con **ZXing (WebAssembly/JS)** en el frontend. Al enfocar el documento de identidad, el navegador detecta y decodifica el código PDF417 o QR en tiempo real en menos de 50 ms, ejecuta el parser de DNI y captura simultáneamente el fotograma del documento como evidencia visual. Esto reduce costos a cero en lectores, elimina cables y otorga máxima movilidad al guardia en el carril.
2. **Descarte de la función de Streaming de Cámaras Hikvision por ISAPI:**
- *Comportamiento actual en desktop:* La aplicación de escritorio ejecutaba hilos continuos `VideoStreamThread` con solicitudes HTTP Digest cada 60 ms para mostrar el video del carril en pantalla.
- *Definición adoptada en OnEverControl:* La versión web cliente para tablets **prescinde del streaming de cámaras Hikvision por ISAPI**. Esta decisión elimina la saturación de ancho de banda sobre la red Wi-Fi de garitas, erradica el drenaje de batería y recalentamiento en las tablets, y simplifica la arquitectura al no requerir proxies de video complejos. El monitoreo perimetral permanente continúa en el sistema de CCTV/NVR de la garita o en OnEverAccess central, mientras que la tablet se enfoca en su objetivo operativo: lectura rápida de DNI con su propia cámara, validaciones de acceso y apertura de paso.
3. **La Tablet como una Workstation oficial de OnEverAccess:**
- *Comportamiento en PC Windows:* En la aplicación de escritorio PyQt6, el sistema invoca `get_workstation_name()` leyendo `os.environ["COMPUTERNAME"]` y valida en base de datos `es_puesto_de_control(workstation_name)` y `listar_modulos_por_workstation(workstation_name)`.
- *Mecanismo para Tablets (Android, iPadOS, Windows):*
Cada tablet se da de alta en la base de datos `videoman` de OnEverAccess como una **Workstation formal** (ejemplo: `TABLET_GARITA_1`, `TABLET_ACCESO_PROV`, `TABLET_PATRULLA`).
En el navegador de la tablet, el `workstation_name` se vincula durante el primer inicio o configuración inicial de la garita y queda persistido de manera inmutable en el almacenamiento seguro de la tablet (`localStorage` y Cookie HttpOnly firmada).
Al iniciar sesión el guardia, el backend FastAPI ejecuta **exactamente las mismas consultas T-SQL que el sistema de escritorio actual**:
- Verifica si la estación es un puesto de control activo (`es_puesto_de_control`).
- Recupera los módulos y carriles físicos/virtuales asignados a esa estación (`listar_modulos_por_workstation`).
- Si la tablet no está autorizada, renderiza la pantalla de bloqueo y advertencia equivalente a `_crear_vista_no_autorizada`.
- Todos los tickets, eventos y auditorías registran el nombre de la Workstation asignada a la tablet, garantizando trazabilidad idéntica a una PC Windows física.
---
## 2. Propuesta de Arquitectura para la Versión Web
### 2.1. Arquitectura General del Sistema
Se adopta una arquitectura desacoplada basada en **Microservicios Híbridos y Clean Architecture**, garantizando alta disponibilidad, aislamiento de fallos y rendimiento en tiempo real:
```mermaid
graph LR
subgraph Cliente_Web [Frontend SPA / PWA Tablets 4GB RAM]
UI[React + TS + Vite SPA]
SW[Service Worker Cache PWA]
WS_Client[WebSocket Client React Hook / Context]
end
subgraph Gateway_Proxy [Reverse Proxy & Edge]
Nginx[Nginx / Caddy SSL & Static Server]
end
subgraph Backend_Core [Backend FastAPI OnEverControl]
API_GW[FastAPI Router & Auth Middleware]
Access_Ctrl[Control de Acceso & Validaciones]
Tck_Service[Servicio de Tickets & Movimientos]
Hardware_Hub[Hardware Hub & Camera Proxy]
WS_Manager[WebSocket Real-time Manager]
DB_Adapter[Async Database Pool pymssql/SQLAlchemy]
end
subgraph Capa_Datos [Persistencia & Hardware Daemon]
MSSQL[(SQL Server 'videoman')]
WPC_Daemon[OnEverWPC Hardware Daemon]
end
UI <-->|HTTPS REST| Nginx
WS_Client <-->|WSS WebSockets| Nginx
Nginx <--> API_GW
API_GW --> Access_Ctrl
API_GW --> Tck_Service
API_GW --> Hardware_Hub
API_GW --> WS_Manager
Access_Ctrl --> DB_Adapter
Tck_Service --> DB_Adapter
DB_Adapter <--> MSSQL
Tck_Service -->|INSERT pdtmdl| MSSQL
MSSQL -.->|POLL pdtmdl| WPC_Daemon
```
### 2.2. Frontend (Diseño Táctil "Touch-First" para Tablets Android, Windows e iPad)
El frontend web está diseñado prioritariamente para **dispositivos de interfaz táctil**, específicamente tablets comerciales y de grado industrial (**Android, Microsoft Windows táctil / Surface, e iPad / iPadOS**), permitiendo a los guardias operar tanto desde soportes fijos en el mostrador de garita como desplazándose directamente hasta la ventanilla del vehículo:
1. **Diseño de Interfaz "Touch-First" & Ergonomía:**
- **Objetivos Táctiles Generosos (Touch Targets):** Todos los botones primarios, selectores y campos de entrada poseen una altura mínima de **48 x 48 píxeles** (cumpliendo los estándares WCAG y Apple Human Interface Guidelines), facilitando la pulsación rápida incluso con guantes o en condiciones de movimiento.
- **Diseño Híbrido "Touch + Keyboard":** La interfaz combina amplias zonas táctiles para tablets con atajos de teclado físicos (`F2`, `F4`, `Enter`, `Esc`) para puestos que cuenten con teclados físicos o lectores de código de barras.
2. **Adaptabilidad a Teclados Virtuales en Pantalla (On-Screen Keyboard):**
- **Viewport Dinámico Resiliente (`dvh`):** Layouts diseñados con unidades de viewport dinámicas (`100dvh`), con scroll interno suave que garantiza que, al desplegarse el teclado virtual de la tablet, los botones críticos de acción (**Confirmar Ingreso** y **Cancelar**) permanezcan visibles o rápidamente accesibles sin desbordar la pantalla.
- **Teclados Numéricos Contextuales:** Uso de atributos HTML5 específicos (`inputmode="numeric"`, `pattern="[0-9]*"`) en campos de DNI, teléfono, código de lote y selector de ocupantes, forzando a iPadOS y Android a desplegar el teclado numérico de dígitos grandes en lugar del teclado alfanumérico completo.
3. **Aprovechamiento de las Cámaras Integradas de la Tablet:**
- En lugar de requerir webcams USB externas, la interfaz web utiliza directamente la **cámara trasera y frontal de la tablet** mediante la API `navigator.mediaDevices.getUserMedia({ video: { facingMode: "environment" } })`. Esto permite al guardia apuntar la tablet hacia el DNI o el rostro del conductor y tomar la fotografía de evidencia con un toque en pantalla.
4. **Modo PWA (Progressive Web App) y Modo Kiosco:**
- Capacidad de **"Agregar a la pantalla de inicio"** en iPad (Safari), tablets Android (Chrome) y Windows (Edge), ejecutándose en modo **pantalla completa (Standalone / Kiosk)** sin barras de URL ni botones del navegador.
- Prevención de gestos indeseados: desactivación de zoom por doble toque accidental (`touch-action: manipulation`) y bloqueo de recargas accidentales por arrastre (`overscroll-behavior-y: contain`).
5. **Orientación Dual (Landscape y Portrait):**
- Soporte fluido para orientación horizontal (**Landscape**, estándar en bases/soportes fijos de garita) y vertical (**Portrait**, ergonómico cuando el guardia sostiene la tablet con una mano en el exterior).
### 2.3. Backend / API (FastAPI)
- **Framework:** **FastAPI (Python 3.11+)**.
- **Ventajas Arquitectónicas:**
- Ejecución asíncrona de alto rendimiento (`asyncio` con servidor `uvicorn`).
- Validación de esquemas y contratos estricta con **Pydantic v2**.
- Documentación interactiva autogenerada lista para auditoría (OpenAPI / Swagger en `/docs`).
- Soporte nativo para WebSockets y Server-Sent Events (SSE) sin extensiones pesadas.
- Reutilización total del código de negocio Python existente (`parser_dni.py`, validaciones de pólizas y cálculo de antipassback).
### 2.4. Base de Datos y Persistencia
- **Motor:** Microsoft SQL Server (base de datos existente `videoman`).
- **Acceso a Datos:** Pool de conexiones asíncrono para operaciones de lectura/escritura críticas, compatible con el collation actual `Modern_Spanish_CI_AS` y compatibilidad SQL Server 2008+.
- **Garantía Transaccional:** Transacciones ACID atómicas en la creación de tickets de ingreso/salida: la inserción de `tck`, la asignación de personas `tckper`, las propiedades dinámicas `tckprx`, el histórico `mvthist` y el encolado de hardware `pdtmdl` se confirman en una única transacción. Si cualquier paso falla, se realiza rollback completo.
### 2.5. Comunicación con Dispositivos y Controladores (Resolución del Desacople)
- **Principio de Diseño:** *El navegador jamás interactúa directamente con los buses industriales RS-485 ni con las placas ST1660.*
- **Flujo de Ejecución de Comandos:**
1. El guardia presiona "Confirmar Ingreso" o pulsa `Enter` en la interfaz web.
2. El frontend envía `POST /api/v1/access/entry` al backend FastAPI con el payload validado.
3. FastAPI procesa la lógica de negocio, registra el ticket y ejecuta `INSERT INTO pdtmdl` con el comando correspondiente (`O3` barrera, `V5` molinete, `T9` ticket).
4. El daemon de hardware `OnEverWPC` (que corre de forma independiente en el servidor o PC concentradora) toma el comando en menos de 50 ms y lo transmite al puerto COM físico.
5. FastAPI responde con código `200 OK` y emite un evento WebSocket al frontend indicando "Acceso Permitido y Barrera Abierta".
- **Comandos Manuales de Emergencia:**
- Endpoint dedicado `POST /api/v1/hardware/modules/{id}/open` para aperturas manuales de cortesía o emergencia desde la interfaz web, con auditoría obligatoria de usuario y motivo.
### 2.6. Comunicación en Tiempo Real y Manejo de Eventos
- **Tecnología:** **WebSockets nativos de FastAPI**.
- **Canales de Eventos:**
- `/ws/station/{station_id}`: Eventos específicos del carril (escaneo de DNI, cambio de estado de cámara, resultado de validación).
- `/ws/global/events`: Alertas perimetrales, avisos de antipassback, nuevas preautorizaciones cargadas por vecinos y estado de salud de los controladores de hardware.
### 2.7. Logs, Auditoría y Trazabilidad
- Toda acción operativa sensible (apertura manual de barrera, anulación de ticket, modificación de póliza, salida forzada de acompañante) se registra en una tabla de auditoría inmutable (`aud_log`) que almacena: `UsuarioID`, `WorkstationID`, `ModuloID`, `FechaHora`, `Accion`, `DetalleJSON` e `IP_Cliente`.
- Logs de aplicación estructurados en formato JSON (usando `structlog` o `loguru`) con rotación automática diaria.
### 2.8. Escalabilidad, Seguridad y Entornos de Ejecución Servidor
- **Entornos de Ejecución Soportados para el Servidor Web / API:**
- **Bare-metal Windows 10/11:** Ejecución nativa en PCs de garita o servidores Windows como servicio del sistema (mediante NSSM o Windows Task Scheduler), ideal para despliegues locales directos.
- **LXC (Linux Containers en Proxmox / Debian / Ubuntu):** Despliegue ultraliviano con overhead de CPU y RAM casi nulo (< 80 MB RAM), administrado por `systemd`. Utiliza FreeTDS y `pymssql` nativo de Linux para comunicarse por red con SQL Server `videoman`.
- **Docker & Docker Compose:** Empaquetado inmutable en contenedores estandarizados multiplataforma (Linux o Windows Docker Host), facilitando actualizaciones rápidas y réplicas.
- **Factor Clave de Portabilidad:** Al estar la capa de hardware físico desacoplada mediante la tabla `pdtmdl` (escuchada por `OnEverWPC` en la máquina Windows donde residen los puertos COM físicos), el servidor de `OnEverControl` **no requiere drivers Win32 ni acceso serial local**, permitiendo que corra de manera 100% nativa y transparente tanto en Linux (LXC/Docker) como en Windows.
- **Alta Disponibilidad:** Posibilidad de ejecutar múltiples réplicas del backend FastAPI detrás de un Reverse Proxy Nginx con balanceo de carga.
- **Monitoreo:** Endpoint de salud `/health` y `/metrics` compatible con Prometheus y dashboards de monitoreo en Grafana.
---
## 3. Tecnologías Recomendadas y Justificación de Decisiones
### 3.1. Cuadro Comparativo del Stack Tecnológico
| Capa / Componente | Tecnología Seleccionada | Alternativas Evaluadas | Justificación de la Elección |
| :--- | :--- | :--- | :--- |
| **Backend Framework** | **FastAPI (Python 3.11+)** | Flask, Django REST, Node.js (Express/NestJS) | **FastAPI** es un requerimiento explícito del proyecto y la mejor opción técnica: ofrece rendimiento asíncrono con `asyncio`/`uvloop`, validación estricta con Pydantic v2, generación automática de OpenAPI y compatibilidad directa con las bibliotecas existentes en Python del proyecto (`parser_dni`, cálculos de hardware, etc.). Flask carece de tipado asíncrono robusto nativo; Django es excesivamente monolítico; Node.js obligaría a reescribir toda la lógica de Python. |
| **Frontend Framework & Build** | **React + TypeScript + Vite** | Next.js, Angular, Vue, NestJS BFF | **React + TypeScript + Vite** produce una Single Page Application (SPA) estática de altísimo rendimiento y huella de memoria ultraliviana (~30-50 MB en navegador). A diferencia de arquitecturas basadas en servidores Node.js/BFF pesados, los activos estáticos compilados con Vite se sirven de forma directa por Nginx o el backend FastAPI. Esta ligereza es determinante para garantizar fluidez sin cierres de pestaña ni retrasos en **tablets Samsung Galaxy Tab A9 y A11 de 4 GB de RAM**, donde el sistema operativo Android y los procesos en segundo plano dejan un margen operativo ajustado de memoria libre. |
| **Diseño / Estilos** | **CSS Puro / Vanilla CSS con Sistema de Tokens (OnEver DS)** | TailwindCSS, Bootstrap, Material UI | **Vanilla CSS estructurado con Design Tokens** (Variables CSS semánticas) respeta las directrices del proyecto y el Design System ya concebido en `styles/design_system.py`. Ofrece control milimétrico de contraste, temas Dark/Light de alto contraste para garitas, máxima velocidad de carga sin dependencias pesadas y layouts compactos optimizados para pantallas de 1360x768 píxeles comunes en puestos de seguridad. |
| **Motor de Base de Datos** | **Microsoft SQL Server (videoman)** | PostgreSQL, MySQL, SQLite | Se mantiene **SQL Server** existente para preservar la compatibilidad total e inmediata con el ecosistema de producción (`videoman`), las tablas de hardware `pdtmdl`, la base histórica de personas y los stored procedures optimizados. |
| **Acceso a Base de Datos** | **pymssql + Pool Asíncrono / SQLAlchemy Core** | pyodbc, Tortoise-ORM, Peewee | **pymssql** ya está implementado y validado en el repositorio actual (`db_config.py`). Funciona de manera nativa tanto en Windows como en Linux sin requerir controladores ODBC externos complicados, admitiendo el nivel de compatibilidad 100 de SQL Server 2008. |
| **Comunicación Real-Time** | **WebSockets (FastAPI WebSocket Endpoint)** | Server-Sent Events (SSE), Long Polling | **WebSockets** proporciona comunicación bidireccional de bajísima latencia (< 5 ms). Permite tanto enviar alertas e imágenes desde el servidor al navegador como recibir comandos inmediatos del operador. |
| **Autenticación & Sesión** | **JWT (JSON Web Token) en Cookies HttpOnly con Refresh Tokens** | Sesiones por BD, OAuth2 externo | Seguridad sólida en contexto web: protección contra robo de tokens (XSS) mediante flags `HttpOnly` y `SameSite=Strict`, con expiración corta de access token (15-30 min) y refresh tokens persistentes para no interrumpir el turno del operador. |
| **Reverse Proxy & Web Server** | **Nginx** | Apache, Traefik, Caddy | **Nginx** es el estándar indiscutido para servir estáticos con máxima velocidad, manejar terminación TLS/SSL (HTTPS) y proxificar peticiones HTTP y WebSockets hacia Uvicorn con balanceo de carga. |
| **Entornos de Servidor & Despliegue** | **Windows 10/11, LXC (Linux Containers) & Docker** | Máquinas virtuales pesadas (KVM/ESXi monolíticas) | OnEverControl está diseñado para máxima versatilidad operativa: (1) **Windows 10/11** bare-metal ejecutándose como servicio de sistema para puestos fijos de garita; (2) **LXC (Linux Containers)** en Proxmox/Debian consumiendo recursos mínimos (< 80 MB RAM de overhead) y gestionado por systemd; y (3) **Docker / Docker Compose** para despliegues estandarizados e inmutables. El desacople de puertos físicos mediante la tabla SQL Server `pdtmdl` hace posible que el backend corra en Linux/LXC/Docker sin requerir passthrough serial ni drivers propietarios. |
| **Herramientas de Testing** | **pytest + HTTPX (Backend) / Vitest + React Testing Library + Playwright (Frontend)** | Selenium, Cypress, unittest | `pytest` con `pytest-asyncio` y `httpx` permite pruebas de integración de API asíncronas ultraveloces. `Vitest` y `React Testing Library` ejecutan pruebas unitarias veloces en frontend, y `Playwright` permite simular escaneos de código de barras y flujos completos de carril en navegadores headless. |
---
## 4. Estructura del Proyecto
Se propone la siguiente estructura para el repositorio `OnEverControl`, manteniendo un desacoplamiento limpio entre frontend, backend, documentación y utilidades de automatización:
```text
OnEverControl/
├── README.md # Documentación principal de inicio rápido
├── ROADMAP.md # Hoja de ruta de desarrollo y fases
├── INFORME_TECNICO_PUESTO_DE_CONTROL_WEB.md # Este informe técnico maestro
├── docker-compose.yml # Orquestación de servicios (API, Web, Proxy)
├── .env.example # Plantilla de variables de entorno
│
├── backend/ # Núcleo API FastAPI
│ ├── Dockerfile
│ ├── pyproject.toml / requirements.txt
│ ├── app/
│ │ ├── main.py # Punto de entrada FastAPI y middlewares
│ │ ├── core/ # Configuraciones y seguridad central
│ │ │ ├── config.py # Settings basados en Pydantic
│ │ │ ├── security.py # Hasheo de claves, JWT y auth helpers
│ │ │ ├── database.py # Pool de conexiones pymssql
│ │ │ └── logging.py # Configuración de logs estructurados
│ │ ├── api/ # Routers de endpoints (v1)
│ │ │ ├── v1/
│ │ │ │ ├── router.py # Agregador de rutas v1
│ │ │ │ ├── auth.py # Login, logout, refresh, usuario actual
│ │ │ │ ├── control_posts.py # Gestión de puestos y carriles asignados
│ │ │ │ ├── access.py # Ingresos, salidas, validaciones, antipassback
│ │ │ │ ├── people.py # Personas, búsqueda predictiva, DNI parsing
│ │ │ │ ├── vehicles.py # Patentes, seguros, autos asociados
│ │ │ │ ├── lots.py # Lotes, propietarios, permisos de lote
│ │ │ │ ├── preauthorizations.py# Visitas preautorizadas y consumo
│ │ │ │ ├── hardware.py # Apertura remota de módulos, cola pdtmdl
│ │ │ │ ├── cameras.py # Proxy ISAPI Hikvision y snapshots
│ │ │ │ └── websockets.py # Gateway WebSocket de eventos en vivo
│ │ ├── schemas/ # Modelos Pydantic (Request / Response DTOs)
│ │ │ ├── auth_schema.py
│ │ │ ├── access_schema.py
│ │ │ ├── person_schema.py
│ │ │ ├── vehicle_schema.py
│ │ │ ├── hardware_schema.py
│ │ │ └── lot_schema.py
│ │ ├── services/ # Lógica de negocio desacoplada
│ │ │ ├── access_service.py # Orquestación de ingreso y salida
│ │ │ ├── antipassback_service.py # Reglas de antipassback y bypass
│ │ │ ├── dni_parser_service.py # Adaptación de parser_dni.py
│ │ │ ├── hardware_service.py # Inserción y formato en pdtmdl
│ │ │ └── camera_service.py # Cliente Digest HTTP persistente Hikvision
│ │ ├── repositories/ # Capa de acceso a SQL Server (T-SQL)
│ │ │ ├── access_repository.py # Consultas tck, tckper, tckprx, mvthist
│ │ │ ├── person_repository.py # Consultas Per, PerDocCatVal
│ │ │ ├── vehicle_repository.py # Consultas Aut, peraut
│ │ │ ├── lot_repository.py # Consultas Lot, permisos
│ │ │ └── hardware_repository.py # Consultas mdl, pdtmdl
│ │ └── utils/ # Funciones auxiliares y formateadores
│ └── tests/ # Suite de pruebas unitarias y de integración
│ ├── conftest.py
│ ├── test_auth.py
│ ├── test_dni_parser.py
│ ├── test_access_flow.py
│ └── test_hardware_commands.py
│
├── frontend/ # Aplicación Web SPA (React + TypeScript + Vite)
│ ├── index.html # Entrypoint HTML5 PWA táctil
│ ├── package.json # Dependencias React 18+, TypeScript, Vite
│ ├── tsconfig.json # Configuración de compilación TypeScript estricta
│ ├── vite.config.ts # Configuración de Vite (pwa plugin, proxy dev)
│ ├── public/ # Favicons, manifest PWA, assets estáticos
│ └── src/
│ ├── main.tsx # Punto de entrada de React (mount en #root)
│ ├── App.tsx # Enrutador principal y layout general
│ ├── api/ # Clientes HTTP hacia backend FastAPI
│ │ ├── client.ts # Instancia base con interceptores de cookies JWT
│ │ ├── authApi.ts # Endpoints /api/v1/auth
│ │ ├── accessApi.ts # Endpoints /api/v1/access
│ │ └── workstationApi.ts # Endpoints /api/v1/control-posts
│ ├── components/ # Componentes modulares de interfaz táctil
│ │ ├── common/ # Botones Touch (>= 48px), Modales, Badges
│ │ ├── scanner/ # Visor de cámara para DNI (PDF417 / QR)
│ │ ├── access/ # Panel de ingreso, carriles, acompañantes
│ │ └── workstation/ # Selector y estado de estación de trabajo
│ ├── context/ # Contextos globales de estado liviano
│ │ ├── AuthContext.tsx # Sesión activa de guardia
│ │ └── WorkstationContext.tsx # Workstation actual y carriles vinculados
│ ├── hooks/ # Custom hooks reutilizables
│ │ ├── useCameraScanner.ts # Control de cámara y decodificación con BarcodeDetector
│ │ ├── useWebSocket.ts # Conexión persistente con /ws/station/{name}
│ │ └── useKeyboardShortcuts.ts # Soporte para atajos de teclado (F2, F4, Esc)
│ ├── views/ # Pantallas principales
│ │ ├── LoginView.tsx # Pantalla de login táctil y selección de workstation
│ │ └── ControlPostView.tsx # Pantalla operativa de Puesto de Control
│ └── styles/ # OnEver Design Tokens en Vanilla CSS
│ ├── tokens.css # Variables de color (Dark/Light), fuentes, sombras
│ ├── base.css # Reset, touch-action: manipulation, 100dvh
│ └── components.css # Estilos modulares para botones y formularios
│ └── tests/ # Pruebas unitarias de componentes con Vitest
│
├── docs/ # Documentación técnica adicional y diagramas
│ ├── architecture_diagrams.png
│ ├── hardware_protocol_spec.md
│ └── api_contracts.md
│
└── scripts/ # Scripts de verificación y despliegue multiplataforma
├── test_sql_connection.py # Test agnóstico de conexión SQL Server (Windows/Linux)
├── windows/ # Despliegue en Windows 10/11
│ ├── install_service.bat # Instalación como servicio de Windows (NSSM)
│ └── start_native.bat # Inicio bare-metal rápido en garita
├── lxc/ # Despliegue en Proxmox / Debian LXC
│ ├── setup_lxc.sh # Instalación de dependencias Linux (FreeTDS, Python, Nginx)
│ └── onevercontrol.service # Unit file para administración con systemd
└── docker/ # Despliegue en Docker / Docker Compose
└── nginx.conf # Configuración de proxy y compresión
```
---
## 5. Modelo de Datos y Entidades
Para soportar la versión web manteniendo total interoperabilidad con la base de datos SQL Server `videoman`, se identifican las entidades clave, sus relaciones y esquemas:
```mermaid
erDiagram
Per ||--o{ PerDocCatVal : "posee documentos"
Per ||--o{ peraut : "conduce / asocia"
Aut ||--o{ peraut : "asociado a"
Lot ||--o{ pre : "preautoriza visitas a"
Lot ||--o{ tckprx : "destino de"
tck ||--o{ tckper : "incluye personas"
Per ||--o{ tckper : "participa en"
tck ||--o{ tckprx : "metadatos extendidos"
tck ||--o| tckhst : "se archiva al salir"
mdl ||--o{ pdtmdl : "recibe comandos para"
usr ||--o{ usrcatval : "privilegios y roles"
Per {
int PersonaID PK
string Apellido
string Nombre
string NroSocio
int Blacklist
datetime CreationDate
}
Aut {
int AutoID PK
string Patente
string Aseguradora
string PolizaNro
date PolizaVigenciaDesde
date PolizaVigenciaHasta
}
Lot {
int LoteID PK
string Lote
string Calle
int EstadoValID
}
tck {
int TicketID PK
datetime FechaHoraIngreso
int ModuloIngresoID FK
}
tckper {
int TicketID FK
int PersonaID FK
int RolID
int EsMenor
}
pdtmdl {
int PdtMdlID PK
int ModuloID FK
string Comando
int Inmediato
string Extra
}
```
### 5.1. Entidades Principales
1. **Persona (`Per`):**
- Identificador único (`PersonaID`), Apellido, Nombre, Número de Socio, Estado de Lista Negra (`Blacklist`), Observaciones.
2. **Documento de Identidad (`PerDocCatVal`):**
- Vínculo a `PersonaID`, Tipo de Documento (`DocumentoTipoID`: 1=DNI, 2=Pasaporte, etc.), Número de documento (`Documento`).
3. **Vehículo (`Aut`):**
- `AutoID`, Dominio/Patente, Datos de seguro (Aseguradora, PolizaNro, PolizaVigenciaDesde, PolizaVigenciaHasta).
4. **Relación Persona-Vehículo (`peraut`):**
- `PersonaID`, `AutoID`. Permite sugerir automáticamente la patente al escanear la persona o viceversa.
5. **Lote / Destino (`Lot`):**
- `LoteID`, Código de Lote (`Lote`), Calle, Estado de habilitación (`EstadoValID`).
6. **Ticket Activo de Ingreso (`tck`):**
- `TicketID`, `FechaHoraIngreso`, `ModuloIngresoID` (carril de entrada). Un registro aquí representa una persona o vehículo dentro del predio.
7. **Personas en Ticket (`tckper`):**
- `TicketID`, `PersonaID`, `RolID` (1 = Conductor, 2 = Peatón/Acompañante), `EsMenor` (0 o 1).
8. **Propiedades Dinámicas de Ticket (`tckprx`):**
- `TicketID`, `PropiedadID` (ej: 4=Patente, 13=LoteID, 5=Entidad/Empresa, 6=Motivo), `Valor`.
9. **Histórico de Movimientos (`tckhst` y `mvthist`):**
- Datos consolidados del ingreso y egreso con estampas de tiempo, módulos de paso, duración y operador interviniente.
10. **Preautorizaciones (`pre`):**
- `PreautorizadoID`, `LoteID`, Apellido, Nombre, Documento, Entidad, Fechas de vigencia (`FechaInicio`, `FechaFin`), Estado de consumo.
11. **Módulos de Hardware (`mdl`):**
- `ModuloID`, Nombre, Dirección física (`Address`), Tipo de acceso (1=Puerta, 2=Molinete, 3/5=Barrera), Configuración de cámara asociada (`HikID`).
12. **Cola de Comandos de Hardware (`pdtmdl`):**
- `PdtMdlID`, `ModuloID`, `Comando` (trama formateada), `Inmediato` (1), `Extra` (TicketID).
13. **Usuarios y Permisos (`usr`, `usrcatval`):**
- `UsuarioID`, Nombre, Password (actualmente MD5 o compatible, a actualizar a bcrypt/argon2), Privilegios de acceso asignados.
---
## 6. Consideraciones de Seguridad
### 6.1. Autenticación y Gestión de Sesión
- **Tokens de Acceso:** Uso de tokens JWT emitidos con algoritmo asimétrico o HMAC-SHA256 con secret de alta entropía.
- **Protección de Almacenamiento:** El token se almacena en **Cookies HTTP con atributos `HttpOnly`, `Secure` y `SameSite=Strict`**, impidiendo que scripts maliciosos puedan extraer el token mediante vulnerabilidades XSS.
- **Cierre de Turno e Inactividad:** Detección de inactividad configurable (ej: bloqueo automático tras 15 minutos sin interacción para proteger garitas en relevos de guardia).
### 6.2. Autorización Basada en Roles (RBAC)
- Permisos granulares asociados a la tabla `UsrCatVal` actual:
- `OPERADOR_GUARDIA`: Registro de ingresos y salidas, escaneo de DNI, apertura por evento.
- `SUPERVISOR`: Apertura manual extraordinaria, anulación de tickets pendientes, gestión de listas negras y bypass de antipassback con clave.
- `ADMINISTRADOR`: Configuración de carriles, módulos de hardware, altas de usuarios y auditoría completa.
### 6.3. Protección de APIs
- **Rate Limiting:** Protección contra ataques de fuerza bruta en `/api/v1/auth/login` y endpoints de búsqueda masiva.
- **Validación Estricta:** Filtrado y saneamiento de todos los inputs en FastAPI mediante Pydantic, previniendo inyección SQL en consultas T-SQL.
- **CORS:** Configuración estricta de Cross-Origin Resource Sharing restringida únicamente al origen del frontend de la intranet.
### 6.4. Seguridad en la Comunicación con Dispositivos
- La red de cámaras Hikvision y los controladores ST1660 deben residir en una **VLAN de Seguridad / Dispositivos aislada**, accesible únicamente por el servidor FastAPI y el servicio OnEverWPC. Ningún dispositivo del carril expone puertos hacia el navegador cliente.
---
## 7. Plan de Migración y Coexistencia con el Sistema Desktop
### 7.1. Estrategia de Convivencia Transparente
Dado que un predio de seguridad no puede detener su operación ni un solo minuto, la versión web debe ser capaz de convivir en paralelo con el sistema de escritorio actual durante todo el período de transición.
```mermaid
graph TD
Garita1[Garita Principal: Puesto Desktop PyQt6]
Garita2[Garita Secundaria: Puesto Web OnEverControl]
BD[(SQL Server 'videoman')]
WPC[Daemon OnEverWPC Hardware]
Placas[Placas ST1660 & Barreras]
Garita1 -->|Lectura / Escritura tck, tckper| BD
Garita1 -->|Encola apertura| BD
Garita2 -->|Lectura / Escritura tck, tckper vía FastAPI| BD
Garita2 -->|Encola apertura vía FastAPI| BD
BD -->|pdtmdl| WPC
WPC -->|RS-485| Placas
```
- **Compatibilidad Total de Base de Datos:** Tanto la aplicación de escritorio como la versión web leen y escriben en las mismas tablas (`tck`, `tckper`, `tckprx`, `pdtmdl`, `mvthist`).
- **Escenario Real de Convivencia:** Una persona puede registrar su ingreso vehicular en la Garita Principal utilizando la aplicación actual de escritorio, y luego egresar por la Garita Secundaria atendida con la nueva versión web. Ambos sistemas verán el mismo ticket activo en tiempo real.
### 7.2. Fases de Migración Progresiva
1. **Fase Piloto en Carril Test / Secundario:** Despliegue de la versión web en un carril de baja carga (ej: acceso de proveedores o salida peatonal).
2. **Operación Espejo:** Monitoreo de latencia, estabilidad del escáner y verificación de que los tickets creados en la web cierran correctamente en escritorio y viceversa.
3. **Reemplazo Progresivo:** Migración terminal por terminal sin impacto en el personal ni en el flujo vehicular.
---
## 8. Decisiones Técnicas Pendientes y Recomendaciones
Durante el análisis del código fuente y los requerimientos, se identificaron las siguientes definiciones clave que requieren alineación con el equipo de infraestructura:
1. **Modalidad de Lectura de Documentos de Identidad (DNI):**
- *Definición adoptada:* **Lectura directa mediante la cámara integrada de la tablet.** Se reemplazan por completo los lectores físicos externos por puerto COM y emulación de teclado. El frontend en React + TypeScript implementa la Barcode Detection API nativa y la biblioteca ZXing (Wasm/JS), decodificando el código PDF417 o QR del DNI en tiempo real con la cámara trasera de la tablet y capturando simultáneamente la foto del documento como evidencia visual. Esto garantiza movilidad total para el guardia en el carril y costo cero en periféricos.
2. **Exclusión del Streaming de Cámaras Hikvision por ISAPI en la Versión Web:**
- *Definición adoptada:* **No se utilizará streaming de cámaras Hikvision por ISAPI.** Se descarta por completo la reemisión de video continuo hacia las tablets para evitar consumo excesivo de batería, recalentamiento y congestión en la red Wi-Fi de garitas. El monitoreo de video de seguridad fijo perimetral continúa en el circuito cerrado de TV (CCTV/NVR) o en el puesto central de OnEverAccess, dejando a la tablet libre y ágil para el control de accesos.
3. **Modernización de Almacenamiento de Contraseñas:**
- *Situación:* La base histórica utiliza esquemas heredados de autenticación.
- *Recomendación:* Implementar actualización automática transparente al iniciar sesión (*hash re-encoding*): cuando un usuario se loguea con éxito con su clave actual, el backend re-hashea la contraseña con **bcrypt / argon2id**, asegurando la base de datos sin obligar a resetear las contraseñas a todos los operadores.
4. **Persistencia Temporal de Sesiones de Carril Pendientes:**
- *Situación:* En escritorio se usa un archivo JSON local en `%TEMP%` (`CarrilProcessSessionManager`).
- *Recomendación:* Implementar persistencia de sesiones en el backend en una tabla ligera `pct_carril_sesion` o Redis/SQLite en memoria del backend, replicando el estado hacia el navegador mediante `localStorage`. De este modo, si el operador recarga el navegador o se traslada a otra PC, puede reanudar el ingreso exactamente donde quedó.
5. **Despliegue Multiplataforma Agnóstico (Windows 10/11, LXC y Docker):**
- *Definición adoptada:* El servidor de OnEverControl se diseña para operar sin acoplamiento a ningún sistema operativo en particular, soportando tres modalidades de despliegue:
- **Windows 10/11 (Bare-metal):** Ejecución directa con Python venv y servicio de Windows mediante NSSM. Ideal para instalaciones en la misma PC de garita donde ya corre Windows.
- **LXC (Linux Containers en Proxmox / Debian):** Opción de máxima eficiencia para virtualización en servidor central o micro-servidores de predio. Overhead de CPU y memoria casi nulo (< 80 MB RAM), arranque en milisegundos y administración estándar mediante unidades de `systemd`.
- **Docker / Docker Compose:** Empaquetado estandarizado en contenedores inmutables con imagen base `python:3.11-slim` y Nginx para servir la SPA de React compilada y proxificar la API FastAPI.
- *Garantía de Portabilidad:* Al desacoplar el hardware mediante la tabla SQL Server `pdtmdl` (leída por el daemon `OnEverWPC` en la máquina Windows conectada al bus RS-485), el backend FastAPI no requiere drivers propietarios ni puertos COM directos. Se garantiza el uso exclusivo de `pathlib.Path` para rutas de archivos y configuración de FreeTDS para interoperabilidad de collations con SQL Server (`Modern_Spanish_CI_AS`).
6. **Gestión de Versiones y Repositorio Oficial Gitea:**
- *Definición adoptada:* El código fuente oficial de OnEverControl se aloja y versiona en el repositorio central de Gitea: [`https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`](https://gitea.oemspot.com.ar/carlostellocba/OnEverControl).
- *Procedimiento de Publicación:* Todo commit a la rama principal `main` o cierre de fase debe cumplir obligatoriamente con:
1. Actualización sincronizada de versión semántica en el backend (`backend/app/__version__.py` o `pyproject.toml`).
2. Actualización sincronizada de versión semántica en el frontend (`frontend/package.json`).
3. Asiento cronológico de cambios en `CHANGELOG.md`.
4. Aprobación completa de la suite de pruebas automatizadas (`pytest` y `npm run build`) antes del push a Gitea.
+28
View File
@@ -0,0 +1,28 @@
# MEMORY.md — OnEverControl
Memoria del proyecto entre sesiones. Máximo ~50 líneas: resume o elimina lo que ya no aporte.
## Estado actual
- **Fase 0 (Completada):** Análisis técnico exhaustivo del puesto de control actual (`OemspotPySYS`), definición de arquitectura, tecnologías y hoja de ruta.
- **Arnés de IA y SDD configurado:** Creados `AGENTS.md`, `docs/constitution.md` y estructura de especificaciones.
- **Pendiente:** Aprobación de la primera spec (`specs/001-login-workstation/`) para dar inicio a la Fase 1.
## Decisiones (y por qué)
- **Backend en FastAPI + Pydantic v2 & Frontend en React + TypeScript + Vite:** FastAPI reutiliza los módulos probados de Python (`parser_dni`, pymssql) y gestiona la persistencia con SQL Server `videoman`. React con TypeScript y Vite produce una SPA estática ultraliviana con huella mínima en memoria RAM (~30-50 MB en navegador), fundamental para operar de forma fluida y sin lag en tablets **Samsung Galaxy Tab A9 y A11 de 4GB de RAM**.
- **Modo Cliente Reducido en LAN:** Se migra exclusivamente el Login y el Puesto de Control operativo (ingreso, salida, acompañantes, barreras, antipassback) conectándose a la base de datos `videoman` de OnEverAccess en la red local. Cero duplicación de módulos administrativos centrales.
- **Tablets como Workstations:** Cada tablet (Android, iPad, Windows) se identifica con un `workstation_name` registrado en SQL Server, heredando exactamente los mismos permisos y carriles asignados que una PC Windows.
- **Lectura de Documento con la Cámara de la Tablet:** Se reemplazan completamente los escáneres físicos externos (puerto COM o emulación de teclado). La tablet utiliza su cámara integrada (trasera/frontal) con Barcode Detection API / ZXing para leer instantáneamente el DNI argentino (PDF417 y QR), capturando al mismo tiempo la foto de evidencia visual. Elimina periféricos, cables y otorga 100% de movilidad al guardia en el carril.
- **Desacople de Hardware vía `pdtmdl`:** El navegador nunca intenta abrir puertos COM o RS-485. Encola comandos en `pdtmdl` para que el servicio `OnEverWPC` existente los despache físicamente a las placas ST1660.
- **Diseño Touch-First para Tablets:** Controles mínimos de 48px, layout `100dvh` para prevenir oclusión por teclado virtual y soporte PWA a pantalla completa.
- **Sin Streaming de Cámaras Hikvision por ISAPI:** Se descarta por completo el streaming de cámaras fijas hacia las tablets. Esto elimina la saturación de red Wi-Fi, evita el recalentamiento y preserva la batería de los dispositivos de garita.
- **Portabilidad Servidor Multiplataforma (Windows 10/11, LXC, Docker):** Al estar desacoplado del hardware COM/RS-485 mediante la tabla `pdtmdl`, OnEverControl es agnóstico del SO de host. Puede ejecutarse bare-metal en Windows 10/11 (como servicio), en contenedores LXC (Proxmox/Debian con systemd y FreeTDS nativo) o empaquetado en Docker / Docker Compose sin necesidad de passthrough de dispositivos ni privilegios especiales.
- **Repositorio Oficial Gitea y Versionado:** Repositorio central en `https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`. Obligatorio incrementar y sincronizar versiones en `backend/` y `frontend/`, registrar en `CHANGELOG.md` y pasar suite de pruebas antes de cada push a Gitea.
## Aprendizajes y errores a evitar
- **No trasladar lógica serial al navegador:** En tablets y navegadores estándar, el acceso serial directo es restrictivo o inexistente; `pdtmdl` es la vía robusta y desacoplada.
- **Evitar streaming de video continuo en tablets:** El video agota aceleradamente la batería y satura la Wi-Fi de garita; mantener la tablet enfocada en la operativa de paso y fotos de evidencia.
- **Evitar re-renders en inputs táctiles:** En tablets, los re-renders pesados provocan pérdida de foco en el teclado en pantalla. Usar estado reactivo localizado.
## Próximos pasos
- [ ] Validar y aprobar la especificación `specs/001-login-workstation/spec.md`.
- [ ] Fase 1: Scaffolding inicial del backend FastAPI y frontend Node.js / Vite.
+251
View File
@@ -0,0 +1,251 @@
# 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).
+190
View File
@@ -0,0 +1,190 @@
# ROADMAP DEL PROYECTO: PUESTO DE CONTROL WEB (OnEverControl)
## Hoja de Ruta de Desarrollo y Despliegue por Etapas (Modo Cliente Web Reducido)
Este documento define el roadmap estructurado para el desarrollo, integración, validación y puesta en marcha de la **versión reducida solo web en modo cliente (Thin Client)** de **OnEverControl**. Su alcance se enfoca exclusivamente en la migración del **Login** y del **Puesto de Control operativo** para operar a través de la **red local (LAN) donde ya funciona OnEverAccess**, utilizando **FastAPI + Pydantic v2 (Python)** en el backend y **React + TypeScript + Vite** en el frontend, bajo control de versiones publicado en Gitea: [`https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`](https://gitea.oemspot.com.ar/carlostellocba/OnEverControl).
---
### Resumen Visual de Fases
```text
[Fase 0: Análisis & Diseño] ➔ [Fase 1: Arquitectura & Setup Base] ➔ [Fase 2: Backend Core & APIs]
│
[Fase 5: Pruebas & QA]  [Fase 4: Integración Hardware/Cámaras]  [Fase 3: Frontend Web SPA]
│
▼
[Fase 6: Piloto & Migración] ➔ [Fase 7: Puesta en Producción] ➔ [Fase 8: Mejoras Posteriores]
```
---
## Detalle de Fases de Ejecución
### Fase 0: Análisis, Diseño y Definición de Arquitectura (ESTADO: COMPLETADA)
* **Objetivos:**
- Auditar exhaustivamente la lógica del sistema actual de escritorio (`OemspotPySYS/puestocontrol/`).
- Identificar todas las dependencias con bases de datos, hardware industrial, protocolos seriales y cámaras.
- Diseñar la arquitectura desacoplada para la versión web con FastAPI y definir el stack tecnológico óptimo.
- Elaborar el informe técnico maestro y el modelo de datos para guiar el desarrollo.
* **Entregables:**
- `OnEverControl/INFORME_TECNICO_PUESTO_DE_CONTROL_WEB.md` (Informe Técnico y Arquitectura).
- `OnEverControl/ROADMAP.md` (Este documento).
- `OnEverControl/README.md` (Guía inicial del proyecto).
* **Dependencias:**
- Acceso al repositorio actual, esquemas de tablas SQL Server `videoman` y documentación de placas ST1660.
* **Riesgos y Mitigación:**
- *Riesgo:* Desalineación en cómo resolver los puertos COM locales en web.
- *Mitigación:* Se definió el estándar USB HID (teclado) y Web Serial API, manteniendo el encolado en `pdtmdl`.
---
### Fase 1: Arquitectura y Base del Proyecto
* **Objetivos:**
- Crear la estructura completa de carpetas y configuración inicial en `OnEverControl/backend` y `OnEverControl/frontend`.
- Configurar los entornos de despliegue agnósticos: Docker Compose, script de instalación LXC (systemd / FreeTDS) y servicio para Windows 10/11 (NSSM).
- Establecer el pool de conexiones asíncrono hacia Microsoft SQL Server (`videoman`) usando `pymssql` compatible con Linux y Windows.
- Configurar middlewares de seguridad (CORS, compresión gzip, logging estructurado, manejo centralizado de excepciones).
- Inicializar el proyecto frontend en React + TypeScript + Vite con arquitectura modular por componentes, estado liviano y servicio de UI táctil (OnEver Design System).
* **Entregables:**
- Archivos de configuración `.env.example`, `docker-compose.yml`, scripts de despliegue para Windows (`scripts/windows/`) y LXC (`scripts/lxc/`).
- Esqueleto del backend FastAPI con endpoint `/health` y documentación Swagger activa en `/docs`.
- Esqueleto del frontend en React + TypeScript + Vite con layout táctil base responsive (100dvh) optimizado para tablets Samsung Galaxy Tab A9/A11 (4GB RAM).
- Script automatizado de verificación de conectividad con la base de datos SQL Server (`test_sql_connection.py`) ejecutable en Windows y Linux.
- Control de versión inicial (`v0.1.0`) configurado en backend y frontend, registrado en `CHANGELOG.md` y subido al repositorio oficial de Gitea (`https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`).
* **Dependencias:**
- Conectividad a la instancia de SQL Server `videoman`.
* **Riesgos y Mitigación:**
- *Riesgo:* Latencias o fallos de conexión en Windows/Linux con pymssql.
- *Mitigación:* Reutilizar los patrones de conexión y timeouts probados en `db_config.py`.
---
### Fase 2: Backend / API Core con FastAPI
* **Objetivos:**
- Implementar el módulo de autenticación con JWT (Cookies HttpOnly) y control de roles basado en `UsrCatVal`.
- Migrar y adaptar la lógica pura de negocio de Python:
- Parser de DNI argentino (`herramientas/parser_dni.py`).
- Lógica de validación de antipassback (`verificar_antipassback`).
- Validación y vigencia de pólizas (ART, Conductor, Seguro Automotor).
- Desarrollar los endpoints RESTful para:
- `/api/v1/control-posts`: Validación de `workstation_name` para tablets y PCs (`es_puesto_de_control` y `listar_modulos_por_workstation`).
- `/api/v1/people`: Búsqueda de personas por DNI, búsqueda predictiva por texto, altas y consultas.
- `/api/v1/vehicles`: Búsqueda de vehículos por patente y relaciones `peraut`.
- `/api/v1/lots`: Búsqueda de lotes y validación de estados de permiso.
- `/api/v1/preauthorizations`: Búsqueda y consumo atómico de preautorizaciones.
- `/api/v1/access/entry`: Registro de ingreso vehicular y peatonal (atómico en `tck`, `tckper`, `tckprx`, `mvthist`).
- `/api/v1/access/exit`: Consulta de ticket activo y registro de egreso (con desacople de acompañantes).
- `/api/v1/access/inside`: Consulta del padrón de visitas dentro del predio.
- `/api/v1/access/mass-exit`: Salida masiva de personal con auditoría.
* **Entregables:**
- Routers, esquemas Pydantic v2 y repositorios SQL implementados en el backend.
- Tests unitarios y de integración con `pytest` para cada flujo de negocio crítico.
* **Dependencias:**
- Finalización de Fase 1.
* **Riesgos y Mitigación:**
- *Riesgo:* Inconsistencias al replicar transacciones complejas de `pct_repository.py`.
- *Mitigación:* Pruebas cruzadas validando que los registros generados por FastAPI sean idénticos a los de PyQt.
---
### Fase 3: Desarrollo del Frontend (Interfaz Web Touch-First para Tablets y Garitas)
* **Objetivos:**
- Construir la interfaz de usuario con diseño táctil prioritario (**Touch-First**) para tablets (**Android, Windows e iPad**):
- Touch targets generosos (mínimo 48 x 48 px) para operación ágil táctil.
- Layout adaptativo con `100dvh` que impide que el teclado virtual en pantalla tape los botones de acción (`Confirmar Ingreso`, `Cancelar`).
- Atributos `inputmode="numeric"` para desplegar teclado numérico automático en DNI y cantidades.
- Soporte de orientación horizontal (Landscape) y vertical (Portrait).
- Modo PWA Standalone (instalable sin barras de navegación del navegador).
- Acceso a las cámaras integradas de la tablet (trasera y frontal) con Barcode Detection API y ZXing Wasm/JS para escanear DNI (PDF417 y QR) en tiempo real, reemplazando totalmente lectores físicos COM o emuladores de teclado.
- Implementar la experiencia híbrida "Touch + Keyboard":
- Atajos de teclado físico para puestos con teclado (`F2`, `F4`, `Enter`, `Esc`).
- Búsqueda manual rápida por número de documento o nombre.
- Desarrollar los drawers y diálogos táctiles interactivos:
- Búsqueda predictiva de personas y vehículos.
- Selector táctil de lotes con indicación visual de permisos.
- Búsqueda y consumo de preautorizados.
- Diálogo interactivo de acompañantes (`DialogoRegistroIntegrantes`).
- Diálogo de verificación y desacople de acompañantes en salida.
- Padrón de ingresados con filtros rápidos táctiles y salida masiva.
- Implementar persistencia de sesiones de carril interrumpidas.
* **Entregables:**
- SPA PWA completamente funcional en Node.js, testeada y optimizada para tablets táctiles (Android, Windows, iPad).
- Suite de pruebas de componentes y validación de formularios en frontend.
* **Dependencias:**
- Disponibilidad de los endpoints de Fase 2.
* **Riesgos y Mitigación:**
- *Riesgo:* Iluminación deficiente o reflejos al escanear el DNI con la cámara de la tablet en el carril.
- *Mitigación:* Visor de cámara con guía visual de encuadre, selector de cámara trasera con autofoco continuo y fallback inmediato para tipeo manual rápido del número de DNI.
---
### Fase 4: Integración con Hardware, Escaneo Óptico y Tiempo Real
* **Objetivos:**
- **Encolado de Hardware:** Implementar en el backend FastAPI la inserción formateada de tramas de apertura y comandos de tickets en la tabla `pdtmdl` (`O3`, `O5`, `O1`, `V3`, `V6`, `T9`).
- **Escaneo Óptico y Captura con Cámara de la Tablet:** Integración en el frontend de la Barcode Detection API y ZXing (Wasm/JS) para decodificar DNI (PDF417/QR) en tiempo real con la cámara de la tablet, capturando simultáneamente la foto de evidencia.
- **WebSockets en Tiempo Real:** Implementar endpoint WebSocket nativo en FastAPI y hook `useWebSocket` en React para sincronizar eventos instantáneos (apertura completada, alertas de antipassback, nuevas preautorizaciones).
* **Entregables:**
- Módulos `hardware_service.py` y componentes de escáner óptico operativos y probados.
- Despacho de órdenes de apertura verificado en la tabla `pdtmdl` y recibido por `OnEverWPC`.
* **Dependencias:**
- Servicio `OnEverWPC` escuchando `pdtmdl` en la red local.
* **Riesgos y Mitigación:**
- *Riesgo:* Desconexión temporal de la tablet de la red Wi-Fi durante el envío de apertura.
- *Mitigación:* Reintento automático con feedback háptico en pantalla indicando estado de conexión con el servidor.
---
### Fase 5: Pruebas Integrales, QA y Stress Testing
* **Objetivos:**
- Realizar pruebas integrales de punta a punta (E2E) simulando el flujo real de guardias en horas pico.
- Pruebas de estrés y latencia:
- Tiempo de respuesta de búsqueda de persona < 100 ms.
- Tiempo de encolado de apertura de barrera en `pdtmdl` < 20 ms.
- Tiempo de renderizado de la UI tras escaneo de DNI < 50 ms.
- Verificación de casos extremos y ergonomía táctil:
- Validación en tablets reales (**iPadOS / Safari, Android / Chrome, Windows Surface / Edge**).
- Despliegue de teclado virtual sin oclusión de botones de confirmación.
- Escaneo con DNI dañado o caracteres especiales.
- Vehículo con 5 acompañantes donde 2 salen a pie y 1 se queda en el lote.
- Desconexión temporal de red y recuperación automática de WebSockets.
* **Entregables:**
- Reporte de aseguramiento de calidad (QA Test Matrix).
- Suite de pruebas E2E automatizadas con Playwright.
* **Dependencias:**
- Fase 3 y Fase 4 completadas.
* **Riesgos y Mitigación:**
- *Riesgo:* Descubrimiento de discrepancias con el sistema legado VB6 o PyQt.
- *Mitigación:* Comparación directa de transacciones en la base de datos contra el entorno de pruebas.
---
### Fase 6: Despliegue Piloto y Convivencia Híbrida
* **Objetivos:**
- Desplegar la versión web en una garita piloto en el entorno elegido (Windows 10/11 bare-metal, LXC en Proxmox o Docker Compose).
- Validar la convivencia híbrida en producción: ingresos registrados en la web cerrados en el sistema de escritorio, y viceversa.
- Capacitar a los guardias en la nueva interfaz web y recolectar feedback de usabilidad en el puesto de trabajo.
* **Entregables:**
- Servidor web productivo desplegado en red local con Nginx y FastAPI (Windows Service, contenedor LXC o contenedor Docker).
- Manual de usuario y guía rápida de atajos de teclado para guardias de seguridad.
* **Dependencias:**
- Aprobación de Fase 5 y validación por supervisores de seguridad.
* **Riesgos y Mitigación:**
- *Riesgo:* Resistencia al cambio o dudas operativas de los guardias.
- *Mitigación:* Interfaz visualmente idéntica en colores y lógica a la versión PyQt para curva de aprendizaje cero.
---
### Fase 7: Puesta en Producción y Migración Total
* **Objetivos:**
- Habilitar la versión web en todos los puestos de control del predio (Garitas Principales, Secundarias y Peatonales).
- Retirar gradualmente la aplicación de escritorio `pct_view.py` en los puestos operativos, conservándola como respaldo.
- Establecer monitoreo continuo de métricas y rendimiento.
* **Entregables:**
- Puesta en producción completa (100% web).
- Backup programado y procedimiento de contingencia ante fallos.
* **Dependencias:**
- Fase 6 exitosa sin incidentes durante 14 días continuos.
* **Riesgos y Mitigación:**
- *Riesgo:* Caída del servidor web.
- *Mitigación:* Configuración de reinicio automático con systemd/Docker y switch inmediato de contingencia al cliente de escritorio si fuera necesario.
Binary file not shown.
Binary file not shown.
Binary file not shown.
+14
View File
@@ -0,0 +1,14 @@
# Constitución — OnEverControl
Principios innegociables del proyecto. Toda spec, plan y tarea debe cumplirlos sin excepción.
1. **Modo Cliente Reducido**: OnEverControl es exclusivamente un cliente web para Login y Puesto de Control en la LAN de OnEverAccess. Prohibido duplicar módulos maestros o administrativos de OnEverAccess.
2. **La Spec manda (SDD)**: Nada se implementa si no está en la spec activa (`specs/NNN-*/`). Si falta una decisión o surge ambigüedad, se detiene la ejecución y se consulta al usuario.
3. **Desacople de Hardware y Lectura por Cámara**: El navegador jamás interactúa directamente con puertos COM o buses RS-485; toda orden a barreras o molinetes se encola en `pdtmdl`. La lectura de documentos (DNI PDF417/QR) se realiza exclusivamente mediante la cámara integrada de la tablet, prescindiendo por completo de escáneres por puerto COM y emulación de teclado.
4. **Diseño Touch-First para Tablets**: La interfaz debe ser 100% operable en tablets (Android, iPad, Windows Surface). Touch targets mínimos de 48x48px, layout `100dvh` resistente a teclado virtual y atajos de teclado físicos como alternativa.
5. **La Tablet es una Workstation**: Toda tablet se identifica ante SQL Server con un `workstation_name` registrado y hereda los mismos permisos y carriles que una PC Windows en OnEverAccess.
6. **Tests como Puerta de Calidad**: En cada tarea de backend o lógica, los tests se escriben primero (en rojo) antes de implementar el código. Prohibido dar por terminada una tarea con tests fallando.
7. **Transaccionalidad en videoman**: Las operaciones de acceso en SQL Server son atómicas (`tck`, `tckper`, `tckprx`, `mvthist`, `pdtmdl`). Si falla una parte, se realiza rollback completo.
8. **Idioma y Nomenclatura**: Código y APIs en inglés con nombres semánticos; interfaz de usuario, mensajes de garita y documentación técnica en español.
9. **Portabilidad Multiplataforma (Windows 10/11, LXC, Docker)**: OnEverControl debe ejecutarse sin modificaciones de código tanto en bare-metal Windows 10/11 (servicio del sistema), como en contenedores ligeros LXC (Proxmox/Debian/Alpine con systemd) y entornos Docker / Docker Compose. Se prohíbe el uso de rutas hardcodeadas con contrabarras (usar siempre `pathlib.Path`), llamadas exclusivas a APIs de Win32 en el backend, o dependencias directas de hardware que impidan el despliegue en entornos Linux sin privilegios.
10. **Versionado Semántico y Repositorio Oficial Gitea**: Todo cambio significativo o cierre de fase requiere actualizar explícitamente la versión del backend (`backend/app/__version__.py`) y del frontend (`frontend/package.json`), asentando el detalle en `CHANGELOG.md` antes de ser integrado y subido al repositorio oficial de Gitea (`https://gitea.oemspot.com.ar/carlostellocba/OnEverControl`). Queda prohibido realizar commits/pushes sin versionado explícito ni validación de pruebas.
+49
View File
@@ -0,0 +1,49 @@
# Plan Técnico — Spec 001: Autenticación y Workstation en Tablets
## 1. Archivos y Responsabilidades
### Backend (FastAPI / Python)
- `backend/app/schemas/auth_schema.py`: Modelos Pydantic para `LoginRequest`, `LoginResponse`, `UserSessionDTO`.
- `backend/app/schemas/workstation_schema.py`: Modelos Pydantic para `WorkstationDTO`, `WorkstationStatusResponse`.
- `backend/app/core/security.py`: Verificación de contraseñas (MD5/bcrypt compatible) y generación de tokens JWT.
- `backend/app/repositories/auth_repository.py`: Consultas SQL Server a tablas `usr` y `usrcatval`.
- `backend/app/repositories/workstation_repository.py`: Consultas a `es_puesto_de_control(name)` y `listar_modulos_por_workstation(name)`.
- `backend/app/api/v1/auth.py`: Endpoints `/api/v1/auth/login`, `/logout`, `/me`.
- `backend/app/api/v1/control_posts.py`: Endpoint `/api/v1/control-posts/workstation/{name}/status`.
- `backend/tests/test_auth.py`: Tests unitarios y de integración para endpoints de login y validación de estación.
### Frontend (React + TypeScript + Vite)
- `frontend/src/api/authApi.ts`: Funciones cliente para `/api/v1/auth/login`, `/logout` y `/me`.
- `frontend/src/api/workstationApi.ts`: Cliente para `/api/v1/control-posts/workstation/{name}/status`.
- `frontend/src/context/AuthContext.tsx`: Proveedor de estado global de autenticación del guardia.
- `frontend/src/context/WorkstationContext.tsx`: Proveedor que resuelve y almacena la Workstation en `localStorage`.
- `frontend/src/views/LoginView.tsx`: Vista táctil de inicio de sesión optimizada para tablets.
- `frontend/src/components/common/TouchInput.tsx`: Campo de entrada numérico/alfanumérico de alto contraste (>= 48px).
- `frontend/src/styles/base.css`: Viewport dinámico `100dvh` para teclados virtuales en pantalla.
---
## 2. Decisiones Técnicas Justificadas
1. **Tokens JWT en Cookies HttpOnly con SameSite=Strict:**
- *Alternativa descartada:* Guardar el token en `localStorage`.
- *Motivo:* Las cookies HttpOnly son inaccesibles por scripts JavaScript en el cliente, protegiendo las tablets ante ataques de XSS en la red local.
2. **Persistencia de Workstation en `localStorage` del Navegador:**
- *Alternativa descartada:* Consultar la IP fija de la tablet.
- *Motivo:* En redes Wi-Fi de garita, las tablets pueden usar DHCP o cambiar de punto de acceso (Access Point). Vincular el `workstation_name` en el almacenamiento local garantiza estabilidad operativa sin depender de IPs estáticas.
3. **Layout Táctil con `100dvh`:**
- *Alternativa descartada:* Altura fija con `100vh`.
- *Motivo:* En iPadOS Safari y Android Chrome, `100vh` no descuenta la barra de herramientas ni el teclado en pantalla, provocando que los botones queden ocultos o desfasados. `100dvh` se ajusta en tiempo real al espacio visible disponible.
---
## 3. Estrategia de Pruebas
- **Backend (Pytest):**
- Test de login con credenciales válidas -> 200 OK y cookie emitida.
- Test de login con credenciales erróneas -> 401 Unauthorized.
- Test de estación registrada válida -> devuelve `es_puesto_de_control: True` y módulos asignados.
- Test de estación no registrada -> devuelve `es_puesto_de_control: False` y lista vacía.
- **Frontend:**
- Validación de campos requeridos antes de enviar.
- Comprobación táctil de elementos >= 48px y despliegue correcto en emulador de tablet (iPad/Android).
+46
View File
@@ -0,0 +1,46 @@
# Spec 001 — Autenticación de Operador y Vinculación de Workstation en Tablets
Estado: borrador
## Contexto y objetivo
Permitir que los operadores y supervisores de seguridad inicien sesión en el cliente web OnEverControl desde tablets táctiles (Android, Windows, iPad) o PCs de garita en la red local, validando sus credenciales existentes contra la base de datos `videoman` de OnEverAccess y reconociendo la tablet como una Workstation autorizada con sus carriles asignados.
## Usuarios / Actores
- **Operador de Garita (Guardia):** Inicia sesión para operar los carriles asignados a su puesto.
- **Supervisor de Seguridad:** Configura o reasigna el identificador de estación (`workstation_name`) en la tablet.
## Historias de usuario
- **HU-1:** Como operador de garita, quiero iniciar sesión con mi usuario y contraseña en la tablet para acceder al puesto de control sin tener que recordar credenciales nuevas.
- **HU-2:** Como supervisor de seguridad, quiero vincular la tablet a un nombre de workstation registrado (ej: `TABLET_01`) para que el sistema cargue automáticamente los carriles correspondientes a ese puesto físico.
- **HU-3:** Como guardia en tablet táctil, quiero pulsar botones amplios y ver un teclado numérico automático para poder autenticarme de forma cómoda y rápida sin errores táctiles.
## Requisitos funcionales (Criterios de aceptación en sintaxis EARS)
- **RF-1 (Login Exitoso):** CUANDO el operador ingresa su usuario y contraseña válidos y pulsa "Ingresar", EL SISTEMA valida las credenciales contra la tabla `usr` de SQL Server `videoman`, genera una sesión segura mediante Cookie HttpOnly y carga el Puesto de Control con la estación activa.
- **RF-2 (Credenciales Inválidas):** SI el usuario o la contraseña ingresados no coinciden o no existen en la base de datos, ENTONCES EL SISTEMA muestra un mensaje de error táctil destacado indicando "Usuario o contraseña incorrectos" y mantiene el foco en el formulario sin cerrar la pantalla.
- **RF-3 (Resolución de Workstation):** CUANDO se carga la aplicación en la tablet, EL SISTEMA consulta si existe un `workstation_name` persistido en el dispositivo y valida mediante `es_puesto_de_control(workstation_name)` que sea una estación habilitada en OnEverAccess.
- **RF-4 (Estación No Autorizada):** SI el `workstation_name` configurado en la tablet no está registrado como puesto de control en OnEverAccess o no tiene módulos asignados, ENTONCES EL SISTEMA muestra una tarjeta informativa de advertencia ("Estación no autorizada") y bloquea la operación hasta que un supervisor configure una estación válida.
- **RF-5 (Configuración de Estación):** CUANDO un supervisor ingresa con credenciales de supervisión, EL SISTEMA permite seleccionar o cambiar el `workstation_name` de la tablet desde un selector de estaciones disponibles en la red local.
- **RF-6 (Cierre de Sesión):** CUANDO el operador pulsa el botón "Cerrar Sesión", EL SISTEMA invalida el token JWT, limpia los datos sensibles de la memoria y regresa a la pantalla de Login.
## Requisitos no funcionales
- **Touch-First:** Campos de texto y botón de ingreso con altura mínima de **48px**, espaciado ergonómico para uso con dedos en tablets de 10" a 13".
- **Teclado Virtual Amigable:** Layout adaptativo con `100dvh` que garantiza que el botón "Ingresar" no quede oculto detrás del teclado en pantalla en iPadOS o Android.
- **Latencia de Autenticación:** La validación de credenciales y carga de carriles debe responder en menos de **250 ms** dentro de la red local.
## Casos límite
- Desconexión temporal de la red local durante el login: mensaje claro de "Servidor OnEverAccess no disponible en la red local".
- Intento de iniciar sesión sin haber seleccionado o configurado una workstation en la tablet.
- Tablet operando en orientación vertical (Portrait) u horizontal (Landscape).
## Fuera de alcance
- Creación o edición de nuevos usuarios en la base de datos (se realiza en la suite central OnEverAccess).
- Asignación de roles o privilegios desde la web (se gestionan en OnEverAccess desktop).
## Criterios de finalización
- Endpoint `/api/v1/auth/login` y `/api/v1/control-posts/workstation` probados con tests automatizados en `pytest` en verde.
- Pantalla de Login en frontend probada en resolución tablet táctil con simulación de teclado virtual y verificación en iPad y Android.
- Sesión persistida y cierre de sesión seguro comprobado.
## Dudas abiertas
- Ninguna. Flujo alineado con la base de datos `videoman` y requerimientos de Workstation.
+18
View File
@@ -0,0 +1,18 @@
# Tareas — Spec 001: Autenticación y Workstation en Tablets
- [ ] **T1. Esquemas Pydantic para Autenticación y Workstation.** RF-1, RF-3
- Hecho cuando: `auth_schema.py` y `workstation_schema.py` validen payloads con tests unitarios en verde.
- [ ] **T2. Repositorio de Usuarios y Workstations contra SQL Server.** RF-1, RF-3, RF-4
- Hecho cuando: `auth_repository.py` y `workstation_repository.py` ejecuten consultas T-SQL y retornen datos de usuario y módulos asociados.
- [ ] **T3. Lógica de Seguridad y Endpoints de Login / Logout en FastAPI.** RF-1, RF-2, RF-6
- Hecho cuando: `test_auth.py` valide respuestas `200 OK` para login exitoso y `401 Unauthorized` para errores en `pytest`.
- [ ] **T4. Endpoint de Validación de Workstation.** RF-3, RF-4, RF-5
- Hecho cuando: `/api/v1/control-posts/workstation/{name}/status` retorne estado de habilitación de la tablet y lista de carriles asignados.
- [ ] **T5. Contextos React y Clientes API en Frontend (React + TypeScript).** RF-1, RF-3, RF-6
- Hecho cuando: `AuthContext.tsx` y `WorkstationContext.tsx` gestionen el estado y persistan `workstation_name` en `localStorage`.
- [ ] **T6. Vista Táctil de Login (LoginView.tsx) para Tablets.** RF-1, RF-2, RF-3, RF-4
- Hecho cuando: La pantalla de login en React renderice controles táctiles de 48px, soporte `100dvh` para teclados virtuales y opere de forma fluida en tablets Samsung Galaxy Tab A9/A11 (4GB RAM), iPad y Windows.
- [ ] **T7. Selector de Workstation para Supervisores.** RF-4, RF-5
- Hecho cuando: Un supervisor pueda seleccionar o reasignar la workstation de la tablet y se actualice el carril en pantalla.
- [ ] **T8. Pruebas de Integración E2E y Validación de Criterios.** RF-1 a RF-6
- Hecho cuando: Se ejecute el flujo completo de login, detección de estación y logout sin errores, y se actualice `MEMORY.md`.
@@ -0,0 +1,36 @@
# Spec 002 — Escaneo Óptico de DNI con Cámara de Tablet y Control de Acceso
Estado: borrador
## Contexto y objetivo
Eliminar por completo los lectores físicos externos de código de barras/QR (puerto COM serie y USB emulando teclado) en los puestos de control de OnEverControl. En su lugar, utilizar directamente la cámara integrada de la tablet (Android, iPad, Windows) para detectar, escanear y decodificar el DNI argentino (PDF417 y QR) en tiempo real, completando instantáneamente los datos de la persona y capturando al mismo tiempo la fotografía del documento como evidencia de seguridad.
## Usuarios / Actores
- **Operador de Garita (Guardia en Tablet):** Apunta la tablet al DNI físico de la visita o conductor en la ventanilla para capturar los datos y registrar el ingreso/salida.
## Historias de usuario
- **HU-1:** Como guardia con tablet en mano, quiero escanear el DNI del ingresante apuntando con la cámara trasera de la tablet para no depender de lectores con cables ni escáneres externos en el puesto.
- **HU-2:** Como guardia, quiero que al detectar el DNI la tablet haga un bip/vibración y complete automáticamente Apellido, Nombre, Documento y Género para no tener que tipear nada manualmente.
- **HU-3:** Como guardia, quiero que el sistema guarde automáticamente la foto del DNI capturada por la cámara como constancia visual de la visita.
## Requisitos funcionales (Criterios de aceptación en sintaxis EARS)
- **RF-1 (Activación de Cámara y Detección):** CUANDO el operador abre el carril de ingreso o pulsa "Escanear DNI", EL SISTEMA activa la cámara trasera de la tablet (`facingMode: "environment"`) con encuadre guiado y escanea continuamente fotogramas mediante la Barcode Detection API nativa y fallback con ZXing (Wasm/JS).
- **RF-2 (Decodificación Instantánea):** CUANDO el encuadre enfoca un código de barras PDF417 (dorso de DNI) o código QR oficial (Renaper / Mi Argentina), EL SISTEMA decodifica la cadena de texto cruda en menos de 100 ms, emite un feedback sonoro/háptico y congela el fotograma como imagen del documento.
- **RF-3 (Parsing de Datos):** CUANDO se decodifica la cadena del DNI, EL SISTEMA ejecuta la función de parsing (formatos 2009, 2012, 2026 y digital) y completa de forma inmediata los campos de Documento, Apellido, Nombre y Sexo en el formulario del carril.
- **RF-4 (Validación de Seguridad y Antipassback):** CUANDO los datos de la persona son cargados, EL SISTEMA consulta de inmediato en SQL Server `videoman` el estado de la persona: antipassback activo, listas de restricción (Blacklist), alertas de seguridad y pólizas registradas.
- **RF-5 (Fallback a Tipeo Manual):** SI el código de barras físico del documento está borroso o ilegible, ENTONCES EL SISTEMA permite al operador ingresar el número de documento directamente con el teclado numérico táctil de pantalla (`inputmode="numeric"`).
- **RF-6 (Cero Dependencia de Periféricos):** EL SISTEMA opera de forma autónoma sin requerir escáneres por puerto COM ni periféricos USB HID conectados.
## Requisitos no funcionales
- **Rendimiento:** Decodificación óptica en cliente en menos de **100 ms** sin enviar video continuo por la red local.
- **Aceleración por Hardware:** Utilización de Barcode Detection API nativa en Chromium/Android y Safari/iPadOS cuando esté disponible.
- **Ergonomía Táctil:** Botón de captura y activación de cámara con tamaño mínimo de **56 x 56 px**.
## Casos límite
- Cámara sin permisos en el navegador: mensaje claro solicitando habilitar permisos de cámara en la tablet.
- DNI con iluminación deficiente o reflejos: guía visual en pantalla recomendando inclinar la tarjeta.
- Persona ya ingresada adentro (Antipassback): visualización inmediata del banner de alerta con botón "Ir a Salida".
## Fuera de alcance
- Conexión con escáneres físicos RS-232 o emuladores de teclado USB.