Files

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