Specyfikacja systemu realizacji afiliacji — dashboard partnera (Convertere / normobaria)

Ten dokument to dogłębna specyfikacja systemu realizacji afiliacji (programu partnerskiego) w formie dashboardu partnera — kompletny projekt funkcjonalny i techniczny, przygotowany przed rozpoczęciem budowy. Oferta v4/v5 obiecuje partnerowi "panel real-time" — niniejszy raport jest pogłębioną specyfikacją tego panelu, tak by zespół deweloperski miał pełny, jednoznaczny projekt do wdrożenia.

1. Cel i zasady projektowe

Czym jest system realizacji afiliacji

System realizacji afiliacji to warstwa informatyczna, która automatyzuje, uwidacznia i rozlicza cały program partnerski Convertere: od momentu, w którym fizjoterapeuta poleca klienta, przez jego wpisanie do systemu, zakup pakietu, naliczenie prowizji, aż po wypłatę na koniec kwartału. Sercem systemu jest dashboard partnera — panel, w którym polecający fizjoterapeuta w czasie rzeczywistym widzi, co dzieje się z każdą jego rekomendacją.

Kto korzysta

System ma spełniać trzy cele

1. W czasie rzeczywistym wiadomo, że system działa. Każda akcja (rejestracja polecenia, wpis klienta, zakup, naliczenie prowizji) generuje natychmiastowe potwierdzenie; przepływ polecenie → wpis → zakup → prowizja jest widoczny krok po kroku, bez ciemnych punktów.
2. Motywuje osobę polecającą. Natychmiastowa gratyfikacja, widoczny postęp, pasek postępu, brak frustracji. Partner czuje, że jego rekomendacje realnie się liczą i przekładają na prowizję.
3. Buduje zaufanie. Pełna przejrzystość naliczania (25% od kwoty netto pierwszego zakupu), kompletna historia zdarzeń (księga audytu), przewidywalność wypłat (kwartał, faktura, status).

Zasady projektowe

• Transparentność ponad wszystko — żadnego "czarnego pudełka"; każda prowizja ma policzalną, jawną ścieżkę.
• Widoczność w czasie rzeczywistym — dane odświeżają się automatycznie, bez ręcznego odświeżania strony.
• Prostota dla partnera — partner (fizjoterapeuta, nie informatyk) ma widzieć swój wynik w 5 sekund.
• Zgodność z modelem biznesowym — jednolita stawka 25% od kwoty netto pierwszego zakupu, wypłacana jako kwota brutto; rozliczenie kwartalne (faktura / umowa zlecenie, klasyfikacja marketing).
• Warunek uznania prowizji nie jest ukryty — wprost komunikowany i zwizualizowany: klient musi być wpisany do systemu pod identyfikatorem partnera.

2. Persona i ścieżka partnera

Persona: fizjoterapeuta-polecający

"Marta, 38 lat, fizjoterapeutka z własnym gabinetem. Codziennie widuje pacjentów po operacjach, złamaniach, z przewlekłym bólem — i chce im pomóc oraz uczciwie zarobić na rekomendacjach, bez ryzyka i bez konfliktu z pracą terapeutyczną. Nie jest specjalistką od technologii — potrzebuje czegoś prostego."

Potrzeby Marty:

• Wiedzieć instynktownie, ile zarobi i od czego to zależy.
• Widzieć, że jej polecenie zostało przyjęte i nie "utonęło".
• Mieć pewność, że rozliczenie przyjdzie zgodnie z zasadami.
• Poświęcać na panel maksymalnie kilkadziesiąt sekund dziennie.

Ścieżka partnera krok po kroku

