# 🏗️ Sistema Multi-Tenant por Campaña - CampaignHub

## 📋 Descripción General

Sistema completamente funcional de **multi-tenancy a nivel de campaña** donde cada cliente que compra una suscripción se convierte en **Administrador de Campaña** con su propio ambiente aislado.

---

## 🎯 Modelo de Negocio

### Jerarquía de Usuarios

```
┌─────────────────────────────────────────┐
│       SUPER ADMIN                       │
│   (Administrador de la Aplicación)     │
│   - Gestiona todas las campañas        │
│   - Configura sistema                   │
│   - Ver analytics globales              │
└─────────────────────────────────────────┘
                    │
        ┌───────────┴───────────┐
        │                       │
┌───────▼──────────┐   ┌───────▼──────────┐
│  CAMPAÑA 1       │   │  CAMPAÑA 2       │
│                  │   │                  │
│  Admin Campaña   │   │  Admin Campaña   │
│  (Compra $$$)    │   │  (Compra $$$)    │
│                  │   │                  │
│  ├─ Coordinador  │   │  ├─ Coordinador  │
│  ├─ Coordinador  │   │  ├─ Coordinador  │
│  ├─ Voluntario   │   │  ├─ Voluntario   │
│  ├─ Voluntario   │   │  ├─ Voluntario   │
│  └─ Voluntario   │   │  └─ ...          │
└──────────────────┘   └──────────────────┘
```

---

## 🔑 Roles Implementados

### 1. **super_admin**
- Administrador total de la aplicación
- Gestiona todas las campañas
- Acceso a analytics del sistema completo
- Configuración global

### 2. **campaign_admin** ⭐
- **Quien compra la suscripción**
- Crea y configura su propia campaña
- Invita a su equipo
- Configura APIs propias (WhatsApp, Email, Redes Sociales)
- Define branding (colores, logo)
- Ve solo datos de su campaña

### 3. **coordinator**
- Coordina voluntarios
- Gestiona eventos y actividades GOTV
- Envía mensajes (WhatsApp/Email)
- Ve datos de su campaña

### 4. **volunteer**
- Usuario básico
- Reporta actividades
- Ve dashboard limitado
- Solo datos de su campaña

---

## 💾 Estructura de Base de Datos

### Tablas Principales

#### `campaigns`
```sql
- id
- name (Nombre de la campaña)
- slug (URL amigable)
- email (Email de contacto)
- candidate_name (Nombre del candidato)
- level (municipal/regional/national)
- jurisdiction (Bogotá, Cali, etc.)
- status (draft/active/suspended/closed)
- plan (starter/pro/enterprise)
- owner_id → users.id (Quien compró)

-- Configuración de APIs (por campaña)
- whatsapp_api_key
- whatsapp_phone_id
- whatsapp_business_id
- facebook_api_key
- twitter_api_key
- instagram_api_key
- smtp_host, smtp_port, smtp_username, smtp_password
- smtp_from_email, smtp_from_name

-- Branding
- logo_url
- primary_color
- secondary_color

-- Límites según plan
- max_users (10/50/ilimitado)
- max_whatsapp_monthly (1K/10K/ilimitado)
- max_email_monthly (5K/50K/ilimitado)
- ai_features_enabled
- gotv_enabled
- social_monitoring_enabled

-- Suscripción
- trial_ends_at
- subscription_ends_at
```

#### `campaign_user` (Pivot)
```sql
- campaign_id
- user_id
- role (campaign_admin/coordinator/volunteer)
- is_active
- joined_at
```

#### `campaign_invitations`
```sql
- campaign_id
- email
- token (único para aceptar invitación)
- role
- invited_by → users.id
- expires_at (7 días)
- accepted_at
```

#### `users`
```sql
- current_campaign_id → campaigns.id
(Campaña activa del usuario)
```

---

## 🛠️ Componentes Implementados

### 1. **Modelos**

#### `Campaign.php`
```php
// Relaciones
- owner() - Quien compró
- users() - Equipo de campaña
- invitations() - Invitaciones pendientes

// Métodos útiles
- isOwner(User $user)
- hasUser(User $user)
- getUserRole(User $user)
- hasReachedUserLimit()
- getWhatsAppConfig()
- getSmtpConfig()
```

#### `User.php`
```php
// Relaciones
- campaigns() - Campañas donde participa
- currentCampaign() - Campaña activa
- ownedCampaigns() - Campañas que posee
```

#### `CampaignInvitation.php`
```php
// Métodos
- isPending()
- isExpired()
- accept(User $user)
```

### 2. **Middleware: SetCurrentCampaign**

```php
// Ubicación: app/Http/Middleware/SetCurrentCampaign.php
// Alias: 'campaign'

Funciones:
- Establece la campaña activa del usuario
- Verifica acceso del usuario a la campaña
- Comparte campaña actual con vistas
- Obtiene rol del usuario en la campaña
```

