ADR-0010 · Pipeline 3-tier corre en JS cliente

ADR-0010 · Pipeline 3-tier de clasificación corre en JS cliente

  • Status: ⚠️ Under review (debate abierto)
  • Fecha: 2026-05-21
  • Tags: caja · sync · debate

Contexto

El pipeline de clasificación de gastos de caja (3-tier: GastosTipificados → MovimientoDetalle+Conceptos → SIN CLASIFICAR) corre en JavaScript dentro del browser durante el sync.

Razón histórica: SheetJS parsea los 6 archivos Excel en el cliente, y el pipeline opera sobre esas estructuras antes de mandar al backend.

Evidencia del problema · bug histórico v2.0.2

El parser parseMovDetalleMap leía la columna 6 (Tipo = letra A/B/C/P/E) en vez de la columna 5 (Comprobante) para detectar comprobantes ME.

Impacto: desde el origen del módulo (~Mayo 2025) hasta v2.0.2 (Mayo 2026):

  • 2024: 1.676 MEs reales no se procesaron (de 5.208 filas).
  • 2025: 3.850 MEs reales no se procesaron (de 12.162 filas).
  • Toda la clasificación dependía 100% de GastosTipificados; el fallback Nivel 2 nunca se aplicó.

¿Por qué no se detectó? Porque no había tests automatizados sobre el pipeline. Como corre en cliente JS, es difícil cubrirlo con PHPUnit.

Decisión actual

Mantener el pipeline en cliente JS por ahora, pero plantear su migración a backend como prioridad alta del roadmap (Fase 1).

Argumentos a favor de mantener cliente

  • Parsing de Excel en cliente alivia al servidor.
  • 6 archivos × 12 meses = mucho data en RAM, mejor procesarlo local.
  • Hostinger shared no quiere procesos PHP largos.

Argumentos a favor de migrar a backend

  • ✅ Testeable — PHPUnit puede cubrir el pipeline completo.
  • ✅ Fragilidad histórica demostrada — el bug v2.0.2 estuvo años.
  • ✅ Browser de admin agotado parseando 6 Excel + ejecutando pipeline.
  • ✅ Backend más rápido — PHP 8 + index loops > JS interpretado.
  • ✅ Auditoría centralizada — caja_audit_log ya existe en backend.

Plan propuesto (Fase 1 del roadmap)

Upload Excel via SheetJS (sólo parseo bruto)
        │
        ▼
POST save_raw.php (uploads crudos a caja_raw_*)
        │
        ▼ async (cron 5 min o trigger)
PHP runs pipeline 3-tier on raw tables → caja_gastos
        │
        ▼
PHPUnit tests cubren cada nivel del pipeline

Consecuencias mientras tanto

⚠️ Cualquier bug del pipeline puede tardar años en detectarse. ⚠️ Archivos > 20 MB ya hacen lento al browser. ⚠️ El equipo debe revisar manualmente la salida después de cada sync.

Acciones pre-migración

Hasta que se migre:

  1. Validación manual del % de SIN CLASIFICAR después de cada sync (debería ser < 5%).
  2. caja_audit_log registra "GT: N | MD: N | SIN CLASIF: N" en cada batch.
  3. Re-sincronizar meses afectados por el bug v2.0.2 (ya completado).

Decisión revisada

Esperada: Q3 2026 (Fase 1 del roadmap del análisis técnico).

Cuando se migre, este ADR se marcará como Superseded by ADR-XXXX.

Referencias