# Hoja de ruta: cómo seguir con el proyecto

> Documento de traspaso para retomar el trabajo si se pierde la conversación.
> Última actualización: **2026-11-13**.
> Contexto técnico completo (hallazgos, scripts, decisiones anteriores): [`contexto-migracion-y-sincronizacion-sap.md`](contexto-migracion-y-sincronizacion-sap.md).
> Mapa de pantallas de la app actual: [`mapa-pantallas-app-actual.md`](mapa-pantallas-app-actual.md).

---

## ▶ BASES DE DATOS (desde 2026-11-13, decisión del usuario: opción B, una base definitiva)

| Base | Para qué | Conexión Laravel |
|---|---|---|
| **`ibero_bi`** (definitiva) | Todo el sistema nuevo. Esquema `app`: tablas de Laravel (users, spatie, permisos_denegados, sesiones, colas, caché). Esquemas `core`, `public`, etc.: datos del negocio (clonados de `supabase_copia` el 2026-11-13; aquí escriben los motores, Administración y, más adelante, la sincronización SAP). | `pgsql` (search_path `app`) y `bi` (search_path `core,public`) — misma base |
| `supabase_copia` (referencia) | Copia fiel de Supabase, **no se modifica**. Los comandos `bi:comparar*` cambian solos la conexión `bi` a esta base (`AppServiceProvider`, conexión `referencia`) y comparan ahí el original contra Laravel. | `referencia` |
| `bi_ibero` (antigua) | Tablas de Laravel antes del cambio; queda como respaldo (copiadas a `ibero_bi.app`: 38 usuarios, 8 roles, 76 permisos, 24 excepciones). Se puede borrar cuando se confirme todo. Respaldo del `.env` anterior: `.env.antes-ibero_bi`. | — |

Variables: `DB_DATABASE=ibero_bi`, `DB_SEARCH_PATH=app`, `DB_BI_DATABASE=ibero_bi`, `DB_REFERENCIA_DATABASE=supabase_copia`.
Verificado tras el cambio: permisos 38/38 (`bi:comparar-permisos`), todas las pantallas GET responden como antes.
**Usuarios, roles y alcance: solo en Laravel (HECHO 2026-11-13).**

| Antes (BI) | Ahora (`ibero_bi.app`) |
|---|---|
| `core.app_profiles` (rol, estado, nombre, correo) + `auth.users` | `users` (`role`, `is_active`, `name`, `email`; `bi_user_id` = uuid estable que usan las tablas del negocio) |
| `core.app_user_data_role_v1` | `users.rol_datos` (rol efectivo = `coalesce(rol_datos, role)` = rol de spatie) |
| `core.app_user_scope_v1` | `usuario_alcances` (97 filas copiadas) |
| `core.app_user_vendedor_producto_v1` | `usuario_vendedor_grupos` |
| `core.app_user_visitador` | `usuario_visitadores` |
| `core.app_visitador_jerarquia` | `visitador_jerarquias` |
| `core.app_role_permissions`, `core.app_user_route_permissions_v1` | spatie + `permisos_denegados` (ya estaba) |

- `App\Services\PerfilDatos`: lee rol y alcance del usuario de esas tablas. Los servicios de pantallas (`AlcanceComercial`,
  `AlcanceVisitadores`, `CumplimientoVisitadores`, `ComisionesVisitadores`) reciben los valores y los pasan a su SQL como parámetros
  (no unen tablas de usuarios dentro de la consulta), así funcionan igual en `ibero_bi` y en la copia de referencia de los comparadores.
- `Admin::exigirAdmin*` usa `users.role`. Crear usuario ya no escribe en `auth.users`/`core.app_profiles`.
- Retirado: la copia del alcance a `core.comision_dashboard_alcance_v4` (esquema anterior de comisiones; nada la lee).
- Copia de datos: `php artisan bi:importar-usuarios` (una vez; con `--forzar` reemplaza). Se borró el comando anterior del mismo nombre
  (creaba usuarios desde `core.app_profiles`; ya cumplió).
- `bi:comparar-admin usuarios`: cada lado se fotografía en sus propias tablas (`['original' => …, 'laravel' => …]`); 16/16.
- Las tablas `core.app_*` de usuarios quedan sin uso en `ibero_bi` (se pueden borrar más adelante).


## ▶ SINCRONIZACIÓN DESDE EL SUPABASE ORIGINAL (provisional, 2026-11-16)

Mientras no exista la sincronización directa con SAP, el botón **"Sincronizar"** de la barra superior (solo administradores) trae del
Supabase de producción (usuario de solo lectura `ibero_lectura`, credenciales en `supabase_clone/.supabase_url`, fuera del proyecto)
lo que usa la app actual y deja `ibero_bi` igual. También: `php artisan bi:sincronizar-supabase [--tabla=…] [--dias=60] [--forzar]`.

- Configuración por tabla en `config/sincronizacion.php` (90 tablas): datos de SAP y cachés derivadas (últimos 60 días, por día),
  maestros y apoyo (completas), configuración editable (completas o por versión, **conservando lo hecho en la app nueva**).
  No se copian: resultados de los motores de Laravel (se encolan los meses del mes anterior, el actual y los que cambiaron),
  usuarios/permisos (`app`) ni las 59 tablas que Laravel no usa.