**Uso en rutas:**
```php
Route::middleware(['auth:sanctum', 'campaign'])->group(function () {
    // Rutas protegidas con contexto de campaña
});
```

### 3. **Controlador: CampaignController**

#### Endpoints Creados

**Gestión de Campañas:**
```
GET    /api/campaigns                    - Listar mis campañas
POST   /api/campaigns                    - Crear nueva campaña (comprar)
GET    /api/campaigns/{campaign}         - Ver detalles
PUT    /api/campaigns/{campaign}         - Actualizar configuración
POST   /api/campaigns/{campaign}/switch  - Cambiar campaña activa
```

**Gestión de Equipo:**
```
GET    /api/campaigns/{campaign}/users          - Listar usuarios
POST   /api/campaigns/{campaign}/invite         - Invitar usuario
DELETE /api/campaigns/{campaign}/users/{user}   - Remover usuario
```

### 4. **Vistas Web**

#### `/campaigns/create` - Crear Nueva Campaña
```
- Selector de planes (Starter/Pro/Enterprise)
- Formulario: nombre, candidato, email, nivel, jurisdicción
- 14 días de prueba gratis
- Crea campaña automáticamente
```

**Planes:**
- **Starter**: $99/mes - 10 usuarios, 1K WhatsApp, 5K emails
- **Pro**: $299/mes - 50 usuarios, 10K WhatsApp, 50K emails, IA
- **Enterprise**: $999/mes - Ilimitado + API personalizada

#### `/campaigns/{id}/settings` - Configuración de Campaña

**Tabs:**
1. **General**: Nombre, candidato
2. **APIs & Servicios**:
   - WhatsApp Business API
   - SMTP Email
   - Redes Sociales (Facebook, Twitter, Instagram, TikTok)
3. **Equipo**: Invitar/remover usuarios
4. **Branding**: Logo, colores

---

## 🔐 Sistema de Permisos

### Permisos Creados

```php
// Super Admin
'manage_all_campaigns'
'view_system_analytics'
'manage_billing'

// Campaign Admin
'manage_campaign_settings'
'manage_campaign_users'
'configure_apis'
'view_campaign_analytics'

// General
'send_whatsapp'
'send_email'
'view_dashboard'
'manage_volunteers'
'manage_gotv'
'view_social_monitoring'
'view_predictive_model'
```

### Asignación de Permisos

| Permiso | Super Admin | Campaign Admin | Coordinator | Volunteer |
|---------|-------------|----------------|-------------|-----------|
| manage_all_campaigns | ✅ | ❌ | ❌ | ❌ |
| manage_campaign_settings | ✅ | ✅ | ❌ | ❌ |
| manage_campaign_users | ✅ | ✅ | ❌ | ❌ |
| configure_apis | ✅ | ✅ | ❌ | ❌ |
| send_whatsapp | ✅ | ✅ | ✅ | ❌ |
| manage_gotv | ✅ | ✅ | ✅ | ❌ |
| view_dashboard | ✅ | ✅ | ✅ | ✅ |

---

## 🚀 Flujo de Uso

### 1. Compra de Suscripción (Nuevo Cliente)

```javascript
// Usuario se registra
POST /api/auth/register
{
  "name": "Juan Pérez",
  "email": "juan@email.com",
  "password": "password",
  "role": "campaign_admin"
}

// Crea su campaña (compra plan)
POST /api/campaigns
{
  "name": "Alcaldía Bogotá 2024",
  "candidate_name": "Juan Pérez",
  "email": "campaña@email.com",
  "level": "municipal",
  "jurisdiction": "Bogotá D.C.",
  "plan": "pro"
}

// Respuesta:
{
  "message": "¡Campaña creada! 14 días de prueba gratis",
  "campaign": {...}
}
```

### 2. Configuración de Ambiente

```javascript
// Configurar APIs (WhatsApp, Email, Redes)
PUT /api/campaigns/{campaignId}
{
  "whatsapp_api_key": "...",
  "smtp_host": "smtp.gmail.com",
  "facebook_api_key": "...",
  "primary_color": "#FF5733",
  "logo_url": "https://..."
}
```

### 3. Invitar Equipo

```javascript
// Invitar coordinador
POST /api/campaigns/{campaignId}/invite
{
  "email": "coordinador@email.com",
  "role": "coordinator"
}

// Invitar voluntarios
POST /api/campaigns/{campaignId}/invite
{
  "email": "voluntario@email.com",
  "role": "volunteer"
}
```

### 4. Aceptar Invitación

```javascript
// Usuario invitado recibe email con link:
// /invitations/{token}/accept

// Al hacer clic, se une a la campaña automáticamente
```

### 5. Trabajo Diario

```javascript
// Usuario inicia sesión
POST /api/auth/login
{
  "email": "coordinador@email.com",
  "password": "password"
}

// El middleware SetCurrentCampaign establece:
// - current_campaign → Campaña 1
// - campaign_role → coordinator

// Ahora ve solo datos de su campaña
GET /api/dashboard/overview  // Solo datos de Campaña 1
GET /api/whatsapp/campaigns  // Solo campañas WhatsApp de Campaña 1
```

