§4 Módulo Caja y Bancos

4.1 🎯 Overview del módulo

Módulo más complejo desde el punto de vista de ingestión. Procesa 6 archivos Excel del ERP por mes, aplica un pipeline de clasificación 3-tier y alimenta 3 dashboards independientes (Gastos, Tesorería, Finanzas) que comparten la misma base de datos.

4.2 🧩 Los 3 submódulos del hub

Mapa funcional

                          ┌────────────────────────────┐
                          │   /reportes/caja/          │   Hub (landing)
                          │   index.php                │   cards + KPIs globales
                          └────────────┬───────────────┘
                                       │
                                       │ via header sticky con sub-tabs
            ┌──────────────────────────┼──────────────────────────┐
            │                          │                          │
            ▼                          ▼                          ▼
       /gastos/                  /tesoreria/                 /finanzas/
       index.php                 index.php                   index.php
       (Tabulator árbol)         (5 pestañas)                (3 pestañas)
            │                          │                          │
            │ api/data.php             │ api/flujo · cobros       │ api/iva · perc · cc
            │                          │     · origen · cajas     │     · proveedores
            │                          │     · alertas            │     · cruce_ventas
            │                          │                          │
            ▼                          ▼                          ▼
   ┌──────────────────────────────────────────────────────────────────┐
   │              BASE DE DATOS COMPARTIDA (Schema v2)                │
   │   caja_sincronizaciones · caja_gastos · caja_raw_*  (10 tablas)  │
   └──────────────────────────────────────────────────────────────────┘
            ▲                                                  ▲
            │                                                  │
            └────────── sync compartido (alimenta a TODOS) ────┘
                       /caja/sync.php (individual)
                       /caja/sync_bulk.php (masivo multi-mes)

4.3 ⛓️ Pipeline de clasificación 3-tier

Para cada fila de EgresosDetalle filtrada por operación de gasto (compras / gastos - caja o gastos - liquidaciones):

   ┌─────────────────────────────────────────────────────────────────┐
   │  EgresosDetalle (gasto detectado)                               │
   │  Extrae nº ME de col "Observaciones" via regex:                 │
   │    /ME\s+0*(\d+)-0*(\d+)/i  →  (serie, numero, empresa)         │
   └───────────────────────────────┬─────────────────────────────────┘
                                   │
                                   ▼
   ┌─────────────────────────────────────────────────────────────────┐
   │  NIVEL 1: GastosTipificados (PRIMARIA)                          │
   │  ¿Existe (serie, numero, empresa) en gastosMap?                 │
   │  ├── SÍ → emite 1 fila por cada línea GT del comprobante        │
   │  │       rubro_id   = GT.rubro_id                               │
   │  │       rubro      = GT.rubro                                  │
   │  │       concepto_libre = GT.concepto                           │
   │  └── NO → continúa al nivel 2 ↓                                 │
   └───────────────────────────────┬─────────────────────────────────┘
                                   │
                                   ▼
   ┌─────────────────────────────────────────────────────────────────┐
   │  NIVEL 2: MovimientoDetalle + ConceptosDeGastos (FALLBACK)      │
   │  ¿Existe (serie, numero, empresa) en movDetMap?                 │
   │  ├── SÍ → tomar mdEntry.concepto_id                             │
   │  │        ├── existe en conceptosMap → usar c.rubro_id, c.rubro │
   │  │        └── no existe → rubro = mdEntry.concepto (libre)      │
   │  └── NO → continúa al nivel 3 ↓                                 │
   └───────────────────────────────┬─────────────────────────────────┘
                                   │
                                   ▼
   ┌─────────────────────────────────────────────────────────────────┐
   │  NIVEL 3: SIN CLASIFICAR (último recurso)                       │
   │  rubro          = 'SIN CLASIFICAR'                              │
   │  concepto_libre = obs.substring(0, 200)                         │
   └─────────────────────────────────────────────────────────────────┘

Mapeo de provincia (paso paralelo)

