Laravel çok kiracılı onboarding süreci, bir kontrolcü işleminden çok bir iş akışı olarak daha iyi çalışır.

Laravel’da bir tenant oluşturmak, genellikle Tenant::create() ve ardından bir yönlendirme ile basit görünür. Ancak bu basitlik, onboarding süreci faturalama, özel alan adı, rol atama, çalışma alanı varsayılları, örnek veri, e-posta ve denetim günlüklerine dokunmaya başladığında kaybolur. Bu aşamada, “tenant oluşturma” bir CRUD aksiyonu olmaktan çıkar ve bir iş akışına dönüşür.

Takımlar genellikle bunu yanlış anlar çünkü ilk sürümü bir denetleyici aksiyonu içinde çalışır. Talebi doğrular, bir tenant satırı oluşturur, belki bir sahip kullanıcı oluşturur, birkaç iş gönderir ve bunu tamamlamış sayar. Ancak ürün büyüdükçe, kaynak tahsisi yavaşlar. Harici sistemler devreye girer. Bir adım başarılı olur, diğeri zaman aşımına uğrar, üçüncüsü iki kez tekrar dener ve aniden üretimde yarım oluşturulmuş hesaplar kalır; bu da güvenilir bir kurtarma hikayesi bulunmadığı anlamına gelir.

Pratik çözüm, tenant onboarding’i tek bir istek-cevap olayı olarak ele almayı bırakmaktır. Bunu izlenebilir bir iş akışı olarak modelleyin; açık adımlar, durum geçişleri, tekrar denemeler, hata yönetimi ve operatör görünürlüğü ile.

Denetleyici-aksiyon versiyonu, tahsis dağınık hale gelene kadar çalışır

Pek çok Laravel SaaS uygulaması, bu en belirgin uygulama olduğu için buradan başlar.

public function store(CreateTenantRequest $request)
{
    $tenant = Tenant::create([
        'name' => $request->string(),
        => $request->string(),
    ]);

    $owner = User::create([
        => $tenant->id,
        => $request->string(),
        => $request->string(),
    ]);

    $owner->assignRole();

    SeedTenantDefaults::dispatch($tenant->id);
    SendWelcomeEmail::dispatch($owner->id);

    return response()->json([
        => $tenant->id,
        => ,
    ], 201);
}

Bu, onboarding süreci küçük, senkronize ve tamamen yerel olduğunda pek bir sorun yaratmaz.

Ancak onboarding genellikle bu kadar küçük kalmaz.

Çabuk bir şekilde, tenant yaratma şu gibi şeyleri içermeye başlar:

• faturalama müşterisini sağlama
• bir abonelik veya deneme oluşturma
• bir alan adını ayarlama veya doğrulama
• özellik bayrakları veya planlar ekleme
• varsayılan roller ve izinler oluşturma
• şablonlar, ayarlar ve başlangıç içeriği ekleme
• davet veya doğrulama e-postası gönderme
• denetim olaylarını yazma
• iç sistemleri veya analiz boru hatlarını bilgilendirme

Bu noktada, denetleyiciniz artık “bir tenant yaratmak” değil, farklı gecikme, hata ve tekrar deneme özelliklerine sahip dağılmış bir operasyon setini başlatmaktadır.

Önce ne kırılır

İlk hata genellikle yıkıcı değildir; sinir bozucudur.

Tenant satırı vardır, ancak faturalama kurulumu başarısız olmuştur.

Ya da faturalama müşterisi vardır, ancak alan adı kaydı oluşturulmamıştır.

Ya da tohumlama işi kısmen çalıştı, ardından karşılama e-postası üç kez tekrar dendi, ardından yönetici arabirimi, sahibi hiç erişim almamasına rağmen çalışma alanının mevcut olduğunu söyler.

Tüm bu başarısızlıklar nadir değildir. Gerçek sistemlerin yaptığı tam olarak budur.

Neden hızlıca operasyonel borç haline gelir

Eğer onboarding, bir denetleyici aksiyonu ve birkaç ayrık iş olarak modellenirse, genellikle üç önemli şeyi kaybedersiniz:

• mevcut onboarding durumu için güvenilir bir kaynak
• sadece başarısız olan adımı tekrar denemek için temiz bir yol
• zaten ne olduğunu ve ne olması gerektiğini görebilen bir operatör görünürlüğü

İşte böyle yarım oluşturulmuş tenant’lar destek biletlerine, manuel betiklere ve “bir SQL çalıştırın ve artisan komutunu çalıştırın” temizleme ritüellerine dönüşüyor.

