# Contexto: migración BI Ibero Farmacos y sincronización con SAP

> Documento de continuidad. Si se pierde el chat, este archivo resume **qué se quiere lograr, qué se hizo, qué se descubrió y qué sigue**.
> Última actualización: 2026-11-11.

---

## 1. Objetivo

Rehacer el sistema BI/dashboard comercial de **Ibero Farmacos, S.R.L.** que hoy está en:

- Frontend: React en Vercel (`proyecto-iberofarmacos.vercel.app`), hecho por un **programador externo** (pagado por la empresa).
- Backend/BD: **Supabase** (proyecto `IBEROFARMACOS-HDS`, ref `yxbpycuqylegocrngtdt`, región `us-east-1`, plan Pro).
- Fuente de datos: **SAP Business One sobre SAP HANA** (única fuente viva). **Softland** = solo histórico ya cargado, no se sincroniza (ver §4).

Nuevo stack: **Laravel 12 + React + Inertia + PostgreSQL** (proyecto en `C:\laragon\www\BiPanelIbero\BiIbero`, BD Laravel `bi_ibero`).

Reglas acordadas:
- **No tocar la BD de Supabase en producción** (la usa la app actual). Solo lectura.
- **Orden de trabajo:** primero las pantallas del sistema usando la copia local; **la sincronización con SAP se deja para el final**.

---

## 2. Copia local de Supabase (HECHO)

