README

Paquete completo de Laravel para construir aplicaciones SaaS multi-tenant con gestión de suscripciones, sistema flexible de límites, integración con WhatsApp, y panel de Super Admin.

🚀 Características

Multi-Tenancy

Tenancy basado en sesión: Sin bases de datos separadas por tenant
Trait BelongsToTenant: Aislamiento automático de datos por tenant
Selector de tenant: Interfaz para cambiar entre tenants
Bypass de super admin: Los administradores pueden acceder a todos los tenants

Sistema de Suscripciones

Gestión completa del ciclo de vida de suscripciones
Activación manual y renovación
Seguimiento de eventos de pago
Notificaciones por email y WhatsApp
Alertas de expiración (7 días antes)
Estados: activa, prueba, vencida, cancelada

Sistema Flexible de Límites

Límites numéricos: max_clients, max_projects, api_calls_per_month
Feature flags booleanos: custom_branding, api_access
Habilitación de módulos: whatsapp, reports, analytics
Rate limiting: Por día, por mes
Overrides personalizados: Para clientes VIP
Tracking de uso: Historial completo de consumo

Directivas Blade

@hasFeature('custom_branding')
    <!-- Mostrar contenido personalizado -->
@endhasFeature

@canUseResource('max_clients', 5)
    <!-- Permitir crear 5 clientes más -->
@endcanUseResource

@hasAnyFeature(['api_access', 'webhooks'])
    <!-- Tiene al menos una característica -->
@endhasAnyFeature

Integración con WhatsApp

API Evolution integrada
Múltiples teléfonos por tenant
Notificaciones automáticas
Sistema de colas con reintentos (3 intentos: 1m, 3m, 10m)
Registro de mensajes y estadísticas
Comando de prueba incluido

Panel de Super Admin

Dashboard con métricas clave
Gestión completa de tenants (crear, editar, ver, límites personalizados)
Gestión completa de usuarios (crear, editar, asignar tenants, cambiar roles)
Gestión de suscripciones con renovación rápida
Gestión de planes con límites configurables
Configuración de WhatsApp por tenant
Historial de uso y eventos
Interfaz de tablas compactas y minimalistas

Gestión de Equipos

Invitaciones por email
Control de acceso basado en roles
Límites de staff por plan
Notificaciones automáticas

📋 Requisitos

PHP 8.2 o superior
Laravel 12.0 o superior
Livewire 3.6.4 o superior

📦 Instalación

1. Instalar vía Composer

composer require bachisoft/thunder-pack

2. Ejecutar el comando de instalación

php artisan thunder-pack:install

Este comando:

Publica las migraciones
Publica la configuración
Publica las vistas (opcional)
Ejecuta las migraciones
Seed los planes por defecto
Crea el primer super admin

3. Configurar el modelo User

Agrega el trait HasTenants a tu modelo User:

use ThunderPack\Traits\HasTenants;

class User extends Authenticatable
{
    use HasTenants;
    
    // ... resto del modelo
}

4. Registrar middleware (Laravel 12)

El paquete registra automáticamente los middleware con aliases:

tenant - Validación de acceso al tenant
subscription - Verificación de suscripción activa
superadmin - Restricción a super admins
tenant.permission - Control de permisos dentro del tenant

Aplícalos en tus rutas:

Route::middleware(['auth', 'tenant', 'subscription'])->group(function () {
    Route::get('/dashboard', [DashboardController::class, 'index']);
});

Route::middleware(['auth', 'superadmin'])->prefix('sa')->group(function () {
    Route::get('/dashboard', [SuperAdminController::class, 'index']);
});

5. Configurar WhatsApp (Opcional)

Agrega las credenciales en tu .env:

WHATSAPP_EVOLUTION_ENABLED=true
WHATSAPP_EVOLUTION_API_URL=https://api.evolutionapi.com
WHATSAPP_EVOLUTION_API_KEY=tu_api_key_aqui
WHATSAPP_EVOLUTION_DEFAULT_INSTANCE=default

🔧 Configuración

Publica el archivo de configuración:

php artisan vendor:publish --tag=thunder-pack-config

El archivo config/thunder-pack.php permite personalizar:

return [
    'table_prefix' => '', // Prefijo para tablas
    
    'models' => [
        'tenant' => \ThunderPack\Models\Tenant::class,
        'plan' => \ThunderPack\Models\Plan::class,
        // Sobrescribe modelos según necesites
    ],
    
    'routes' => [
        'enabled' => true,
        'prefix' => '',
        'middleware' => ['web', 'auth'],
        'super_admin_prefix' => 'sa',
    ],
    
    'features' => [
        'whatsapp' => true,
        'team_invitations' => true,
        'super_admin_panel' => true,
    ],
    
    'cache' => [
        'ttl' => [
            'limits' => 300,    // 5 minutos
            'features' => 600,  // 10 minutos
        ],
    ],
];

📖 Uso

Verificar características

use ThunderPack\Facades\FeatureGate;

// Verificar si el tenant tiene una característica
if (FeatureGate::has('api_access')) {
    // Permitir acceso a la API
}

// Verificar límite numérico
if (FeatureGate::can('max_clients', 10)) {
    // Puede crear 10 clientes más
}

// Obtener valor de límite
$maxProjects = FeatureGate::get('max_projects', 5); // 5 es el valor por defecto

Registrar uso de recursos

use ThunderPack\Facades\PlanLimitService;

// Registrar uso de recurso
PlanLimitService::recordUsage('api_calls', 1);

// Obtener uso actual
$usage = PlanLimitService::getCurrentUsage('api_calls', 'month');

Gestionar suscripciones

use ThunderPack\Facades\SubscriptionService;

// Activar suscripción manualmente
SubscriptionService::activateManual($tenant, $plan, $days = 30);

// Verificar estado
if (SubscriptionService::isSubscriptionActive($tenant)) {
    // Suscripción activa
}

// Obtener días restantes
$daysLeft = SubscriptionService::getDaysUntilExpiration($tenant);

Enviar notificaciones WhatsApp

use ThunderPack\Services\WhatsAppService;
use ThunderPack\Jobs\SendWhatsAppNotificationJob;

// Enviar vía Job (recomendado)
SendWhatsAppNotificationJob::dispatch(
    $tenant,
    'subscription_activated',
    ['plan_name' => 'Pro']
);

// O directamente
$whatsapp = app(WhatsAppService::class);
$whatsapp->sendNotification($tenant, 'payment_received', ['amount' => 500]);

🎨 Vistas Personalizables

Publica las vistas para personalizarlas:

php artisan vendor:publish --tag=thunder-pack-views

Las vistas se copiarán a resources/views/vendor/thunder-pack/

🧪 Testing

composer test

📚 Documentación Adicional

🔄 Actualización

composer update bachisoft/thunder-pack
php artisan migrate
php artisan view:clear

🤝 Contribuciones

Las contribuciones son bienvenidas. Por favor, abre un issue primero para discutir cambios mayores.

📄 Licencia

MIT License. Ver LICENSE para más detalles.

🙏 Créditos

Desarrollado por Bachisoft

🐛 Soporte

Para reportar bugs o solicitar características, por favor usa GitHub Issues.

bachisoft / thunder-pack

Maintainers

Details