D1 🔄 Sync mensual de ventas (lote × lote)
Hostinger mata HTTP largas a los ~4 minutos → AJAX lote × lote orquestado desde el browser.
Usuario Browser (sync_api.php) Server (sync_api_process.php) ChessERP
│ │ │ │
│ click "Sync" │ │ │
├──────────────────────►│ │ │
│ │ POST action=init │ │
│ │ {mes, anio} │ │
│ ├─────────────────────────────►│ │
│ │ │ DELETE sync previo │
│ │ │ INSERT sincronizaciones │
│ │ │ estado='procesando' │
│ │◄─────────────────────────────┤ {ok, sync_id} │
│ │ │ │
│ │ ╔═══════ LOOP lote=1..N ═════╗ │
│ │ ║ ║ │
│ │ ║ POST action=lote ║ │
│ │ ║ {sync_id, lote, mes, anio} ║ │
│ │ ║───────────────────────────►║ │
│ │ ║ ║ login() (1er lote) │
│ │ ║ ║──────────────────────────────►│
│ │ ║ ║◄─── sessionId ───────────────┤
│ │ ║ ║ GET /ventas?nroLote=N │
│ │ ║ ║──────────────────────────────►│
│ │ ║ ║◄─── rows[] (200-2000) ───────┤
│ │ ║ ║ INSERT ventas (prepared) │
│ │ ║◄───────────────────────────║ {ok, filas, finalizado} │
│ │ ║ ║ │
│ │ ║ progress bar update ║ │
│ │ ║ si finalizado==false → ║ │
│ │ ║ lote++ y repite ║ │
│ │ ╚════════════════════════════╝ │
│ │ │ │
│ │ POST action=finalizar │ │
│ ├─────────────────────────────►│ │
│ │ │ UPDATE estado='completado' │
│ │ │ fecha_fin=NOW() │
│ │◄─────────────────────────────┤ {ok} │
│ ✅ "Mes cargado" │ │ │
│◄──────────────────────┤ │ │
Tiempo típico: 25-40 segundos para ~20K filas (3-8 lotes).
D2 ⛓️ Pipeline 3-tier de clasificación (caja gastos)
┌─────────────────────────────────────────────────────────────────┐
│ ENTRADA: 6 archivos Excel del ERP │
│ ──────────────────────────────────────── │
│ 1. EgresosCaja.xlsx │
│ 2. ConceptosDeGastos.xlsx (catálogo persistente) │
│ 3. EgresosDetalle.xlsx ← FUENTE de los gastos │
│ 4. GastosTipificados.xlsx ← Nivel 1 PRIMARIA │
│ 5. MovimientoDetalle.xlsx ← Nivel 2 FALLBACK │
│ 6. MovimientoResumido.xlsx (opcional, para IVA) │
└────────────────────────────────────┬────────────────────────────┘
│
│ SheetJS parsea cliente
│ Filtro por operación:
│ 'compras / gastos - caja' ó
│ 'gastos - liquidaciones'
▼
┌─────────────────────────────────────────────────────────────────┐
│ Por cada fila de EgresosDetalle filtrada: │
│ ┌─────────────────────────────────────────────────┐ │
│ │ Extrae nº ME de col "Observaciones" via regex: │ │
│ │ /ME\s+0*(\d+)-0*(\d+)/i │ │
│ │ → (serie, numero, empresa) │ │
│ └────────────────────┬─────────────────────────────┘ │
└────────────────────────┼────────────────────────────────────────┘
▼
┌────────────────────────┐
│ ¿Match en gastosMap? │
│ key = (s, n, e) │
└───────┬─────────┬──────┘
SI NO
│ │
▼ ▼
┌──────────────────────┐ ┌──────────────────────┐
│ NIVEL 1: GT │ │ ¿Match en movDetMap?│
│ rubro_id = GT.rubro │ │ key = (s, n, e) │
│ concepto = GT.conc │ └────┬──────────┬──────┘
└──────────┬───────────┘ SI NO
│ │ │
│ ▼ ▼
│ ┌──────────────────────┐ ┌──────────────────────────┐
│ │ NIVEL 2: MD + Conc │ │ NIVEL 3: SIN CLASIFICAR │
│ │ MD → concepto_id │ │ rubro = 'SIN CLASIFICAR' │
│ │ Conc[id] → rubro │ │ concepto_libre = obs[:200]│
│ └──────────┬───────────┘ └──────────────┬────────────┘
│ │ │
└────────────────┴──────────────┬───────────────┘
▼
┌─────────────────────────────────────────────────────────────────┐
│ Mapeo de provincia │
│ cajero = cajaMap[`${empresa}-${cajaNro}`] │
│ provincia = CAJERO_PROV[cajero.toLowerCase().trim()] || 'OTRAS'│
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ INSERT caja_gastos (sync_id, mes, anio, provincia, │
│ rubro_id, rubro, concepto_id, │
│ concepto_libre, tipo_comprobante, │
│ serie, numero, empresa, caja_nro, │
│ cajero, fecha, monto) │
└─────────────────────────────────────────────────────────────────┘
Bug histórico fix v2.0.2: el parser leía col 6 (Tipo) en vez de col 5 (Comprobante). Ver §10 hallazgo CAJ-bug-1.
D3 📦 Sync bulk multi-mes (caja)
Usuario sube N archivos (cada uno con M meses)
────────────────────────────────────────────────
│
▼
┌────────────────────────────────────────────────────────────┐
│ SheetJS parsea TODOS los archivos │
│ → cajaRowsGlobal, detalleRowsGlobal, tipificadosRowsGlobal│
│ movDetalleRowsGlobal, movResumidoRowsGlobal, │
│ conceptosRowsGlobal │
└────────────────────────────┬───────────────────────────────┘
│
▼
┌────────────────────────────────────────────────────────────┐
│ JS escanea fechas → detecta meses únicos │
│ meses = [{mes:1, anio:2025}, {mes:2, anio:2025}, ...] │
└────────────────────────────┬───────────────────────────────┘
│
▼
╔═════════════════════════════════════╗
║ Para cada mes en la cola: ║
║ ║
║ 1. POST init.php → sync_id ║
║ ║
║ 2. Filtra cada Excel por fecha ║
║ que coincida con (mes, anio) ║
║ ║
║ 3. Ejecuta pipeline 3-tier ║
║ sobre las filas filtradas ║
║ ║
║ 4. POST save_raw.php × 5-6 tablas ║
║ (linkeadas a este sync_id) ║
║ ║
║ 5. POST save.php × N (caja_gastos) ║
║ ║
║ 6. POST save.php {finalizar:true} ║
║ → caja_rebuild_cajeros() ║
║ → caja_audit_log() ║
║ ║
╚═════════════════════════════════════╝
│
▼
✅ Todos los meses
self-contained en BD
Antes de v2.0.1: los archivos compartidos quedaban con el sync_id del primer mes. Eliminar ese mes borraba la raw histórica de todos los demás.
D4 💸 Cashflow data.php (composición del JSON)
GET /reportes/cashflow/api/data.php?corte=2026-05-20[&sucursal=...]
│
▼
┌──────────────────────────────────────────────────────────────────┐
│ 1) Validar corte (regex YYYY-MM-DD) o usar MAX(fecha_corte) │
│ 2) cashflow_ensure_schema() │
│ 3) Listar sucursales disponibles (para selector) │
└────────────────┬─────────────────────────────────────────────────┘
│
┌────────────────┼────────────────────────────────────────────┐
│ Bloque ▼ │
│ CLIENTES cartera_clientes │
│ │
│ ├─ KPI: COUNT, SUM(saldo_total), SUM(d7/d15/d30/d60) │
│ ├─ Aging: 8 tramos del antiguedad_dias │
│ ├─ Top 50 deudores │
│ ├─ Por vendedor │
│ └─ Por provincia │
└────────────────┬────────────────────────────────────────────┘
│
┌────────────────┼────────────────────────────────────────────┐
│ Bloque ▼ │
│ PROVEEDORES cartera_proveedores │
│ │
│ ├─ KPI: a_pagar, vencido, anticipos │
│ ├─ Aging por dias_atraso │
│ ├─ Top proveedores │
│ ├─ Pagos futuros (próximos vencimientos) │
│ └─ Vencidos (ya vencidos) │
└────────────────┬────────────────────────────────────────────┘
│
┌────────────────┼────────────────────────────────────────────┐
│ Bloque ▼ │
│ CHEQUES cheques_cartera │
│ │
│ ├─ KPI: n_cartera, monto_cartera, monto_vencidos, │
│ │ monto_endosados, monto_rechazados │
│ ├─ Lista completa con dias_a_presentar │
│ ├─ Por banco │
│ └─ Por cliente emisor │
└────────────────┬────────────────────────────────────────────┘
│
┌────────────────┼────────────────────────────────────────────┐
│ Bloque ▼ │
│ CRUCE COMERCIAL │
│ │
│ Para cada cliente con saldo > 0: │
│ ├─ GROUP BY idCliente en ventas (últimos 6 syncs) │
│ ├─ Calcula: venta_6m, ultima_compra, dias_sin_comprar │
│ ├─ Calcula: ndcons_n, ndcons_monto │
│ └─ Clasifica: critico/fantasma/riesgo/sano │
└────────────────┬────────────────────────────────────────────┘
│
┌────────────────┼────────────────────────────────────────────┐
│ Bloque ▼ │
│ SALDO CAJA HOY │
│ │
│ SELECT total_saldo_final FROM caja_raw_egresos_caja │
│ ORDER BY fecha_caja DESC LIMIT 1 │
└────────────────┬────────────────────────────────────────────┘
│
┌────────────────┼────────────────────────────────────────────┐
│ Bloque ▼ │
│ CALENDARIO SEMANAL (4 semanas) │
│ │
│ Por cada semana w en [0..3]: │
│ ├─ cobranzas = heurística sobre aging │
│ ├─ cheques = SUM(importe) cuyo fecha_pres ∈ semana │
│ ├─ pagos = SUM(saldo) cuyo fecha_vto ∈ semana │
│ └─ neto = cobranzas + cheques - pagos │
└────────────────┬────────────────────────────────────────────┘
│
▼
{ ok, corte, clientes, proveedores, cheques,
calendario, saldo_caja_hoy, alertas, ... }
D5 🔗 Cross-module bootstrap del schema
Cualquier endpoint del módulo VENTA
────────────────────────────────────
│
▼
┌──────────────────────────────────────────────┐
│ require_once 'includes/db_reportes.php' │
└─────────────────────┬────────────────────────┘
│
▼ (al primer require, sólo una vez por proceso)
┌─────────────────────────────────────────────────────────┐
│ db_reportes.php carga al inicio: │
│ require_once '../../articulos/api/_schema.php' │
└─────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Cuando llamás getApiDB() por primera vez: │
│ │
│ 1. Crear PDO singleton │
│ 2. Llamar articulos_ensure_schema($pdo) │
│ ├─ CREATE TABLE IF NOT EXISTS articulos_raw │
│ ├─ CREATE TABLE IF NOT EXISTS articulos_raw_prov… │
│ ├─ CREATE TABLE IF NOT EXISTS … (5 tablas) │
│ └─ ALTER TABLE defensivos en try/catch │
│ │
│ 3. Return PDO │
└─────────────────────┬───────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────┐
│ Queries de venta hacen JOIN seguro con articulos_raw │
│ (la tabla siempre existe, aunque esté vacía) │
│ │
│ Si está vacía → IFNULL hace fallback a pesoTotal │
│ Si está cargada → usa cat_peso × cantidadesTotal │
└─────────────────────────────────────────────────────────┘
Beneficio: nunca falla con "Table 'articulos_raw' doesn't exist" aunque el módulo Artículos no se haya inicializado.
D6 🎯 Cross-filter (drill-down) — request lifecycle
Usuario en dashboard.php click en una fila de la tabla "Supervisores"
────────────────────────────────────────────────────────────────────
│
▼
┌──────────────────────────────────────────────────────────┐
│ JS captura el click + lee dataset del row: │
│ tipo = 'supervisor' │
│ valor = 'LAR | ANDREA SANCHEZ (SUPERVISOR)' │
│ id = sync_id actual │
│ sucursal = filtro actual │
└─────────────────────┬────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ fetch('/reportes/venta/api/filter.php? │
│ id=28&tipo=supervisor&valor=...&sucursal=...') │
└─────────────────────┬────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ api/filter.php │
│ ──────────────── │
│ 1. Validar: │
│ · id INT > 0 │
│ · tipo ∈ whitelist │
│ · valor != '' │
│ 2. Verificar sync existe y estado='completado' │
│ 3. switch(tipo): │
│ case 'supervisor': │
│ query principal (KPIs filtrados) │
│ query 2: top 15 proveedores │
│ case 'deposito': … │
│ case 'provincia': … │
│ case 'vendedor': … │
│ 4. Devolver JSON │
└─────────────────────┬────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────┐
│ JS recibe el JSON y abre modal con: │
│ · 6 KPI cards filtrados │
│ · tabla top 15 proveedores │
│ · breadcrumb "Volver" → cierra modal │
└──────────────────────────────────────────────────────────┘
D7 🗺️ Mapa de dependencias completo
┌───────────────────────────┐
│ u120688891_chess (BD) │
│ 33 tablas · ~915K filas │
└────────────┬──────────────┘
│
┌──────────────┬────────────┬──┴───────┬────────────┬───────────────┐
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
┌────────┐ ┌────────┐ ┌────────┐ ┌──────────┐ ┌────────┐ ┌──────────┐
│ VENTA │ │ CAJA │ │CASHFLOW│ │ARTICULOS │ │ LISTAS │ │ /hub/ │
│ v2.4.0 │ │ v2.0.2 │ │ v1.1.0 │ │ (no v) │ │ (no v) │ │ /reportes│
└───┬────┘ └───┬────┘ └───┬────┘ └────┬─────┘ └────┬───┘ └─────┬────┘
│ │ │ │ │ │
│ ┌─────────┘ │ │ │ │
│ │ │ │ │ │
│ │ ┌──────────────────┘ │ │ │
│ │ │ │ │ │
▼ ▼ ▼ ▼ ▼ ▼
┌─────────────────┐ ┌────────────────────┐
│ JOINS Y LECTURAS CRUZADAS │ │ SYNC DELEGADO │
│ ───────────────────────── │ │ ────────────────── │
│ • venta → articulos_raw │ │ listas/sync.php │
│ (peso fallback) │ │ → /catalogo/admin │
│ │ │ /api_sync.php │
│ • caja/finanzas → ventas │ │ (fuera de reportes)│
│ (cruce rentabilidad) │ └────────────────────┘
│ │
│ • cashflow → ventas │
│ (cruce comercial 6m) │
│ │
│ • cashflow → caja_raw_ │
│ egresos_caja (saldo) │
│ │
│ • /hub → ventas + caja + │
│ articulos_raw (stats) │
└───────────────────────────┘
APIs externas
─────────────
│
│ HTTPS
▼
┌──────────────────────────────┐
│ ChessERP │
│ /AR1185/web/api/chess/v1 │
│ • /auth/login │
│ • /ventas?fechaDesde=… │
└──────────────────────────────┘
D8 🎨 Theme switching (anti-flash)
Usuario navega a /reportes/venta/dashboard.php
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ <head> │
│ ★ PRIMERA línea del head (anti-flash): │
│ <script> │
│ (function(){ │
│ var t = localStorage.getItem('za-theme') || 'dark'; │
│ document.documentElement.setAttribute('data-theme', t); │
│ })(); │
│ </script> │
│ │
│ <link rel="stylesheet" href="style.css"> │
│ ↑ Variables CSS leen :root o [data-theme='dark'] │
└─────────────────────────┬────────────────────────────────────────┘
│
│ ★ NO HAY FLASH: el atributo se setea
│ antes de que el CSS pinte
▼
┌─────────────────────────────────────────────────────────────────┐
│ <body> renderiza con tema correcto desde el primer pixel │
│ │
│ Toggle button: │
│ click → cur = dark ? 'light' : 'dark' │
│ localStorage.setItem('za-theme', cur) │
│ html.dataset.theme = cur │
│ (transición CSS de 0.35s) │
└─────────────────────────────────────────────────────────────────┘
Clave za-theme compartida por todos los módulos del sitio.
D9 ⚡ Lifecycle de una request al dashboard
GET /reportes/venta/dashboard.php?sync=28&sucursal=ZONAS+ARIDAS
│
▼
┌───────────────────────────────────────────────────────────────┐
│ 1. PHP carga incluyes: │
│ require config/database.php → constantes DB + API │
│ require includes/db_reportes.php │
│ └─► require articulos/api/_schema.php │
│ require includes/data_api.php │
│ require includes/functions.php │
└─────────────────────┬─────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ 2. Validar params: │
│ $syncId = (int)$_GET['sync'] │
│ $sucursal = trim($_GET['sucursal']) │
│ Validar sync existe + estado='completado' │
└─────────────────────┬─────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ 3. loadDashboardDataFromApi($syncId, $sucursal) │
│ Devuelve bundle con ~18 keys: │
│ kpis, diarias, supervisores, provincias, │
│ prov_sup, prov_dep, rankings, empresas, │
│ localidades, devoluciones, anulados, evolucion_12m, │
│ margen_vend, margen_sup, margen_dep, │
│ margen_cli, margen_art, margen_prov, │
│ merc_sc, abc, clientes_comp, sin_articulo │
│ │
│ ★ ~20 queries SQL ejecutadas secuencialmente │
│ Tiempo típico: 800ms - 2s según mes/sucursal │
└─────────────────────┬─────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ 4. Renderiza HTML inline: │
│ · Header sticky + filtros │
│ · Resumen Ejecutivo │
│ · Las 14 secciones con datos pre-renderizados │
│ · Inyecta datos JSON en variables JS: │
│ const RENT_VEND_DATA = <?= json_encode(...) ?> │
│ const RENT_SUP_DATA = <?= json_encode(...) ?> │
│ ... etc │
└─────────────────────┬─────────────────────────────────────────┘
│
▼
┌───────────────────────────────────────────────────────────────┐
│ 5. Browser ejecuta JS: │
│ · Crea instancias Tabulator (6 tabs Rentabilidad) │
│ · Crea instancias Chart.js (ventas diarias, evolución 12m) │
│ · Setup event listeners (openTab, fullscreen, filter) │
│ │
│ Drill-downs son requests AJAX adicionales a filter.php │
└───────────────────────────────────────────────────────────────┘
D10 📊 Tabulator render lifecycle (con tabs)
El usuario llega al dashboard con tab "Por Vendedor" activo
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Cada tab inicializa su Tabulator AL CARGAR la página: │
│ │
│ tabRentVend = new Tabulator("#tabulator-rent-vend", { │
│ data: RENT_VEND_DATA, │
│ columns: [...], │
│ rowFormatter: makeRentRowFormatter(...) │
│ }); │
│ │
│ ★ Tabulator NO mide bien containers con display:none │
│ → Los tabs no activos renderean con dimensiones erróneas │
└─────────────────────┬────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Usuario hace click en otro tab (ej. "Por Cliente"): │
│ │
│ openTab(event, 'rent-tab-cli') { │
│ 1. Quitar .active a todos los .tab-content │
│ 2. Quitar .active a todos los .tab-btn │
│ 3. Agregar .active al nuevo tab-content (display:block) │
│ 4. setTimeout(()=> { │
│ tabRentCli.redraw(true) // ★ recalcula dimensiones │
│ }, 50); │
│ } │
└─────────────────────┬────────────────────────────────────────┘
│
▼
┌──────────────────────────────────────────────────────────────┐
│ Cada vez que se entra a un tab por primera vez: │
│ · Tabulator recalcula widths/heights con el container │
│ ya visible │
│ · Renderiza virtual scroll (sólo filas visibles) │
│ · bottomCalc se ejecuta con todos los datos │
│ · rowFormatter aplica .rent-row-top / .rent-row-bot │
└──────────────────────────────────────────────────────────────┘
El setTimeout(50ms) es necesario porque display:block no
es inmediato (espera al próximo reflow).