Odtwarzalne stany subskrypcji dla SaaS

Dostawca płatności może potwierdzić obciążenie z opóźnieniem, wysłać to samo zdarzenie więcej niż raz albo pozostawić operację częściowo przetworzoną. Dlatego „opłacono” i „ma dostęp” nie są równoważne. Jeśli uprawnienie konta zależy bezpośrednio od ostatniej odpowiedzi otrzymanej z API płatności, przejściowa awaria może zablokować klienta, który faktycznie zapłacił, albo udostępnić produkt innemu, którego obciążenie ostatecznie się nie powiodło.

W przypadku stanów subskrypcji w SaaS PHP celem nie jest przechowywanie jednej etykiety w tabeli. Chodzi o zbudowanie odtwarzalnego procesu: każda decyzja musi mieć dowód, podmiot odpowiedzialny, prawidłowe przejście oraz sposób uzgodnienia po nadejściu nowych danych.

Zdefiniuj reguły produktowe przed modelem technicznym

Model danych nie rozwiązuje niejednoznaczności biznesowych. Przed zaprojektowaniem encji lub webhooków zespoły produktu, finansów i operacji muszą uzgodnić, co dzieje się w każdej istotnej sytuacji.

• Aktywacja: czy dostęp jest przyznawany przed potwierdzeniem pierwszej płatności, po autoryzacji czy dopiero po rozliczeniu?
• Odnowienie: kiedy rozpoczyna się okres karencji i jakie możliwości są w nim zachowane?
• Brak płatności: czy występują automatyczne ponowienia, powiadomienia, częściowe ograniczenia czy pełne zawieszenie?
• Anulowanie: czy dostęp kończy się natychmiast, czy wraz z końcem już opłaconego okresu?
• Zwrot lub spór: czy wymagają natychmiastowej blokady, ręcznej weryfikacji czy cofnięcia dostępu po potwierdzeniu wyniku?
• Reaktywacja: czy przywraca dokładnie poprzedni plan, tworzy nowy cykl rozliczeniowy czy wymaga walidacji operacyjnej?

Warto także odróżnić anulowanie zlecone przez klienta od anulowania skutecznego. Pierwsze wyraża intencję; drugie zmienia przyszłe prawo dostępu. Ich mieszanie prowadzi do mylących interfejsów i automatyzacji trudnych do skorygowania.

Rozdziel umowę, płatność i faktyczny dostęp

Architektura łatwa w utrzymaniu reprezentuje co najmniej cztery pojęcia. Konto identyfikuje właściciela i jego członków. Umowa handlowa opisuje plan, uzgodnioną cenę, datę odnowienia oraz decyzję o anulowaniu. Cykl rozliczeniowy reprezentuje konkretne zobowiązanie za dany okres, jego kwotę i wynik. Wreszcie włączone możliwości określają, co konto może robić w produkcie.

Ten podział zapobiega przekształceniu dostawcy płatności w jedyne źródło prawdy dla całego SaaS. Cykl może być oczekujący, podczas gdy umowa nadal obowiązuje w okresie karencji. Jednocześnie konto może zachować dostęp do odczytu, ale nie móc tworzyć nowych zasobów. Możliwości pozwalają wyrazić tę decyzję bez wymuszania fałszywego podziału na aktywne i nieaktywne.

W PHP aplikacja może udostępniać usługę autoryzacji, która odpyta lokalną projekcję możliwości, na przykład canCreateProject lub canExportData. Ta projekcja jest aktualizowana, gdy zmieniają się fakty handlowe lub rozliczeniowe; nie musi wywoływać dostawcy przy każdym żądaniu. Zmniejsza to opóźnienia, zależność od systemu zewnętrznego i rozproszenie warunków w kontrolerach, kolejkach i zadaniach harmonogramu.

Modeluj przejścia, podmioty odpowiedzialne i dowody

Unikaj pojedynczego pola status z wartościami dodawanymi w miarę pojawiania się incydentów. Lepiej deklarować stany dla każdego agregatu oraz dozwolone przejścia. Na przykład cykl rozliczeniowy może przejść z open do payment_pending, paid, failed, refunded albo disputed. Nie każde przejście jest odwracalne ani nie każdy podmiot może je wykonać.

Każda zmiana powinna zapisywać datę, źródło, identyfikator zewnętrzny, gdy istnieje, oraz dowód. Źródłem może być wewnętrzne polecenie, zweryfikowany webhook, zapytanie uzgadniające lub autoryzowane działanie ręczne. Korekta wsparcia nie powinna po cichu nadpisywać historii: musi zostać zarejestrowana jako odrębna decyzja, z uzasadnieniem i odpowiedzialnym operatorem.

Priorytet w przypadku sprzecznych informacji

Zdefiniuj, który dowód ma pierwszeństwo. Ekran przekierowania po płatności nie powinien potwierdzać cyklu: służy do poinformowania użytkownika, a nie jako ostateczny dowód. Podpisany i zweryfikowany webhook zazwyczaj zapewnia lepszy sygnał, lecz może nadejść późno. Uwierzytelnione zapytanie do dostawcy podczas uzgadniania może wyjaśnić brakujące zdarzenia. Jeśli dwa źródła są sprzeczne, system powinien przejść do weryfikacji lub do zdefiniowanego stanu oczekującego, a nie arbitralnie wybierać najnowszą informację.

Przetwarzaj spóźnione, zduplikowane i niekompletne zdarzenia

Odbiór zdarzenia musi być idempotentny. Zapisuj stabilny identyfikator zewnętrznego zdarzenia oraz hash lub referencję istotnego ładunku. Jeśli zostanie odebrane ponownie, odpowiedz bez powtarzania skutku biznesowego. Jest to szczególnie ważne, jeśli zdarzenie płatnicze uruchamia wystawienie dokumentu, wydłużenie okresu lub powiadomienie.

