📚 Pré-requisitos Teóricos: Este projeto prático aplica os conceitos avançados de arquitetura multi-inquilino ensinados na Especialização em Backend com PHP e Laravel. Recomendamos sua consulta para contextualização sobre isolamento de dados e Scopes globais do Eloquent.

A Plataforma SaaS Multi-Tenant com Filament Admin v3 aborda a engenharia de sistemas B2B escaláveis onde múltiplas organizações compartilham a mesma base de código mantendo estrito isolamento lógico e físico de dados. Utilizando o Laravel 11, o painel administrativo Filament v3 e estratégias de Global Scopes e Schemas Dedicados, o projeto entrega uma infraestrutura corporativa robusta e pronta para produção.

🏛️ Arquitetura de Isolamento Multi-Tenancy

O diagrama abaixo detalha a resolução da requisição por subdomínio corporativo e a injeção do escopo de inquilino no Eloquent ORM:

📁 Estrutura de Pastas Padronizada

A base de código segue o padrão canônico com nomenclatura anti-colisão:

catalogo_projetos/backend_php_04_saas_multitenancy/
├── api-laravel/              # Backend SaaS corporativo com Laravel 11
│   ├── app/
│   │   ├── Filament/         # Recursos, páginas e painéis do Filament v3
│   │   │   └── Resources/
│   │   ├── Http/
│   │   │   └── Middleware/
│   │   │       └── IdentifyTenantMiddleware.php  # Resolução por subdomínio
│   │   ├── Models/
│   │   │   ├── Tenant.php    # Entidade central do inquilino
│   │   │   └── Scopes/
│   │   │       └── TenantScope.php  # Escopo global do Eloquent
│   ├── config/
│   │   └── tenancy.php       # Estratégia de conexão e separação
│   └── composer.json         # Dependências: filament/filament, stancl/tenancy
├── assets/                   # Galeria de diagramas visuais e arquitetura
│   └── arquitetura_laravel_multitenancy.svg
└── index.md                  # Especificação executiva e Padrão Ouro

🧑‍💼 Engenharia de Software & Requisitos

1. Histórias de Usuário (US)

2. Requisitos Funcionais (RF)

3. Requisitos Não-Funcionais (RNF)

4. Diagrama de Casos de Uso

flowchart TD
    subgraph Atores
        TEN["Usuário da Empresa (Tenant)"]
        SYS["Kernel HTTP Laravel"]
        ADM["Super Admin da Plataforma"]
    end

    subgraph "Plataforma SaaS (api-laravel)"
        UC1["Acessar Aplicação via Subdomínio"]
        UC2["Identificar Tenant no Middleware"]
        UC3["Aplicar Global Scope Eloquent nas Consultas"]
        UC4["Navegar no Painel Filament Admin v3"]
        UC5["Executar Migrações em Lote (tenants:migrate)"]
    end

    TEN --> UC1
    UC1 --> UC2
    UC2 --> UC3
    TEN --> UC4
    ADM --> UC5

5. Matriz de Rastreabilidade (RTM)

🛠️ Implementação do Modelo de Inquilino (api-laravel/app/Models/Tenant.php)

<?php

namespace App\Models;

use Illuminate\Database\Eloquent\Model;
use Illuminate\Database\Eloquent\Relations\HasMany;
use Illuminate\Support\Str;

class Tenant extends Model
{
    protected $fillable = [
        'id',
        'nome',
        'subdominio',
        'plano',
        'ativo',
        'database_schema',
    ];

    protected $casts = [
        'ativo' => 'boolean',
    ];

    public $incrementing = false;
    protected $keyType = 'string';

    protected static function booted(): void
    {
        static::creating(function (Tenant $tenant) {
            if (empty($tenant->id)) {
                $tenant->id = (string) Str::uuid();
            }
            if (empty($tenant->database_schema)) {
                $tenant->database_schema = 'tenant_' . Str::slug($tenant->subdominio, '_');
            }
        });
    }

    public function usuarios(): HasMany
    {
        return $this->hasMany(User::class);
    }
}

🚀 Roteiro de Execução

1. Instalar Dependências e Configurar Tenancy

cd catalogo_projetos/backend_php_04_saas_multitenancy/api-laravel
composer install
php artisan migrate

2. Criar Tenant Demonstrativo

php artisan tinker --execute="App\Models\Tenant::create(['nome'=>'Empresa Alpha','subdominio'=>'alpha','plano'=>'pro','ativo'=>true]);"

3. Iniciar Servidor Local

php artisan serve --port=8000

Teste o acesso via requisição com cabeçalho ou subdomínio configurado no /etc/hosts (alpha.localhost:8000).

🎯 Matriz de Checkpoints de Entrega