════════════════════════════════════════════════════════════════════
  DASHBOARD BI IMBLASCO — VERSIÓN DE PRUEBAS (Creaciones Madrid)
  Versión 1.1 · 23-09-2026
════════════════════════════════════════════════════════════════════

CAMBIOS DE ESTA VERSIÓN
  · Sin cron: se actualiza solo cuando alguien abre el panel
    (etl/refrescar.php). Tiempos en config.php, sección 5.
  · WordPress desactivado (BI_USAR_WP = false) para no leer el
    WordPress de Creaciones Madrid.
  · Marca DEMO por módulo; los datos de ejemplo se borran solos
    cuando la ruta real empieza a traer información.
  · requerimientos.php: arquitectura y contrato de la API para el
    informático del ERP, con enlace para compartir sin clave.
  · cobertura.php: cada punto del encargo y su estado.
  · La ruta de productos del ERP se llama productos_erp, para no
    chocar con la ruta productos (catálogo) que ya existe.

INSTALACIÓN RÁPIDA EN CREACIONES MADRID
  1. cPanel → Bases de datos MySQL: crear base, usuario y darle
     todos los permisos.
  2. Subir el contenido de esta carpeta a /public_html/dashboard/
  3. Editar config.php: BI_DB_NOMBRE, BI_DB_USUARIO, BI_DB_CLAVE.
  4. Copiar ga4.json del dashboard antiguo a /public_html/dashboard/
  5. Abrir https://creacionesmadrid.cl/dashboard/instalar.php
     (clave provisoria: imblasco2026) → "Crear las tablas ahora"
     → "Cargar datos DEMO" → "Sincronizar ahora".
  6. Entrar a https://creacionesmadrid.cl/dashboard/
  NO hay que crear ningún cron.

PARA PASARLO A IMBLASCO.CL
  Cambiar en config.php: la base de datos, BI_USAR_WP = true y
  BI_ENTORNO = 'produccion'. Antes, borrar los DEMO:
      etl/demo.php?secret=TU_SECRETO&limpiar=1

(Lo que sigue es la guía original de la versión 1.0. Donde hable
 de cron cada hora, ya no aplica.)

════════════════════════════════════════════════════════════════════
  DASHBOARD BI IMBLASCO — instalación y puesta en marcha
  Versión 1.0 · 14-09-2026
════════════════════════════════════════════════════════════════════

Este panel NO reemplaza al dashboard actual. Se instala en su propia
carpeta y convive con él. El de siempre (/dashboard/index.php) sigue
funcionando igual mientras este se llena de datos.


────────────────────────────────────────────────────────────────────
 1. QUÉ HAY ADENTRO
────────────────────────────────────────────────────────────────────

  config.php            Lo único que hay que editar. Base de datos,
                        llave de la API, clave de acceso, umbrales.
  instalar.php          Crea las tablas y revisa el entorno. Se abre
                        una vez desde el navegador.

  index.php             Resumen gerencial
  ventas.php            Ventas
  cotizaciones.php      Cotizaciones
  clientes.php          Clientes, RFM y clientes en riesgo
  productos.php         Productos, rankings y comprados juntos
  web.php               Tráfico, embudo y buscador
  inventario.php        Stock, cobertura y quiebres
  operacion.php         Pedidos y tiempos de proceso
  alertas.php           Alertas y configuración de sus umbrales
  exportar.php          Excel e impresión / PDF de cada informe

  lib/bi.php            Núcleo: base, esquema, login, filtros, UI
  lib/consultas.php     Todas las consultas de los módulos

  etl/sync.php          Sincronizador. Lo llama el cron cada hora.
  etl/metricas.php      Recálculo de métricas de clientes y productos
  etl/demo.php          Datos de ejemplo, para mostrarle el panel al
                        jefe antes de que exista la API

  assets/bi.css         Estilos
  assets/bi.js          Gráficos e interfaz
  assets/chart.umd.js   Chart.js 4.4.3, incluido: no depende de CDN


────────────────────────────────────────────────────────────────────
 2. INSTALACIÓN, PASO A PASO
────────────────────────────────────────────────────────────────────

PASO 1 — Crear la base de datos
  En cPanel → Bases de datos MySQL, crea una base nueva (por ejemplo
  imblasc_bi), un usuario, y dale todos los permisos sobre esa base.

  Si prefieres no crear una base aparte, deja BI_DB_NOMBRE vacío en
  config.php: el panel usa la misma base de WordPress y crea sus
  tablas con el prefijo bi_. Funciona igual, solo queda todo junto.

