# Motor de comisiones (vendedores): cómo funciona hoy en Supabase

> Paso 1 del plan "opción 1" (ver `hoja-de-ruta-como-seguir.md`). Leído de `supabase_clone\out\funciones` el 2026-11-13.
> Objetivo: reproducirlo en Laravel con resultados idénticos al centavo.

## Punto de entrada

`core.procesar_mes_comisiones_v6_seguro(mes)`. Hoy se dispara **al abrir** Ventas vs Presupuesto
(`get_dashboard_ventas_cumplimiento_v2_calc_v1`) cuando el resultado del mes en curso tiene más de 2 minutos.
Usa un candado (`pg_advisory_xact_lock`) por mes. Todo corre en una transacción.

```
procesar_mes_comisiones_v6_seguro(mes)
├─ A. _refresh_presupuesto_vendedor_fuente_facturacion_v3(mes)     → venta por vendedor×producto del mes
├─ controles de calidad (si fallan, se cancela todo)
└─ B. procesar_mes_comercial_v6(mes)
   ├─ procesar_mes_comercial_v6_base(mes)
   │  ├─ asegurar_presupuesto_publicado_v1_8(mes)                  → versión de presupuesto vigente
   │  ├─ generar_distribucion_presupuesto_v6(version, mes)         → ajusta el presupuesto por vendedor
   │  │  ├─ aplicar_distribucion_tipo_vendedor_v1                  (carga tipo VENDEDOR, la actual)
   │  │  └─ completar_presupuesto_no_asignado_v1
   │  ├─ atribución de venta → responsable, cruce con presupuesto  → comision_resultado_detalle_v6
   │  ├─ comisión por participante con reglas de pago               → comision_resultado_participante_v6
   │  └─ incidencias y estado del periodo                           → comision_incidencia_v6, comision_periodo_v6
   └─ comision_calcular_gerencia_v6(mes)                            → comisión de gerentes/supervisores (pull)
```

## A. Venta del mes por vendedor (`presupuesto_vendedor_fuente_facturacion_v3`)

1. Borra el mes y lo reconstruye.
2. **Ventas**: `public.fact_ventas_sap` del mes, agrupadas por producto (`item_code`) y vendedor (texto `vendedor`).
   Si no hay filas, usa `public.fact_ventas_raw` (Softland). Venta = `total_venta`; unidades = `cantidad_vendida` o `cantidad`; clientes = distintos `card_code`.
3. **Devoluciones**: `public.fact_devoluciones_sap` del mes (si la venta vino de SAP), por producto y vendedor; monto = |`total_venta_movimiento`|.
4. **Alta automática de vendedores nuevos** (efecto secundario): un nombre de vendedor de SAP que no está en alias ni catálogo
   se registra en `presupuesto_vendedor_catalogo` (código `VDnn` siguiente, zona por su mayor venta, no comisionable),
   `presupuesto_vendedor_alias` y `vendedor_codigo_homologacion`.
5. **Resolución del código de vendedor**: alias normalizado → código de catálogo → nombre de catálogo → el texto si parece código
   (`VD…`, `PV-…`, `E…`) → `PV-AUTO-<md5>`. Zona: la de la venta → la del catálogo → `SIN ZONA`. Grupo: venta → producto → `SIN GRUPO`.
6. Inserta ventas (venta_neta = bruta) y luego devoluciones (resta de la neta y de unidades) por mes×vendedor×producto×zona×grupo.

Controles en `_seguro`: fuente no vacía; si hay facturación (`dashboard_clientes_facturacion_cache`) la fuente no puede ser 0
ni diferir más de **5 %** de la facturación; el resultado debe tener filas y venta.

## B. Cálculo (`procesar_mes_comercial_v6_base`)

### Presupuesto vigente
- `asegurar_presupuesto_publicado_v1_8`: toma la versión **PUBLICADA** del año en `presupuesto_version` (legacy) y asegura su
  espejo en `presupuesto_version_v6` (crea o actualiza; archiva otras del año). Hoy: v6 = 122 (legacy 63).
- `generar_distribucion_presupuesto_v6`: con la carga tipo VENDEDOR (la actual) **no recalcula desde cero**, pero:
  - `aplicar_distribucion_tipo_vendedor_v1`: reescala `fact_presupuesto_vendedor` para que cada producto respete el % por zona
    configurado en `comision_distribucion_tipo_v6` (por tipo de producto; solo si las 2 zonas suman 100 %).
  - `completar_presupuesto_no_asignado_v1`: reparte el presupuesto "sin asignar" (`presupuesto_comercial_no_asignado_v6`)
    entre vendedores con `presupuesto_vendedor_peso_zona` (o 50/50) y `presupuesto_vendedor_peso`; lo inserta como
    `origen = AUTO_V6_COMPLETAR` y desactiva el no asignado.
  - ⚠ Es decir: **cada corrida modifica el presupuesto oficial**. En Laravel esto debería ocurrir al publicar el presupuesto, no en cada cálculo (decidir con el usuario; para la validación se replica igual).

### Atribución de la venta
Por fila de venta (vendedor facturador × producto × zona):
- Zona: `ZONA 1` / `ZONA 2`; cualquier otra → **ZONA 2** ("oficina").
- Tipo de producto: el del presupuesto del producto (`presupuesto_producto_v6`) → el del grupo de la venta → `SIN_CLASIFICAR`.
- Responsable, en este orden:
  1. **Responsable por línea**: `comision_responsabilidad_v6` del facturador → responsable de ETICOS / GENERICOS / OTC (OTC cae a genéricos) si es participante activo y comisionable.
  2. **Fallback de zona**: `comision_fallback_zona_v6`.
  3. **El propio facturador** si es participante activo.
  4. Sin responsable → queda fuera (incidencia CRÍTICA).
