Przejdź do głównej zawartości

Płatności i Historia Płatności

Przewodnik dla pracowników recepcji po obsłudze płatności, odczytywaniu historii portfela i oznaczaniu zaległości.

👤 Instrukcja dla pracownika (Recepcja / Administracja)​

Moduł płatności umożliwia szybką weryfikację oraz rozliczanie zadłużenia klientów. Zapewnia on scentralizowany dostęp do wszystkich wpłat powiązanych z danym profilem (w tym z profilami dzieci/podopiecznych).

1. Przegląd historii płatności klienta​

Weryfikacja zadłużenia oraz historii transakcji klienta możliwa jest z poziomu panelu administracyjnego: Ścieżka dla pracownika: Dashboard ➔ Uczestnicy ➔ Szukaj uczestnika ➔ Kliknij "Historia płatności"

Wyświetlone okno dialogowe zawiera:

  • Wykres miesięczny obrazujący przepływy finansowe.
  • Karty podsumowujące łączną kwotę wydatków oraz aktualne zadłużenie.
  • Kompleksową listę transakcji (opłaconych, zaległych oraz zwróconych). Lista transakcji może być filtrowana według miesiąca, statusu oraz zawężana do konkretnego podopiecznego.

2. Rejestracja płatności (Wpłaty w recepcji)​

W przypadku dokonywania wpłaty w sposób stacjonarny (gotówka, terminal płatniczy): Ścieżka dla pracownika: Dashboard ➔ Uczestnicy ➔ Historia płatności ➔ Wybierz płatność ➔ Kliknij "Oznacz jako opłacone" ➔ Wybierz formę (Gotówka/Karta)

  • Zatwierdzenie formularza powoduje natychmiastową zmianę statusu na "Opłacona".
  • Jeżeli opłacone z góry zajęcia zostały anulowane przez administrację (np. z winy obiektu), w opcjach wybranej płatności dostępna jest funkcja Zwrotu do Wirtualnego Portfela klienta.

3. Płatności online Klienta (Płatność z Portfela i płatności mieszane)​

Klienci regulują swoje zobowiązania logując się do Portalu Klienta. Ścieżka dla klienta: Portal Klienta ➔ Płatności ➔ Zaznacz pozycje na liście ➔ Kliknij "Zapłać"

System obsługuje płatności mieszane, umożliwiając częściowe pokrycie kosztów z salda Wirtualnego Portfela (np. zgromadzonego w wyniku zwrotów):

  • Podczas finalizacji transakcji, system pozwala na użycie dostępnych środków z portfela.
  • Moduł płatności automatycznie pobiera maksymalną dostępną kwotę z salda, a różnicę przekazuje do obsługi poprzez zintegrowaną bramkę (Przelewy24) lub do opłacenia stacjonarnego.
  • W przypadku anulowania takich zajęć w przyszłości, algorytm precyzyjnie rozdziela kwotę zwrotu, automatycznie księgując odpowiednią wartość z powrotem na saldo Wirtualnego Portfela. Wymaga to zerowej ingerencji manualnej ze strony personelu.

4. Interpretacja statusów Płatności​

  • Oczekująca (Pending) – transakcja wygenerowana w momencie rejestracji; termin jej zapłaty jeszcze nie upłynął.
  • Zaległa (Overdue) – transakcja nieopłacona w terminie. W zależności od konfiguracji lokalnej, status ten może skutkować blokadą na rejestrację kolejnych rezerwacji oraz automatycznym wysłaniem powiadomienia windykacyjnego SMS. Zmiana statusu na opłaconą (np. po uregulowaniu długu na recepcji) natychmiast znosi te blokady.
  • Zwrócona / Anulowana – ewidencja anulowanych rezerwacji oraz zrealizowanych zwrotów. System przechowuje historię tych operacji do celów weryfikacyjnych, jednak nie są one wliczane do bieżącego zadłużenia.

🛠️ Dokumentacja techniczna​

Szczegóły operacji na transakcjach (payments) dla programistów.

Architektura i rozliczanie Portfela (Wallet)​

Model bazy przechowuje historię w tabelach payment oraz wallet_transaction. Mechanizm obsługi w API:

  1. Wpłaty częściowe: Podczas płatności (np. payMultipleWithWallet), endpoint iteruje przez listę płatności i alokuje dostępny walletBalance. Zmienia status zapłaconych w całości na paid_wallet, w części na status wirtualny z saldem początkowym w portfelu. Zwraca tablicę pendingPaymentIds, żeby Frontend mógł dynamicznie zostawić użytkownikowi do zapłaty (P24) kwoty resztowe.
  2. Automatyczny Refund: Funkcje takie jak refundPaymentsByRelatedId sumują użycie portfela zapytaniem: COALESCE((SELECT SUM(amount) FROM wallet_transaction WHERE related_payment_id = p.id AND transaction_type = 'debit'), 0) Umożliwia to odesłanie precyzyjnej wartości na saldo portfela (INSERT do wallet_transaction typu credit), z pominięciem części uregulowanych Przelewami24 (te wymagają manualnej lub APIowej inicjacji zwrotu na kartę bankową klienta poprzez providera).
  3. Transakcje o statuse refunded nigdy nie kasują relacji z Invoice (jeżeli wygenerowano fakturę czy paragon to zachowuje referencję do wglądu księgowego).

Cachowanie i optymalizacja UI​

Z uwagi na naturę App Router i RSC w Next.js:

  • Konteksty dialogów historii posiadają wymuszony brak cacha. Trasy REST API (odczyt historii płatności gracza i klienta z /api/clients/ oraz /api/players/) opatrzone są flagami: export const dynamic = 'force-dynamic'; export const revalidate = 0; oraz nagłówkami HTTP: Cache-Control: private, no-cache, no-store, must-revalidate.
  • Każdy fetch pod spodem przekazuje { cache: 'no-store' }. Eliminuje to błędy "staleness", gdy po opłaceniu zaległości w P24 klient nadal widział na froncie dług.

Obsługa statusu Overdue i Pending​

W skryptach filtrujących czy blokujących (cron przypomnień, blokady wejścia na nowe rezerwacje - hasPlayerOverduePayments) zdefiniowany jest SQL lookup jako: status IN ('pending', 'overdue'). Status overdue to stan stricte logiczno-biznesowy nakładany na pending, gdy upłynie due_date. System traktuje je równoważnie przy wyliczaniu obrotów ARR oraz długu klienta. Odrzucane dla zliczania blokad są natomiast statusy cancelled i refunded.

UI w tabelkach korzysta z jednej, scentralizowanej tablicy SETTLED_PAYMENT_STATUSES z pliku @/constants/data dla określenia czy wiersz malować na zielono (opłacono) czy czerwono (zalega). Zabezpiecza to aplikację przed bugami przy wdrażaniu kolejnych rodzajów płatności dzielonych.