Doładowanie portfela z dokumentem

Klient z włączonym rozliczeniem zaległością może doładować portfel — online sam, albo gotówką i kartą przy ladzie. Do każdej wpłaty powstaje dokument: faktura albo paragon, z pozycją wybraną z listy przygotowanej przez recepcję.

Doładowanie jest drugą połową kredytu na portfelu: zaległość robi saldo ujemne, a doładowanie je zeruje.

👤 Instrukcja dla pracownika

Przygotowanie listy usług

Ścieżka: Dashboard ➔ Klienci ➔ (klient) ➔ Edycja ➔ Ustawienia ➔ Zaległość

Usługi są w sekcji Zaległość, pod przełącznikiem „Zezwól na rozliczenie zaległością" — pojawiają się dopiero po jego włączeniu, bo doładowanie istnieje po to, żeby uregulować zaległość. Dodaj pozycje: nazwa (wolny tekst) plus stawka VAT (8%, 23%, 0% albo zwolniona). Kolejność na liście jest kolejnością na rozwijanej liście u klienta.

Limit zaległości, przełącznik doładowania i usługi zapisuje jeden przycisk „Zapisz zaległość".

Kto może doładować

Przełącznik „Klient może doładować portfel sam" (domyślnie włączony) rozdziela dwie rzeczy:

• włączony — klient widzi „Doładuj portfel" w aplikacji i płaci online przez Przelewy24; recepcja też może przyjąć wpłatę przy ladzie,
• wyłączony — przycisk znika klientowi z aplikacji, a wpłatę przyjmuje wyłącznie recepcja. Dokument powstaje tak samo.

Sprawdzenie jest po stronie serwera, nie tylko w UI: próba założenia doładowania przez samego klienta przy wyłączonym przełączniku wraca błędem TOPUP_SELF_SERVICE_DISABLED.

Bez ani jednej usługi doładowanie nie jest dla klienta dostępne — przycisk nie pojawia się ani u niego, ani na jego profilu. Dokument musi mieć co wpisać w pozycji.

Usunięcie usługi z listy nie kasuje jej z bazy, tylko archiwizuje — dokumenty już wystawione zachowują swoją nazwę i stawkę.

Doładowanie przy ladzie

Ścieżka: Dashboard ➔ Klienci ➔ (klient) ➔ profil ➔ Doładuj portfel

Wybierz usługę, wpisz kwotę (albo kliknij jedną z szybkich: 200 / 500 / 1000 / 2000 zł) i przyjmij Gotówkę lub Kartę. Maksimum to 5000 zł na jedno doładowanie — saldo portfela samo nie ma górnego limitu.

Po zatwierdzeniu: portfel rośnie, wpłata trafia do raportu kasowego lokalizacji, a dokument idzie do klienta.

Doładowanie przez klienta

Ścieżka (klient): Płatności ➔ Doładuj portfel

Ta sama lista usług i te same kwoty, tylko płatność idzie przez Przelewy24. Portfel rośnie dopiero po potwierdzeniu wpłaty przez Przelewy24, nie w chwili kliknięcia — porzucony koszyk zostawia po sobie tylko nieopłaconą płatność.

Faktura czy paragon

Decyduje ustawienie faktur na koncie klienta, dokładnie tak jak przy każdej innej jego płatności. Dialog pokazuje, co powstanie, jeszcze przed wpłatą. Zmiana jest w Edycja ➔ Faktury.

Nie ma osobnego przełącznika „faktura/paragon" per doładowanie — jedno ustawienie oznacza, że klient nie dostanie faktury za zajęcia i paragonu za doładowanie tego samego dnia.

🛠️ Dokumentacja techniczna

Model danych

Migracja 0263_wallet_topup_services.sql:

• client_wallet_topup_service — pozycje per klient (name, vat_rate, sort_order, archived),
• client_settings.allow_self_topup (migracja 0264) — czy klient może doładować sam; domyślnie 1, bo każdy klient z włączoną zaległością mógł to robić wcześniej,
• payment.topup_service_name i payment.topup_vat_rate — nazwa i stawka zamrożone na płatności w chwili jej utworzenia.

Zamrożenie jest celowe: lista usług jest edytowalna, a dokument już wystawiony musi zachować brzmienie i stawkę, z jakimi wyszedł. Kolumny siedzą na payment, a nie w tabeli obok, żeby generowanie dokumentu zostało jednym zapytaniem.

Dlaczego doładowanie to zwykły payment

Doładowanie zapisuje się jako payment z payment_type = 'wallet_topup'. Dzięki temu trzy rzeczy działają bez nowego kodu:

Efekt	Skąd wynika
Wpłata gotówką wchodzi do utargu	getCashBalance liczy paid_cash / paid_card niezależnie od typu płatności
Dokument powstaje sam	processPaymentStatusChange obsługuje każdą płatność w statusie paid_*
Płatność online przechodzi normalną ścieżką	/api/payments/initialize operuje na identyfikatorach płatności, bez wiedzy o typie

Przepływ

Idempotencja po stronie webhooka

Przelewy24 ponawia powiadomienie, a ponowienie nie może doładować portfela drugi raz. completeWalletTopup sprawdza, czy istnieje już wallet_transaction typu credit wskazująca na tę płatność, i jeśli tak — kończy z alreadyCredited: true, nie dotykając salda. Dokument też nie jest wtedy wystawiany po raz drugi.

VAT na pozycji

calculateNetFromGross(gross, tax) przelicza brutto na netto stawką pozycji, a nie zaszytymi 8%. Domyślnie zostaje klubowe 8% (usługi sportowe), pozycja zwolniona (zw) ma netto równe brutto, a doładowanie bierze stawkę z wybranej usługi. Zmiana jest zgodna wstecz — wszystkie dotychczasowe wywołania nie podają stawki i dostają 8%.

Ograniczenia

• Wygenerowanie dokumentu jest nieblokujące: pieniądze są już w kasie i na portfelu, więc awaria Fakturowni nie może tego wycofać. Błąd trafia do logów i do raportu brakujących dokumentów.
• Zwrot niewykorzystanych środków z portfela nie jest objęty tą funkcją — admin koryguje saldo ręcznie w EditWalletDialog.
• Doładowanie online jest liczone jako wpływ w chwili potwierdzenia przez Przelewy24; usługa, którą finansuje, mogła być wykonana wcześniej (patrz uwaga księgowa w rozliczeniu zaległością).

Testy

• __tests__/lib/wallet-topup.test.ts — limity kwoty (0, 5000, powyżej, grosze) oraz nazwa pozycji na dokumencie dla wallet_topup i brak wpływu na pozostałe typy.