1. Rozpoznanie oferty — czyta ofertę v4/v5, widzi obietnicę "panelu real-time".
2. Rejestracja / onboarding — wypełnia krótki formularz (imię, nazwisko, NIP/PESEL do faktury, adres e-mail, telefon, dane do umowy zlecenie). System tworzy konto Partner z unikalnym identyfikatorem (ID) i linkiem polecającym.
3. Pierwsze logowanie — widzi pusty dashboard z przewodnikiem konfiguracyjnym ("Jak polecić pierwszego klienta") i spersonalizowanym linkiem polecającym do skopiowania.
4. Polecenie klienta — poleca pakiet, wpisuje klienta do systemu pod swoim ID (formularz lub link polecający).
5. Obserwacja w czasie rzeczywistym — widzi status rekomendacji zmieniający się: wpisane → potwierdzone → kupione → prowizja naliczona.
6. Koniec kwartału — widzi zbiorcze rozliczenie, zatwierdza/bada je, otrzymuje fakturę i wypłatę; status rozliczenia zmienia się na wypłacone.

Doświadczenie "pierwszego razu" (magiczna chwila)

Najważniejszy moment budujący zaufanie to potwierdzenie rejestracji akcji w czasie rzeczywistym: partner wpisuje klienta i natychmiast (w ciągu sekund) widzi nową pozycję na liście ze statusem wpisane i zielonym "✓ System przyjął Twoje polecenie". Ta natychmiastowa reakcja jest fundamentem celu #1 (widać, że działa) i celu #3 (zaufanie).

3. Architektura danych / model

Encje i pola

Definicje i wzory

• Wartość netto pierwszego zakupu — kwota za pakiet (1 turnus = 6 wizyt, 2 turnusy = 12 wizyt) bez podatku VAT.
• Prowizja = 25% × wartość netto pierwszego zakupu; wypłacana jako kwota brutto.
• 1 turnus: wartość netto → 25% → 300 zł brutto prowizji.
• 2 turnusy: wartość netto → 25% → 600 zł brutto prowizji.
• Zasada 1× — prowizja naliczana jest od pierwszego zakupu danego klienta (nie od każdego kolejnego).
• Atrybucja — prowizja przypisywana wyłącznie do partnera, pod którego ID klient został wpisany przed zakupem.

Relacje

**Partner 1—N Klient polecony 1—1 Sprzedaż 1—1 Prowizja N—1 Rozliczenie**

Każdy klient polecony ma dokładnie jednego partnera-atrybutora; każdy pierwszy zakup generuje co najwyżej jedną prowizję; rozliczenie kwartalne agreguje wiele prowizji jednego partnera.

4. Przepływ "od polecenia do wypłaty" — mapa stanów

Cykl życia akcji (rekomendacji)

Zasady przejść

• Nie można pominąć wpisu do systemu (krok 2). Bez Wpisane pod ID partnera — brak atrybucji, brak prowizji, bez względu na to czy klient kupił.
• Prowizja nalicza się tylko od pierwszego zakupu (Kupione po raz pierwszy dla danego klienta).
• Wszystkie przejścia są logowane timestampem w księdze zdarzeń (patrz sekcja 8).
• Statusy są niezmienne historycznie — zmiana statusu dodaje nowy event, nie nadpisuje starego (powód do audytu).

Wizualizacja przepływu w panelu

Każda akcja pokazywana jest jako pasek postępu 7 kroków z podświetlonym aktualnym statusem. Partner zawsze wie, gdzie w cyklu jest jego rekomendacja i co się wydarzy dalej.

5. Panel partnera (dashboard) — sekcja po sekcji

5.1 Nagłówek / podsumowanie (widok 5 sekund)

Na górze, zawsze widoczne po zalogowaniu:

• "Mój wynik w tym kwartale" — suma prowizji brutto zakwalifikowanych do rozliczenia + wyraźne "do wypłaty na koniec kwartału".
• Aktualna liczba aktywnych akcji (wpisane / potwierdzone / kupione).
• Stawka przypomnienie: 25% od kwoty netto pierwszego zakupu (300 zł / 600 zł brutto) — rozliczenie kwartalne.
• Kafel "wszystko działa" — zielony wskaźnik live (kropka "na żywo") potwierdzający synchronizację danych w czasie rzeczywistym.

5.2 Status akcji w czasie rzeczywistym (główna lista)

• Tabela każdej rekomendacji ze statusem (7 stanów z sekcji 4), datami, typem pakietu.
• Live badge przy pozycjach, które zmieniły status w ostatnich sekundach/minutach.
• Filtry: wszystkie / wpisane / kupione / naliczone / rozliczone.
• Każda pozycja otwiera kartę szczegółów akcji z pełną chronologią eventów.