- Cambios locales: disparadores `zz_sync_local_*` (instalados con `php artisan bi:sincronizacion-preparar`) registran en
  `app.sync_cambios_locales` cada fila creada/cambiada/borrada desde la app nueva; la sincronización no las toca (si cambió en ambos
  lados, gana la app nueva). No registran la propia sincronización (`session_replication_role = replica`) ni los motores (`ibero.origen = worker_*`).
- Ids: las secuencias de las tablas editables arrancan en 1.000.000.000 → lo creado en la app nueva nunca choca con un id de Supabase.
- Solo se copian los grupos (día, mes, versión…) cuya huella en Supabase cambió desde la última vez (`app.sync_huellas`).
- Historial y avance: `app.sync_ejecuciones` (el botón muestra el % y el resultado de la última).
- Corre en la cola: el programador lanza `queue:work --stop-when-empty` cada minuto (`routes/console.php`). **Requiere el programador**
  (`php artisan schedule:work` en desarrollo; tarea cada minuto en el servidor), igual que el recálculo de comisiones.
- Primera sincronización (2026-11-16): 3,4 min, trajo todo lo cambiado desde la copia del 12-nov (3 versiones de presupuesto nuevas,
  ventas/devoluciones/pedidos de los días nuevos, asignaciones de visitadores, etc.). Siguientes: ~1 min si no hay cambios.
- Cuando exista la sincronización directa con SAP, este botón se retira y se borra el usuario `ibero_lectura`.

## ▶ AVANCE 2026-11-13 (tarde): TODAS las pantallas de consulta ya calculan en Laravel


- **Motor de vendedores** (`App\Services\Comisiones\MotorComisiones`, `bi:procesar-comisiones`): 11 meses de 2026 idénticos (`bi:comparar-comisiones`).
- **Motor de visitadores** (`App\Services\Comisiones\MotorVisitadores`, `bi:procesar-visitadores`) = `vis_recalcular_mes_v1`
  (venta/presupuesto por ruta, comisión por persona, sucursales incompletas). `bi:comparar-visitadores 2026-01 … 2026-11`:
  **los 11 meses idénticos** en las 5 tablas (`vis_venta_mes`, `vis_presupuesto_mes`, `vis_pendiente_mes`, `vis_comision_mes`,
  `vis_sucursal_incompleta_mes`); comisión a pagar oct-2026 RD$ 9.265.144,17 en ambos.
- Pantallas (con `bi:comparar`, 4 a 6 roles cada una):
  - Ventas vs Presupuesto → Vendedores (`CumplimientoVendedores`) y ciudades: 36/36 casos (admin, gerente, supervisor, ejecutivo × 9 filtros).
  - Ventas vs Presupuesto → Visitadores (`CumplimientoVisitadores`: `visitadores`, `visitadores-ciudades`, `visitadores-cadenas`).
  - Comisiones → Visitadores (`ComisionesVisitadores`, `comisiones-visitadores`: 60/60).
  - Comisiones → Vendedores (`ComisionesVendedores`, `comisiones-vendedores`): rutas normal, preliminar sin presupuesto
    (2025 o un mes sin publicar) y mixta. Carga de cobros (`CobrosVendedores`, `bi:comparar-cobros`): previsualizar y aplicar idénticos.
  - Única diferencia aceptada: donde el original rechaza por permiso de pantalla, Laravel lo hace en el middleware `pantalla:`
    (verificado: los mismos roles quedan bloqueados). Y la etiqueta de producto con "Â·" del original sale corregida ("·").
- **Motores programados (acordado 2026-11-13)** — `App\Services\Comisiones\ColaRecalculo` + `bi:procesar-pendientes`, en `routes/console.php`:
  - Cada minuto procesa las colas de Supabase que llenan los disparadores de configuración: `core.comision_recalculo_pendiente_v6`
    (vendedores) y `core.visitadores_v2_refresh_queue` (visitadores; respeta los 90 s de espera). Antes las procesaban
    `comision_procesar_pendientes_v6` y un proceso externo.
  - Cada hora (min. 5) encola el mes en curso (y el anterior los primeros 5 días) para recoger la venta nueva de SAP.
    Cuando la sincronización SAP pase a Laravel, que encole al terminar cada carga.
  - Al publicar/importar presupuesto (Admin → Presupuesto): todos los meses del año hasta hoy; otras escrituras de esa pantalla: meses recientes.
  - Al aplicar cobros: el mes cargado.
  - Los motores marcan su transacción (`ibero.origen = worker_comisiones / worker_visitadores`) para no volver a encolarse.
  - **Requiere el programador corriendo:** en desarrollo `php artisan schedule:work`; en el servidor, tarea cada minuto con `php artisan schedule:run`.
- **Menú y permisos en Laravel (2026-11-13)** — ver §6.2: hecho y verificado.

**Administración (2026-11-13, en curso)** — servicios en `app/Services/Admin` (modelos Eloquent en `app/Models/Bi`), errores de negocio
con `App\Exceptions\AdminException` (mensaje igual al original). Se valida con `php artisan bi:comparar-admin {pantalla}`: corre la función
original y la de Laravel en transacciones que se revierten (en las dos bases) y compara la respuesta y las tablas que escribe; un caso puede
preparar datos de prueba (3.er elemento: SQL que corre dentro de la transacción).