Przetwarzanie powinno rozdzielać odbiór i zastosowanie. Najpierw zweryfikuj podpis, schemat i pochodzenie; następnie trwale zapisz odebrane zdarzenie; na końcu przetwórz zadanie próbujące zastosować przejście. Jeśli proces zakończy się awarią po utrwaleniu zdarzenia, kolejka lub proces odzyskiwania może je wznowić. Jeśli zawiedzie przed utrwaleniem, uzgadnianie będzie musiało wykryć różnicę, porównując wewnętrzne cykle ze źródłem zewnętrznym.

odebrane zdarzenie → walidacja → trwały zapis → idempotentne zastosowanie
                                      ↓
                              ponowienie lub uzgadnianie

Nie zakładaj kolejności dostarczania. Zwrot może nadejść przed spóźnionym potwierdzeniem pierwotnej płatności. Reguły muszą oceniać bieżący stan, referencje operacji i znaną sekwencję, pozostawiając przypadki niemożliwe lub niejednoznaczne w kolejce do weryfikacji. Bezrefleksyjne stosowanie „ostatniego odebranego zdarzenia” jest częstą przyczyną błędnych uprawnień.

Uzgadnianie i uprawnienia jako kontrolowana projekcja

Okresowe uzgadnianie nie jest obejściem; jest częścią projektu. Powinno wykrywać cykle otwarte zbyt długo, płatności potwierdzone poza systemem, zarejestrowane, lecz nieprzetworzone zdarzenia, zduplikowane referencje zewnętrzne oraz możliwości niezgodne z obowiązującą umową. Po wykryciu różnicy zarejestruj ustalenie i zastosuj śledzalne przejście, zamiast bezpośrednio aktualizować pola.

Projekcja możliwości musi mieć jawne reguły. Na przykład obowiązująca umowa z przeterminowanym cyklem, ale nadal w okresie karencji, może zachować kluczowe funkcje; po zakończeniu karencji może odebrać operacje zapisu. Gdy spóźniona płatność zostanie potwierdzona, system ponownie aktywuje możliwości przewidziane dla planu i zachowuje historię wcześniejszego ograniczenia.

Cache uprawnień może być przydatny, ale wymaga unieważnienia przy zmianie projekcji oraz limitu ważności. Krytyczna autoryzacja nie powinna też opierać się wyłącznie na danych przechowywanych w przeglądarce. Serwer musi podejmować decyzję na podstawie aktualnej możliwości oraz właściwego zakresu konta, użytkownika i zasobu.

Backoffice, audyt i testy odzyskiwania

Zespół wsparcia musi móc zobaczyć, bez edytowania rekordów w bazie danych, umowę, cykle, zdarzenia zewnętrzne, zastosowane przejścia, bieżące możliwości i działania ręczne. Powinien móc zażądać uzgodnienia, ponowić bezpieczne zdarzenie i otworzyć weryfikację. Korekty zmieniające dostęp lub saldo wymagają zróżnicowanych uprawnień, obowiązkowego uzasadnienia i rejestru audytowego.

Testuj przepływ jako sekwencję awarii, a nie tylko jako prawidłową płatność. Uwzględnij potwierdzone odnowienie, niepewną płatność, duplikaty, zdarzenia w niewłaściwej kolejności, zwrot, anulowanie na koniec okresu i reaktywację. Zweryfikuj zarówno końcowy wynik, jak i to, że żadne ponowienie nie tworzy dwóch okresów, dwóch dokumentów ani podwójnego rozszerzenia uprawnień.

Przykładowy przypadek: cykl wygasa, obciążenie pozostaje oczekujące, a konto wchodzi w okres karencji z ograniczonymi możliwościami. Webhook potwierdzający nie zostaje przetworzony z powodu tymczasowej przerwy, ale zdarzenie pozostaje zarejestrowane. Idempotentne ponowienie potwierdza cykl, przedłuża umowę i odtwarza możliwości. Gdyby zdarzenie nie nadeszło, uzgadnianie znalazłoby potwierdzoną operację zewnętrzną i wygenerowało to samo przejście z własnym dowodem.

Sygnały ostrzegawcze i lista kontrolna

Mierz konta z niespójną umową i możliwościami, przeterminowane cykle bez decyzji, nieprzetworzone zdarzenia, wyczerpane ponowienia, różnice wykryte przez uzgadnianie oraz częstotliwość zmian ręcznych. Wzrost liczby ręcznych korekt zwykle wskazuje na niewystarczające reguły, a nie wyłącznie na problem operacyjny.

• Czy umowa, cykl rozliczeniowy i możliwości są odrębnymi encjami?
• Czy każde przejście ma podmiot, dowód, datę i uzasadnienie?
• Czy zdarzenia zewnętrzne są idempotentne i zapisywane przed zastosowaniem?
• Czy istnieje uzgadnianie zdolne odzyskać niekompletne operacje?
• Czy uprawnienia są obliczane z lokalnej projekcji, a nie z odpowiedzi płatniczej w czasie rzeczywistym?
• Czy wsparcie może prowadzić dochodzenie i wprowadzać korekty z audytem, bez bezpośrednich zmian na produkcji?
• Czy testy obejmują opóźnienia, duplikaty, nieuporządkowanie i sprzeczności?

Odtwarzalny model nie eliminuje awarii zewnętrznych. Sprawia, że są wykrywalne, ograniczone i możliwe do skorygowania bez przekształcania incydentu płatniczego w utratę kontroli nad dostępem do produktu.