Bir iş akışı modeli, gerçeği depolamak için bir yer sağlar

İlk gerçek iyileştirme kavramsaldır, teknik değildir: onboarding’i bir yan etki değil, bir durum olarak ele alın.

“Bir tenant yarattık” yerine, şunlar hakkında düşünün:

• bir onboarding denemesi başlatıldı
• belirli tahsis adımları planlandı
• bazı adımlar tamamlandı
• bazıları bekliyor
• bazıları başarısız oldu
• iş akışı tamamlandı, tekrar denemeye açık, engellendi veya iptal edildi

Bu, normalde kalıcı bir onboarding kaydı istemeniz gerektiği anlamına gelir.

Schema::create(, function (Blueprint $table) {
            $table->id();
            $table->foreignId()->nullable()->constrained();
            $table->string();
            $table->string();
            $table->json();
            $table->timestamp()->nullable();
            $table->timestamp()->nullable();
            $table->timestamp()->nullable();
            $table->text()->nullable();
            $table->timestamps();
        });

Bu kayıt, gereksiz iş yükü değildir. Sisteminize tahsis hikayesini depolamak için bir yer sağlar.

O kaydın hangi soruları yanıtlaması gerekir

En azından, onboarding modelinizin şu soruları yanıtlayabilmesi gerekir:

• tenant’ı kim talep etti
• hangi tenant, eğer var ise, zaten oluşturulmuş
• onboarding şu anda hangi durumdadır
• en son hangi adım başarısız oldu
• iş akışı tekrar denemeye açık mı
• onboarding ne zaman tamamlandı veya başarısız oldu

Bunlar olmadan, her aşağıdan gelen iş yerel kararlar almakta ancak paylaşılan kontrol düzlemi olmaksızın hareket etmektedir.

Durum açık olmalı, yan etkilerden çıkarılmamalıdır

Yaygın bir hata, onboarding durumunu başka yerlerdeki satırların varlığından çıkarmaktır:

• eğer tenant var ise, onboarding başarılı oldu
• eğer abonelik var ise, faturalama adımı başarıyla geçti
• eğer alan adı var ise, DNS adımı başarıyla geçti

Bu akıllıca görünebilir ama hızla karmaşık hale gelir.

Bunun yerine açık iş akışı durumları istemelisiniz:

• pending
• running
• awaiting_external_confirmation
• failed_retryable
• failed_manual_review
• completed

Bu durumlar, niyeti diğer on tabloya yayılmış çıkarımlardan çok daha iyi iletir.

Onboarding’i farklı hata anlamsalara sahip izlenen adımlara ayırın

Bu tasarım gerçeğin zor noktasıdır. Her onboarding adımı aynı şekilde davranmaz, bu yüzden onları öyle modellemeyin.

Bazı adımlar işlemsel ve yereldir. Bazıları asenkron ve uzaktır. Bazıları güvenle tekrar denemeye açık. Bazıları ise körlemesine tekrar yapılmamalıdır.

Güçlü bir Laravel tenant onboarding iş akışı bu gerçeklere göre adımları ayırır.

Yararlı bir adım ayrıştırması

Tipik bir SaaS uygulaması için onboarding şöyle görünebilir:

1. tenant kaydı oluştur
2. sahip hesabı oluştur
3. planı veya denemeyi iliştir
4. faturalama müşterisini sağla
5. varsayılan çalışma alanı verilerini tohumla
6. varsayılan roller ve izinleri ata
7. alan veya alt alan adını ayarla
8. onboarding e-postasını gönder
9. denetim ve analiz olaylarını yayınla
10. onboarding’i tamamla

Bu, her şeyin ardışık çalışması gerektiği anlamına gelmez. Her adım açık, izlenebilir ve düşünülmeli.

Her başarısızlık aynı durumu gerektirmez

Takımlar genellikle bu noktada çok saf kalmaktan yanlar.

Eğer karşılama e-postasını göndermek başarısız olursa, onboarding başarısız mı işaretlenmelidir? Belki hayır.

Eğer faturalama müşteri oluşturma başarısız olursa, tenant hala aktif kabul edilmeli mi? Genellikle hayır.

Eğer alan doğrulaması kullanıcı DNS değişikliklerine bağlıysa, bu bir hata mı? Kesinlikle değil.

Bunun anlamı her adımın kendi tamamlanma ve engelleyici anlamlarını taşımasıdır.

Pratik bir adım modeli