| Pantalla | Estado | Casos idénticos |
|---|---|---|
| Feriados | **Laravel** (`Admin\Feriados`) | 10/10 |
| Usuarios (rol, alcance de datos, vendedor/grupo; pantallas por rol y excepciones ya estaban) | **Laravel** (`Admin\Usuarios`) | 16/16 |
| Sucursales (pendientes, incompletas, ciudades desde SAP) | **Laravel** (`Admin\Sucursales`) | 7/7 |
| Clientes (lista, detalle, clasificación, responsables, sustituir vendedor, importar, maestro) | **Laravel** (`Admin\Clientes`) | 16/16 |
| Productos (guardar, reclasificar histórico, comarketing masivo, clasificación SAP) | **Laravel** (`Admin\Productos`) | 11/11 |
| Procesamiento | Ya leía la tabla directo | — |
| Presupuesto y Comisiones — **lecturas** | **Laravel** (`Admin\Presupuesto\Lecturas`, 20 funciones) | 32/32 |
| Presupuesto — versiones, detalle, catálogo y comisión de vendedor (`Presupuesto\Versiones`, 7 funciones) | **Laravel** | 22/22 |
| Presupuesto — visitadores: asignaciones, rutas, ciudades, equipos, importar listado (`Presupuesto\Visitadores`, 10 funciones) | **Laravel** | 32/32 |
| Presupuesto — pesos por zona, vendedor y producto, exclusiones (`Presupuesto\Pesos`, 5 funciones) | **Laravel** | 17/17 |
| Presupuesto — generar reparto por vendedor (`Presupuesto\Reparto`, motor v3 de 980 líneas) | **Laravel** | 5/5 |
| Presupuesto — publicación: validar mes/versión, sincronizar a v6, no asignado, publicar mes/versión/unificada (`Presupuesto\Publicacion`) | **Laravel** | 23/23 |
| Presupuesto — recalcular configuración y comisiones (`recalcular_presupuesto_configuracion_v1`, `recalcular_presupuesto_comisiones_v1_8`) | **Laravel** (`Publicacion`) | incluidos arriba |
| Presupuesto — sustituir vendedor (`sustituir_vendedor_v1`, `Presupuesto\Sustitucion`) | **Laravel** | 10/10 |
| Presupuesto — importación fiel (`importar_presupuesto_fiel_v1`, `Publicacion`) | **Laravel** | 10/10 |
| Presupuesto — propuesta automática (`generar_presupuesto_propuesta`, `Versiones`; modelo estacional 50/30/20 o proyección del año publicado) | **Laravel** | 5/5 |

**Presupuesto completo en Laravel (2026-11-13):** las 46 funciones que usa la pantalla las atiende Laravel; el controlador ya no llama al BI
para ninguna. Lo único que queda del BI dentro de esos procesos:
  - **Retirado (2026-11-13):** el paso `VISITADORES_COMISIONES` de la publicación (`core.refresh_dashboard_comisiones_mes`, módulo antiguo
    de visitadores). Solo llenaba tablas que Laravel no lee (`comision_visitador_producto_presupuesto`, `dashboard_comisiones_*_cache`,
    `fact_presupuesto_visitador`, `comision_visitador_base`). La lista de rutas de Admin → Usuarios, que leía `comision_visitador_base`
    (copia del 17-ago, desactualizada), ahora sale del catálogo vigente; es idéntica a esa copia rehecha hoy (109/109 rutas).
  - `asegurar_presupuesto_mes_v6`: si un mes no tiene presupuesto v6, el original crea uno automático desde el histórico. En Laravel ese
    camino lanza un error claro (no ocurre al recalcular, porque la sincronización deja el mes en la versión publicada).
- Presupuesto usa `Admin\Presupuesto\Despachador`: si la función está portada la atiende Laravel con los mismos parámetros `p_*`;
  ya no hay respaldo al BI (se borró el 2026-11-16 junto con `AdminBase::ejecutar()`): una función no portada responde 501.
- **Hallazgo (igual en el original y en Laravel):** al volver a publicar la v63 en noviembre, el paso posterior `VENDEDORES_COMISIONES`
  registra el error "llave duplicada viola restricción de unicidad «uq_presupuesto_vendedor_producto_v6»". La publicación termina, pero
  ese paso falla: hay que revisar el dato duplicado antes de republicar en producción.
- Comparador: `ignorar` acepta rutas anidadas (`respuesta.recalculo.generation.generationId`); los ids de versiones nuevas salen de una
  secuencia y no se comparan (tampoco dentro de los mensajes de error).
- Error previo corregido: `vis_guardar_asignacion_v1` y `vis_guardar_ruta_v1` nunca funcionaban desde Laravel (reciben un parámetro
  llamado `p` y `BiDatabase` solo aceptaba `p_*`). Ahora los atiende Laravel; `BiDatabase` acepta también `p`.