5.3 Wysokość prowizji "na żywo"

• Obok każdej akcji kupione widnieje naliczona kwota: 300 zł (1 turnus) lub 600 zł (2 turnusy) — z dopiskiem "25% od kwoty netto pierwszego zakupu".
• Suma prowizji rośnie na żywo w nagłówku przy każdej zmianie statusu na naliczone.
• Prowizja wyświetlana jako kwota brutto (wartość którą partner faktycznie otrzyma), z jawnie pokazaną kalkulacją: 25% × netto = brutto prowizji.

5.4 Historia (pełna księga zdarzeń)

• Kompletna lista wszystkich akcji i zdarzeń w czasie — nic nie znika, wszystko ma znacznik czasu.
• Eksport historii do CSV/PDF (dla własnej weryfikacji i księgowości).
• Wyszukiwarka po nazwisku klienta, statusie, dacie.

5.5 Status rozliczeń kwartalnych

• Lista kwartałów z: sumą prowizji, numerem faktury / umowy zlecenie, statusem (w przygotowaniu / wystawiona / wypłacona).
• Plik faktury do pobrania (PDF) przy statusie wystawiona.
• Przewidywany termin wypłaty pokazany z wyprzedzeniem.

5.6 Powiadomienia (centrum)

• Log wszystkich powiadomień (e-mail, SMS, push w panelu): "Klient potwierdził turnus", "Klient kupił — prowizja 300 zł naliczona", "Rozliczenie kwartału wystawione", "Wypłata zrealizowana".
• Możliwość wyboru kanałów preferencji.

5.7 Wskaźniki (KPI) widoczne dla partnera

6. Real-time — mechanizm techniczny

Aby cel #1 ("widać, że działa") był realny, panel musi odświeżać dane automatycznie i natychmiastowo reagować na zmiany stanu.

Model zdarzeń (event-driven)

System działa w architekturze opartej o zdarzenia (event-driven). Każda zmiana stanu biznesowego emituje event:

Mechanizmy przekazu danych w czasie rzeczywistym

Gwarancja "widoczności działania"

• Zielona kropka "na żywo" w nagłówku — wizualna gwarancja aktywnego połączenia.
• Live badge na nowo zaktualizowanych pozycjach.
• Potwierdzenie zapisu — po każdej akcji partnera (np. wpisaniu klienta) panel pokazuje animowane potwierdzenie "✓ System przyjął Twoje polecenie" w ciągu sekund.
• Idempotencja — każdy event jest idempotentny (ponowione dostarczenie nie zdubluje prowizji), co chroni integralność rozliczeń.

Wymóg biznesowy

Czas między wystąpieniem zdarzenia (np. zakup klienta) a jego odzwierciedleniem w panelu partnera nie powinien przekraczać kilku sekund (target < 5 s).

7. Motywacja i psychologia

Celem #2 jest motywacja osoby polecającej. Wspierają ją sprawdzone mechanizmy psychologiczne programów partnerskich:

Mechanizmy motywacyjne

1. Natychmiastowa gratyfikacja. Potwierdzenie wpisu w czasie rzeczywistym daje poczucie "moja akcja zadziałała" — to nagroda natychmiastowa, nie odroczona o kwartał.
2. Widoczny postęp (progress). Pasek 7 kroków dla każdej akcji pokazuje, że rekomendacja "idzie do przodu" — każdy krok to mała wygrana.
3. Jasność zysku. Partner zna kwotę do złotówki (300 / 600 zł brutto) i widzi sumę narastającą na żywo. Konkret zwycięża z abstrakcyjnym "możesz zarobić".
4. Efekt narastania. Pasek postępu kwartału ("do wypłaty w tym kwartale") — samo widzenie rosnącej liczby podtrzymuje zaangażowanie.
5. Osiągnięcia (gamifikacja, niewielka). Kamienie milowe: "Pierwsza prowizja 🎉", "3 polecenia w miesiącu", "1000 zł łącznie". Proste, nie nachalne, bez systemu punktów moralnych.
6. Brak frustracji (eliminacja tarcia). Żadnych ukrytych zasad. Warunek wpisania pod ID jest widoczny, a system przypomina, gdy klient "leci" bez wpisania (np. przez link polecający bez rejestracji).
7. Aspiracja społeczna. Pokazanie, że rekomendacja pomaga pacjentowi + przynosi godziwe rozliczenie — zgodne z tożsamością zawodową fizjoterapeuty (pomoc > sprzedaż).