Schema::create(, function (Blueprint $table) {
            $table->id();
            $table->foreignId()->constrained();
            $table->string();
            $table->string();
            $table->unsignedInteger()->default(0);
            $table->timestamp()->nullable();
            $table->timestamp()->nullable();
            $table->timestamp()->nullable();
            $table->text()->nullable();
            $table->json()->nullable();
            $table->timestamps();
        });

Artık adım düzeyindeki durumu takip edebilirsiniz; tüm iş akışının tek bir ikili başarı/başarısızlık olayı olduğunu varsaymadan.

Doğru yürütme modeli, orkestrasyon değil, denetleyici yapıştırmasıdır

Onboarding bir iş akışı haline geldiğinde, onu yönetmek için bir şeye ihtiyacınız vardır.

Bu, ilk aşamada büyük bir iş akışı motoruna ihtiyaç duymaz, ancak yalnızca bir denetleyicinin ilgisiz işlere göndermedeki umudundan daha fazlasını gerektirir.

Orkestrasyon katmanı şunları belirlemelidir:

• hangi adımın çalıştırılacağı
• hangi adımların paralel çalışabileceği
• neyin engelleyici olduğuna
• ne zaman tekrar deneneceğine
• ne zaman durulması ve yükseltilmesi gerektiğine
• ne zaman iş akışının tamamlandığına

Basit bir uygulama servisi iyi bir başlangıçtır

Odaklanmış bir koordine sınıfıyla başlayabilirsiniz.

final class StartTenantOnboarding
{
    public function handle(array $input): TenantOnboarding
    {
        $onboarding = TenantOnboarding::create([
            => ,
            => $input[],
            => $input,
            => now(),
        ]);

        RunTenantOnboardingWorkflow::dispatch($onboarding->id);

        return $onboarding;
    }
}

Şimdi iş akışı yöneticisi adım ilerlemeyi yönetebilir.

final class RunTenantOnboardingWorkflow implements ShouldQueue
{
    use Dispatchable, InteractsWithQueue, Queueable, SerializesModels;

    public function __construct(public int $onboardingId) {}

    public function handle(TenantOnboardingCoordinator $coordinator): void
    {
        $coordinator->advance($this->onboardingId);
    }
}

Bu, her şeyi bir denetleyiciye yerleştirmekten çok daha iyi; çünkü orkestrasyon artık bir yere sahiptir.

Koordinatör idempotent olmalıdır

Bu çok önemlidir.

Queue tekrarları, çoğaltma gönderimleri ve kısmi adım tamamlama gibi şeyler olacaktır. Koordinatörünüz tekrar girmeye güvenli olmalıdır.

Bu genellikle şunları gerektirir:

• hareket etmeden önce mevcut iş akışı durumunu kontrol etme
• zaten tamamlanmış adımları atlama
• tekrar eden yan etkileri önlemek için benzersiz kısıtlamalar veya adım işaretçileri kullanma
• harici sağlama çağrılarını mümkün olduğunda idempotent hale getirme

Eğer iş akışı yöneticisi idempotent değilse, tekrar denemeler yardımcı olmaktan ziyade tehlikeli hale gelir.

Harici sistemleri nihayetinde başarılı, nihayetinde başarısız veya nihayetinde manuel olarak ele alın

Bu, onboarding tasarımlarının genellikle gerçekçilikten uzaklaştığı yerdir. Takımlar, harici adımların yerel metot çağrıları gibi davrandığını varsayarlar.

Bu doğru değildir.

Faturalama, alan adları, e-posta ve üçüncü taraf sağlama her biri farklı belirsizlik türlerine sahiptir. Temiz bir iş akışı bunu kabul eder.

Modellenmesi gereken üç harici sonuç

Çoğu harici onboarding adımının sonucu yalnızca başarı veya başarısızlık değildir. Genellikle şu şekildendir:

• tamamlandı: harici sistem eylemi doğruladı
• tekrar denemeye açık hata: adım, daha sonra başarılı olabilecek bir şekilde başarısız oldu
• bekliyor/manual: adım henüz otomatik olarak ilerleyemez

Alan adı onboarding’u mükemmel bir örnek teşkil etmektedir.

Bir alan adı kaydını başarıyla oluşturabilirsiniz, ancak gerçek doğrulama, müşterinin henüz yapmadığı DNS değişikliklerine bağlıdır. Bu, başarısız bir iş akışı değil, harici bir eylem bekleyen bir iş akışıdır.

Örnek: faturalama artı alan adı adımları

