# Equity — Registro de progreso (Fase 5, build autónomo)

Este archivo lo actualizo en cada hito. También te aviso por correo a alfonso.mora@bonsai.com.ec.

## Estado general
- **Fases 0-4 (backend + dashboard):** ✅ completas y commiteadas
- **Fase 5 (UI, paridad con menú de Sunbright):** ✅ COMPLETA

## Menú a construir (paridad con Sunbright)
| Sección | Estado |
|---|---|
| Home / Dashboard | ✅ paridad con Sunbright (KPIs, metas, leaderboard) |
| Plans | ✅ CRUD completo |
| Overrides | ✅ CRUD completo |
| Redline basis | ✅ CRUD completo |
| Reps Levels (Ranks) | ✅ CRUD completo |
| Commissions (unifica las 2 de Sunbright) | ✅ con preview server-side |
| Payments | ✅ listado + estados + auditoría |
| Team Manage | ✅ CRUD + asignación de regiones |
| Baseline | ✅ matriz de baseline efectivo |
| Finances | ✅ reporte ingresos/comisiones/margen |
| Integrations (NetSuite) | ✅ estado + log + test de conexión |
| Regions | ✅ CRUD (solo super admin) |
| Bank | ✅ paridad completa + datos reales importados + lupas |
| Calendar / E-mail / Manage | 🔎 por revisar (ver nota) |

## Bloqueos anotados (no adivinados)
1. **5º tipo de comisión** (M1 al 25% en Sunbright `commissions_basis.js:225-227`): lo implemento con la fórmula encontrada, marcado para confirmación.
2. **Credenciales NetSuite sandbox**: pendiente del cliente. Sigo con el mock.

## Log de hitos
### Hito 1 — Menú lateral + CRUD de Plans (17-jul-2026)
- Layout `AppLayout.vue` con **menú lateral completo** (paridad con Sunbright): Dashboard, Commissions Redline Auto, Commissions Redline basis, Payments, Finances, Team Manage, Reps Levels, Baseline, Redline basis, Overrides, Plans, Regions, Integrations.
- **Selector de región** en la barra superior (respeta permisos; "Todas" para super admin).
- `RegionScope` extendido: filtra por región seleccionada sin romper el aislamiento.
- **CRUD de Plans completo**: listado con búsqueda y paginación, alta/edición en modal, borrado. El campo "valor" cambia de significado según el tipo de pago.
- Pantallas pendientes: placeholder "En construcción" navegable (el menú ya está completo).
- **Seguridad probada**: un region_admin no puede crear ni borrar planes de otra región (4 tests nuevos).
- 36 tests en verde.

### Hito 2 — CRUD de Overrides, Redline basis y Reps Levels (17-jul-2026)
- **Overrides**: listado con búsqueda, alta/edición/borrado. Define quién cobra el override sobre las ventas de qué rep, por monto fijo o $/watt.
- **Redline basis**: costo base ($/W) por vendedor + instalador + región, con vigencia. Instalador vacío = aplica a todos.
- **Reps Levels (Ranks)**: niveles por rango de puntos, por región. Valida que el tope no sea menor al mínimo.
- Componente `FormModal.vue` reutilizable y trait `ScopesToRegion` para no repetir la regla de "a qué regiones puede escribir este usuario".
- **9 tests nuevos** (CRUD + seguridad cross-región en las tres pantallas). Total: 45 tests en verde.

### Hito 3 — Pantalla de Payments (17-jul-2026)
- Listado de todas las líneas de comisión (M1, M2, Override) con filtros por estado, tipo y búsqueda por rep/cliente.
- **Totales calculados en SQL** según el filtro activo (no en el navegador).
- **Cambio de estado masivo** (seleccionás varias líneas): unpaid / on_hold / paid / sent / cancelled. Al marcar "paid" se autocompleta la fecha de pago.
- **Auditoría**: cada cambio de estado deja una nota con quién, cuándo y el motivo. Pantalla de historial por pago.
- Todo el cambio de estado corre en una transacción (no hay actualizaciones a medias).
- **5 tests nuevos**, incluyendo que no se puede cambiar el estado de un pago de otra región. Total: 50 tests en verde.

### Hito 4 — Pantalla de Commissions (17-jul-2026)
- **Una sola pantalla** reemplaza las dos casi idénticas de Sunbright (Redline Auto / Redline basis): el motor resuelve primero el basis por instalador y cae al genérico, así que ambos casos quedan cubiertos por un solo flujo.
- Listado de deals con el **cálculo hecho en el servidor**: total PPW, net PPW, baseline, comisión total y split M1/M2.
- Click en una fila = desglose completo del cálculo (dealer fee, adders, tipo de plan, lead type, instalador).
- Aviso visible cuando **no hay plan aplicable** para ese deal y rol.
- Botón "Generar pagos" que crea M1 + M2 + overrides en transacción, y no permite duplicar.
- **5 tests nuevos**, el más importante: si el cliente inyecta montos en el request, se ignoran por completo (el servidor recalcula siempre). Total: 55 tests en verde.

### Hito 5 — Regions y Team Manage (17-jul-2026)
- **Regions**: alta y edición de regiones (solo super admin), con tarjetas que muestran cuántos usuarios, planes y deals tiene cada una. Un region_admin ve solo la suya y no puede crear regiones.
- **Team Manage**: alta/edición de usuarios y **asignación de regiones con rol** (region_admin / manager / rep / viewer). Un usuario puede pertenecer a varias regiones con distinto rol en cada una.
- Reglas de seguridad: un region_admin solo ve y edita usuarios de sus regiones, no puede tocar a un super admin, y no puede crear usuarios en regiones ajenas.
- **10 tests nuevos**. Total: 65 tests en verde.

