3.8 KiB
3.8 KiB
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 Servervideoman.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 parasystemd.
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ón0.1.0-alpha.backend/app/core/config.py: ClaseSettingsde Pydantic Settings para cargar.envde 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/healthy metadatos de versión.
Frontend (React + TypeScript + Vite)
frontend/package.json: Dependencias (react,react-dom,@types/react,@types/react-dom,vite,typescript). Versión0.1.0-alpha.frontend/tsconfig.json: Configuración estricta de TypeScript.frontend/vite.config.ts: Configuración de Vite con base, proxy dev hacia backendhttp://localhost:8000y 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
- Uso de
pydantic-settingspara la Configuración:- Alternativa descartada:
os.getenvdirecto en múltiples módulos. - Motivo:
pydantic-settingsvalida tipos, formatos de host/puerto y valores por defecto en tiempo de arranque, fallando rápido si falta una variable crítica.
- Alternativa descartada:
- 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.
- Manejo Centralizado de Conectividad con FreeTDS /
pymssql:- Alternativa descartada: Usar pyodbc con drivers ODBC propietarios de Microsoft.
- Motivo: FreeTDS y
pymssqlson 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.pycomprobando código 200 y JSON estructurado.
- Ejecutar
- Frontend:
- Ejecutar
npm run buildcomprobando generación de bundle limpio endist/sin advertencias de tipos.
- Ejecutar
- Herramientas de Diagnóstico:
- Ejecutar
python scripts/test_sql_connection.pypara validar parsing de.env.
- Ejecutar