HACKACOES — Grupo 3 · Automatización del módulo de Liquidaciones

Proyecto del Grupo 3 de la HACKACOES.

El problema

Hoy la información de liquidaciones del COES llega a las empresas del sector de forma dispersa y difícil de rastrear:

• Información fragmentada — los datos viven en informes, anexos y archivos separados, y armar una vista completa exige juntarlos a mano.
• Demoras en la búsqueda — encontrar el detalle de una liquidación puntual puede tomar horas de revisar documentos.
• Trazabilidad débil — cuando un monto cambia entre la versión original y sus revisiones (R1, R2), no queda claro qué cambió, cuándo ni por qué.

La propuesta

Automatizar el módulo de Liquidaciones para disponibilizar correctamente la información a las distintas empresas del sector, con:

• Consolidación de las liquidaciones en una sola fuente consultable.
• Trazabilidad extremo a extremo: de cada monto al informe y la revisión que lo originó.
• Búsqueda y filtrado inmediatos, en lugar de rastreo manual entre archivos.
• Análisis de integridad y detección de inconsistencias entre versiones.

Para el equipo: cómo trabajar con Git

Si es tu primera vez con Git, abre GUIA-GIT.html con doble clic. Tiene el paso a paso completo — clonar, crear tu rama, commitear y mergear a master — con botones para copiar cada comando.

Resumen del ciclo:

git checkout master && git pull          # 1. actualizar
git checkout -b nombre-de-tu-tarea       # 2. tu rama
git add . && git commit -m "Qué hiciste" # 3. guardar
git push -u origin nombre-de-tu-tarea    # 4. subir
git pull origin master                   # 5. traer master antes del pull request

Reglas: nunca trabajar directo en master, siempre git pull antes de empezar, y una rama por tarea.

Stack

Capa	Tecnología
Frontend	React 19 + Vite 8 · Recharts (gráficos) · Axios (HTTP) · oxlint
Backend	Python + FastAPI + Uvicorn · Pydantic
Datos y análisis	pandas · numpy · pyarrow

Node.js se usa únicamente como herramienta de desarrollo del frontend (servidor de desarrollo de Vite y compilación). No hay backend en Node: la API es FastAPI y el frontend compila a archivos estáticos.

Estructura

COES_2026/
├── backend/                API FastAPI
│   ├── app/
│   │   ├── main.py            ensamblador de la app (CORS, routers)
│   │   ├── analysis.py        análisis de liquidaciones
│   │   ├── data/loader.py     carga perezosa de la capa curada
│   │   ├── routers/           endpoints por dominio (catálogos, panorama, empresa, revisiones, red, contactos)
│   │   └── services/          trazabilidad, integridad, agente, revisiones, pagos, red, contactos
│   ├── scripts/
│   │   ├── preparar_datos.py        ETL: welcome kit -> data/curated/
│   │   ├── identidad_empresa.py     adjudica RUC y razón social a los códigos con liquidación
│   │   ├── extraer_padron.py        saca el padrón real del libro de liquidaciones (una vez)
│   │   ├── estimar_coordenadas.py   estima lat/lon de cada barra por su nombre -> ../data/
│   │   └── proyectar_bilateral.py   proyecta el detalle de pagos y cobros de los meses que no lo traen
│   ├── data/
│   │   ├── raw/                copia de trabajo del welcome kit (no versionada)
│   │   ├── curated/             parquet consumidos por la API (sí versionada)
│   │   └── padron_empresas.csv  87 empresas reales del COES (RUC, razón social)
│   └── tests/                pruebas de ETL, servicios y endpoints
├── data/                  insumos y salidas que viven fuera del backend
│   ├── coordenadas_barras.csv        ubicación estimada de las 828 barras (mapa)
│   ├── cruce_bilateral_proyectado.csv pagos y cobros proyectados para los meses sin detalle (2026 salvo julio)
│   ├── contactos.xlsx                fichas de contacto; lo crea el portal al guardar la primera
│   ├── simulado_liquidaciones_*.xlsx libro del que sale el padrón real
│   └── spotPriceBarraRevisado/       costo marginal a 15 minutos por barra (reserva para intradía)
├── frontend/         aplicación React + Vite
│   └── src/
│       ├── app/          cáscara: navegación, selección global, tema
│       ├── secciones/    una por entrada del menú
│       ├── componentes/  tarjetas, variaciones, estados de carga
│       ├── lib/          formato de cifras y semántica de variaciones
│       ├── api/          cliente HTTP por dominio
│       ├── estilos/      tokens.css (identidad HackaCOES: color, modo claro/oscuro) y base.css (tipografía, componentes base, accesibilidad)
│       ├── assets/       imágenes
│       ├── main.jsx      punto de entrada de la aplicación
│       ├── App.css       hoja del componente legado; sus selectores van acotados bajo `.legacy` para no competir con el sistema de diseño
│       └── LegacyApp.jsx flujo causal A1→A7, montado dentro de las secciones
├── presentacion/            PPT de la exposición
└── COES.txt                 notas de instalación del entorno