PASO 2 — Subir la carpeta
  Sube la carpeta completa a:
      /public_html/dashboard/bi/

PASO 3 — Editar config.php
  Cambia, como mínimo, estas cinco cosas:

    BI_DB_NOMBRE / BI_DB_USUARIO / BI_DB_CLAVE
        Los datos de la base del paso 1.

    BI_CLAVE_HASH
        Viene con la clave provisoria "imblasco2026". Genera la tuya
        por SSH y pega el resultado:
          php -r "echo password_hash('TU_CLAVE', PASSWORD_DEFAULT), PHP_EOL;"
        Ojo: entre comillas SIMPLES en config.php.

    BI_API_KEY
        La llave de api.imblasco.cl.

    BI_SYNC_SECRET
        Inventa un texto largo. Es lo que protege la dirección del
        cron para que nadie más la pueda disparar.

    BI_GA4_JSON
        Por defecto apunta a /dashboard/ga4.json, que ya está en el
        servidor. Si lo mueves, corrige la ruta.

PASO 4 — Crear las tablas
  Abre en el navegador:
      https://imblasco.cl/dashboard/bi/instalar.php
  Te pide la clave, muestra una revisión del entorno con visto bueno
  o cruz en cada punto, y tiene un botón para crear las tablas.
  Se puede volver a abrir cuando quieras: no borra nada.

PASO 5 — Primera sincronización
  Abre:
      https://imblasco.cl/dashboard/bi/etl/sync.php?secret=TU_SECRETO

  Va escribiendo lo que hace en pantalla. Las rutas que el ERP
  todavía no publica salen marcadas como "todavía no existe en la
  API — se salta". Eso es lo normal hoy: no es un error.

PASO 6 — Cron en cPanel
  Cada hora:
      curl -s "https://imblasco.cl/dashboard/bi/etl/sync.php?secret=TU_SECRETO" > /dev/null

  Si tienes acceso SSH, esta otra forma es más liviana:
      php /home/USUARIO/public_html/dashboard/bi/etl/sync.php

PASO 7 — Entrar
      https://imblasco.cl/dashboard/bi/


────────────────────────────────────────────────────────────────────
 3. QUÉ FUNCIONA DESDE EL PRIMER DÍA Y QUÉ ESPERA AL ERP
────────────────────────────────────────────────────────────────────

CON DATOS REALES DE INMEDIATO
  · Inventario: stock, valorización, cobertura y quiebres
    (desde el catálogo que ya existe)
  · Movimiento de bodega por diferencial de stock
  · Embarques y fabricación (plugin IM Variation Stock Table)
  · Web: tráfico, origen, dispositivos y páginas (Google Analytics)
  · Buscador: lo más buscado y las búsquedas sin resultado
  · Alertas de inventario y de búsquedas sin resultado

ESPERANDO LA API DEL ERP
  · Ventas, márgenes y facturas          → ruta ventas + ventas_detalle
  · Cotizaciones y conversión            → ruta cotizaciones
  · Clientes, RFM y clientes en riesgo   → ruta clientes
  · Tiempos de operación                 → ruta operacion
  · Cuadratura contra el ERP             → ruta totales

  Cada módulo que espera muestra un aviso explicando qué falta, en vez
  de aparecer en blanco o con ceros. El día que la ruta empiece a
  responder, el módulo se llena solo: no hay que tocar el panel.

  En Alertas, al final de la página, hay una tabla que muestra en qué
  estado está cada ruta. Es el primer lugar donde mirar si algo no
  aparece.


────────────────────────────────────────────────────────────────────
 4. DATOS DE EJEMPLO PARA MOSTRARLE AL JEFE
────────────────────────────────────────────────────────────────────