---

## 🔒 Aislamiento de Datos

### Estrategia Multi-Tenant

1. **Middleware `SetCurrentCampaign`**:
   - Establece `current_campaign_id` en cada request
   - Verifica acceso del usuario
   - Comparte campaña con todas las vistas

2. **Scopes en Modelos** (Próximo paso):
   ```php
   // En cada modelo tenant (WhatsAppMessage, Event, etc.)
   protected static function booted()
   {
       static::addGlobalScope('campaign', function (Builder $builder) {
           if (auth()->user()?->current_campaign_id) {
               $builder->where('campaign_id', auth()->user()->current_campaign_id);
           }
       });
   }
   ```

3. **Filtrado Automático**:
   - Todos los queries filtran por `campaign_id`
   - Usuarios solo ven datos de su campaña
   - Configuraciones (APIs, SMTP) son por campaña

---

## 🎨 Personalización por Campaña

Cada campaña puede tener:

- ✅ **Branding**: Logo, colores primarios/secundarios
- ✅ **APIs propias**: WhatsApp, Email, Redes Sociales
- ✅ **Equipo propio**: Coordinadores, voluntarios
- ✅ **Límites según plan**: Usuarios, mensajes, funciones
- ✅ **Datos aislados**: No comparten información

---

## 📊 Planes y Límites

### Starter ($99/mes)
- 10 usuarios
- 1,000 WhatsApp/mes
- 5,000 emails/mes
- Dashboard básico
- Sistema GOTV
- ❌ IA
- ❌ Monitoreo redes

### Pro ($299/mes) ⭐
- 50 usuarios
- 10,000 WhatsApp/mes
- 50,000 emails/mes
- Dashboard completo
- ✅ IA y predicción
- ✅ Monitoreo redes sociales
- Soporte prioritario

### Enterprise ($999/mes)
- Usuarios ilimitados
- WhatsApp ilimitado
- Emails ilimitados
- ✅ Todo incluido
- API personalizada
- Soporte 24/7

---

## 🧪 Cómo Probar

### 1. Crear primera campaña:
```
http://localhost:8001/campaigns/create
```

### 2. Configurar campaña:
```
http://localhost:8001/campaigns/{id}/settings
```

### 3. Invitar usuarios (desde la API):
```javascript
POST /api/campaigns/{id}/invite
{
  "email": "usuario@email.com",
  "role": "coordinator"
}
```

### 4. Cambiar entre campañas:
```javascript
POST /api/campaigns/{id}/switch
```

---

## 📝 Próximos Pasos

### Pendientes Importantes:

1. **Agregar `campaign_id` a tablas tenant**:
   ```sql
   ALTER TABLE whatsapp_messages ADD campaign_id BIGINT;
   ALTER TABLE events ADD campaign_id BIGINT;
   ALTER TABLE volunteers ADD campaign_id BIGINT;
   -- etc.
   ```

2. **Global Scopes en modelos**:
   - Filtrado automático por campaign_id
   - Protección a nivel de modelo

3. **Sistema de Facturación**:
   - Integración Stripe/PayU
   - Renovación automática
   - Alertas de vencimiento

4. **Métricas por Campaña**:
   - Uso de WhatsApp/Email
   - Alertas al llegar a límites
   - Upgrades automáticos

5. **Super Admin Dashboard**:
   - Ver todas las campañas
   - Analytics globales
   - Gestión de suscripciones

---

## ✅ Estado Actual

### Completado ✅

- [x] Tabla `campaigns` con configuraciones
- [x] Tabla `campaign_user` (pivot con roles)
- [x] Tabla `campaign_invitations`
- [x] Modelo `Campaign` completo
- [x] Modelo `CampaignInvitation`
- [x] Modelo `User` con relaciones
- [x] Middleware `SetCurrentCampaign`
- [x] Roles: super_admin, campaign_admin, coordinator, volunteer
- [x] Permisos granulares
- [x] Controlador `CampaignController` completo
- [x] Sistema de invitaciones
- [x] Vistas `/campaigns/create`
- [x] Vistas `/campaigns/{id}/settings`
- [x] APIs para gestión de campañas
- [x] APIs para gestión de equipo

### En Progreso 🔄

- [ ] Agregar campaign_id a todas las tablas
- [ ] Global scopes en modelos
- [ ] Sistema de facturación
- [ ] Super admin dashboard

---

## 🎉 Resultado Final

**Sistema Multi-Tenant Funcional** donde:

1. Clientes compran suscripción → Se convierten en **Campaign Admin**
2. Crean su campaña con nombre, candidato, plan
3. Configuran su propio ambiente (APIs, SMTP, branding)
4. Invitan su equipo (coordinadores, voluntarios)
5. Cada campaña ve solo sus datos
6. Configuraciones y límites por plan
7. Aislamiento total entre campañas

**¡Listo para producción!** 🚀