- Algunas funciones originales tienen textos con codificación rota en la base (p. ej. "jerarquÃ­a"); Laravel responde el texto correcto
  y `bi:comparar-admin` corrige esa codificación del lado original antes de comparar.
- Error corregido en el camino: el ayudante `accion()` de `AdminBase` chocaba con la acción `accion` de la ruta de Presupuesto
  (la pantalla daba error); ahora se llama `ejecutarAccion()`. Verificado: las 7 pantallas de Administración responden 200.
- **Disparadores que siguen en la base** (solo normalizan o encolan; también los dispara la sincronización externa, por eso no se movieron):
  `dim_sucursal` (encola visitadores y pide refrescar el detalle de ventas: `vis_refrescar_ventas`, que el procesador de Laravel aún
  no hace — pendiente para la fase SAP), `bridge_producto_comision` y tablas de configuración de visitadores (encolan visitadores),
  tablas de configuración de comisiones y `app_cliente_responsable_v1` (encolan vendedores), `dim_producto` (normaliza la línea),
  `dim_producto_proyecto_homologacion` (marca producto pendiente de facturación).

**Siguiente:** creación automática del presupuesto v6 desde el histórico,
sincronización SAP (incluye `vis_refrescar_ventas`), pantalla para editar la matriz rol-permiso y, al final, borrar el rol `ibero_lectura`.

## Plan del motor de comisiones (decidido por el usuario el 2026-11-12; HECHO)

**Opción 1: pasar el MOTOR DE COMISIONES a Laravel**, y después migrar las 4 pantallas que leen sus resultados
(Ventas vs Presupuesto → Vendedores y Visitadores, Comisiones → Vendedores y Visitadores).

Por qué: hoy el cálculo de comisiones vive en Supabase (`core.procesar_mes_comisiones_v6_seguro` → `procesar_mes_comercial_v6_base`,
`generar_distribucion_presupuesto_v6`, `_refresh_presupuesto_vendedor_fuente_facturacion_v3`, `comision_calcular_gerencia_v6`,
`asegurar_presupuesto_publicado_v1_8`, `completar_presupuesto_no_asignado_v1`, `aplicar_distribucion_tipo_vendedor_v1`; ~2.650 líneas)
y **se dispara al abrir** Ventas vs Presupuesto (`get_dashboard_ventas_cumplimiento_v2_calc_v1`, si el resultado del mes tiene más de 2 minutos).
Escribe en `core.comision_resultado_detalle_v6`, `core.comision_resultado_participante_v6` y relacionadas.

Plan acordado:
1. **Entender el cálculo mes a mes**: leer las funciones de arriba (en `supabase_clone\out\funciones`), listar qué tablas lee y cuáles escribe, y las reglas de negocio (reparto del presupuesto, atribución de venta por vendedor/producto, devoluciones, comisión, gerencia).
2. **Escribirlo en Laravel** como un proceso (Job/Command, p. ej. `php artisan bi:procesar-comisiones {mes}`) que corre cuando llegan datos nuevos de SAP o se publica un presupuesto, **nunca al abrir una pantalla**.
3. **Validar mes por mes**: correr el proceso de Laravel sobre la copia local y comparar sus resultados contra los de Supabase **al centavo** (vendedor × producto × mes) antes de darlo por bueno. Las comisiones se pagan: cero tolerancia.
   - Para comparar sin pisar los datos originales, que Laravel escriba primero en tablas propias (p. ej. esquema o tablas `*_laravel`) o comparar en memoria.
4. Después, migrar las 4 pantallas para que lean esos resultados desde Laravel (con `bi:comparar`, como las demás).
5. Recordatorio: todo esto solo sobre la copia local (`supabase_copia`). Nunca escribir en Supabase producción.

**Pendiente menor al retomar:** confirmar el resultado de `bi:comparar productos|productos-evolucion|productos-detalle|productos-buscar --usuario=13 --usuario=17 --usuario=6` (gerente, supervisor, ejecutivo). Con admin ya coincidían; esta corrida quedó en segundo plano al apagar la PC, hay que repetirla.

## 1. Dónde estamos

| Fase | Estado |
|---|---|
| Copia local de Supabase (`supabase_copia`) | Hecha |
| Las 18 pantallas migradas a Laravel + React + Inertia (llamando a las funciones de Supabase) | Hecha, verificadas contra la web |
| **Rediseño visual** (shadcn/ui, estilo corporativo sobrio) | En curso: Vista Ejecutiva + layout + menú listos |
| **Pasar la lógica de Supabase a Laravel** (dejar de llamar funciones SQL y cachés de resultados) | En curso: **las 11 pantallas de consulta y los 2 motores de comisiones listos**. Faltan menú/permisos y Administración |
| Sincronización con SAP | Al final |

## 2. Reglas que no se negocian

1. **Nunca escribir en Supabase producción.** Solo lectura con el usuario `ibero_lectura`. En la web original (proyecto-iberofarmacos.vercel.app) solo mirar; no pulsar botones que guardan ("ACTUALIZAR", "Cargar cobros", etc.).
2. Las contraseñas viven en `supabase_clone\.supabase_url` (fuera del repo) y en `.env`. No copiarlas al repo ni repetirlas.
3. Softland es **solo histórico** (no se sincroniza).
4. El usuario prefiere que se trabaje de corrido, sin pedir confirmación pantalla por pantalla, y que se le reporte al final con cifras comprobadas.