Ton komunikacji

• Pozytywny, partnerski, konkretny — bez presji i nachalnej "sprzedaży".
• Język zysku wprost: "Polecasz — wpisujesz — klient kupuje — Ty dostajesz 300 zł. Prosto."
• Każde powiadomienie o naliczeniu prowizji jest zaprojektowane jako małe święto (zwięzłe, z kwotą, z gratulacją).

Design motywacyjny zgodny z modelem

Prowizja 25% od pierwszego zakupu oznacza, że kluczowe jest wpisanie pod ID i doprowadzenie do pierwszego zakupu. Dlatego wizualizacja podkreśla właśnie te dwa kroki (wpisanie = warunek; pierwszy zakup = chwila prowizji) — cały mechanizm motywacyjny spina się z regułami biznesowymi.

8. Budowanie zaufania

Cel #3 to zaufanie. Przejrzystość jest fundamentem programu, w którym rozliczenie następuje dopiero na koniec kwartału.

8.1 Księga zdarzeń / audyt

• Każdy event jest zapisywany w niezmiennej księdze: co się stało, kiedy, dla kogo, przez kogo/jaki system.
• Partner widzi pełną historię swojej akcji — od wpisu do wypłaty — z timestampami.
• Zapis audit-trail jest odporny na manipulację (logowanie append-only, kontrolowane prawa dostępu), choć partner widzi tylko własne zdarzenia.

8.2 Jawność naliczania

• Każda prowizja ma rozbudowaną kartę kalkulacji: typ pakietu → wartość netto → 25% → wartość brutto prowizji.
• Stawka jest zawsze widoczna i spójna (25% od netto pierwszego zakupu; 300 / 600 zł brutto).
• Brak "ukrytych kosztów" i "drobnego druku"; warunek wpisania pod ID jest jawnie komunikowany w panelu i w umowie.

8.3 Przewidywalność rozliczeń

• Reguła kwartalna jest jawna: rozliczenie na koniec kwartału, na podstawie wystawionej faktury / umowy zlecenie (klasyfikacja marketing).
• Panel pokazuje kalendarz wypłat i przewidywany termin z wyprzedzeniem.
• Partner wie z góry, ile i kiedy otrzyma — brak niepewności.

8.4 Polityka rozliczeń (słowna, jawna)

1. Prowizja przysługuje od pierwszego zakupu klienta wpisanego pod ID partnera.
2. Naliczenia opierają się na kwocie netto; wypłata jako kwota brutto prowizji.
3. Naliczanie jest automatyczne (prowizja.naliczona), rozliczenie kwartalne na podstawie faktury / umowy zlecenie.
4. Wszelkie zmiany zasad są komunikowane z wyprzedzeniem i odnotowane w księdze.

8.5 Kontakt i wsparcie

• Przycisk "Masz pytanie?" → bezpośredni kontakt z opiekunem partnerów.
• Centrum pomocy z odpowiedziami na najczęstsze pytania o naliczanie.

9. Wymagania funkcjonalne i techniczne

Backend

• Baza danych relacyjna z modelami: Partner, Klient polecony, Sprzedaż, Prowizja, Rozliczenie, Event (audit).
• Silnik naliczania — niezależny moduł wyliczający 15% zasady: prowizja = 0.25 × netto_pierwszego_zakupu, wypłata brutto, jednorazowość.
• Silnik zdarzeń — centralny bus emitujący eventy (sekcja 6).
• Tokenizacja atrybucji — każdy wpis klienta niesie id_partnera; prowizja przypisywana tylko do tego partnera.
• API REST (JSON): GET/POST akcje, statusy, prowizje, rozliczenia; autoryzacja per-partner.
• Rozliczenia kwartalne — agregacja prowizji w cykle kwartalne (Q1–Q4), generowanie danych faktury.