- Se excluye la venta `SIN_CLASIFICAR`.

### Detalle (`comision_resultado_detalle_v6`)
Cruce completo (FULL JOIN) entre presupuesto por vendedor×producto×zona (`fact_presupuesto_vendedor`) y venta atribuida.
Cumplimiento = venta neta / presupuesto (0 si no hay presupuesto).

### Participante (`comision_resultado_participante_v6`)
Totales por vendedor y por componente (ÉTICOS, GENÉRICO GENERAL, GENÉRICO CRÓNICO, OTC), cobros (`comision_cobro_v6`: meta y real).
**Comisión** = base_comision × Σ (peso × min(max(cumplimiento_componente, 0), tope)) según `comision_regla_pago_v6` del perfil del participante.
Solo si es comisionable. Estado: NO_COMISIONABLE / PRELIMINAR_SIN_BASE / PRELIMINAR_SIN_META_COBRO / PRELIMINAR.

### Incidencias (`comision_incidencia_v6`, solo informativas)
VENTA_SIN_PRESUPUESTO, TIPO_PRODUCTO_NO_CLASIFICADO, ATRIBUCION_AUTOMATICA_POR_ZONA, SIN_RESPONSABLE (crítica),
BASE_COMISION_NO_CONFIGURADA, COBROS_NO_CARGADOS. El periodo queda CALCULADO o CALCULADO_CON_ADVERTENCIAS.

### Gerencia (`comision_calcular_gerencia_v6`)
Para cada fila activa de `comision_gerencia_v6` (21 hoy) suma los resultados de los vendedores según su regla y calcula:
| Regla | Base de suma | Comisión |
|---|---|---|
| ZONA_1 | vendedores de Zona 1 | 60 % × cumplimiento total (tope 1,2) + 40 % × cumplimiento de cobro (tope 1,2) |
| ZONA_2_SIN_OFICINA | Zona 2 sin oficina | igual que ZONA_1 |
| TOTAL_CON_COBROS | todos | igual que ZONA_1 |
| TOTAL_SIN_COBROS | todos | cumplimiento total (tope 1,2) |
| OTC_ZONA_1_MAS_OFICINA | Zona 1 sin oficina + oficina | cumplimiento OTC (tope 1,2) |
| IF_ZONA_1 / IF_ZONA_2 | su zona sin oficina | 90 % genéricos + 10 % OTC (cada uno tope 1,2; total tope 1,2) |
⚠ Esos porcentajes y topes están **escritos en el código**, no en tablas de configuración.

## Estado en Laravel (2026-11-13): HECHO Y VALIDADO

- Motor: `App\Services\Comisiones\MotorComisiones` (mismas reglas; normalizaciones en línea, sin llamar funciones de Supabase).
  Excepción: la generación de presupuesto "desde configuración" (versiones con carga tipo PRODUCTO) no se portó porque
  la versión vigente es carga por VENDEDOR; si apareciera, el motor se detiene con un mensaje claro.
- Correr: `php artisan bi:procesar-comisiones [2026-11 ...]` (sin mes = mes en curso).
- Validar: `php artisan bi:comparar-comisiones 2026-01 ... 2026-11 [--detalle]` corre original y Laravel en transacciones
  revertidas y compara 10 tablas: fuente V3, detalle, participante, incidencias, presupuesto por vendedor, no asignado,
  periodo, catálogo/alias/homologación de vendedores.
- **Resultado: los 11 meses de 2026 idénticos en las 10 tablas.** Laravel ~2× más rápido (3–6 s por mes vs 8–12 s).
- Detalles de la validación: los ids del presupuesto "sin asignar" cambian en cada corrida (un disparador los recrea y la
  secuencia no se revierte) → se comparan por producto+zona; la venta de Softland (ene–abr) es punto flotante y su suma
  varía en la 10.ª decimal según el orden → los números dentro de JSON se comparan con tolerancia de una millonésima.

### Pendiente
1. Decidir **cuándo corre** el cálculo (ya no debe ser al abrir la pantalla): al terminar cada sincronización con SAP,
   al publicar un presupuesto y al cargar cobros. Hasta tener la sincronización en Laravel, se puede programar con el
   scheduler (p. ej. cada hora en horario laboral) o correr a mano.
2. Migrar las pantallas que leen estos resultados (Ventas vs Presupuesto vendedores/visitadores, Comisiones) y quitar
   la llamada a `get_dashboard_ventas_cumplimiento_v2`, que hoy dispara el cálculo de Supabase.
3. Con el usuario: que el reajuste del presupuesto oficial (tipo/zona y "sin asignar") pase al momento de publicar el
   presupuesto, y que los porcentajes fijos de gerencia (60/40, 90/10, tope 1,2) pasen a configuración.

## Validación prevista
Ambos cálculos (Supabase y Laravel) se corren sobre la copia local **dentro de una transacción que se revierte**,
partiendo del mismo estado; se comparan todas las filas de detalle, participante, fuente e incidencias (sin fechas de proceso).
Meses con datos: 2026-01 a 2026-11 (versión 122).