Si quieres enseñar el panel completo antes de que exista la API:

  Cargar:
      php etl/demo.php --cargar
      (o https://imblasco.cl/dashboard/bi/etl/demo.php?secret=TU_SECRETO&cargar=1)

  Genera dos años de ventas, cotizaciones, clientes, productos,
  tráfico web y operación, con magnitudes parecidas a las reales.
  Todo lo que crea lleva el prefijo DEMO- en sus identificadores.

  Borrar:
      php etl/demo.php --limpiar

IMPORTANTE: no dejar datos de ejemplo cuando el panel pase a
producción. Se mezclan con los reales en los totales.


────────────────────────────────────────────────────────────────────
 5. CÓMO USAR EL PANEL
────────────────────────────────────────────────────────────────────

FILTROS
  La barra de arriba aplica a toda la pantalla: período, con qué se
  compara, canal (web o ERP), línea de producto y región. Los filtros
  se mantienen al cambiar de módulo, así que se puede entrar a Ventas
  filtrando por una región y saltar a Productos con el mismo filtro
  puesto.

COMPARACIONES
  Cada tarjeta muestra la variación contra el período elegido en
  "Comparar con". Verde es que mejoró, rojo que empeoró. En las tasas
  (porcentajes de margen, de conversión) la variación se muestra en
  puntos porcentuales, que es lo correcto: pasar de 30% a 33% es
  "+3 pp", no "+10%".

LA FÓRMULA DE CADA INDICADOR
  El signo de interrogación gris al lado del título de cada tarjeta
  explica exactamente cómo se calcula ese número. El encargo lo pedía
  como criterio de aceptación.

PROFUNDIZAR
  Casi todo es clicleable: las tarjetas llevan a su módulo, los
  nombres de cliente y de producto abren su ficha, y los tramos de
  las tablas aplican el filtro correspondiente.

EXPORTAR
  Arriba a la derecha de cada módulo. "Exportar Excel" baja un CSV
  que Excel en español abre bien, con los acentos y los decimales
  correctos. "Imprimir / PDF" abre una versión limpia para imprimir
  o guardar como PDF. Ambos respetan el período y los filtros que
  estén puestos.

ALERTAS
  Los umbrales de cada regla se cambian desde la misma pantalla de
  Alertas, sin tocar código. Se aplican en la siguiente corrida del
  cron.

CUADRATURA
  Al final del módulo Ventas, cuando el ERP entregue la ruta totales,
  aparece una tabla que compara día a día lo que dice el ERP contra
  lo que suma el panel. Es el chequeo que pide el encargo antes de
  pasar a producción.


────────────────────────────────────────────────────────────────────
 6. SI ALGO NO ANDA
────────────────────────────────────────────────────────────────────

"No se pudo conectar a la base del BI"
    Revisa BI_DB_NOMBRE, BI_DB_USUARIO y BI_DB_CLAVE. Si los dejaste
    vacíos, revisa que BI_WP_CONFIG apunte al wp-config.php del sitio.

"Las tablas del BI todavía no existen"
    Abre instalar.php y aprieta el botón.

Un módulo aparece vacío
    Mira la tabla del final de alertas.php: dice si la ruta responde,
    si todavía no existe o si dio error, y cuándo fue la última vez.

El cron no corre
    Prueba la dirección a mano en el navegador. Si pide permiso, el
    secreto de la URL no coincide con BI_SYNC_SECRET.

La sincronización se corta a medias
    Corre los pasos por separado para aislar cuál falla:
        php etl/sync.php --solo=productos
        php etl/sync.php --solo=ventas
        php etl/sync.php --solo=web
        php etl/sync.php --solo=metricas

Recargar todo el histórico desde cero
    php etl/sync.php --completo
    Ignora la marca incremental y vuelve a pedir todo. Tarda, pero no
    duplica nada: cada registro se pisa por su identificador.

Los números no cuadran con el ERP
    Módulo Ventas, tabla "Cuadratura contra el ERP". Las filas
    marcadas "Revisar" son los días donde hay diferencia.


────────────────────────────────────────────────────────────────────
 7. LO QUE FALTA POR DEFINIR
────────────────────────────────────────────────────────────────────

  1. El canal de origen. El ERP tiene que escribir WEB o ERP en cada
     documento. Como los pedidos del sitio hoy viven en el panel
     externo, alguien tiene que llevar ese número hasta el pedido del
     ERP. Es procedimiento, no programación.

  2. Las horas de operación. Si en bodega nadie marca el inicio y el
     término de la preparación, el módulo Operación mostrará el estado
     de cada pedido pero no los tiempos.

  3. Los eventos propios del sitio. La tabla bi_web_evento ya está
     creada. Cuando el sitio empiece a registrar vistas de producto y
     agregados al carro, el embudo y el informe de "vistos contra
     comprados" pasan a usar datos propios en vez de los de Analytics.

  4. Usuarios y roles. Hoy hay una sola clave compartida. Cuando haga
     falta que gerencia, ventas y bodega vean cosas distintas, se
     agrega una tabla de usuarios.

════════════════════════════════════════════════════════════════════
