feat(base): finalizada Fase 1 scaffolding v0.1.0-alpha

This commit is contained in:
Carlos Tello
2026-10-13 15:15:52 -03:00
parent 12c5649427
commit 78c1a306de
34 changed files with 3113 additions and 5 deletions
+54
View File
@@ -0,0 +1,54 @@
# Plan Técnico — Spec 000: Arquitectura Base y Scaffolding (Fase 1)
## 1. Archivos y Responsabilidades
### Configuración Raíz y Despliegue Multiplataforma
- `OnEverControl/.env.example`: Plantilla unificada de variables de entorno (SQL Server, JWT, CORS, puertos).
- `OnEverControl/docker-compose.yml`: Orquestación multicontenedor (FastAPI + Nginx reverse proxy y estáticos de React).
- `OnEverControl/scripts/test_sql_connection.py`: Script de diagnóstico y conectividad hacia SQL Server `videoman`.
- `OnEverControl/scripts/windows/install_service.bat`: Script de registro del servicio en Windows 10/11 vía NSSM.
- `OnEverControl/scripts/windows/start_native.bat`: Script de inicio rápido bare-metal en garita.
- `OnEverControl/scripts/lxc/setup_lxc.sh`: Instalador de dependencias Linux (Python, FreeTDS, Nginx) para Proxmox/Debian.
- `OnEverControl/scripts/lxc/onevercontrol.service`: Unit file para `systemd`.
### Backend (FastAPI / Python)
- `backend/pyproject.toml` / `backend/requirements.txt`: Dependencias (`fastapi`, `uvicorn[standard]`, `pydantic>=2.0`, `pydantic-settings`, `pymssql`, `pytest`, `httpx`).
- `backend/app/__version__.py`: Definición de versión `0.1.0-alpha`.
- `backend/app/core/config.py`: Clase `Settings` de Pydantic Settings para cargar `.env` de forma tipada.
- `backend/app/main.py`: Instancia FastAPI, configuración de CORS, compresión GZip y router base con `/health`.
- `backend/app/api/v1/router.py`: Agregador de rutas v1.
- `backend/tests/test_health.py`: Pruebas de endpoint `/health` y metadatos de versión.
### Frontend (React + TypeScript + Vite)
- `frontend/package.json`: Dependencias (`react`, `react-dom`, `@types/react`, `@types/react-dom`, `vite`, `typescript`). Versión `0.1.0-alpha`.
- `frontend/tsconfig.json`: Configuración estricta de TypeScript.
- `frontend/vite.config.ts`: Configuración de Vite con base, proxy dev hacia backend `http://localhost:8000` y build optimizado.
- `frontend/index.html`: Entrypoint HTML5 táctil con meta tags para PWA, viewport dinámico y prevención de zoom accidental.
- `frontend/src/main.tsx`: Punto de montaje de React.
- `frontend/src/App.tsx`: Shell base táctil con indicador de estado del sistema y selector de modo oscuro.
- `frontend/src/styles/tokens.css`: Variables CSS del OnEver Design System (colores semánticos Dark/Light, contrastes garita).
- `frontend/src/styles/base.css`: Reset, `100dvh`, utilidades táctiles (touch targets >= 48px).
---
## 2. Decisiones Técnicas Justificadas
1. **Uso de `pydantic-settings` para la Configuración:**
- *Alternativa descartada:* `os.getenv` directo en múltiples módulos.
- *Motivo:* `pydantic-settings` valida tipos, formatos de host/puerto y valores por defecto en tiempo de arranque, fallando rápido si falta una variable crítica.
2. **Estructura Estática de React servida vía Nginx o FastAPI:**
- *Alternativa descartada:* Servidor Node.js SSR en tiempo de ejecución.
- *Motivo:* La compilación estática SPA consume cero CPU en el servidor de estáticos y mantiene el consumo de memoria en la tablet Samsung Galaxy Tab A9/A11 en menos de 50 MB de RAM.
3. **Manejo Centralizado de Conectividad con FreeTDS / `pymssql`:**
- *Alternativa descartada:* Usar pyodbc con drivers ODBC propietarios de Microsoft.
- *Motivo:* FreeTDS y `pymssql` son de código abierto, ultralivianos y se instalan limpiamente en Windows, Alpine, Debian y Proxmox LXC sin dependencias binarias pesadas.
---
## 3. Estrategia de Pruebas y Validación
- **Backend:**
- Ejecutar `pytest backend/tests/test_health.py` comprobando código 200 y JSON estructurado.
- **Frontend:**
- Ejecutar `npm run build` comprobando generación de bundle limpio en `dist/` sin advertencias de tipos.
- **Herramientas de Diagnóstico:**
- Ejecutar `python scripts/test_sql_connection.py` para validar parsing de `.env`.
+64
View File
@@ -0,0 +1,64 @@
# 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.
+14
View File
@@ -0,0 +1,14 @@
# Tareas — Spec 000: Arquitectura Base y Scaffolding (Fase 1)
- [x] **T1. Configuración de Entorno y Scripts Multiplataforma (Windows, LXC, Docker).** RF-0.1, RF-0.2
- Hecho cuando: Existan `.env.example`, `docker-compose.yml`, `scripts/windows/` y `scripts/lxc/` listos para ser configurados.
- [x] **T2. Dependencias de Backend y Configuración Tipada (Pydantic Settings).** RF-0.1, RF-0.2
- Hecho cuando: `backend/requirements.txt`, `backend/app/__version__.py` (v0.1.0-alpha) y `backend/app/core/config.py` carguen variables de forma tipada sin fallos.
- [x] **T3. Endpoint de Salud `/health` y Middleware FastAPI con Pruebas Unitarias.** RF-0.1
- Hecho cuando: `backend/app/main.py` levante la aplicación FastAPI con CORS y `pytest backend/tests/test_health.py` pase en verde con respuesta 200 OK y metadatos de versión.
- [x] **T4. Script de Verificación de Conectividad SQL Server (`test_sql_connection.py`).** RF-0.2
- Hecho cuando: El script intente conectarse usando los parámetros de configuración y muestre diagnóstico claro tanto en Windows como en Linux.
- [x] **T5. Scaffolding del Frontend en React + TypeScript + Vite con Layout Touch-First.** RF-0.1, RF-0.2
- Hecho cuando: `frontend/` contenga `package.json` (v0.1.0-alpha), `vite.config.ts`, `tokens.css`, `base.css` (`100dvh`), `App.tsx` y compile limpiamente con `npm run build`.
- [x] **T6. Validación Integral de Fase 1 y Actualización de Memoria.** RF-0.1, RF-0.2
- Hecho cuando: Se ejecuten los tests del backend, el build del frontend, se verifique la versión en `CHANGELOG.md` y se actualice `MEMORY.md` para el usuario.