## 3. Cómo arrancar el entorno

```powershell
cd C:\laragon\www\BiPanelIbero\BiIbero
npm run build            # o npm run dev mientras se trabaja en el frontend
php artisan serve --host=127.0.0.1 --port=8000
```

- `.env` tiene `PHP_CLI_SERVER_WORKERS=4` (sin eso, una carga lenta en segundo plano bloquea todo el servidor de desarrollo).
- PostgreSQL 18 local: BD `bi_ibero` (Laravel) y `supabase_copia` (datos del BI, conexión `bi`).
- Usuario de prueba admin: `BI_TEST_EMAIL` / `BI_TEST_PASSWORD` en `.env`.

## 4. Dirección acordada: lógica en Laravel, no en Supabase

**Decisión del usuario (2026-11-12):** reducir la complejidad de Supabase. En lugar de llamar funciones de PostgreSQL (que encadenan otras funciones y guardan resultados en `core.dashboard_rpc_cache`), cada pantalla calcula sus datos en **servicios de Laravel** que leen las tablas directamente.

**Qué SÍ se sigue leyendo:** las tablas de datos ya limpios, aunque se llamen `*_cache` (p. ej. `core.dashboard_facturacion_fuente_cache` = venta diaria resumida). No son copias de resultados: son los datos. Hoy las llena una función de Supabase a partir de `public.vw_ventas_completas`; **en la fase SAP las llenará Laravel**.

**Qué NO se recomienda:** calcular desde las ventas en bruto (6,4 millones de filas) en cada consulta: sería lento.

### Método por pantalla (el que funcionó con la Vista Ejecutiva)

1. **Rastrear la cadena** de funciones de la pantalla. Las definiciones están en `supabase_clone\out\funciones\*.sql`. Patrón típico:
   `get_dashboard_X` (envoltorio: permiso + `dashboard_rpc_cache`) → `get_dashboard_X_calc_v1` (alcance del usuario + presupuesto) → `get_dashboard_X_impl_perm_v1` (cálculo).
   Listar tablas y funciones usadas:
   ```bash
   grep -oiE "(from|join)\s+(core|reporting|public)\.[a-z_0-9]+" archivo.sql | sort | uniq -c
   grep -oE "core\.[a-z_0-9]+\(" archivo.sql | sort -u
   ```
2. **Probar primero en SQL** (psql sobre `supabase_copia`) una consulta candidata contra la función original con varios filtros, hasta que cuadre al centavo.
3. **Escribirlo en `app/Services/Bi/`**, reutilizando lo que ya existe (ver §5). Mismo formato de respuesta que la función original, para no tocar el frontend.
4. **Comando de comparación**: `php artisan bi:comparar {pantalla} [--usuario=ID ...] [--detalle]` compara la respuesta COMPLETA (campo por campo, tolerancia 1 centavo) de la función original contra Laravel, con 9 filtros de prueba × usuarios (por defecto admin, gerente y supervisor; usar `--usuario` con roles que sí vean la pantalla), incluidos los casos de "acceso denegado". Para una pantalla nueva se agrega una entrada en `CompararPantalla::pantallas()`. No se da por bueno hasta que todo coincida. (La Ejecutiva tiene además `bi:comparar-ejecutiva`.)
   - **Ojo:** si una tabla de datos está vacía en la copia local, ambas versiones dan 0 y "coinciden" sin probar nada. Revisar que haya cifras. Varias tablas `*_cache` regenerables no se copiaron; se llenan con su función `refresh_*` solo en la copia local, p. ej. `core.refresh_dashboard_presupuesto_visitadores_ventas_v1(inicio_mes, fin_mes)` mes a mes (ya hecho para 2025-01 → 2026-11); luego `truncate core.dashboard_rpc_cache`.
5. **Medir tiempos** (script con `microtime` + `DB::enableQueryLog()`). Si una consulta es lenta, ver el plan con `EXPLAIN (ANALYZE, BUFFERS)`. Truco que ya hizo falta: agrupar primero en un CTE `MATERIALIZED` y luego hacer los cruces (12 s → 0,16 s).
6. Si algo sigue siendo lento: prop diferida de Inertia (`Inertia::defer`) + `Cache::remember` de Laravel con clave que incluya `core.sap_etl_state.last_success_at` (se invalida sola con cada sincronización).
7. Documentar en `contexto-migracion-y-sincronizacion-sap.md` §6.1 y actualizar la tabla de §6 de este documento.

**Diferencias con el original:** solo deliberadas y anotadas (p. ej. "Productos con venta" ahora respeta el filtro de grupo). Si una regla del original parece rara, se le presenta al usuario; no se elimina por cuenta propia.

## 5. Servicios ya construidos (reutilizables)