Frontend (dashboard partnera)

• SPA (np. React/Vue) lub lekki SSR; mobile-first (partner używa głównie telefonu).
• Auto-odświeżanie live (SSE/WebSocket) z fallback polling (sekcja 6).
• Widoki: podsumowanie, lista akcji, karta akcji (chronologia), historia, rozliczenia, powiadomienia, ustawienia.
• Eksport CSV/PDF historii i rozliczeń.

Bezpieczeństwo i role

• Uwierzytelnianie — każdy partner loguje się przez bezpieczne konto (e-mail + hasło / magic link / 2FA).
• Autoryzacja (RBAC):
• Partner: tylko własne dane (swoje akcje, prowizje, rozliczenia) — izolacja między partnerami.
• Back-office: zarządzanie akcjami, statusami, atrybucją.
• Księgowość: rozliczenia, faktury, wypłaty.
• Admin: konfiguracja stawek, użytkownicy, audyt.
• RODO: dane osobowe klientów i partnerów przetwarzane zgodnie z polityką; partner widzi tylko niezbędne dane; zgoda klienta poleconego (osobna zgoda dostępna w regulaminie pakietu).
• Audit trail — append-only, ograniczone uprawnienia zapisu.
• Idempotencja eventów i transakcyjność — brak zdublowanych prowizji (ABWAD na id_sprzedazy).
• HTTPS/TLS — obowiązkowe; bezpieczne przechowywanie haseł (bcrypt/argon2) i danych fakturalnych.

Checklist funkcjonalna (MVP)

• [ ] Rejestracja partnera i generowanie ID + linku polecającego
• [ ] Formularz wpisania poleconego klienta pod ID partnera (z potwierdzeniem live)
• [ ] Lista akcji ze statusami i paskiem postępu
• [ ] Silnik naliczania 25% od netto (300/600 zł brutto), jednorazowość
• [ ] Podsumowanie kwartału i status rozliczeń (faktura/umowa zlecenie)
• [ ] Powiadomienia o zmianach statusów
• [ ] Historia / księga zdarzeń z eksportem
• [ ] Back-office do potwierdzania rezerwacji i zakupów

10. Metryki sukcesu

Jak zmierzyć, że system osiąga swoje trzy cele.

