# Módulos y Roles — ASISMA CRM

## Roles

| Rol | Descripción | Alcance de datos |
|---|---|---|
| `admin` | Matriz ASISMA | Todo el sistema, todos los tenants |
| `franquiciado` | Operador de zona | Solo los datos de su franquicia |
| `vendedor` | Ejecutivo comercial | Solo los datos de su franquicia |
| `marca` | Representante de marca/proveedor | Dashboard y operaciones post-venta |

Permisos por módulo definidos en `SessionHelper::hasPermiso()` y aplicados por
`PermissionMiddleware` según la columna `permiso` de `config/routes.php`.

| Módulo | admin | franquiciado | vendedor | marca |
|---|:-:|:-:|:-:|:-:|
| Dashboard | ✔ | ✔ | ✔ | ✔ |
| Leads | ✔ | ✔ | ✔ | — |
| Cotizaciones | ✔ | ✔ | ✔ | — |
| Empresas / Contactos | ✔ | ✔ | ✔ | — |
| WhatsApp | ✔ | ✔ | ✔ | — |
| Catálogo (verticales/marcas/productos) | ✔ | ✔ (productos solo vend.) | productos | — |
| Franquiciados / Cola | ✔ | — | — | — |
| Usuarios | ✔ | ✔ | — | — |
| Regiones | ✔ | — | — | — |
| Operaciones | ✔ | ✔ | — | ✔ |
| Reportes | ✔ | ✔ | — | — |
| Cobros por Lead | ✔ | — | — | — |
| Configuración | ✔ | solo lectura (grupo general) | — | — |
| Auditoría | ✔ | — | — | — |

## Alcance del franquiciado (regla de oro)

Un franquiciado opera **solo** dentro de: su **región**, su **vertical**, las
**marcas que la matriz le autorizó** (botón 🏷 en Gestión de Franquiciados) y los
**productos de esas marcas**. Esto restringe — en la UI y en el servidor
(`AlcanceHelper`) — la creación/edición de leads, el catálogo visible, los
productos cotizables y la rotación en cascada. La matriz (admin) no tiene
restricciones y es la única que administra el catálogo y las autorizaciones.

## Ciclo de vida del lead

```
nuevo → asignado → contactado → cotizado → negociando → firma → ganado
                                                              ↘ perdido / invalido
```

1. **Captura**: manual (`/leads/crear`), API pública (`POST /api/leads`) o futuro sync.
   Teléfono y correo quedan **enmascarados** para el franquiciado.
2. **Asignación en cascada** (`RotacionHelper` + `cron/rotacion_leads.php`):
   - Califican franquiciados **activos** con la misma **región** y **vertical** del lead
     y, si el lead tiene **marca de interés**, solo los que tienen esa marca
     **autorizada por la matriz** (tabla `franquiciado_marcas`).
   - Orden: `prioridad` descendente (número mayor = más prioritario).
   - Dentro del franquiciado: primer vendedor de `cola_asignacion` no intentado.
   - Timeout por franquiciado (`tiempo_toma_lead`, default 300 s). Al vencer,
     la asignación queda en `timeout` y pasa al siguiente vendedor/franquiciado.
   - Cascada agotada → lead vuelve a matriz con actividad "ALERTA: sin
     franquiciados disponibles".
3. **Aceptación**: el botón "Aceptar Lead y Ver Datos" libera los datos reales
   (`datos_liberados`) y marca la asignación como `aceptado`.
4. **Gestión**: bitácora de actividades (notas, llamadas, reuniones, WhatsApp
   integrado), cotizaciones con enlace público + PDF.
5. **Cierre**:
   - **Ganado**: crea `operaciones_marca` (post-venta), provisiona el cliente en
     Control Empresas y notifica la API de facturación del franquiciado (si están
     configuradas). Los resultados quedan en la bitácora.
   - **Perdido**: exige motivo (precio, competencia, sin contacto, etc.) + nota.

## WhatsApp (Evolution API)

- **Chats** (`/whatsapp`): bandeja de conversaciones por lead (filtrada por
  tenant), chat con polling cada 4 s, envío de texto y adjuntos (imagen, audio,
  video, documento, máx. 16 MB), y contador de no leídos.
- **Instancias** (`/whatsapp/instancias`): una línea por franquiciado; las
  instancias sin franquicia son de la matriz y actúan como fallback. Muestra el
  estado de conexión en vivo (`connectionState`).
- Resolución de instancia al enviar: instancia fijada en el lead →
  instancia del franquiciado → instancia global de matriz.
- Todos los mensajes se reflejan como actividades en la bitácora del lead.

## Cotizaciones

- Precios validados contra `precio_minimo` del catálogo (bandas de precio).
- Descuento fijo o porcentual, impuesto configurable (default 19%).
- Enlace público con hash: `/cotizaciones/publica?h={hash}` (+ `&pdf=1` para PDF).
- Al abrirse por primera vez pasa a estado `vista` (con fecha).
- Estados: borrador → enviada → vista → aceptada / vencida / rechazada.

## Reportes

- KPIs: total de leads, tasa de conversión, tiempo promedio de respuesta a
  asignaciones, cotizaciones aceptadas y monto.
- Embudo por etapa, leads por origen, evolución mensual (6 meses).
- Ranking de franquiciados (solo admin): leads, ganados, conversión, respuesta.
- Export CSV de leads (`/reportes/export`), respetando el tenant.

## Monetización (preparado)

Estructura lista en `cobros_leads` (tipos: por asignación, por cierre, mensual,
paquete) y módulo de consulta para admin en `/cobros`. La generación automática
de cobros queda pendiente de la definición del modelo comercial.

## Auditoría

Acciones sensibles (login, CRUD, cambios de estado, liberación de datos,
configuración) quedan en `audit_log` vía `AuditHelper::log()`, visibles en
`/auditoria` (solo admin).
