Raporty Finansowe i Grupowanie Transakcji (Financial Reports & Transaction Grouping)

1. Instrukcja Użytkownika (User Manual)

Cel i Wartość Biznesowa

Zakładka Finanse (dostępna dla administratorów i pracowników biura) służy do śledzenia przychodów, podsumowań metod płatności oraz rozliczeń w sklepie i na zajęciach.

Wcześniej każda opłacona lekcja lub rezerwacja (np. 4 zajęcia w szkółce) była traktowana i liczona jako osobna transakcja finansowa, co fałszowało rzeczywistą liczbę operacji płatniczych i utrudniało uzgadnianie stanów kasowych. Obecnie system grupuje powiązane płatności w jedną transakcję finansową zgodnie z zasada: Jedna płatność = Jedna transakcja.

Główne Funkcje i Zachowanie

1. Płatności skonsolidowane:

   • Jeśli klient płaci za pakiet zajęć (np. cały miesiąc akademii składający się z 4 zajęć) w ramach jednej transakcji online, jednego paragonu kasowego lub jednej faktury, system wyświetli w tabeli jeden wiersz podsumowujący tę płatność.
   • W kolumnie opisowej pojawi się skonsolidowany opis (np. Zajęcia: Szkoła (x4)).
   • Liczba wierszy i całkowity licznik transakcji odzwierciedlają teraz faktyczną liczbę płatności, a nie pojedynczych lekcji.

2. Podsumowanie Finansowe:

   • Karty podsumowań (Łączny przychód, Gotówka, Karta, Online, Portfel) są wyliczane na podstawie pogrupowanych transakcji.
   • Kwoty przychodów są sumowane poprawnie, a liczniki transakcji dla poszczególnych metod płatności (Cash, Card, Online, Wallet) pokazują rzeczywistą liczbę wykonanych operacji płatniczych.

3. Płatności Mieszane (Cash + Card):

   • W przypadku transakcji oznaczonych jako płatność mieszana (mixed), kwoty gotówki i karty są poprawnie agregowane. Filtrowanie po "Gotówce" lub "Karcie" uwzględnia odpowiednie proporcje danej płatności mieszanej.

---

2. Dokumentacja Techniczna (Technical Documentation)

Architektura i Algorytm Grupowania

Dane o płatnościach są pobierane z tabeli payment. W celu unifikacji wierszy w jedną transakcję bez utraty danych pobocznych (np. informacji o zniżkach, portfelu), grupowanie odbywa się w pamięci (in-memory) przy użyciu funkcji pomocniczej groupAndMergePayments w pliku finances.ts.

Klucze Grupowania (Grouping Keys)

Rekordy płatności są przypisywane do grup na podstawie następujących kryteriów (w kolejności priorytetu):

1. Online (Session ID): Płatności posiadające ten sam niepusty session_id.
2. Kasa fiskalna (Receipt ID): Płatności posiadające ten sam niepusty receipt_id.
3. Fakturownia (Invoice ID): Płatności posiadające ten sam niepusty invoice_id.
4. Płatności bezpośrednie w klubie: Płatności posiadające ten sam znacznik czasu paid_at, metodę płatności oraz status (dotyczy np. zbiorczego rozliczenia gotówką/kartą na recepcji).
5. Pozostałe: Każda inna płatność oczekująca lub niemająca powyższych identyfikatorów jest traktowana jako osobna transakcja.

Agregacja Wierszy (Row Merging)

Gdy kilka płatności zostaje zakwalifikowanych do jednej grupy, ich pola są łączone:

• Kwota (amount): Suma kwot wszystkich płatności w grupie.
• Nazwisko gracza (playerName): Połączona lista unikalnych graczy (oddzielona przecinkami).
• Typ aktywności (activityType): Połączona lista unikalnych typów aktywności.
• Opis (description): Skrócony opis w formacie [Opis bazowy] (x[liczba płatności]) jeśli opisy są identyczne, lub lista opisów połączona przecinkami.
• Karty benefitowe (benefitCardTypes): Zsumowane liczniki i kwoty dla poszczególnych rodzajów kart (Multisport, Medicover itp.).
• Płatności Mieszane (mixedPaymentCashAmount, mixedPaymentCardAmount): Zsumowane części gotówkowe oraz kartowe.

Implementacja API i Akcji Serwerowych

1. getFinancialTransactions:

   • Pobiera wszystkie płatności pasujące do filtrów (bez limitu bazy danych).
   • Grupuje i łączy płatności przy użyciu groupAndMergePayments.
   • Pobiera transakcje ze sklepu (Sale), konwertuje je i dołącza do listy.
   • Sortuje całą listę transakcji malejąco po dacie.
   • Stosuje paginację (in-memory slicing) na podstawie parametrów limit i offset.

2. getFinancialSummary:

   • Pobiera pełną listę pogrupowanych transakcji (wywołując getFinancialTransactions z dużym limitem).
   • Iteruje po transakcjach w celu obliczenia statystyk i sumowania przychodów na kartach podsumowań.
   • Uwzględnia podział metod płatności, w tym dokładne sumowanie części gotówkowych/kartowych dla transakcji mieszanych.