Sevastopol ETL Island

Propósito

EtlViewIsland es la única UI del frontend para disparar loaders de Nostromo. Vive en admin/ (mismo módulo que el resto del workspace SUPER_ADMIN) y consume directamente /api/etl/* del Orchestrator. No hay tenant ni período del workspace involucrado — los loaders operan a nivel de plataforma sobre la base maestra.

La island sostiene un historial in-memory de los últimos 10 runs disparados desde esa sesión, con polling automático cada 3s sobre los running.

Decisiones de UX

Decisión	Motivo
5 scripts hardcoded en AVAILABLE_SCRIPTS	El catálogo cambia con baja frecuencia y se versiona junto con el backend. Hardcoded simplifica vs. carga dinámica.
Período YYYY-MM con default mes actual	getCurrentPeriod() autocompleta — el caso típico es cargar el mes en curso.
Selector visual de script (grid de cards)	Cada script lleva ícono + descripción para identificación rápida. El click selecciona; el dispatch es botón aparte.
Modo BC: month (default) o custom	Toggle entre rango derivado del período o fechaInicio/fechaFin explícitos. Útil para backfill no-mensual.
impuesto_2cat: periodoTipo + utm opcional	mensual es el default operacional; all regenera todos los tramos (mensual/quincenal/semanal/diario). UTM vacío exige que exista en parametros.indicadores.
Moneda BC con default ALL	Cubre el caso común (UF + USD + EUR juntos). Override solo si se debugea uno.
Polling cada 3s solo si hay runs running	ensurePolling arranca el intervalo cuando runningCount() > 0; se detiene al terminar. Sin runs activos, sin tráfico.
Historial limitado a 10 entradas	Buffer de la sesión. Para auditoría de largo plazo el operador consulta logs server-side.
Validación de fechas en cliente	fechaInicio > fechaFin se rechaza antes del POST. Evita rebote del backend.
Toast diferenciado por estado	completed → success; failed con timedOut → “timeout”; failed con exit code → "exit {N}". El operador entiende inmediatamente qué pasó.
Sin useActiveTenant ni useActivePeriod	El ETL no es per-tenant — escribe en parametros.* (global) o en bases de tenants identificados por archivo (run_cargas_sii).

Scripts disponibles

ID	Nombre	Período requerido	Flags adicionales
sii_loader	SII Loader	sí	—
previred_loader	Previred Loader	sí	—
correccion_monetaria	Corrección Monetaria	sí	—
banco_central_loader	Banco Central Loader	sí	moneda, fechaInicio/fechaFin opcionales
impuesto_2cat_loader	Impuesto 2ª Categoría Loader	sí	periodoTipo, utm opcional

Estados de un run en la UI

Estado	UI
running	Pill ámbar, polling activo.
completed	Pill verde + toast success.
failed	Pill rojo + toast con razón (timeout o exit code).
unknown	PID no encontrado en registry — toast informativo.

Polling

const POLL_INTERVAL_MS = 3000;

createEffect(() => {
  if (runningCount() > 0) ensurePolling();
});

onCleanup(() => {
  if (pollTimer) clearInterval(pollTimer);
});

refreshExecution(pid) actualiza endedAt, exitCode, errorTail, timedOut desde /api/etl/status/:pid. La UI re-renderiza por reactividad del signal executions.

Endpoints consumidos

Método + ruta	Uso
POST /api/etl/trigger	Dispara el loader. Body: { script, period, year, month, periodoTipo?, utm?, fechaInicio?, fechaFin?, moneda? }.
GET /api/etl/status/:pid	Estado del run. Poleado cada 3s mientras esté running.

Estructura del payload por script

banco_central_loader

{
  "script": "banco_central_loader",
  "period": "2026-05",
  "year": "2026",
  "month": "05",
  "fechaInicio": "2026-05-01",
  "fechaFin": "2026-05-31",
  "moneda": "UF"
}

fechaInicio/fechaFin solo se envían si bcRangeMode === "custom". moneda solo si no es ALL.

impuesto_2cat_loader

{
  "script": "impuesto_2cat_loader",
  "period": "2026-05",
  "year": "2026",
  "month": "05",
  "periodoTipo": "mensual",
  "utm": "67890.50"
}

utm solo si está provisto explícitamente. Si vacío, el controller valida que exista en parametros.indicadores.

Repositorio

sevastopol/src/components/islands/admin/EtlViewIsland.tsx — 566 líneas, una sola island con ToastProvider envolvente.

Relación con otras capas

• Orchestrator EtlController — es el único backend que la UI consume.
• ETL Scripts (Nostromo) — son los loaders que terminan ejecutándose como hijos del Orchestrator.