Files

4.8 KiB

Especificación — Spec 000: Arquitectura Base y Scaffolding (Fase 1)

1. Contexto y Objetivo

Establecer la estructura fundacional, dependencias, entornos de ejecución y esqueletos funcionales del Backend (FastAPI + Pydantic v2) y Frontend (React + TypeScript + Vite) para OnEverControl. El objetivo es contar con un entorno de desarrollo reproducible, verificable y agnóstico al sistema operativo (Windows 10/11, LXC y Docker), con verificación de salud (/health), conectividad a SQL Server videoman y diseño base Touch-First para tablets Samsung Galaxy Tab A9/A11 (4GB RAM), versionado en v0.1.0-alpha.


2. Usuarios / Actores

  • Desarrollador / Agente de IA: Necesita un entorno estructurado, comandos reproducibles de tests y compilación limpia sin errores de dependencias.
  • Administrador de Infraestructura: Requiere opciones de despliegue directo en Windows (servicio), contenedores ligeros LXC en Proxmox o Docker Compose.
  • Operador de Garita (Cliente Web): Accede a la interfaz web táctil base desde la tablet en la red local.

3. Historias de Usuario

  • HU-0.1: Como desarrollador, quiero levantar el backend con FastAPI y verificar que /health responda status: ok y /docs exponga la documentación OpenAPI para validar que la API está operativa.
  • HU-0.2: Como desarrollador, quiero ejecutar un script de verificación de base de datos (test_sql_connection.py) para confirmar la conectividad con SQL Server videoman tanto en Windows como en Linux.
  • HU-0.3: Como desarrollador, quiero levantar la aplicación frontend con Vite y visualizar el shell táctil responsive a pantalla completa (100dvh) en emulador de tablet.
  • HU-0.4: Como administrador de infraestructura, quiero disponer de configuración Docker Compose y scripts para Windows y LXC para desplegar el sistema según los recursos del predio.

4. Requisitos Funcionales (Sintaxis EARS)

Ubicuo (Comportamiento Permanente)

  • RF-0.1: EL SISTEMA mantendrá la versión semántica sincronizada (v0.1.0-alpha) en backend/app/__version__.py y frontend/package.json.
  • RF-0.2: EL SISTEMA utilizará rutas relativas o resueltas mediante pathlib.Path, prohibiendo contrabarras hardcodeadas para garantizar portabilidad en Windows, LXC y Docker.

Con Evento

  • CUANDO el cliente realice una petición GET /health, EL SISTEMA retornará código 200 OK con un JSON que incluya {"status": "ok", "version": "0.1.0-alpha", "timestamp": "<ISO-8601>"}.
  • CUANDO el cliente acceda a GET /docs, EL SISTEMA servirá la interfaz interactiva de Swagger UI de OpenAPI.
  • CUANDO se ejecute scripts/test_sql_connection.py, EL SISTEMA intentará conectarse a SQL Server videoman usando las variables de entorno de .env y reportará si la conexión fue exitosa o el motivo exacto del fallo.

Con Condición No Deseada

  • SI las credenciales o el host de SQL Server en .env son inalcanzables, ENTONCES EL SISTEMA reportará un mensaje claro de diagnóstico sin generar caídas silenciosas ni excepciones no controladas.
  • SI se produce una petición con un endpoint no existente, ENTONCES EL SISTEMA responderá un error 404 estandarizado en formato JSON.

Con Estado

  • MIENTRAS la aplicación frontend de React esté abierta en una tablet táctil, EL SISTEMA mantendrá un contenedor raíz con altura fija de viewport dinámico 100dvh, impidiendo que el teclado virtual tape las acciones principales.

5. Requisitos No Funcionales

  • Rendimiento Backend: Tiempo de respuesta de /health inferior a 5 ms en red local.
  • Huella de Memoria Frontend: Compilación estática optimizada de React con Vite con bundle gzip < 150 KB para operar fluidamente en tablets con 4 GB de RAM.
  • Portabilidad: Compatibilidad verificada con Python 3.11/3.12 y Node.js 20+.
  • Touch-First: Hoja de estilos con variables semánticas (Design Tokens de OnEver), clases base para controles >= 48px y soporte para gestos táctiles sin zoom accidental.

6. Fuera de Alcance (Para esta fase)

  • Endpoints de autenticación JWT de negocio y login (pertenecen a Spec 001).
  • Lectura de cámara de DNI y decodificación de código de barras (pertenece a Spec 002).
  • Encolado de tramas a barreras físicas en pdtmdl (pertenece a Fase 4).

7. Criterios de Finalización (DoD)

  1. pytest en backend/ ejecuta tests unitarios de /health y configuración en verde.
  2. npm run build en frontend/ compila la SPA de React con TypeScript sin errores ni advertencias.
  3. .env.example, docker-compose.yml, scripts para Windows (scripts/windows/) y LXC (scripts/lxc/) creados y documentados.
  4. Versión sincronizada v0.1.0-alpha en backend, frontend y registrada en CHANGELOG.md.
  5. MEMORY.md actualizado con el cierre de las tareas.