| Qué | Dónde |
|---|---|
| BD local con la copia | PostgreSQL 18 local → base **`supabase_copia`** (localhost:5432, usuario `postgres`, misma clave que `BiIbero/.env`) |
| Script de copia | `C:\laragon\www\BiPanelIbero\supabase_clone\clonar_supabase.ps1` |
| Preparación local (roles/auth/extensiones) | `C:\laragon\www\BiPanelIbero\supabase_clone\preparar_local.sql` |
| SQL del usuario de solo lectura | `C:\laragon\www\BiPanelIbero\supabase_clone\crear_usuario_lectura.sql` |
| Cadena de conexión (contiene clave, **NO subir a git**) | `C:\laragon\www\BiPanelIbero\supabase_clone\.supabase_url` |
| Inventario exportado | `C:\laragon\www\BiPanelIbero\supabase_clone\out\` (475 funciones `.sql`, `esquema.sql`, `vistas.csv`, `tablas.csv`, logs de restore) |

Detalles:
- Se copió con el usuario **`ibero_lectura`** creado en Supabase: `default_transaction_read_only=on`, `bypassrls`, solo `SELECT` en esquemas propios. Borrarlo al terminar: `drop owned by ibero_lectura; drop role ibero_lectura;`
- Conexión vía **Session pooler** (`aws-1-us-east-1.pooler.supabase.com:5432`, usuario `ibero_lectura.yxbpycuqylegocrngtdt`, `sslmode=require`).
- Los backups de Supabase son **PHYSICAL** (BD de 23 GB) → no se pueden descargar desde el panel. **Nunca pulsar "Restore"** en Database → Backups (sobrescribe producción).
- Copia de datos al **11/11/2026 (sync de las 08:00)**. Tamaño local: 8,5 GB.
- Las tablas `*_cache*` se copiaron **solo con estructura (vacías)**: son agregados regenerables (~9 GB).
- `auth.users` local solo tiene los 37 ids necesarios para FKs (sin emails ni claves).
- Para refrescar la copia: `cd C:\laragon\www\BiPanelIbero\supabase_clone; .\clonar_supabase.ps1` (descarga ~7 min + restore). `-SoloPrueba` = solo prueba conexión; `-SoloRestaurar` = re-restaura desde `out\supabase.dump` sin conectar a Supabase.

Esquemas: `core` (principal), `public` (datos crudos SAP), `reporting`, `mart`, `archivo_public`, `fase_g_quarantine`, `metabase_cache_cb481_3`.

Tablas principales (filas):
- `core.fact_ventas_desglosadas` 6,45M · `core.fact_facturacion_linea` 4,33M · `public.fact_ventas_raw` 3,85M · `core.fact_ventas_base` 3,0M · `public.fact_ventas_sap` 476k · `public.fact_devoluciones_sap` 33k · `public.fact_pedidos_sap`
- Maestros SAP: `core.sap_product_master_current_v3`, `core.sap_customer_master_current_v3`, `core.sap_vendedor_master`, `core.producto_sap_master_map`, `core.cliente_sap_master_map`, `core.cliente_rnc_sap_map`

---

## 3. Cómo funciona HOY la sincronización con SAP (descubierto)

**La sincronización NO está dentro de Supabase.** No hay `pg_cron`, ni llamadas HTTP (`pg_net`), ni Edge Function de sync detectada. Es un **ETL externo** (programa en un servidor con acceso a SAP) que **lee SAP HANA directo** y **escribe en Supabase**.

Evidencias:
- Errores en la bitácora: `(258, "insufficient privilege ...")` → código de error de **SAP HANA**; formato típico de Python (`hdbcli`) → probablemente ETL en **Python** conectado directo a HANA.
- `core.sap_etl_state` (fila única, `source_name='SAP_ETL'`): ventana sincronizada, `sap_max_docentry`, `sap_max_docnum`, `sap_fingerprint`, `last_success_at`, `detail.daily_states` (totales por día). `DocEntry/DocNum` = campos de SAP B1.
- `core.etl_refresh_log`: bitácora de cada ejecución (`source_name`, `step_name`, `status`, `duration_seconds`, `detail` jsonb, `error_message`).
- Trigger `core.notify_sap_master_refresh_request` sobre `etl_refresh_log`: al insertar una solicitud `SAP_MASTER_REFRESH_REQUEST` con `queue_status=PENDING` hace `pg_notify('ibero_sap_master_refresh', step_name)` → **el ETL externo escucha (LISTEN) ese canal** y procesa la actualización de maestros (clientes/productos).
- Triggers en `public.fact_ventas_raw` / `fact_ventas_sap` / `fact_devoluciones_sap` / `fact_pedidos_sap`: normalizan geografía (`trg_geo_canonica_*`) y marcan días a recalcular (`trg_facturacion_marcar_dias`).

Procesos (`source_name` en `etl_refresh_log`):
- `SAP_ETL` → reconciliación: lee ventana de ~7 días, calcula huella por día; si no cambió → `sap_daily_reconciliation_no_changes` (SKIPPED), si cambió → `sap_daily_reconciliation_apply` (reescribe esos días, ~53 s).
- `SAP_MASTER_REFRESH_REQUEST` → actualización de maestros bajo demanda (cola + pg_notify).
- `SAP_PEDIDOS_ETL`, `SAP_PEDIDOS_KPI_LIGHT` → pedidos (inactivos últimos 30 días).
- `SAP_ETL_LIGHT`, `SAP_ETL_MAIN_FAST`, `DASHBOARD_MAIN_10MIN`, `DASHBOARD_HOURLY_BALANCED`, `COMPARATIVA_*`, `REPORTES_CADENAS`, `VISITADORES_V2` → refrescos de caches/dashboards.

Frecuencia y carga observada:
- `SAP_ETL`: 13.596 ejecuciones desde 2026-06-09; últimos 30 días ~18/día; actualmente **5 al día entre 08:00 y 20:00** (en horario laboral).
- ~75% de ejecuciones terminan "sin cambios" pero igual leen y totalizan 7 días en SAP.
- Ejecuciones de hasta **2.543 s (~42 min)**. Probable causa de que **SAP se ponga lento**.

Datos de referencia para validar una nueva sincronización (de `sap_etl_state.detail.daily_states`):

| Fecha | Facturas | Líneas | Venta total | max DocEntry | max DocNum |
|---|---|---|---|---|---|
| 2026-11-05 | 190 | 4.194 | 21.016.610,18 | 75200 | 31544 |
| 2026-11-06 | 116 | 2.008 | 8.750.502,68 | 75432 | 31660 |
| 2026-11-10 | 297 | 5.691 | 25.919.984,08 | 76001 | 31957 |

---

## 4. Softland

**Softland es solo HISTÓRICO (confirmado por el usuario, 2026-11-11).** Fue el ERP de los años anteriores; ya no se usa. Sus datos se importaron **una sola vez** y ya están completos en la BD (p. ej. `provincia_softland` en `fact_ventas_raw`, `core.dashboard_devoluciones_softland_cache`).

- **No hay que sincronizar, refrescar ni leer nada de Softland.** Esos datos se conservan tal cual (vienen en la copia local).
- **La única fuente a sincronizar es SAP.**
- Al diseñar pantallas y la sync: los datos de Softland y SAP conviven en las mismas tablas `fact_*`; la sync de SAP **no debe borrar ni sobrescribir** los periodos/filas de origen Softland.

---

## 5. Plan para la sincronización (FASE FINAL)

### Opción A — Pedir el ETL al programador externo
Solicitar (revisar contrato sobre propiedad del código):
- Código fuente completo del ETL y **dónde corre** (servidor, tarea programada/servicio, horarios).
- Consultas a SAP (tablas leídas, cálculo de la huella/fingerprint).
- Dependencias y configuración (versión Python, librerías, variables de entorno; credenciales propias, no las suyas).
- También el **código del frontend** (Vercel) como referencia de cálculos de cada pantalla.

### Opción B — Rehacerla con la API de SAP (Service Layer)
La empresa tiene acceso al **SAP Business One Service Layer**: `https://<servidor>:50000/b1s/v1/...`
- Login: `POST /b1s/v1/Login` (CompanyDB, UserName, Password) → cookie de sesión `B1SESSION`. Siempre `POST /Logout` al terminar.
- Entidades: `Invoices`, `CreditNotes` (devoluciones), `Orders`, `BusinessPartners`, `Items`, `SalesPersons` (con `$filter`, `$select`).
- **`SQLQueries`**: crear y ejecutar SELECT propios → lo más útil (factura + líneas + cliente + vendedor + producto en una consulta).
- Tablas SAP B1: `OINV/INV1` (facturas), `ORIN/RIN1` (notas de crédito), `ORDR/RDR1` (pedidos), `OCRD` (clientes), `OITM` (productos), `OSLP` (vendedores).
- No requiere driver/ODBC/usuario HANA (depende de HANA solo indirectamente).
- Consideraciones: certificado SSL normalmente autofirmado; el servidor de Laravel necesita acceso de red al puerto 50000; credenciales en `.env`; paginación (`Prefer: odata.maxpagesize`); `SQLQueries` solo SELECT y puede restringir tablas/funciones.
- **El histórico NO se carga por API** (ya está en la copia); solo se sincroniza lo nuevo.
- La API de SAP cubre todo lo que hay que sincronizar: Softland no se sincroniza (es histórico).

