# Plan: Módulo Supervisores (SUP-01)

**Fecha inicio**: 2026-05-08  
**Estado**: ✅ IMPLEMENTADO COMPLETO

---

## Decisiones de diseño

| Decisión | Valor |
|---|---|
| Supervisor = entidad separada | Tabla `supervisores` (NO un tipo en `vendedores_cobradores`) |
| Sin vínculo a `personas` | Supervisores son empleados simples, sin FK a `personas` |
| Un supervisor tiene N vendedores/cobradores | Tabla junction `supervisor_vendedores_cobradores` |
| Comisión supervisor | % separados: `porcentaje_comision_ventas` + `porcentaje_comision_cobros` |
| Asignación por dirección | `cliente_direcciones` tiene `vendedor_id`, `cobrador_id`, `supervisor_id` |
| Auto-sugerencia supervisor | Al seleccionar vendedor en form de dirección → se pre-rellena su supervisor |
| Comisión supervisor — lógica | Facturas con `cliente_direccion.supervisor_id = supervisorId` (prioridad) + fallback a facturas sin dirección pero con vendedor del equipo |
| Panel supervisor | Tab "Supervisores" en VendedoresCobradoresModule |

---

## Estado de implementación

### Fase 1 — Base de datos ✅

| Archivo | Estado |
|---|---|
| `prisma/migrations/20260508_supervisores/migration.sql` | ✅ Aplicada |
| `prisma/migrations/20260508_cliente_dir_asignaciones/migration.sql` | ✅ Aplicada |
| `prisma/schema.prisma` — modelos `supervisores`, `supervisor_vendedores_cobradores`, `comisiones_supervisores` | ✅ |
| `prisma/schema.prisma` — `cliente_direcciones` +3 campos + relaciones | ✅ |
| `prisma/schema.prisma` — back-relations en `vendedores_cobradores`, `empresas` | ✅ |

Tablas creadas en BD:
- `supervisores` (sin `persona_id`)
- `supervisor_vendedores_cobradores` (junction N:M)
- `comisiones_supervisores`
- `cliente_direcciones.vendedor_id`, `.cobrador_id`, `.supervisor_id`

### Fase 2 — Backend NestJS ✅

| Archivo | Estado |
|---|---|
| `src/supervisores/supervisores.module.ts` | ✅ |
| `src/supervisores/supervisores.service.ts` | ✅ |
| `src/supervisores/supervisores.controller.ts` | ✅ |
| `src/supervisores/dto/create-supervisor.dto.ts` | ✅ |
| `src/supervisores/dto/generar-comision.dto.ts` | ✅ |
| `src/app.module.ts` | ✅ SupervisoresModule registrado |
| `src/clientes/clientes.service.ts` | ✅ getDirecciones/create/update con vendedor/cobrador/supervisor |
| `src/vendedores-cobradores/vendedores-cobradores.service.ts` | ✅ findVendedoresActivos y findCobradoresActivos incluyen `supervisores_asignados[0]` |

#### Endpoints disponibles

| Método | Ruta | Descripción |
|---|---|---|
| GET | `/supervisores` | Listar (filtros: active, search) + `_count.equipo` |
| GET | `/supervisores/activos` | Solo activos (para selects) |
| GET | `/supervisores/reporte-comisiones` | Reporte filtrable por supervisor + período |
| POST | `/supervisores` | Crear supervisor |
| GET | `/supervisores/:id` | Detalle + equipo completo |
| PATCH | `/supervisores/:id` | Actualizar (incluye toggle active) |
| DELETE | `/supervisores/:id` | Desactivar (soft delete) |
| GET | `/supervisores/:id/equipo` | Listar equipo |
| POST | `/supervisores/:id/equipo` | Asignar vendedores/cobradores (`vendedor_cobrador_ids[]`) |
| DELETE | `/supervisores/:id/equipo/:vcId` | Desasignar |
| POST | `/supervisores/:id/comisiones/generar` | Generar comisión por período |
| GET | `/supervisores/:id/comisiones` | Historial comisiones del supervisor |

#### Lógica de comisiones supervisores (fix 2026-05-08)

Bugs corregidos en `generarComision`:
- ~~`dfecemi`~~ → `dfeemide` (campo correcto en `factura_cab`)
- ~~`dtotgral`~~ → `total_factura` (campo correcto en `factura_cab`)

Lógica de ventas actualizada:
```
OR [
  factura.cliente_direccion.supervisor_id = supervisorId,  // dirección asignada
  factura.cliente_direccion_id IS NULL AND factura.vendedor_id IN equipoIds  // fallback
]
```

Los cobros siguen usando `cobrador_id IN equipoIds` (recibos no tienen dirección).

### Fase 3 — Frontend ✅

| Archivo | Estado |
|---|---|
| `pos-ventas/src/api/supervisores.service.js` | ✅ Todas las funciones CRUD + equipo + comisiones |
| `pos-ventas/src/components/organismos/VendedoresCobradoresDesign/SupervisoresList.jsx` | ✅ |
| `pos-ventas/src/components/organismos/VendedoresCobradoresDesign/VendedoresCobradoresModule.jsx` | ✅ Tab "Supervisores" agregado |
| `pos-ventas/src/components/organismos/ClientesDesign/ClienteDireccionesPanel.jsx` | ✅ 3 selects (vendedor/cobrador/supervisor) + auto-sugerencia supervisor |
| `pos-ventas/src/components/organismos/VendedoresCobradoresDesign/SupervisoresComisionesTab.jsx` | ✅ Tab "Comisiones" con filtros, cards resumen, tabla, dialog generar |

#### Auto-sugerencia supervisor en form dirección
Al seleccionar vendedor o cobrador → si tiene `supervisores_asignados[0].supervisor`, se pre-rellena el campo Supervisor (el usuario puede cambiarlo).

Los endpoints `GET /vendedores-activos` y `GET /cobradores-activos` ahora incluyen `supervisores_asignados[0].supervisor` en la respuesta.

---

## Pendiente

| Item | Prioridad |
|---|---|
| `pm2 restart smartfactpy-api` en servidor para activar cambios del backend | 🔴 bloqueante para prod |

---

## Archivos críticos

### Backend
```
prisma/migrations/20260508_supervisores/migration.sql
prisma/migrations/20260508_cliente_dir_asignaciones/migration.sql
src/supervisores/supervisores.module.ts
src/supervisores/supervisores.service.ts
src/supervisores/supervisores.controller.ts
src/supervisores/dto/create-supervisor.dto.ts
src/supervisores/dto/generar-comision.dto.ts
src/clientes/clientes.service.ts                      ← getDirecciones include supervisor
src/vendedores-cobradores/vendedores-cobradores.service.ts  ← activos include supervisores_asignados
```

### Frontend
```
pos-ventas/src/api/supervisores.service.js
pos-ventas/src/components/organismos/VendedoresCobradoresDesign/SupervisoresList.jsx
pos-ventas/src/components/organismos/VendedoresCobradoresDesign/SupervisoresComisionesTab.jsx
pos-ventas/src/components/organismos/VendedoresCobradoresDesign/VendedoresCobradoresModule.jsx
pos-ventas/src/components/organismos/ClientesDesign/ClienteDireccionesPanel.jsx
```