Datos y ETL Nostromo

Propósito

Nostromo es el subsistema ETL del ecosistema. Su responsabilidad es alimentar la base de datos con parámetros, indicadores y documentos que el resto de las aplicaciones consume. A diferencia del Orchestrator (lógica de negocio) y Sevastopol (interfaz), Nostromo opera fuera del ciclo de petición del usuario: corre como scripts CLI en Python.

Esta sección documenta las tres capas que cooperan para que una carga ETL ocurra:

Capa	Rol	Tecnología
Nostromo (loaders)	Scripts Python que descargan, transforman y persisten datos en la base.	Python + Playwright + psycopg.
Orchestrator (EtlController)	API HTTP que dispara los loaders como procesos hijo, valida prerrequisitos y mantiene registry de ejecuciones.	Node/Express + child_process.spawn.
Sevastopol (EtlViewIsland)	UI SUPER_ADMIN para seleccionar script + período, disparar y monitorear ejecución.	SolidJS island + polling.

Flujo end-to-end

flowchart LR
  UI[Sevastopol EtlViewIsland] -->|POST /api/etl/trigger| OC[Orchestrator EtlController]
  OC -->|spawn| PY[Python loader]
  PY -->|escribe| DB[(PostgreSQL parametros/operaciones_sii)]
  UI -->|GET /api/etl/status/:pid every 3s| OC
  OC -->|stdout/stderr/exit| PY

1. Operador SUPER_ADMIN selecciona script + período en la UI.
2. EtlViewIsland envía POST /api/etl/trigger con { script, period, ...flags }.
3. EtlController valida prerrequisitos (ej. UTM disponible para impuesto_2cat), resuelve el módulo Python y ejecuta spawn() contra el venv de Nostromo.
4. El loader Python ejecuta y escribe en la base. Su PID + estado vive en un registry in-memory del controller.
5. La UI polea /api/etl/status/:pid cada 3s hasta que el estado sea completed o failed.

Qué carga

Fuente	Datos	Destino	Loader
Banco Central	UF, USD, EUR	parametros.monedas	bc_loader.py
Previred (JSON)	Topes, rentas mínimas, AFC, AFP	parametros.*	previred_loader.py
SII	Tramos Impuesto Único 2ª categoría	parametros.impuesto_2cat	impuesto_2cat_loader.py
SII (Playwright)	Boletas de honorarios, RCV	Archivos descargados	sii_loader.py
Archivos SII descargados	Operaciones	operaciones_sii.* por tenant	run_cargas_sii.py
SII	Factores corrección monetaria	parametros.*	correccion_monetaria_loader.py

Decisiones de arquitectura

Decisión	Motivo
Loaders en Python, no en Node	Playwright/Selenium para scraping, ecosistema de scientific computing y compatibilidad con scripts ya existentes del equipo contable.
child_process.spawn desde Orchestrator	Mantiene Nostromo como módulo independiente — el Orchestrator no importa Python. La frontera es el contrato CLI.
Registry in-memory en el controller	El estado de una corrida vive en memoria del proceso Express por MAX_REGISTRY_SIZE=100 entradas. Se pierde al reiniciar — los logs persistentes viven en stdout/stderr capturados.
Watchdog con timeout 15min	ETL_TIMEOUT_MS mata procesos colgados. La UI lo refleja como timedOut: true.
Polling cada 3s vs push	No hay WebSocket — el cliente polea. Volumen bajo (1-2 corridas simultáneas típicas); simplicidad sobre eficiencia.
Prerrequisito UTM en impuesto_2cat_loader	El controller valida parametros.indicadores antes del spawn — devuelve 409 con accionRecomendada si falta. Evita corridas que fallarán inevitablemente.
Ruta absoluta a Nostromo (c:\dev\Nostromo)	MVP. Se asume el mismo host para Orchestrator y Nostromo. Documentado como “Quick & Dirty” en el código.
Venv detection	resolvePythonExecutable prefiere .venv/Scripts/python.exe si existe; cae a python del PATH. Soporta dev (venv) y prod (system Python).

Documentación por capa

Capa	Documentación	Endpoint / módulo
Python loaders	ETL Scripts	accounting_system.{bc,previred,impuesto_2cat,sii,correccion_monetaria}_loader
HTTP controller	Orchestrator ETL	POST /api/etl/trigger · GET /api/etl/status/:pid
Frontend UI	Sevastopol ETL (UI)	EtlViewIsland en admin/

Repositorios

Capa	Repositorio	Lenguaje
Loaders	github.com/ChrisTkm/Nostromo	Python
Controller	orchestrator/src/controllers/EtlController.ts + routes/etlRoutes.ts	TypeScript / Node
UI	sevastopol/src/components/islands/admin/EtlViewIsland.tsx	SolidJS / TSX

Relación con otros dominios

• Parámetros del tenant (UF, UTM, AFP, etc.) salen de aquí — PayrollService, F29GeneratorService y otros los consumen.
• Operaciones SII llenadas por run_cargas_sii.py alimentan compras/ventas/honorarios que el ciclo contable consume.
• Command (SUPER_ADMIN) protege la API ETL — solo roles privilegiados disparan corridas.

Estas relaciones se documentan en cada destino, no aquí.