Metryki aktywacji i konwersji (cel #1 — system działa)

Metryki motywacji i zaufania (cele #2 i #3)

Metryki techniczne (jakość runtime)

11. Plan wdrożenia (fazy MVP → pełny)

Faza 0 — Zdefiniowanie zasad (przed kodem)

• Ustalenie finalnych reguł (25% od netto, wypłata brutto, kwartał, warunek wpisu pod ID) w dokumentacji i umowie.
• Decyzja o atrybucji przez link polecający vs formularz wpisu (rekomendacja: oba, z jednym źródłem atrybucji).

Faza 1 — MVP (minimum widoczności i zaufania)

• Rejestracja partnera z ID i linkiem polecającym.
• Formularz wpisania klienta pod ID z potwierdzeniem live (cel #1).
• Lista akcji ze statusami (wpisane → potwierdzone → kupione → prowizja).
• Prosty silnik naliczania 25% (300/600 zł brutto) i podsumowanie kwartału.
• Powiadomienia e-mail o zmianach statusu.
• Cel fazy: partner widzi swój przepływ i ufa naliczaniu.

Faza 2 — Motywacja i real-time (cel #2)

• Pelny live (SSE/WebSocket), zielona kropka, badge, natychmiastowe aktualizacje.
• Pasek postępu akcji, kamienie milowe, powiadomienia push/SMS.
• Historia z eksportem CSV/PDF; lepsze KPIs w nagłówku.

Faza 3 — Pełne rozliczenia i audyt (cel #3)

• Automatyczne rozliczenia kwartalne, generowanie danych faktury / umowy zlecenie.
• Moduł księgowości: eksporty, statusy wypłat, kalendarz wypłat.
• Pełna księga zdarzeń (audit) widoczna partnerowi.

Faza 4 — Optymalizacja i skalowanie

• Analiza metryk (sekcja 10), iteracje UX, automatyzacja onboarding.
• Integracje z systemem płatności i księgowym; raporty dla zarządu.

12. Źródła (pliki)

Pliki źródłowe znajdujące się na serwerze, stanowiące podstawę i kontekst tej specyfikacji:

• /root/convertere/reports/v5-partner-fizjoterapeuci.md — najnowsza oferta partnerska v5 z obietnicą "panelu real-time" i pełną strukturą pakietu (6/12 wizyt, 2h/wizyta).
• /root/convertere/reports/v4-partner-fizjoterapeuci.md — oferta v4 (pierwsza zapowiedź panelu partnera).
• /root/convertere/reports/partner-fizjoterapeuci.md — bazowa wersja oferty partnerskiej.
• /root/convertere/reports/prowizje-partner.md — model prowizyjny (25% od netto, wypłata brutto, 1/2 turnusy).
• /root/convertere/reports/regulamin-pakiet-regeneracyjny.md — regulamin pakietu i zasady współpracy.
• /root/convertere/reports/v10-prowizje-partner.md / v9-… / v8-… — iteracje modelu prowizyjnego.
• Ten dokument: /root/convertere/reports/realizacja-afiliacji.md.

13. Źródła (Linki URL)

Zewnętrzne publikacje (zweryfikowane HTTP 200), do których odnosi się ten projekt:

• Oferta partnerska v5 — panel partnera real-time
• Oferta partnerska v4 — panel partnera
• Oferta partnerska (wersja bazowa)
• Model prowizyjny partnerów
• Regulamin pakietu regeneracyjnego

Glosariusz

Afiliacja (program partnerski) — model, w którym osoba polecająca (partner) otrzymuje prowizję za doprowadzenie klienta do zakupu. Tu: fizjoterapeuta poleca klienta na pakiet regeneracyjny.

Program partnerski — formalne zasady współpracy: kto poleca, od czego zależy prowizja, jak i kiedy następuje rozliczenie.

Prowizja — wynagrodzenie partnera za pierwszego zakup poleconego klienta; 25% od kwoty netto, wypłacane jako kwota brutto (300 zł / 600 zł).

Kwota netto — wartość zakupu bez podatku VAT; podstawa naliczenia prowizji (25% × netto).

Kwota brutto — wartość z podatkiem; prowizja wypłacana partnerowi jako kwota brutto.

Rozliczenie (kwartalne) — zbiorcze rozliczenie prowizji za kwartał, na podstawie wystawionej faktury / umowy zlecenie.

Faktura / umowa zlecenie — dokument rozliczeniowy wystawiany na koniec kwartału (klasyfikacja marketing), na podstawie którego następuje wypłata.

Atrybucja — przypisanie sprzedaży do konkretnego partnera na podstawie wpisu klienta pod jego identyfikatorem.

Wpis pod ID partnera — warunek uznania prowizji: polecany klient musi zostać wpisany do systemu pod identyfikatorem polecającego.

Dashboard (panel partnera) — widok dla partnera pokazujący statusy akcji, prowizje i rozliczenia w czasie rzeczywistym.

Real-time / live — aktualizacja danych na bieżąco, bez ręcznego odświeżania, dzięki połączeniu SSE/WebSocket.

Webhook / Event — komunikat o zdarzeniu (np. zakup klienta) przekazywany automatycznie między częściami systemu; podstawa mechanizmu real-time.

Księga zdarzeń (audyt) — niezmienna, pełna historia zdarzeń w systemie, budująca zaufanie do naliczeń.

KPI (wskaźnik) — metryka sukcesu, np. liczba aktywnych akcji, konwersja rekomendacji, suma prowizji do wypłaty.

Turnus regeneracyjny — pakiet wizyt: 1 turnus = 6 wizyt (300 zł prowizji), 2 turnusy = 12 wizyt (600 zł prowizji).

Normobaria — przebywanie w komorze o podwyższonym ciśnieniu (1500 hPa) z podwyższonym stężeniem tlenu oraz dodatkiem CO₂ i wodoru (H₂); terapia wspomagająca oferowana w ośrodku Convertere.