final class ProvisionBillingCustomerStep
{
    public function handle(TenantOnboarding $onboarding): StepResult
    {
        try {
            $customerId = $this->billing->createCustomer([
                => $onboarding->input[],
                => $onboarding->input[],
            ]);

            $onboarding->tenant->update([=> $customerId]);

            return StepResult::completed();
        } catch (TemporaryProviderException $e) {
            return StepResult::retryable($e->getMessage());
        } catch (PermanentProviderException $e) {
            return StepResult::manualReview(->getMessage());
        }
    }
}

Bu, sadece istisnalar fırlatmak ve sıranın ne yapacağını tahmin etmesine izin vermekten çok daha kullanışlı bir sözleşmedir.

Manuel gözden geçirme, mimari bir başarısızlık değildir

Takımlar, iş akışının tamamen otomatik hissedilmesini istediklerinden, açık manuel-inceleme durumlarına karşı direnirler. Bu, birçok gerçek onboarding sisteminin altyapısına karşı bir fantazi.

Eğer bir vergi yapılandırma uyumsuzluğu, faturalama dolandırıcılık kontrolü veya alan doğrulama sorunu insan müdahalesini gerektiriyorsa, bunu dürüstçe modelleyin.

“Manuel gözden geçirme gerekli” diyen bir sistem çok daha sağlıklıdır; sürekli olarak umutsuz bir adımı tekrar denemektense.

Vaka çalışması dersi: kısmi başarı gizleme değil, kurtarma yolları gerektirir

Bu, çoğu takımın sadece yanıldıklarında öğrendiği bir noktadır.

Gerçekçi bir onboarding yolu hayal edin:

• tenant satırı oluşturuldu
• sahip hesabı oluşturuldu
• tohum verisi başarılı oldu
• faturalama müşteri oluşturma, sağlayıcı tarafında başarı ile zaman aşımına uğradı
• tekrar denemek güvenli değil çünkü ikinci bir müşteri oluşturulabilir
• faturalamanın engelleyici olarak kabul edilmesi nedeniyle alan adı adımı hiç başlamadı
• destek, “var olan” bir tenant görüyor ancak onboarding’in güvenli bir şekilde devam edip edemeyeceğini bilmiyor.

Bu tuhaf bir kenar durumu değil. Uzaktan sistemlerle iletişime geçtiği anda gerçekleşen durum tam olarak budur.

İyi bir iş akışı burada ne yapmanıza izin verir

İyi bir iş akışı modeli, kesin olarak aşağıdakileri yapmanıza olanak tanır:

• tamamlanmış ve eksik olan adımları inceleyin
• faturalama müşteri oluşturma işleminin idempotent olduğunu doğrulayın
• sadece engellenmiş adımı yeniden çalıştırın
• tekrardan tohumlama veya tenant’ı yeniden oluşturmaktan kaçının
• nhangesi dindeki kimlerin neyi ve neden devam ettirdiği hakkında bir denetim kaydı tutun.

İşte bu, iş akışına dayalı onboarding ile denetleyiciye dayalı onboarding arasındaki farktır.

Kurtarma, üretim acısı bunu zorlamadan önce tasarlanmalıdır

Her onboarding adımının bu cevaplardan birine sahip olması gerekir:

• otomatik olarak tekrar denemeye güvenli
• manuel olarak tekrar denemeye güvenli
• tekrar denememeli; operatör kararı gerektirir
• geri alma ile telafi edilebilir

Eğer sisteminiz her adım için bunları yanıtlayamıyorsa, gerçek anlamda üretim hazır bir onboarding sistemine sahip olamazsınız.

Operatör görünürlüğü ürünün bir parçasıdır, bir düşünce değil

Eğer onboarding kısmen başarısız olabiliyorsa, birinin nerede ve neden olduğunu görmesi gerekir.

{
            "onboarding_id": 481,
            "tenant_id": 102,
            "status": "failed_retryable",
            "steps": [
                {"step": "create_tenant", "status": "completed"},
                {"step": "create_owner", "status": "completed"},
                {"step": "provision_billing_customer", "status": "failed_retryable",
                "last_error": "timeout from provider"},
                {"step": "seed_defaults", "status": "completed"},
                {"step": "configure_domain", "status": "pending"}
            ]
        }

public function store(CreateTenantRequest $request, StartTenantOnboarding $start)
{
    $onboarding = $start->handle(->validated());

    return response()->json([
        => $onboarding->id,
        => $onboarding->status,
    ], 202);
}