Documentación del Motor PEPS

Dos páginas principales

• Clasificador — Pipeline parcial: importa el extracto, clasifica movimientos, asigna tipo de cambio y separa por moneda. No ejecuta la valuación FIFO.
• Motor PEPS — Pipeline completo: incluye todo lo del Clasificador más la consolidación de lotes, validaciones y la valuación FIFO con cálculo de resultados.

Arquitectura

Los archivos se suben via FormData desde el cliente. El flujo es:

Cliente (FormData)
  → API Routes (app/api/*)        — Validación, manejo de errores HTTP
    → Server Actions (app/actions/*) — Lógica de negocio ("use server")
      → Engine Functions (lib/activos/) — Funciones puras de procesamiento

El frontend nunca llama directamente a las server actions; siempre pasa por las API routes.

Paso 1 — parseBalanz()

Lee el archivo xlsx de Balanz. Busca la fila de encabezado escaneando hasta encontrar la celda que contiene IMPORTE. A partir de ahí extrae las siguientes columnas:

Adicionalmente extrae el número de boleto del texto de la descripción y determina la fuente (ARGENTINA o EXTRANJERA) según el tipo de instrumento.

Paso 2 — clasificarBalanz()

Aplica 21+ reglas secuenciales basadas en palabras clave del campo "Detalle" (descripción). La última regla que matchea gana (no la primera). Las reglas son:

Post-procesamiento: los movimientos cuyo ticker sea "Dólares ROFEX" se reclasifican como tipo Futuros. Los movimientos de Futuros con clasificación FICOMPRA o FIVENTA se reclasifican como GASTOS.

Paso 3 — parseTipoCambio()

Lee el archivo xlsx de tipo de cambio. Extrae las columnas:

• Codigo Moneda — Identificador de la moneda
• Fecha — Fecha de cotización
• Compra — Tipo de cambio comprador
• Venta — Tipo de cambio vendedor

Filtra filas de encabezado duplicadas o vacías.

Paso 4 — lookupTC()

Para cada movimiento, busca el tipo de cambio por fecha y moneda. Si no encuentra la fecha exacta, retrocede al día hábil anterior más cercano. Los movimientos en pesos siempre tienen TC = 1. Asigna tanto tcc (tipo cambio compra) como tcv (tipo cambio venta).

Paso 5 — Cálculo de montoPesos

montoPesos = monto × tcc

Convierte el importe original a pesos argentinos usando el tipo de cambio comprador.

Paso 6 — splitPorMoneda()

Separa los movimientos en 4 arrays según la moneda:

Para cada array calcula el saldo corrido (running balance) acumulando los importes en orden cronológico.

Tab RESUMEN — Configuración global

Antes de procesar, el usuario configura los parámetros globales del período: Banco, Período, Moneda, CUIT, Razón Social y Nro. Cuenta. Después de procesar, este tab muestra un resumen global de transacciones por clasificación.

Tab TRANSFERENCIA_ACTIVOS (G-1) — Transferencias entre cuentas

Tabla editable para registrar transferencias de títulos entre cuentas propias o de terceros. Campos: Nombre, Código, Tipo Activo, Fecha, Cantidad, Monto, TC, Es Repago.

El motor cruza las transferencias con DETALLE_MOV por código + fecha + cantidad para asignar montos y TC cuando la operación original solo muestra cantidades sin precio. Actualmente solo se muestra la tabla editable — el procesamiento automático de transferencias se implementará en una versión futura.

Paso 7 — buildTotal()

Consolida los movimientos relevantes para la valuación. Solo incluye las clasificaciones que afectan el stock de activos:

• COMPRA
• VENTA
• AMORTIZACION
• TRANSF. EXTERNA
• CAMBIO RATIO
• DIVIDENDOS EN ESPECIE
• ACTIVOS_INICIO (cargados como SALDO INICIAL)

Ordena por:

1. código ASC (alfabético)
2. fecha ASC (cronológico)
3. Compras antes que ventas en la misma fecha

Asigna un Nro.Ref secuencial por cada código de activo único.

Paso 8 — Validaciones

Ejecuta validaciones sobre los movimientos consolidados:

• Código faltante — COMPRA o VENTA sin código de activo asignado
• Cantidad cero — COMPRA o VENTA con cantidad = 0

Genera un array de errores que se muestra al usuario antes de continuar.

Paso 9 — valuarFIFO() — EL NÚCLEO

Esta es la función central del sistema. Para cada activo (agrupado por Nro.Ref) ejecuta el motor FIFO bidireccional.

Paso 10 — Enriquecimiento del RESULTADO (G-3)

Para cada código de activo, suma desde DETALLE_MOVIMIENTOS los conceptos complementarios:

La fórmula aplicada para cada concepto es: montoPesos = monto × tcc, acumulado por código.

Archivo Balanz (.xlsx)

Extracto de cuenta exportado desde la plataforma de Balanz. El sistema busca automáticamente la fila de encabezado.

Archivo Tipo de Cambio (.xlsx)

Archivo con cotizaciones históricas de monedas extranjeras.

Activos Inicio (carga manual)

Posición de activos al inicio del período fiscal, ingresada manualmente por el usuario. Se incorporan al pipeline como SALDO INICIAL.

Operaciones de entrada

Compra 1:  100 AAPL a USD 150  (01/03, TC = 900)
Compra 2:   50 AAPL a USD 160  (15/05, TC = 950)
Venta:     120 AAPL a USD 180  (01/09, TC = 1.000)

Estado de buyLayers antes de la venta

Ejecución FIFO de la Venta (120 unidades)

take        = 100 (se agota el lote completo)
compraPesos = 100 × 150 × 900   = 13.500.000
ventaPesos  = 100 × 180 × 1.000 = 18.000.000
resultado   = 18.000.000 - 13.500.000 = +4.500.000

take        = 20 (consumo parcial del lote)
compraPesos = 20 × 160 × 950   = 3.040.000
ventaPesos  = 20 × 180 × 1.000 = 3.600.000
resultado   = 3.600.000 - 3.040.000 = +560.000

Stock Final

Resultado Total

Resultado Compra 1 → Venta:  +4.500.000
Resultado Compra 2 → Venta:    +560.000
                              ──────────
Resultado Total AAPL:        +5.060.000

El resultado total de +5.060.000 ARS representa la ganancia gravada por la enajenación de 120 Cedears de AAPL, calculada respetando el orden FIFO de adquisición y convirtiendo tanto el costo de compra como el ingreso de venta al tipo de cambio vigente en cada momento.