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