65 lines
4.8 KiB
Markdown
65 lines
4.8 KiB
Markdown
# 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.
|