### Importante: la API por sí sola NO arregla la lentitud de SAP
El Service Layer consulta la misma HANA. Lo que arregla la lentitud es el **diseño**:
1. **Incremental**: traer solo documentos con `DocEntry` > último guardado o `UpdateDate` reciente.
2. **Reconciliación pesada (7 días) una vez de madrugada** (ej. 02:00), no en horario laboral.
3. **Solo columnas necesarias** vía `SQLQueries` (no documentos completos).
4. **Paginar** (500–1000 filas) con pausas cortas; **Logout siempre** (sesiones abiertas = lentitud + licencias).
5. **Cálculos pesados en PostgreSQL**, no en SAP (caches, agregados, normalización).

Implementación prevista en Laravel: comandos Artisan + Scheduler (ej. `php artisan sap:sync`, `php artisan sap:probar`).
Primera prueba propuesta: `sap:probar` que haga login y compare el día **2026-11-10** contra la tabla de §3 (297 facturas / 5.691 líneas / 25.919.984,08).

---

## 6. Proyecto Laravel: cómo está armado (avance 2026-11-12)

Stack instalado: Laravel 12 + Inertia (inertia-laravel 3) + React 19 + TypeScript + Tailwind 4 + Vite 7 + Recharts + lucide-react.

**Conexiones de BD**
- `pgsql` (por defecto) → `bi_ibero`: tablas propias de Laravel (users, sessions, cache, jobs).
- `bi` → `supabase_copia` (`search_path core,public`): datos del BI. Variables `DB_BI_*` en `.env`.

**Usuarios y permisos**
- `users` tiene `bi_user_id` (= `core.app_profiles.user_id`), `role`, `is_active`.
- `php artisan bi:importar-usuarios` crea/actualiza usuarios desde `core.app_profiles` (37). Las claves de Supabase no se pueden copiar: los usuarios nuevos reciben la clave temporal `BI_DEV_PASSWORD` del `.env`.
- Al iniciar sesión se guarda en sesión `core.get_current_app_context()` (rol, alcance, `permissions[].route`). Con eso se filtra el menú (`config/bi_menu.php`) y se protege cada ruta con el middleware `pantalla:/ruta` (`EnsureRouteAllowed`). Tras el login se va a la primera pantalla permitida.

