Guía de Desarrollo e Integración Técnica¶

Esta guía documenta el stack tecnológico de Nexus Energy, el aprovisionamiento de bases de datos locales, el flujo de ingesta de mediciones de campo y los comandos para el despliegue en producción.

🛠️ Stack Tecnológico y Arquitectura¶

Fullstack Framework: SvelteKit con Svelte 5 (uso nativo de runas $state, $derived, $props).
Hosting y Edge Runtime: Cloudflare Pages para respuestas de bajísima latencia distribuidas globalmente.
Base de Datos: Cloudflare D1 (Motor SQLite nativo en el Edge).
Autenticación: Clerk (con flujos de inicialización locales sincronizados por webhook).
Estilos: Tailwind CSS con un sistema de tokens de diseño semánticos en app.css.

🐍 Entorno de Desarrollo Python (`uv`)¶

Para el soporte de generación de datos y compilación de manuales estáticos, el proyecto requiere de un entorno Python aislado. Hemos simplificado y optimizado este proceso utilizando uv, el resolvedor y compilador de Python ultra-rápido escrito en Rust.

Creación e Instalación del Entorno:¶

# 1. Crear el entorno virtual .venv
uv venv

# 2. Instalar todas las dependencias declaradas en el requirements.txt
uv pip install -r requirements.txt

🗄️ Aprovisionamiento y Migraciones de Base de Datos (D1)¶

El esquema de base de datos se consolida en schema.sql y evoluciona incrementalmente a través de scripts en migrations/.

Comandos de Base de Datos:¶

# Crear base de datos en desarrollo local (Wrangler local)
pnpm exec wrangler d1 create nexus-db

# Aplicar las migraciones incrementales en base local
pnpm db:migrate:local

# Aplicar las migraciones en la base de datos remota de producción
pnpm db:migrate

[!WARNING] En la base de datos local emulada y en producción, siempre vincula la base de datos D1 a la constante DB dentro de tu configuración de entorno (wrangler.toml).

📈 Generación de Mediciones Sintéticas (`generate_measurements.py`)¶

Para probar la robustez de los gráficos y cálculos analíticos sin requerir hardware físico, el proyecto incluye un generador de telemetría de alta fidelidad física.

El script generate_measurements.py simula curvas de irradiancia solar realistas (siguiendo curvas de Gauss), consumos distribuidos lógicos de oficina/industria, carga/descarga de baterías según el excedente solar y cálculo preciso de contadores monótonamente crecientes (kWh).

Pasos para Poblar tu Base de Datos Local:¶

# 1. Ejecutar el generador para crear el archivo de transacciones SQL
python generate_measurements.py

# 2. Ingestar el seed resultante en la base local SQLite de Wrangler
npx wrangler d1 execute nexus-db --local --file=./measurements_seed.sql

📡 Pipeline de Ingesta de Mediciones (API)¶

Los dispositivos físicos en campo transmiten lecturas eléctricas en formato JSON al endpoint de ingesta:

POST /api/v1/ingest
Content-Type: application/json
Authorization: Bearer <device_token>

Formato Simplificado de Ingesta:¶

{
  "device_serial": "INV-DEYE-50KW-004",
  "timestamp": "2026-05-23T13:00:00Z",
  "inverter_active_power_kw": 42.5,
  "battery_soc": 92.0,
  "grid_voltage_a": 120.5,
  "raw_data": {
    "firmware_version": "v3.1.2",
    "ambient_temp_c": 28.5
  }
}

Validación: El servidor valida el número de serie en la tabla devices y graba la muestra en inverter_measurements.
Backup: Datos específicos no soportados en las columnas tipadas principales se graban de manera flexible en el campo JSON raw_data para posterior análisis mediante queries json_extract.