// JavaScript en sync.php / sync_bulk.php
const cajero    = cajaMap[`${empresa}-${cajaNro}`];
const provincia = CAJERO_PROV[cajero?.toLowerCase()?.trim()] || 'OTRAS';

// CAJERO_PROV es un objeto hardcoded:
const CAJERO_PROV = {
  'lar-cajero1': 'LA RIOJA',
  'sgo-cajero2': 'SANTIAGO DEL ESTERO',
  'cat-cajero3': 'CATAMARCA',
  // …
};

🔥 Bug histórico (FIXED v2.0.2)

Métricas en log del bulk

GT: 185 | MD: 0 | SIN CLASIF: 0 | Sin ME: 37 | Otros meses: 2336 | Total: 278

• GT: clasificadas por nivel 1 (GastosTipificados)
• MD: clasificadas por nivel 2 (MovimientoDetalle + Conceptos)
• SIN CLASIF: nivel 3 (rubro = 'SIN CLASIFICAR')
• Sin ME: filas de EgresosDetalle sin nº ME extraíble
• Otros meses: filas de archivos compartidos filtradas por fecha
• Total: filas finalmente insertadas en caja_gastos

4.4 🗄️ Schema v2 detallado

Vista global de las 10 tablas

                ┌──────────────────────────────┐
                │   caja_sincronizaciones      │ control
                │   PK id · UK (mes, anio)     │
                └──────────────┬───────────────┘
                               │ 1
                               │
       ┌───────────────────────┼─────────────────────────┐
       │ N                     │ N                       │ N
       ▼                       ▼                         ▼
 ┌──────────────┐  ┌────────────────────────┐  ┌──────────────────┐
 │ caja_gastos  │  │   caja_raw_*  (6 tab.) │  │ caja_audit_log   │
 │ (derivada)   │  │   - egresos_caja       │  │ (eventos sync)   │
 │              │  │   - egresos_detalle    │  └──────────────────┘
 └──────────────┘  │   - gastos_tipificados │
                   │   - movimiento_detalle │  ┌──────────────────┐
                   │   - movimiento_resumido│  │ caja_cajeros     │
                   │   - conceptos          │  │ (denormalización)│
                   │     (catálogo persist) │  │ rebuilt post-sync│
                   └────────────────────────┘  └──────────────────┘

Helpers PHP en api/_schema.php

caja_ensure_schema(PDO $pdo)
    // Crea las 10 tablas con CREATE IF NOT EXISTS
    // Aplica ALTER TABLE defensivos en try/catch para migraciones idempotentes

caja_rebuild_cajeros(PDO $pdo)
    // Reconstruye caja_cajeros desde caja_gastos JOIN caja_raw_egresos_caja
    // Llamado al finalizar cada sync (save.php finalizar=true)

caja_audit_log(PDO $pdo, ?int $syncId, string $evento, ?string $tabla, ?int $filas, ?string $msg)
    // INSERT en caja_audit_log
    // try/catch silencioso: si falla no rompe el sync

Tipos de tablas y su rol

4.5 📤 Sync individual (sync.php · 37 KB)

