Files

55 lines
3.8 KiB
Markdown

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