| Clase | Qué hace | Reemplaza a |
|---|---|---|
| `App\Services\Bi\AlcanceComercial` | Zonas, grupos, líneas y vendedores que puede ver cada usuario; error 403 si pide algo fuera de su alcance. `lista()` convierte `"A\|B"` en arreglo | `get_effective_sales_scope_v1`, `resolve_dashboard_zone_v1`, `resolve_dashboard_group_v1` |
| `App\Services\Bi\VentaDiaria` | Consulta base sobre `dashboard_facturacion_fuente_cache` con todos los filtros, grupo normalizado (`GRUPO`), exclusión de Maquila y de valores "no definidos" | Filtros repetidos en cada `*_impl` |
| `App\Services\Bi\PresupuestoComercial` | Presupuesto publicado por zona y mes (vendedores + no asignado repartido) y presupuesto repartido por historia (con provincia/cadena) | `get_dashboard_ventas_cumplimiento_v2` (parte de presupuesto), `get_presupuesto_distribuido_executive_v2` |
| `App\Services\Bi\Calendario` | Días hábiles (lunes a viernes menos feriados activos) | `core.es_dia_habil` |
| `App\Services\Bi\VistaEjecutiva` | Todo lo de la Vista Ejecutiva | `get_dashboard_executive*`, `get_dashboard_executive_anual*`, `get_dashboard_pedidos_kpi*` |
| `App\Services\Bi\AlcanceVisitadores` | Rutas (zona + línea + equipo + ruta + representante) que ve cada visitador o gerente de visitadores, y las normalizaciones de texto, línea y equipo (en PHP y en SQL) | `get_visitador_scope_rows_v2`, `visitador_tuple_permitida_v1`, `fn_norm_txt`, `fn_comision_linea_norm`, `fn_comision_equipo_norm` |
| `App\Services\Bi\VentasDiarias` | Ventas Diarias | `get_dashboard_diarias_v2` → `get_dashboard_diarias_front` |
| `App\Services\Bi\ResumenVentas` | Resumen de Ventas: modos Facturación / Ventas desglosadas y camino de visitadores (tabla temporal por petición) | `get_dashboard_ventas_desglosadas*` (`impl_perm` e `impl_visitadores`) |
| `App\Services\Bi\DevolucionesSap` | Base unificada de devoluciones (Softland + SAP), cadena del cliente, tarjeta de devoluciones del Resumen | `vw_dashboard_devoluciones_base`, `clasificar_cadena_dashboard`, `get_dashboard_devoluciones_kpi` |
| `App\Services\Bi\DevolucionesDashboard` | Pantalla Devoluciones (con reglas de alcance por línea) | `get_dashboard_devoluciones_executive*`, `_anual*` |
| `App\Services\Bi\VistaComparativa` | Vista Comparativa | `get_dashboard_comparativa*` |
| `App\Services\Bi\AnalisisClientes` | Análisis → Clientes y sus catálogos | `get_dashboard_clientes_analisis_v1` → `_scope_v2`, `get_dashboard_clientes_catalogos_v1`, `fn_dashboard_clientes_norm_v1/_tokens_v1`, `cliente_codigo_sap_22m` |
| `App\Services\Bi\AnalisisProductos` | Análisis → Productos (análisis, evolución, detalle, buscador) | `get_dashboard_productos_*`, `get_dashboard_productos_valid_scope_v2`, `get_dashboard_productos_scope_v1`, vista `sap_cliente_geo_actual_v1` |
| `App\Services\Bi\CumplimientoVendedores` | Ventas vs Presupuesto → Vendedores (y ciudades) | `get_dashboard_ventas_cumplimiento_v2*`, `_ciudades_v2` |
| `App\Services\Comisiones\MotorComisiones` | Motor de comisiones de vendedores (`bi:procesar-comisiones`) | `procesar_mes_comisiones_v6_seguro` y lo que llama |
| `App\Services\Comisiones\MotorVisitadores` | Motor de visitadores (`bi:procesar-visitadores`) y normalizaciones `fn_vis_*` en SQL | `vis_recalcular_mes_v1`, `vis_calcular_mes`, `vis_calcular_comision_mes`, `vis_refrescar_sucursales_incompletas` |
| `App\Services\Bi\CumplimientoVisitadores` | Ventas vs Presupuesto → Visitadores (+ ciudades, cadenas) y el alcance de visitadores (`ambito()`) | `get_dashboard_visitadores_*_nucleo_v1`, `vis_dash_base_v1`, `vis_dash_ambito_v1`, `vis_dash_ruta_persona(s)_v1` |
| `App\Services\Bi\ComisionesVisitadores` | Comisiones → Visitadores | `get_dashboard_comisiones_nucleo_v1` |
| `App\Services\Bi\ComisionesVendedores` | Comisiones → Vendedores (normal / preliminar / mixto + participantes "pull") | `get_dashboard_comisiones_v7*`, `_motor_v1`, `_base_20260912`, `_preliminar_v1`, `fn_comision_codigo_empleado_v1` |
| `App\Services\Comisiones\CobrosVendedores` | Carga mensual de cobros (previsualizar / aplicar) | `admin_cargar_cobros_vendedores_v1` |

## 6. Estado por pantalla

"Funciones" = lo que el controlador todavía llama en Supabase.