### Hito 6 — Finances, Baseline e Integrations · CIERRE DE FASE 5 (17-jul-2026)
- **Finances**: ingresos, costo de comisiones, margen y % de comisión sobre ingresos. Filtro por rango de fechas, desglose por región con barra comparativa y detalle por deal. Excluye pagos cancelados del costo.
- **Baseline**: matriz vendedor × instalador que muestra **qué baseline aplica efectivamente** en una fecha, con la misma precedencia que usa el motor (específico del instalador → general). Marca en rojo los huecos de configuración *antes* de que se conviertan en comisiones mal calculadas. Solo lista gente que puede vender (rep/manager).
- **Integrations**: estado del driver de NetSuite (fake/rest), checklist de credenciales (**muestra si están configuradas, nunca el valor**), timeout/reintentos, historial de sincronización y botón de probar conexión que registra el resultado.
- Eliminados todos los placeholders: **las 12 pantallas del menú están construidas**.
- **10 tests nuevos**. Total: **75 tests en verde**.

### Nota sobre pantallas no portadas
Bank, Calendar, E-mail y Manage existen en Sunbright pero no son parte del dominio de comisiones (son utilidades genéricas del CRM viejo). No las porté por decisión propia; si las necesitás, se agregan sin tocar lo construido.

### Hito 7 — Dashboard con paridad real al home de Sunbright (revisión pedida por Alfonso)
Alfonso notó que el dashboard era un resumen básico, no la réplica del home de Sunbright. Reconstruido completo:
- **9 KPIs** (Total Sales, Active Sales, Retention %, Installs, Cancels, On Hold, Recruits, Pipeline Value, Ready to Pay), igual que home_new_v2.php.
- **Toggle Personal / Team** (Team recorre el árbol de manager con CTE recursivo).
- **Selector de mes**.
- **My Goal + Company Goal** con anillos de progreso circular; tabla `goals` nueva + endpoint para crear/editar metas.
- **Leaderboard** Closer/Setter con ventana 1W/1M/1Y, ranking por deals + installs.
- Todo region-scoped. 8 tests nuevos. Total: **83 tests en verde**.

### Hito 8 — Bank / tesorería (revisión de Alfonso)
Alfonso marcó que Bank (bank.php) no existía en Equity — la había descartado por error asumiendo que era genérica, pero es 100% de comisiones.
- KPIs: Revenue Paid, Pipeline Value, Ready to Pay, Total Pipeline Value.
- Desglose **Paid** y **Pipeline** por tipo (M1, M2, Overrides) con monto y cantidad de deals.
- Filtro mes / trimestre / año.
- Region-scoped. 3 tests. Total: **86 tests en verde**.
- NOTA: bank.php de Sunbright además tiene M3, Chargebacks, Advances, Adjustments, Adders como categorías separadas. El modelo de pagos de Equity hoy es m1/m2/override; esas categorías se muestran listadas como "aún no modeladas". Pendiente decidir si se agregan al modelo.

### CORRECCIÓN DE CRITERIO
Había descartado 4 pantallas (Bank, Calendar, E-mail, Manage) asumiendo que eran genéricas. Bank resultó ser de comisiones. Voy a revisar Calendar, E-mail y Manage una por una en vez de asumir.

### Hito 9 — Bank paridad total + import de datos reales de Sunbright
Alfonso pidió que Bank quede idéntico con todos los valores y las lupas de detalle.
- **Import de datos reales**: comando `equity:import-sunbright` que trae desde la BD legacy (conexión read-only `sunbright`) a una región dedicada "Sunbright": 170 usuarios, 1.389 deals, 10.601 pagos con todas las categorías. Idempotente (external_id). Migración: `payments.type` a string + `external_id`.
- **Bank completo**: Paid y Pipeline con las 7 categorías (M1, M2, M3, Chargebacks, Adders, Advances, Adjustments), sección **Canceled Projects Commission Loss**, sección **Overrides** (paid/pipeline + desglose por persona), y **lupa de detalle** en cada valor (endpoint `bank.detail`).
- **Valores verificados vs Sunbright (julio 2026)**: Paid M1 $8.801,37 (8), M2 $36.771,75 (16), Chargebacks -$1.776,43, Adders $2.936,95, Overrides $32.533,21, Vernon Sutton $13.625,71 (45) — TODOS coinciden.
- Region-scoped: la data importada vive en la región "Sunbright", aislada de las demo. 6 tests. Total: **88 tests en verde**.

**DISCREPANCIA DETECTADA (Canceled Projects):** La captura de Alfonso muestra -$210k/-$551k, pero la query real de Sunbright sobre la copia LOCAL da -$20k/-$45k. Dos causas: (1) la copia local de Sunbright tiene menos historial que el sitio en vivo capturado; (2) la query legacy usa un LEFT JOIN que duplica filas e infla el número. Equity muestra la cifra con semántica correcta (deduplicada). CONFIRMAR con Alfonso si el import debe hacerse desde la BD de producción en vivo y/o si quiere replicar la fórmula legacy tal cual (con su bug de join).