Flujo

 Usuario          Browser (sync.php)              Server (api/*.php)
   │                       │                              │
   │ click "Cargar mes"    │                              │
   ├──────────────────────►│                              │
   │                       │ Dropzone 6 archivos:         │
   │ drag 6 Excel ───────►│  · EgresosCaja               │
   │                       │  · ConceptosDeGastos         │
   │                       │  · EgresosDetalle            │
   │                       │  · GastosTipificados         │
   │                       │  · MovimientoDetalle         │
   │                       │  · MovimientoResumido (opt)  │
   │                       │                              │
   │ click "Procesar"      │                              │
   ├──────────────────────►│                              │
   │                       │ SheetJS parsea los 6 (browser)│
   │                       │ → arrays JS en memoria       │
   │                       │                              │
   │                       │ POST api/init.php            │
   │                       │ {mes, anio}                  │
   │                       ├─────────────────────────────►│
   │                       │                              │ caja_ensure_schema()
   │                       │                              │ INSERT caja_sincronizaciones
   │                       │                              │ → sync_id
   │                       │◄─────────────────────────────┤
   │                       │                              │
   │                       │ ╔════ POST save_raw.php × 6 ════╗
   │                       │ ║ {tabla, sync_id, rows: 300}   ║
   │                       │ ║ INSERT a la tabla raw         ║
   │                       │ ║                               ║
   │                       │ ║ Pipeline 3-tier en cliente:   ║
   │                       │ ║   1. Detectar gastos          ║
   │                       │ ║   2. Match GT por (s,n,e)    ║
   │                       │ ║   3. Fallback MD+Conceptos    ║
   │                       │ ║   4. SIN CLASIFICAR           ║
   │                       │ ╚═══════════════════════════════╝
   │                       │                              │
   │                       │ POST save.php × N (caja_gastos)│
   │                       │ {sync_id, rows: 300}         │
   │                       ├─────────────────────────────►│
   │                       │                              │
   │                       │ POST save.php {finalizar:1}  │
   │                       ├─────────────────────────────►│
   │                       │                              │ caja_rebuild_cajeros()
   │                       │                              │ caja_audit_log()
   │                       │◄─────────────────────────────┤ UPDATE estado='completado'
   │                       │                              │
   │ ✅ "Sync OK"          │                              │
   │◄──────────────────────┤                              │

4.6 📦 Sync bulk multi-mes (sync_bulk.php · 57 KB)

UI más sofisticada: detecta automáticamente los meses contenidos en cada Excel y los procesa secuencialmente.

Algoritmo

1. Usuario sube 1 archivo por tipo (cada uno puede contener varios meses).
2. SheetJS parsea todos.
3. JS escanea las fechas y detecta los meses únicos.
4. Genera una "cola" de meses a procesar.
5. Por cada mes: filtra las filas de cada Excel que pertenecen a ese mes, ejecuta el pipeline 3-tier, persiste con un sync_id dedicado.
6. Al final: cada mes queda self-contained en la BD (eliminar uno no afecta los demás).

Variables globales del JS del bulk

// Estado global (antes era const local → bug v2.0.1)
let cajaRowsGlobal = null;        // EgresosCaja parseado
let detalleRowsGlobal = null;     // EgresosDetalle
let tipificadosRowsGlobal = null;
let movDetalleRowsGlobal = null;
let movResumidoRowsGlobal = null;
let conceptosRowsGlobal = null;
let conceptosMap = {};            // Map para nivel 2
let CAJERO_PROV = { ... };        // ⚠️ Duplicado con sync.php

4.7 🏦 Submódulo Tesorería (5 pestañas)

KPIs ejecutivos (siempre visibles)

Pestaña 1 · 💰 Flujo de Caja

Endpoint: api/flujo.php?anio=N

• Bar chart Ingresos (verde) vs Egresos (rojo) por mes + línea Flujo Neto.
• Stacked bar Saldo Final = Efectivo + Cheques de terceros, por mes.
• Tabla detallada Categorías × Meses con secciones ➕ INGRESOS y ➖ EGRESOS.

Pestaña 2 · 💳 Cobros & Pagos

Endpoint: api/cobros.php?anio=N

• Donut Cobros por forma (Efectivo / Cheques / Transferencias / Venta cheques).
• Stacked bar Contado vs Cta Cte por mes.
• Donut Pagos por forma (vista anual).
• Tabla Top 20 cuentas acreedoras con forma de pago dominante (sub-query).

Pestaña 3 · 🎯 Origen de Cobros

Endpoint: api/origen.php?anio=N

• Donut distribución anual por origen con % en leyenda.
• Stacked bar estado de pago (PAGADO / PENDIENTE / PARCIAL).
• Tabla Top 25 cuentas que más cobran.

Pestaña 4 · 🏦 Cajas & Cheques (Mayo 2026)

Endpoint: api/cajas.php?anio=N

• Bar + línea: promedio mensual y máximo de cheques en cartera.
• Línea apilada 90 días: saldo diario consolidado (efectivo + cheques).
• Tabla Top 30 cajeros con eficiencia (neto coloreado).
• Tabla saldo por caja física.

Pestaña 5 · ⚠️ Alertas (Mayo 2026)

Endpoint: api/alertas.php?anio=N

• Anticipos: entregados vs rendidos vs pendiente acumulado.
• Runway defensivo (sin ingresos) vs estresado (-70% ingresos).
• Anulados por mes (cantidad + monto).
• Diferencia de cotización (exposición USD).

Niveles de alerta del runway

4.8 📊 Submódulo Finanzas (3 pestañas)

Pestaña 1 · 📑 Impuestos

Endpoints: api/iva.php · api/percepciones.php

• IVA Crédito: viene de caja_raw_movimiento_resumido. Discrimina por tasa (21%, 27%, 10.5%, otras).
• IVA Débito: aproximado como subtotalNeto × 0.21 desde tabla ventas.
• Saldo = Débito − Crédito. Positivo = a pagar, negativo = a favor.
• Percepciones: per_ibrutos + per_3337 + per_5329 + perc_munic desde caja_raw_gastos_tipificados.

Pestaña 2 · 🏢 Costos & Proveedores

Endpoints: api/centros_costo.php · api/proveedores.php

• Centros de Costo: bar horizontal Top 10 + stacked Top 6 × meses.
• Top Proveedores: total facturado, neto gravado, comprobantes, última compra, plazo promedio, forma de pago dominante.
• Métricas de concentración: top10_pct, top20_pct.

Pestaña 3 · 📊 Rentabilidad

Endpoint: api/cruce_ventas.php?anio=N

Ventas netas     = SUM(subtotalNeto) FROM ventas
Ventas reales    = SUM(subtotalNeto WHERE dsArticulo IS NOT NULL)
Costo mercadería = SUM(preciocomprant * cantidadesTotal)
Peso (ton)       = SUM(cantidadesTotal * peso) / 1000

Margen bruto     = Ventas reales − Costo mercadería
Margen limpio    = Margen bruto − Gastos de Caja totales
% Margen limpio  = Margen limpio / Ventas reales

Costo logístico  = SUM(monto WHERE rubro LIKE %COMBUSTIBLE/FLETE/TRANSPORTE/...)
Costo admin      = SUM(monto WHERE rubro LIKE %SUELDO/SERVICIO/ALQUILER/...)

$/Tonelada       = Costo logístico / Peso (ton)
Admin/Venta      = Costo admin / Ventas netas  (%)

Heurísticas de clasificación de rubros

$rubrosLogisticos = ['COMBUSTIBLE','FLETE','TRANSPORTE','LUBRICANTE','PEAJE','GOMERIA','REPUESTO'];
$rubrosAdmin      = ['SALARIO','SUELDO','HONORARIO','SERVICIO','TELEFONIA','INTERNET','ALQUILER','SEGURO','BANCO','IMPUESTO'];

// Se hace UPPER(rubro) LIKE '%KEY%' por cada palabra

4.9 💸 Submódulo Gastos (el dashboard original)

Endpoint: api/data.php?anio=N&mes=M&prov=P&rubro=R

Dashboard

• Tabulator dataTree: árbol RUBRO ▸ CONCEPTO con expansión y suma.
• Chart.js: bar chart por mes con stacked rubros.
• Filtros: año, mes (botonera), provincia (LA RIOJA / SGO / CAT / OTRAS), rubro.
• KPI: gasto total, # comprobantes, # cajeros activos, promedio diario.

Queries clave

-- Agregado RUBRO × CONCEPTO × MES (Mayo 2024 - Diciembre 2025 actual)
SELECT
  rubro,
  concepto_libre AS concepto,
  mes,
  SUM(monto) AS monto,
  COUNT(*) AS lineas
FROM caja_gastos
WHERE anio = ?
  AND ($mes = 0 OR mes = $mes)
  AND ($prov = '' OR provincia = $prov)
GROUP BY rubro, concepto, mes
ORDER BY rubro, concepto, mes;

4.10 🐛 Bugs históricos resueltos (changelog)

4.11 ⚠️ Hallazgos específicos del módulo

4.12 🚀 Propuestas específicas del módulo

P-CAJ-1 · Tabla DB para CAJERO_PROV

CREATE TABLE caja_cajero_provincia (
  cajero       VARCHAR(100) PRIMARY KEY,
  provincia    VARCHAR(50)  NOT NULL,
  activo       TINYINT(1)   DEFAULT 1,
  notas        TEXT,
  creado_at    TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
  updated_at   TIMESTAMP DEFAULT CURRENT_TIMESTAMP ON UPDATE CURRENT_TIMESTAMP
);
-- UI admin: /reportes/caja/admin/cajero_provincia.php
-- Pipeline lee de DB en vez de JS hardcoded

P-CAJ-2 · Mover pipeline 3-tier al backend

Actualmente el pipeline corre en JS (frontend). Esto:

• Fragilidad: el bug histórico de col 5 vs 6 estuvo años sin detectarse.
• Difícil testear unitariamente.
• Pesa el browser (parsear 6 Excel grandes consume RAM).

Propuesta: upload de archivos crudos → save_raw.php los persiste tal cual → cron job nocturno reconstruye caja_gastos en PHP con tests unitarios. Esfuerzo: 1 semana.

P-CAJ-3 · Tabla DB para reglas de clasificación de rubros

CREATE TABLE caja_rubro_categoria (
  id         INT PK AI,
  pattern    VARCHAR(100) NOT NULL,   -- ej: "%COMBUSTIBLE%"
  categoria  ENUM('logistico','administrativo','operativo','otro'),
  prioridad  TINYINT DEFAULT 0,
  activo     TINYINT(1) DEFAULT 1
);
-- Reemplaza los arrays hardcoded en cruce_ventas.php
-- UI admin para editar sin tocar código

P-CAJ-4 · FK CASCADE para reset_db.php más simple

ALTER TABLE caja_gastos                  ADD FOREIGN KEY (sync_id) REFERENCES caja_sincronizaciones(id) ON DELETE CASCADE;
ALTER TABLE caja_raw_egresos_caja        ADD FOREIGN KEY (sync_id) REFERENCES caja_sincronizaciones(id) ON DELETE CASCADE;
-- ... etc para las 6 raw

-- Luego reset_db.php delete_period queda en 1 línea:
DELETE FROM caja_sincronizaciones WHERE id = ?;
-- (las raw + gastos se borran solas)

P-CAJ-5 · IVA débito discriminado por tasa

Hoy: débito = ventas * 0.21 (genérico).

Propuesta: usar tipoIvaArticulo de la tabla ventas (existe pero no se usa) para discriminar tasas. Si no existe, crearla.

P-CAJ-6 · Alertas proactivas en sync

• Al finalizar sync, verificar que el % de SIN CLASIFICAR < 5%. Si no, mostrar warning en UI.
• Verificar que cajeros nuevos sin provincia matched > 0 → email + UI badge.
• Verificar que SUM(monto) del mes está en rango ±50% del promedio histórico — alerta de anomalía.

P-CAJ-7 · Eliminar dashboard.jsx

30 segundos. Backup si querés (dashboard.jsx.bak.2026-05-21) y eliminarlo del doc root.

P-CAJ-8 · Vista materializada para Tesorería

Los KPIs ejecutivos se recalculan en cada hit a /tesoreria/. Con cron diario:

CREATE TABLE caja_tesoreria_mensual_mv (
  anio        SMALLINT,
  mes         TINYINT,
  ingresos    DECIMAL(15,2),
  egresos     DECIMAL(15,2),
  saldo_final DECIMAL(15,2),
  dias_caja   INT,
  updated_at  TIMESTAMP,
  PRIMARY KEY (anio, mes)
);

-- Refresh cron diario 03:30:
INSERT INTO caja_tesoreria_mensual_mv ...
ON DUPLICATE KEY UPDATE ...;