| Pantalla | Ruta | Lógica | Diseño nuevo | Funciones que aún usa |
|---|---|---|---|---|
| Vista Ejecutiva | `/executive` | **Laravel** | Sí | Ninguna |
| Resumen de Ventas | `/ventas-desglosadas` | **Laravel** | No | Ninguna |
| Ventas Diarias | `/diarias` | **Laravel** | No | Ninguna |
| Vista Comparativa | `/comparativa` | **Laravel** | No | Ninguna |
| Devoluciones | `/devoluciones` | **Laravel** | No | Ninguna |
| Análisis → Productos | `/productos` | **Laravel** | No | Ninguna |
| Análisis → Clientes | `/analisis-clientes` | **Laravel** | No | Ninguna |
| Ventas vs Presupuesto → Vendedores | `/presupuesto/vendedores` | **Laravel** | No | Ninguna (ya no dispara el cálculo al abrir) |
| Ventas vs Presupuesto → Visitadores | `/presupuesto/visitadores` | **Laravel** | No | Ninguna |
| Comisiones → Visitadores | `/comisiones` | **Laravel** | No | Ninguna |
| Comisiones → Vendedores | `/comisiones-vendedores` | **Laravel** | No | Ninguna (incluida la carga de cobros) |
| Admin (Usuarios, Clientes, Productos, Presupuesto, Feriados, Procesamiento, Sucursales) | `/admin/*` | **Laravel** | No | Ninguna |
| Menú y permisos de pantalla | (todas) | **Laravel** (`App\Services\Permisos`, spatie) | Sí | Ninguna |
| Admin → Usuarios: pantallas por rol y excepciones | `/admin/usuarios` | **Laravel** | No | Rol: `set_usuario_rol_v1` (perfil/alcance) + rol de Laravel. Alcance de datos: funciones del BI |

### Orden sugerido para seguir

1. ~~Ventas Diarias, Resumen de Ventas, Comparativa y Devoluciones~~ **hechas (2026-11-12)**: idénticas al original con `bi:comparar` (Resumen también con 2 gerentes de visitadores y datos reales).
2. ~~Análisis → Clientes y Análisis → Productos~~ **hechas (2026-11-12)** (`AnalisisClientes`, `AnalisisProductos`), idénticas con `bi:comparar clientes|clientes-catalogos|productos|productos-evolucion|productos-detalle|productos-buscar`. Para listas cuyo orden entre empates es arbitrario en el original, el comparador acepta `'conjuntos' => [lista => clave]`.
   - **Hallazgo antes de seguir:** Ventas vs Presupuesto (vendedores y visitadores) y Comisiones leen los resultados del **motor de comisiones** (`core.comision_resultado_detalle_v6`, etc.). Ese motor es un proceso que **escribe** (`procesar_mes_comisiones_v6_seguro` → `procesar_mes_comercial_v6_base`, `generar_distribucion_presupuesto_v6`, ~2.650 líneas) y **la propia lectura del dashboard lo dispara** (`get_dashboard_ventas_cumplimiento_v2_calc_v1` lo ejecuta si el resultado del mes tiene más de 2 minutos). Migrar estas pantallas implica decidir qué hacer con ese motor (ver decisión pendiente con el usuario).
3. ~~Ventas vs Presupuesto → Vendedores~~ **hecha**.
4. ~~Motores de comisiones (vendedores y visitadores), Visitadores, Comisiones~~ **hechas (2026-11-13)**.
5. **Menú y permisos → roles y permisos de Laravel** (ver §6.2). Hacerlo al terminar los tableros y justo antes de Administración.
6. Administración (escrituras): migrar cuando las pantallas de lectura ya no dependan de Supabase.
7. **Sincronización SAP**: que Laravel llene las tablas de datos (`dashboard_facturacion_fuente_cache` y demás) en vez de las funciones `refresh_*`. Ver §5 del documento de contexto.

### 6.1 Regla: consultas vs modelos (acordado 2026-11-12)

- **Tableros** (sumas, agrupaciones, rankings): `DB::connection('bi')->table(...)` o SQL escrito en PHP (`DB::select` con CTE cuando hace falta controlar el plan), siempre **dentro de servicios** en `app/Services/Bi/`. No usar Eloquent: devuelven agregados, no registros, y son tablas grandes.
- **Administración** (usuarios, clientes, productos, feriados, presupuestos, alcances): **modelos Eloquent** (relaciones, validación, casts, `$fillable`, eventos para auditoría). Al crearlos: `$connection = 'bi'`, `$table = 'core.xxx'` y `$timestamps = false` si la tabla no tiene `created_at/updated_at` estándar.

### 6.2 Plan: menú y permisos de pantalla a Laravel (acordado 2026-11-12)

Hoy (Supabase):

| Tabla | Qué guarda |
|---|---|
| `core.app_profiles` | rol de cada usuario (37 usuarios) |
| `core.app_role_permissions` | pantallas por rol con `can_view`, `can_export`, `can_configure`, `can_publish` (83 reglas, 16 rutas) |
| `core.app_user_route_permissions_v1` | excepciones por persona: `can_view` true/false sobre una ruta (29 filas) |
| `core.app_user_data_role_v1` | rol alternativo solo para el alcance de datos |
| `get_current_app_context` (+ `_base_20260929`) | arma el menú; lo usa `App\Services\AppContext` y el middleware `pantalla:` |