**Cómo se reutilizan las funciones del BI**
- `App\Services\BiDatabase::call($user, 'get_dashboard_xxx', ['p_param' => valor])` ejecuta `core.<función>` en una transacción con `set_config('request.jwt.claim.sub', <bi_user_id>)`.
- En la copia local, `auth.uid()` lee ese valor (redefinido en `supabase_clone/preparar_local.sql`), así que **cada función aplica el alcance del usuario igual que en Supabase** (verificado: un gerente de Zona 2 solo ve Zona 2).
- Los parámetros de cada función se toman de cómo los llama el frontend anterior (ver `mapa-pantallas-app-actual.md`).

**Caches del BI**
- Las tablas `*_cache` se copiaron vacías; se regeneran en local con `supabase_clone\reconstruir_caches.ps1` (usa `core.post_load_refresh_dashboards` y los `refresh_*_range`, ~2-3 min por mes). Por defecto desde 2025-01-01; `-Desde 2020-01-01` para todo el histórico.
- Hay que volver a correrlo cada vez que se refresca la copia con `clonar_supabase.ps1`.
- **Excepción importante:** 9 tablas con "cache" en el nombre **no las llena ninguna función**: son datos originales y se copian con datos (lista `$cachesConDatos` en `clonar_supabase.ps1`). La principal es `core.dashboard_devoluciones_softland_cache`: el **histórico de devoluciones de Softland** (2020-01 a 2026-04); sin ella, las devoluciones de enero a abril de 2026 y años anteriores salen en cero.
- Las funciones guardan resultados en `core.dashboard_rpc_cache`; tras regenerar caches hay que vaciarla (`truncate core.dashboard_rpc_cache`), si no, siguen sirviendo respuestas viejas. `reconstruir_caches.ps1` ya lo hace al final.
- Estrategia acordada: no regenerar todo; regenerar solo lo que pide cada pantalla al migrarla.

**Pantallas: TODAS migradas (18/18, 2026-11-12).** Detalle de cada una en §7.

**Administración (escrituras)**
- Base común `App\Http\Controllers\Admin\AdminBase`: ejecuta la función de escritura como el usuario, devuelve mensaje de éxito/error (mensajes de `RAISE EXCEPTION` de la base) y vacía `core.dashboard_rpc_cache`.
- **Todas las escrituras van a `supabase_copia` (local), nunca a Supabase.**
- Presupuesto y Comisiones usa dos endpoints con LISTA BLANCA (`/admin/presupuesto/leer` y `/admin/presupuesto/accion`): solo se ejecutan las funciones declaradas en `PresupuestoController::LECTURA` / `ACCIONES`, cada una con sus parámetros validados; las acciones exigen rol admin.
- Productos, Sucursales y Procesamiento usaban rutas API de Next.js (código en Vercel, NO disponible). Se reconstruyeron sobre las mismas tablas/funciones: `admin_guardar_producto`, `reclasificar_producto_pendiente_historico`, `admin_comarketing_masivo_v1`, `refresh_dim_producto_clasificacion_desde_sap`, `get_admin_sucursales_pendientes_fast`, `vis_get_sucursales_incompletas_v1`, `dim_sucursal`, `admin_reconciliar_ciudades_sap_v1`, `dashboard_control_archivos`. Conviene contrastar con el código real cuando lo entreguen.
- Excel en el navegador con SheetJS 0.20.3 (instalado desde cdn.sheetjs.com, no la 0.18.5 de npm que tiene vulnerabilidades).

**Pruebas**: scripts en el scratchpad de la sesión (no versionados) ejecutaban cada controlador como `amata@iberofarmacos.net` y comparaban con la web.

**Cómo levantarlo**
```
cd C:\laragon\www\BiPanelIbero\BiIbero
php artisan serve          # http://127.0.0.1:8000
npm run dev                # en otra terminal (recarga en caliente); o npm run build
```

## 6.1 Rediseño (en curso, desde 2026-11-12)

