Cel i zakres#

Przykład przedstawia płatność za zamówienie w sklepie internetowym. Sklep inicjuje operację u zewnętrznego operatora, otrzymuje wynik i aktualizuje stan zamówienia. Diagram podkreśla, że timeout nie musi oznaczać odmowy: odpowiedź mogła zaginąć, mimo że operator przetworzył płatność.

Model jest neutralny wobec dostawcy i nie określa konkretnego protokołu, metod płatności, wymagań prawnych ani sposobu przechowywania danych płatniczych. Wybór integracji i zabezpieczeń wymaga osobnego projektu oraz przeglądu odpowiedzialności systemu.

Uczestnicy i słownik#

Klient rozpoczyna zakup; Sklep zarządza zamówieniem i wywołuje Operatora płatności; operator komunikuje się z bankiem lub inną siecią poza zakresem tego diagramu. Repozytorium zamówień zapisuje status, a Powiadomienia może przekazać wynik klientowi.

Autoryzacja (authorization of payment) oznacza w tym kontekście decyzję o zgodzie na operację płatniczą; nie jest autoryzacją dostępu użytkownika. Uchwyt środków (capture) i rozliczenie mogą być osobnymi krokami albo częścią jednej operacji, zależnie od rozwiązania. Wymagania powinny jasno określać, kiedy zamówienie uważa się za opłacone.

Przebieg#

  1. Sklep tworzy lokalny rekord płatności powiązany z zamówieniem.
  2. Wysyła operatorowi kwotę, walutę oraz unikalny identyfikator operacji.
  3. Operator przetwarza żądanie i zwraca wynik albo odpowiedź asynchroniczną.
  4. Sklep oznacza płatność zgodnie z potwierdzonym wynikiem.
  5. Przy odmowie zamówienie nie przechodzi do stanu opłaconego.
  6. Przy timeoutcie sklep zachowuje stan niepewny i uzgadnia wynik, zamiast od razu tworzyć nowe obciążenie.
Sklep tworzy płatność u zewnętrznego operatora i czeka na wynik; płatność może zostać potwierdzona, odrzucona albo pozostać nieznana po timeoutcie, co wymaga późniejszego uzgodnienia statusu.
Główne wyniki interakcji sklepu z operatorem płatności.

Wynik nieznany oznacza, że sklep nie wie jeszcze, czy operator wykonał operację. Nie jest równoważny odmowie. System powinien odpytać operatora, przetworzyć podpisane powiadomienie lub wykonać uzgodnienie w inny zatwierdzony sposób. Klient nie powinien być zachęcany do ponownego obciążenia, zanim status poprzedniej próby zostanie rozstrzygnięty.

Statusy i idempotencja#

Płatność może mieć cykl życia obejmujący Utworzona, Oczekująca, Autoryzowana, Uchwycona, Odrzucona, Anulowana, Nieznana i Zwrócona. Nie każdy system używa wszystkich statusów, a różni operatorzy stosują odmienne nazwy. Zmapuj je na wewnętrzny model i określ dozwolone przejścia.

Identyfikator idempotencji (idempotency key) wiąże ponowione żądanie z tą samą logiczną operacją, aby retry po utracie odpowiedzi nie utworzył drugiego obciążenia. Ustal, kto generuje klucz, jak długo jest ważny i co zrobić, jeśli te same dane biznesowe zostaną wysłane pod nowym kluczem. Sam identyfikator nie rozwiązuje wszystkich duplikatów; wymaga spójnego kontraktu po stronie klienta i dostawcy.

Powiadomienia asynchroniczne mogą dotrzeć więcej niż raz, po czasie albo w innej kolejności niż oczekiwano. Obsługa powinna weryfikować źródło, identyfikator operacji i dozwoloność przejścia statusu. Szczegóły zależą od dokumentacji dostawcy, nie od samego diagramu UML.

Testy scenariusza#

  • Potwierdzenie sukcesu aktualizuje płatność i zamówienie spójnie.
  • Odmowa nie oznacza zamówienia jako opłaconego.
  • Timeout nie jest automatycznie mapowany na odmowę.
  • Ponowienie identycznego żądania nie tworzy drugiego obciążenia.
  • Opóźnione powiadomienie aktualizuje właściwą operację tylko raz.
  • Powiadomienie o niedozwolonym przejściu statusu jest obsługiwane i monitorowane.
  • Błąd zapisu po sukcesie u operatora uruchamia uzgodnienie, nie ukrywa transakcji.
  • Zwrot jest odrębną operacją z własnym statusem i śladem audytowym.

Inne przydatne diagramy#

Diagram aktywności może pokazać proces biznesowy zakupu i warianty, a maszyna stanów — cykl życia płatności. Diagram komponentów objaśni granicę między sklepem a operatorem. Wymagania jakościowe i bezpieczeństwa określą ochronę danych, dostępność oraz obsługę incydentów.

Nie łącz modelu płatności z modelem zamówienia jako jednego statusu. Zamówienie może oczekiwać, zostać anulowane lub być realizowane, podczas gdy płatność ma niezależny status. Ich relacja i reguły synchronizacji muszą być jawne.

Typowe błędy#

  • Uznanie timeoutu za odmowę. Wynik może być nieznany, a obciążenie mogło dojść do skutku.
  • Ponowne obciążenie bez uzgodnienia. Może utworzyć duplikat płatności.
  • Brak statusu oczekującego. System nie potrafi opisać operacji asynchronicznej.
  • Aktualizacja zamówienia przed potwierdzeniem. Klient otrzymuje fałszywy sukces.
  • Mieszanie autoryzacji płatniczej i dostępu. To odrębne pojęcia.
  • Jedna wartość statusu dla zamówienia i płatności. Każdy obiekt ma własny cykl życia.
  • Założenie jednokrotnego powiadomienia. Zdarzenia mogą się powtarzać lub opóźniać.
  • Brak mapowania statusów operatora. Zewnętrzne wartości powinny być tłumaczone na kontrolowany model wewnętrzny.
  • Traktowanie przykładu jako projektu bezpieczeństwa. Integracja wymaga weryfikacji aktualnych wymagań dostawcy i właściwych standardów.

Co przykład pokazuje, a czego nie#

Diagram wyjaśnia uczestników, główne wyniki płatności i szczególne znaczenie timeoutu. Pomaga uzgodnić, kiedy system może potwierdzić zamówienie i jak uniknąć prostego ponawiania nieznanej operacji.

Nie definiuje protokołu, konkretnych statusów dostawcy, wymagań prawnych ani całego modelu bezpieczeństwa. Przed wdrożeniem opracuj osobne wymagania, zweryfikuj dokumentację operatora i przetestuj przypadki awarii oraz duplikatów.