Secciones de COES Hub, en el orden del menú: Panorama, Mi empresa, Evolución histórica, Procesos (pagos y cobros), Comparador de empresas, Simulador (cálculo preliminar con tu energía y tus valores), Red y precios (mapa del SEIN por capas: costo marginal, entregas y retiros), Contactos (fichas en Supabase), APIs y descargas y Calidad y trazabilidad. El selector de publicación y empresa vive en la cabecera, arriba a la derecha, y gobierna todas ellas. El diseño y sus decisiones están en docs/superpowers/specs/.

frontend/src/LegacyApp.jsx tiene cerca de 7.900 líneas en una sola función. No es un descuido: ahí vive el análisis causal (flujo A1→A7) que ya funciona, y reescribirlo no era parte del alcance de la reconstrucción del frontend. Se conserva tal cual y se monta dentro de las secciones Panorama y Mi empresa (secciones/Panorama.jsx, secciones/MiEmpresa.jsx), que le pasan el periodo y la empresa seleccionados por props.

Cómo levantarlo

Requisitos: Python 3.13 y Node.js.

Backend

cd backend
python -m venv venv

Activar el entorno virtual:

# Windows (PowerShell)
.\venv\Scripts\Activate.ps1

# macOS / Linux
source venv/bin/activate

Instalar dependencias:

pip install -r requirements.txt

Preparar la capa de datos curada (una sola vez, antes de levantar la API por primera vez o cuando cambie el welcome kit en data/raw/):

python -m scripts.preparar_datos

Levantar la API:

uvicorn app.main:app --reload

La API queda en http://localhost:8000 y su documentación interactiva en http://localhost:8000/docs.

Frontend

En otra terminal:

cd frontend
npm install
npm run dev

La aplicación queda en http://localhost:5173.

Despliegue

• Backend en Render: crear el servicio como Blueprint apuntando al repo (el render.yaml está en la raíz y declara rootDir: backend). Configurar la variable de entorno CORS_ORIGINS con la URL del frontend en Vercel (por ejemplo https://coes-2026.vercel.app). Si se omite, el navegador bloquea las respuestas por CORS y el backend no deja rastro del problema en sus propios logs — el error solo aparece en la consola del navegador.
• Frontend en Vercel: Root Directory frontend/, y variable de entorno VITE_API_URL con la URL pública del backend en Render (por ejemplo https://coes-liquidaciones-api.onrender.com).

Pruebas

cd backend
pytest

Los 23 tests de test_etl_*.py requieren el welcome kit en backend/data/raw/ (no versionado). En un clon limpio, sin ese directorio, se saltan automáticamente en vez de fallar.

cd frontend
npm test      # tests de formato, variaciones y exportación

Sobre los datos

La fuente de datos ya no es un generador sintético ni un CSV: es el welcome kit de HackaCOES, la copia de trabajo del cual vive en backend/data/raw/ (no se versiona; ver .gitignore). El script python -m scripts.preparar_datos lo transforma en la capa curada de backend/data/curated/ (parquet, sí versionada), que es lo único que el backend lee en tiempo de ejecución.

El welcome kit trae datos reales hasta cierto corte y, a partir de ahí, un backcast 2025: periodos generados sintéticamente para completar el histórico. Cada periodo indica su procedencia en el campo origen, con valor real o sintetico — así queda explícito qué cifras corresponden a liquidaciones reales del mercado y cuáles son una proyección hacia atrás.

Las empresas se identifican internamente por su clave técnica (EMPRESA_00X), la única que participa en cálculos y relaciones. De cara al usuario, los 74 códigos con liquidación se muestran con razón social y RUC reales tomados del padrón del COES (backend/data/padron_empresas.csv) mediante una adjudicación determinista (scripts/identidad_empresa.py): no hay clave común entre el kit y el padrón, así que es una asignación para la presentación, no una recuperación de identidad, y las cifras bajo cada nombre son simuladas. Los 57 códigos sin liquidación conservan un alias ficticio y no aparecen en el selector. La sección "Calidad y trazabilidad" del portal lo documenta; las demás pantallas no etiquetan la procedencia (decisión D13 del spec).

Las coordenadas de las barras del mapa (data/coordenadas_barras.csv) son estimadas por nombre contra una tabla de localidades; las no reconocidas se dibujan en posición nominal y se marcan como tal. Las fichas de contacto se guardan en data/contactos.xlsx (una fila por empresa) como persistencia provisional antes de Supabase.

Equipo

Grupo 3 — HACKACOES.