Decisiones del usuario: estilo **corporativo limpio**, **shadcn/ui** sobre Tailwind 4, **solo tema claro**.
- shadcn/ui configurado (`components.json`, `resources/js/components/ui/*`, `resources/js/lib/utils.ts` con `cn`). Tema en `resources/css/app.css` (variables de shadcn; primario = azul Ibero `#1c4f9c`, acento de marca naranja `#f47c20`; menú lateral azul marino).
- El color morado de marca que usaban las pantallas antiguas se renombró de `accent` a **`brand`** (shadcn reserva `accent`).
- Layout nuevo (`layouts/AppLayout.tsx`): menú lateral shadcn `Sidebar` (contraíble a iconos, submenús, activo en naranja) + barra superior con migas, insignia "Datos SAP al …" (`core.sap_etl_state.last_success_at`, prop compartida `datosAl`) y menú de perfil (Mi perfil, Cambiar contraseña, Cerrar sesión).
- `/perfil` (`PerfilController`): el usuario cambia su propia contraseña.
- Componentes nuevos para tableros: `components/filtros.tsx` (`PeriodoPicker` con atajos + calendario de rango, `Filtro`, `LimpiarFiltros`) y `components/kpi.tsx` (`StatCard`, `Variacion`, `Seccion`).
- **Vista Ejecutiva rediseñada** y revisada en el navegador. Pendiente: rediseñar el resto de pantallas con los mismos componentes.
- Estilo sobrio (pedido del usuario): sin degradados, sin "pastillas" de color, esquinas 0.5rem, sin efectos animados.
- **Mejoras propias de la Vista Ejecutiva (no existen en la app original)**, en `ExecutiveController`:
  - Comparación contra **los mismos días del mes anterior** (o mismo rango del año anterior si el periodo abarca varios meses), en lugar del "periodo anterior del mismo largo" de la función original.
  - **Ritmo**: días hábiles transcurridos / del mes (`core.es_dia_habil`, respeta feriados). Marca "esperado a la fecha" en la barra, puntos por encima/debajo y **proyección de cierre** (venta ÷ hábiles transcurridos × hábiles del mes). Solo si el periodo empieza el día 1 dentro de un mes no terminado.
  - % de cumplimiento grande en cada tarjeta.
  - Gráfico mensual: mes en curso atenuado y **línea de presupuesto mensual** (`core.get_presupuesto_distribuido_executive_v2` por mes; ~60 s la primera vez → prop diferida de Inertia + caché 6 h). Requiere `PHP_CLI_SERVER_WORKERS=4` en `.env` para que `artisan serve` no se bloquee.
- **Vista Ejecutiva ya NO usa funciones de Supabase (2026-11-12).** Todo el cálculo está en Laravel, leyendo tablas directamente:
  - `App\Services\Bi\AlcanceComercial`: zonas/grupos/líneas/vendedores que ve cada usuario (= `get_effective_sales_scope_v1`, `resolve_dashboard_zone_v1`, `resolve_dashboard_group_v1`). Tablas `core.app_profiles`, `app_user_data_role_v1`, `app_user_scope_v1`, `app_user_vendedor_producto_v1`, `app_user_visitador`.
  - `App\Services\Bi\VentaDiaria`: consultas sobre `core.dashboard_facturacion_fuente_cache` (venta diaria resumida; pese al nombre es la tabla de ventas limpias, la llena hoy `refresh_dashboard_facturacion_fuente_cache_range` desde `public.vw_ventas_completas`; en la fase SAP la llenará Laravel).
  - `App\Services\Bi\PresupuestoComercial`: presupuesto publicado por zona (`fact_presupuesto_vendedor` + `presupuesto_comercial_no_asignado_v6` repartido con `presupuesto_vendedor_peso_zona`; versión publicada por año vía `presupuesto_version`) y, con filtro de provincia/cadena, reparto por historia (`fact_presupuesto` + `dashboard_productos_sap_rango_cache`).
  - `App\Services\Bi\VistaEjecutiva`: KPIs, último día, rankings, catálogos, gráfico anual, pedidos pendientes (`public.fact_pedidos_sap` + maestros SAP). `App\Services\Bi\Calendario`: días hábiles.
  - Validación: `php artisan bi:comparar-ejecutiva` compara contra las funciones originales (8 filtros × admin, gerente, supervisor, incluidos los "acceso denegado"): **todo coincide**. Gráfico anual también idéntico. Pedidos no se pudo validar con datos (la copia tiene `fact_pedidos_sap` vacía).
  - Diferencia deliberada: "Productos con venta" respeta el filtro de grupo (la función original daba 0).
  - Tiempos sin caché: ~1 s la página. Presupuesto mensual del gráfico: 0.4 s; con provincia/cadena ~13 s → prop diferida + caché de Laravel invalidada por `core.sap_etl_state.last_success_at`.
  - Ya no se usan para esta pantalla: `get_dashboard_executive*`, `get_dashboard_executive_anual*`, `get_dashboard_pedidos_kpi*`, `get_dashboard_ventas_cumplimiento_v2*`, `get_presupuesto_distribuido_executive_v2`, `core.dashboard_rpc_cache`.