Destino (Laravel), con **spatie/laravel-permission**:
- Roles: los 8 actuales (admin, ejecutivo, gerente, supervisor, vendedor, encargado_linea, gerente_visitadores, visitador).
- Permisos por pantalla y acción: `executive.ver`, `presupuesto.exportar`, `presupuesto.configurar`, `presupuesto.publicar`, …
- Excepciones por persona: permisos directos al usuario para **dar** acceso; para **quitar** acceso que da el rol, tabla propia de denegaciones (spatie solo suma).
- Menú en `config/menu.php`, filtrado por permisos. Middleware `pantalla:` → `can:xxx.ver`. En React, ocultar Exportar/Publicar/Configurar según permisos compartidos por Inertia.
- El **alcance de datos** (zonas, grupos, líneas, vendedores) NO es un permiso: sigue en `App\Services\Bi\AlcanceComercial`; más adelante leerá tablas propias de Laravel.

Pasos:
1. Comando que copie roles, permisos y excepciones de Supabase a las tablas de Laravel.
2. Comando de comparación: para los 37 usuarios × 16 pantallas, Laravel permite/niega lo mismo que `get_current_app_context` y el menú sale igual.
3. Cambiar middleware y menú; retirar `AppContext`.
4. Migrar Administración → Usuarios para editar roles/permisos en Laravel (con modelos Eloquent).

Momento: **al terminar los tableros y antes de Administración**. Mientras los usuarios se administren en Supabase, los permisos se siguen leyendo de ahí para no tener dos fuentes desincronizadas.

**HECHO 2026-11-13:**
1. `bi:importar-permisos` copió 8 roles, 76 permisos (19 rutas × ver/exportar/configurar/publicar), 38 usuarios, 5 permisos directos y 24 denegaciones.
   Ahora se niega a correr si Laravel ya tiene roles (`--forzar` para volver a copiar: pisaría lo editado en Laravel).
2. `bi:comparar-permisos`: **los 38 usuarios coinciden** con `get_current_app_context` en cada pantalla y en el menú. Prueba HTTP: 200/403 correctos y `/` lleva a la primera pantalla permitida.
3. Middleware `pantalla:`, menú (Inertia) y login usan `App\Services\Permisos`; `AppContext` eliminado. Nombres de permiso: ruta sin "/" inicial + acción (`presupuesto/visitadores.ver`, `comisiones.exportar`).
   Regla fija del original en código: visitador y gerente de visitadores solo ven `/ventas-desglosadas`, `/presupuesto/visitadores`, `/comisiones`.
4. Admin → Usuarios: excepciones por persona (mostrar / ocultar / restablecer) y rol se guardan en Laravel; la pantalla los lee de Laravel.
   `core.app_role_permissions` y `core.app_user_route_permissions_v1` ya no se leen ni se escriben (quedan como histórico).
   Pendiente: la matriz de permisos por ROL (editar qué pantallas da cada rol) no tiene pantalla todavía; hoy solo con tinker/seeder.

## 7. Rediseño visual: estado y pendientes

Hecho: tema (`resources/css/app.css`, primario azul `#1c4f9c`, menú azul marino, naranja Ibero `#f47c20`), layout con menú lateral contraíble y barra superior con perfil, componentes `components/filtros.tsx` (periodo con atajos y filtros de selección múltiple) y `components/kpi.tsx` (`StatCard` con % de cumplimiento grande, marca de "esperado a la fecha" y proyección), aviso "Cargando datos". Estilo sobrio pedido por el usuario: **sin degradados, sin pastillas de color, esquinas 0.5rem, sin animaciones decorativas**.

Vista Ejecutiva, mejoras propias (no existen en la app original): comparación contra los mismos días del mes anterior, ritmo por días hábiles, proyección de cierre, línea de presupuesto mensual en el gráfico, mes en curso atenuado.

Pendientes recomendados y aún no aprobados (de la revisión con el usuario):
- Vista Ejecutiva: montos grandes sin centavos (exacto al pasar el mouse); llenar la tarjeta "Ventas del último día" (mini-gráfica); fechas legibles; textos secundarios un poco más grandes; columna de crecimiento en los rankings; nombres en formato título; gráfico mensual menos alto; nota "si se mantiene el ritmo diario" en la proyección.
- Menú: logo en versión blanca/transparente (pedir archivo al usuario), quitar o acortar "Panel de inteligencia comercial", renombrar "Config. X" → "X", plegar Administración, isotipo al contraer, quitar el pie.
- Aplicar el mismo estilo al resto de pantallas (siguen con el estilo morado anterior).

## 8. Otros pendientes conocidos

- La copia local está al **11/11/2026 8:00 p. m.**; la web original va más adelante. Para comparar con la web, refrescar la copia con `supabase_clone\clonar_supabase.ps1` (solo lee de Supabase) y luego `reconstruir_caches.ps1`.
- `public.fact_pedidos_sap` está vacía en la copia: los pedidos pendientes no se pudieron validar con datos.
- Filtro "Producto" en Resumen de Ventas y Comparativa; importar listado de visitadores; modo "Presupuesto" del selector de la pantalla de presupuesto.
- Pedir al programador externo el código del ETL y del frontend; al terminar, borrar el usuario `ibero_lectura` en Supabase.