- Usuario de prueba local (solo en la copia): `BI_TEST_EMAIL` / `BI_TEST_PASSWORD` en `.env`.

## 7. Próximos pasos

> **Para retomar, leer primero [`hoja-de-ruta-como-seguir.md`](hoja-de-ruta-como-seguir.md)**: estado por pantalla, método para pasar la lógica de Supabase a Laravel y orden sugerido.

1. [ ] Pedir al programador externo el código del ETL y del frontend (§5 Opción A).
2. [ ] Construir las pantallas en Laravel + React + Inertia leyendo de la copia (`supabase_copia`). Tratar las `fact_*` como contrato: la futura sync solo debe llenarlas.
   - [x] Base: Inertia + React + TS, login, menú con permisos, conexión `bi`, servicio `BiDatabase`.
   - [x] Vista Ejecutiva.
   - [x] Resumen de Ventas (`/ventas-desglosadas`, `VentasDesglosadasController`): modos Facturación / Ventas desglosadas (`p_fuente` = `FACTURACION` | `CADENAS`), RD$/Unidades, KPIs, evolución mensual con proyección y Prom. 3M (promedio del cierre de los últimos 3 meses), peso por zona con días hábiles (lunes–viernes menos `core.dim_calendario_no_laboral`), cadenas por zona (en Facturación la app reparte 60% Z1 / 40% Z2), participación por cadena, ventas por clasificación. Verificado contra la web en ambos modos (1–12 nov 2026).
     - Pendiente: filtro **Producto** (la función no lo recibe; la app anterior lo aplica con `get_dashboard_producto_scope` + lógica del frontend).
   - [x] Devoluciones (`/devoluciones`, `DevolucionesController`): `get_dashboard_devoluciones_executive` + `get_dashboard_devoluciones_anual`. Verificado contra la web (1–12 nov 2026: total RD$ 2.679.765,09; 343 notas; 258 productos; 278 clientes).
   - [x] Componentes comunes: `resources/js/components/dashboard.tsx` (filtros, tarjetas, paneles) y `charts.tsx` (evolución por grupo, mix por línea, ranking por provincia). La Vista Ejecutiva ya los usa.
   - [x] Vista Comparativa (`/comparativa`, `ComparativaController`): `get_dashboard_comparativa` (año actual vs anterior con el mismo filtro). Mejor/peor/último mes cerrado y variación mes a mes se calculan en el frontend como en la app anterior. Gráfico: barras año actual vs anterior con el % de crecimiento como etiqueta (se evitó el doble eje del original). Verificado (1–12 nov 2026: 164.979.534,35 vs 147.233.502,82; +12,1%).
   - [x] Ventas Diarias (`/diarias`, `DiariasController`): `get_dashboard_diarias_v2`. Verificado (1–12 nov 2026: 164.979.534,35; 28.480 registros; 327.786 unidades; ritmo 20.622.441,79).
     - **Diferencia intencional:** la app anterior excluía feriados del gráfico usando la API pública `date.nager.at` (tenía la Constitución el 6-nov), distinta del calendario interno `core.dim_calendario_no_laboral` (9-nov) que usa el resto de la app. Aquí se usa el calendario interno → el 6-nov aparece en el gráfico.
   - [x] Análisis → Productos (`/productos`, `ProductosController`): `get_dashboard_productos_analisis_v7`, `..._evolucion_anual_v1`, `..._detalle_v2` (tabla completa, se carga bajo demanda con recarga parcial de Inertia), `..._busqueda_analisis_v6` (endpoint JSON `/productos/buscar`, multiselección, IDs unidos con `|`). Verificado (1–12 nov 2026: RD$ 164.241.877,13; 224.748 unid.; 452 SKUs).
     - Caches que usa: `dashboard_clientes_facturacion_cache` (`refresh_dashboard_clientes_facturacion_cache_fast(desde, hasta, '2026-05-01')`) y `dashboard_clientes_facturacion_month_cache` (`refresh_dashboard_clientes_21p_mes(mes)`). Regenerados para 2026.
     - Primera carga ~10 s con caches de resultados vacíos; luego responde rápido (la función guarda el resultado en `dashboard_rpc_cache`).
   - [x] Análisis → Clientes (`/analisis-clientes`, `ClientesAnalisisController`): `get_dashboard_clientes_analisis_v1` + `get_dashboard_clientes_catalogos_v1` (cacheado 30 min). Filtros multiselección (componente `MultiSelect`, valores con `|`). Verificado (bruta 164.979.534,35; neta 162.299.769,26). **Bug corregido:** la app anterior mostraba como "Promedio mensual" la SUMA del año (3.999M); aquí se usa `promedioVenta` (363,6M).
   - [x] Ventas vs Presupuesto → Vendedores (`/presupuesto/vendedores`, `CumplimientoVendedoresController`): `get_dashboard_ventas_cumplimiento_v2` (+ `_ciudades_v2` bajo demanda). La respuesta (6.000+ filas) se agrega en el servidor. Tablas idénticas a la web.
   - [x] Ventas vs Presupuesto → Visitadores (`/presupuesto/visitadores`, `CumplimientoVisitadoresController`): `get_dashboard_visitadores_nucleo_v1` (+ ciudades y cadenas bajo demanda). Presupuesto 244.442.910 idéntico.
   - [x] Comisiones → Visitadores (`/comisiones`): `get_dashboard_comisiones_nucleo_v1`.
   - [x] Comisiones → Vendedores (`/comisiones-vendedores`): `get_dashboard_comisiones_v7` + **Cargar cobros** (`admin_cargar_cobros_vendedores_v1`: validar → aplicar; Excel VENDEDOR | ZONA | META | COBRADO).
   - [x] Admin → Usuarios (`/admin/usuarios`): rol, dashboards por usuario, alcances, vendedor/grupo, activar/desactivar, contraseña, alta de usuarios (crea `users` + `auth.users` + `core.app_profiles`). "Eliminar" = desactivar.
   - [x] Admin → Config. Clientes (`/admin/clientes`): clasificación, responsables, sustituir vendedor (simular/aplicar), importar/exportar Excel.
   - [x] Admin → Config. Productos (`/admin_productos`): buscar, editar producto + alias + distribución de comisión, sin match, descargar/subir base, comarketing masivo, clasificación desde SAP.
   - [x] Admin → Presupuesto y Comisiones (`/admin/presupuesto`): 10 pestañas (resumen, versiones/detalle/importación/ajustes/publicación, distribución por tipo, pesos vendedores, pesos por producto, exclusiones, vendedores, equipo/responsables, asignación de visitadores, comisión).
   - [x] Admin → Feriados, Control Procesamiento (`dashboard_control_archivos`, 167 archivos activos = web) y Config. Sucursales.
   - [x] Carga diferida de páginas (bundle inicial 776 KB → 369 KB).
   - [ ] Filtro "Producto" en Resumen de Ventas y Comparativa (la app anterior lo aplica con `get_dashboard_producto_scope` + lógica del frontend). Ejecutiva/Resumen/Comparativa/Diarias/Devoluciones siguen con filtros de selección única (la anterior permitía varios con `|`).
   - [ ] Importar listado de visitadores (`vis_importar_listado_v1`) y el modo "Presupuesto" del selector superior de la pantalla de presupuesto: no se replicaron (formato de archivo no deducible sin el código original).
   - [ ] Pantalla para que cada usuario cambie su contraseña y "olvidé mi contraseña" (hoy: admin la cambia en Usuarios o `php artisan bi:cambiar-clave`).
   - [ ] Revisión visual en navegador de todas las pantallas (se verificaron datos ejecutando los controladores, no el dibujo).
3. [ ] Decidir para cada pantalla: regenerar caches existentes (funciones `refresh_*` en `out\funciones`) o crear agregaciones propias en Laravel (preferido).
4. [x] Confirmar estado de Softland → solo histórico, ya cargado, no se sincroniza.
5. [ ] Fase final: sincronización (ETL entregado o nueva vía Service Layer con diseño incremental).
6. [ ] Al terminar con la copia: borrar usuario `ibero_lectura` en Supabase.

Pantallas actuales vistas en la app (referencia): Vista Ejecutiva, Devoluciones, Resumen de Ventas (filtros: rango de fechas, zona, provincia, línea médica, grupo producto, producto, cadena; modos Facturación / Ventas desglosadas; RD$ / Unidades; botón Actualizar). RPCs usadas por el frontend, p. ej.: `get_effective_sales_scope_v1`, `get_dashboard_producto_scope`, y la función/endpoint `dashboard-update-status`.
