akademiawodociagowca/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Projekt

Platforma do organizacji szkolen i webinarow. Obsluguje pelny cykl zycia wydarzenia:

• rejestracja uczestnika
• przypomnienia mailowe
• spotkanie online
• nagranie
• pytania od uczestnikow
• zapisy na zadania powstale podczas webinaru

Model wdrozenia

Osobna instancja dla kazdego klienta, na jego serwerze i jego domenie.

• jedno repozytorium, jedna wersja kodu
• roznice miedzy klientami wylacznie w konfiguracji (zmienne srodowiskowe)
• zadnych galezi per klient
• zadnych danych klienta w obrazie Docker

Stack

Backend

• Java 21, Spring Boot 3.4.1
• Maven systemowy (mvn), bez wrappera - nie dodawac mvnw
• Spring Web (REST), base path API: /api
• Spring Security, stateless JWT HS256, biblioteka jjwt
• Spring Data JPA / Hibernate, spring.jpa.hibernate.ddl-auto: validate
• Flyway jako jedyne zrodlo schematu bazy, migracje w db/migration/Vn__opis.sql
• PostgreSQL 16, bez PostGIS
• MinIO (S3-compatible) na nagrania, materialy i zalaczniki
• springdoc-openapi (Swagger UI)
• Lombok
• Spring Mail do wysylki zaproszen i przypomnien
• WebSocket ze STOMP do czatu, pytan na zywo i zgloszen do zabrania glosu

Frontend

• React 18 + TypeScript, Vite 6
• React Router 6
• TanStack Query 5
• axios z interceptorem dokladajacym JWT
• Tailwind CSS 3, tokeny designu w tailwind.config.js wedlug systemu HydroNexis
• Lucide (lucide-react) jako ikony, przez komponent Icon z jawna mapa nazw
• IBM Plex Sans do interfejsu, IBM Plex Mono do danych i terminow

Infrastruktura

• Docker Compose: postgres + minio + backend + frontend
• nginx serwuje SPA i proxuje /api do backendu
• cala konfiguracja instancji przez zmienne srodowiskowe w .env

Wideo

Aplikacja nie jest przywiazana do jednego dostawcy wideo. W backendzie interfejs VideoProvider z operacjami:

• utworzenie pokoju
• wygenerowanie tokenu dostepu dla uczestnika
• pobranie nagrania
• obsluga webhooka

Implementacja wybierana zmienna VIDEO_PROVIDER. Kazdy klient ma wlasne konto i wlasne klucze u dostawcy.

Role w pokoju

Trzy role, egzekwowane uprawnieniami w tokenie dostepu, nie regulaminem:

Rola	Uprawnienia
prelegent	publikuje obraz i dzwiek
uczestnik	tylko odbiera, ma czat i pytania
uczestnik z glosem	publikuje wylacznie dzwiek, po zgodzie moderatora
uczestnik z kamera albo ekranem	publikuje obraz lub ekran, wylacznie po indywidualnej zgodzie prowadzacego

Wideo i ekran uczestnikow sa domyslnie wylaczone na poziomie uprawnien. Wlacza je wylacznie prowadzacy: calej sali ("wideo dla wszystkich", bez ekranu) albo konkretnej osobie (kamera i ekran osobno, patrz "Indywidualna zgoda na kamere i ekran"). Uczestnik sam niczego sobie nie wlaczy.

Zasady pracy

• Zmiany schematu bazy wylacznie przez nowa migracje Flyway. Nigdy przez edycje istniejacej migracji ani przez Hibernate.
• Zadnych sekretow, kluczy ani adresow w kodzie. Wszystko przez zmienne srodowiskowe.
• Komentarze i dokumentacja po polsku, nazwy klas, pol i endpointow po angielsku.
• Nie uzywac znaku em dash ani en dash. Wylacznie zwykly minus.
• Tresc widoczna dla uzytkownika koncowego pisana jest poprawna polszczyzna, z ogonkami. Zasada pisania bez znakow diakrytycznych dotyczy wylacznie komentarzy w kodzie, dokumentacji i nazw technicznych. Szczegoly nizej, w sekcji "Polskie znaki".
• Nie dodawac bibliotek spoza powyzszej listy bez pytania. Zatwierdzone wyjatki: TipTap (@tiptap/react, starter-kit, rozszerzenia obrazka, linku i wyrownania), @tailwindcss/typography oraz jsoup po stronie backendu.

Dane nietykalne

Tabela app_settings i konto administratora sa nietykalne.

• Nigdy docker compose down -v. Flaga -v kasuje wolumeny, czyli baze i MinIO razem z cala konfiguracja instancji. Odtworzenie wymaga recznego wpisania na nowo danych SMTP, kluczy bramki SMS i kluczy dostawcy wideo, ktorych nie ma nigdzie indziej: .env ich nie zawiera, bo konfiguracja poczty i SMS idzie wylacznie przez panel. Do zatrzymania sluzy docker compose down bez flagi.

• Nigdy nie kasowac wolumenu bazy ani wolumenu MinIO zadna inna droga (docker volume rm, docker system prune -a --volumes).

• Zadnego DELETE, TRUNCATE ani DROP obejmujacego app_settings lub users. Dotyczy to takze polecen bez klauzuli WHERE i takich, ktore obejmuja te tabele posrednio, przez kasowanie kaskadowe.

• Czyszczenie danych testowych ogranicza sie do tabel operacyjnych: webinars i wszystko, co od nich zalezy kaskadowo (registrations, consents, interactions, interaction_votes, tasks, offer_topics, reminder_rules, recordings, materials), oraz notifications i media_files.

• Przed kazdym krokiem, ktory moze wyslac maila albo SMS, sprawdz faktyczny stan konfiguracji w bazie, zamiast polegac na tym, co zostalo ustalone wczesniej w rozmowie. Ustawienia zmieniaja sie przez panel, bez restartu aplikacji, wiec wartosc sprzed kilku minut moze juz nie obowiazywac. Dotyczy to zwlaszcza MAIL_SAFE_MODE, MAIL_SAFE_RECIPIENT, SMS_SAFE_MODE, SMS_SAFE_RECIPIENT i SMS_ENABLED:

  docker exec webinar-postgres psql -U webinar -d webinar -c \
    "SELECT \"key\", value FROM app_settings WHERE \"key\" LIKE '%SAFE%' OR \"key\"='SMS_ENABLED';"
  

• Dane testowe z terminem w przeszlosci wystarcza, zeby scheduler ruszyl. Zadanie podsumowan raz wyslalo z tego powodu 12 realnych wiadomosci przez produkcyjny SMTP klienta. Zakladajac dane testowe, dawaj terminy w przyszlosci albo najpierw sprawdz tryb bezpieczny.

Polskie znaki

Wszystko, co czyta czlowiek, ma pelne znaki diakrytyczne (ą ć ę ł ń ó ś ź ż). Audyt z 2026-08-29 znalazl okolo 240 napisow w interfejsie i 100 komunikatow backendu napisanych bez ogonkow, bo zasada "bez diakrytykow" zostala bledem rozciagnieta z komentarzy na cala tresc produktu.

• Z ogonkami: etykiety i naglowki w panelu, komunikaty bledow zwracane przez API (ResponseStatusException, message w Bean Validation), szablony maili, strony publiczne, aria-label, title, alt, teksty w confirm(), opisy ustawien z SettingKey (trafiaja do panelu przez SettingsController), tresci zgod, zajawka Open Graph w index.html.
• Bez ogonkow: komentarze w kodzie, ten plik, nazwy klas, pol i endpointow, slugi, klucze ustawien (MAIL_HOST, DEFAULT_REMINDERS), enumy backendu (DRAFT, CONFIRMED), nazwy ikon, wartosci tone i variant, klasy CSS, sciezki tras, nazwy plikow eksportu.
• Logi zostaja bez ogonkow. log.info i pokrewne czyta administrator w terminalu, gdzie kodowanie bywa przypadkowe. To nie jest tresc dla uzytkownika.
• Opisy springdoc (@Operation, @Schema) zostaja bez ogonkow. To dokumentacja techniczna, nie interfejs produktu.
• Tresc SMS nigdy nie dostaje ogonkow. Przelaczaja bramke na UCS-2, gdzie limit spada ze 160 do 70 znakow i jedna wiadomosc rozbija sie na kilka platnych czesci. Ta sama zasada dotyczy ReminderTextBuilder.
• Kodowanie: wszystkie pliki w UTF-8 bez BOM. Java dziedziczy project.build.sourceEncoding=UTF-8 ze spring-boot-starter-parent, wiec nie trzeba go dopisywac, ale nie wolno tego nadpisac.
• Tresc zgod poprawia sie migracja, bez podnoszenia CONSENT_VERSION (V11), bo zmienia sie wylacznie pisownia, a nie znaczenie oswiadczenia. Podniesienie wersji sugerowaloby, ze uczestnik zgodzil sie na cos innego, i wymagaloby zbierania zgod od nowa. Migracja aktualizuje tylko wpisy o dokladnie starej tresci domyslnej, wiec nie nadpisuje tego, co administrator zmienil w panelu.
• Nowa etykieta pisana jest poprawnie od razu. Poprawianie tego audytem po fakcie kosztuje wielokrotnie wiecej niz napisanie dobrze za pierwszym razem.

Kopiowanie webinaru

Ikona kopiowania w wierszu listy tworzy nowy webinar na podstawie istniejacego (WebinarCopyService, POST /admin/webinars/{id}/copy). To najczestsza czynnosc przy szkoleniach cyklicznych, wiec granica "co sie kopiuje" jest tu regula, a nie szczegolem implementacji.

• Kopiujemy pomysl na wydarzenie, nie slad po tym, ze sie odbylo. Przechodzi tresc strony, tresc zaproszenia, ustawienia certyfikatow, reguly przypomnien, tematy zapytan i materialy. Nie przechodza zapisy, obecnosc, interakcje, nagrania, certyfikaty, pokoj u dostawcy ani summary_sent_at. Skopiowanie czegokolwiek z drugiej listy oznaczaloby uczestnikow zapisanych na wydarzenie, ktore sie nie odbylo, albo certyfikaty z cudzego szkolenia.
• Termin nie jest przepisywany, ale nie moze tez zostac pusty. starts_at i ends_at maja NOT NULL, a WebinarRequest wymaga obu pol. Kopia dostaje termin zastepczy: pelna godzina za tydzien, o dlugosci przepisanej z oryginalu. Data w przyszlosci, a nie w przeszlosci, bo przy przypadkowej publikacji zapisy maja zostac otwarte, a nie zamknac sie natychmiast. Status DRAFT i tak wymusza swiadome opublikowanie.
• Plik materialu jest kopiowany w skladzie, nie wspoldzielony. Wspolny obiekt sprawialby, ze usuniecie materialu przy jednej edycji psuje druga, a podmiana pliku zmienia go wstecz w szkoleniu juz zakonczonym.
• Blad kopiowania jednego pliku nie przerywa calosci. Kopia webinaru jest przydatna takze bez jednego zalacznika; odtwarzanie wszystkiego od zera kosztuje znacznie wiecej. Nieudany plik idzie do logu.
• Flaga enabled reguly przypomnienia przechodzi bez zmian. Regula wylaczona swiadomie ma zostac wylaczona takze w kopii.
• Po skopiowaniu panel przechodzi od razu do edycji kopii i mowi wprost, ze termin jest tymczasowy. Pilnuje tego WebinarCopyTest, ktory sprawdza obie strony granicy: co ma sie znalezc w kopii i czego w niej byc nie moze.

Wyszukiwanie na listach

Lista webinarow ma wyszukiwanie po tytule, lista zapisanych po nazwisku, imieniu i adresie. Oba filtruja w bazie, w tym samym zapytaniu co paginacja.

• cast(:parametr as ...) przy KAZDYM parametrze opcjonalnym jest obowiazkowe. Sterownik wysyla null bez typu, a PostgreSQL nie wywnioskuje go z samego ? is null. Przy tekscie konczy sie to bledem "function lower(bytea) does not exist", przy dacie "could not determine data type of parameter". W obu przypadkach cala lista przestaje dzialac dokladnie wtedy, gdy filtr nie jest uzywany, czyli w najzwyklejszym uzyciu. Blad wszedl na instancje, bo zaden test nie wolal listy bez frazy; pilnuje tego teraz WebinarSearchTest.
• Nowy test listy zaczyna sie od przypadku bez filtru. Wariant z fraza dziala nawet wtedy, gdy wariant pusty jest zepsuty, wiec sama fraza niczego nie chroni.
• Sortowanie po liczbie zapisanych nadal nie jest mozliwe, bo licznik powstaje osobnym zapytaniem do juz pobranej strony. Ta sama regula co przy kolumnie "Zapisani". Sortowanie idzie po tytule, terminie, statusie i dacie dodania.
• Lista zapisanych sortuje sie takze po obecnosci (attended), a kolumna Obecnosc jest widoczna w tabeli i na karcie mobilnej.
• Zmiana frazy cofa na pierwsza strone, tak samo jak zmiana kazdego innego filtru.

Potwierdzenia operacji nieodwracalnych

Kazda operacja kasujaca pyta o potwierdzenie, a pytanie nazywa konkretny obiekt. "Czy na pewno?" bez nazwy nie daje uzytkownikowi niczego, na czym moglby oprzec decyzje.

• Usuniecie webinaru pokazuje, ile przepadnie. Panel pobiera najpierw GET /admin/webinars/{id}/deletion-impact (liczba zapisow i certyfikatow) i dopiero z tymi liczbami pyta. Przy webinarze z setka zapisow i wydanymi certyfikatami odpowiedz jest zupelnie inna niz przy pustym szkicu.
• Pytanie podpowiada odwolanie jako lagodniejsza alternatywe. W wiekszosci przypadkow uzytkownik chce zamknac zapisy, a nie skasowac dane.
• Usuniecie webinaru kasuje kaskadowo zapisy, zgody, obecnosc, interakcje, nagrania, materialy, zaproszenia i certyfikaty. Pliki w MinIO zostaja: utrata pliku jest gorsza niz zajete miejsce.

Ustawienia o zamknietym zbiorze wartosci i wskazujace na plik

SettingType ma poza STRING, INT, BOOLEAN i PASSWORD takze SELECT i MEDIA.

• SELECT pokazuje liste wyboru, a backend odrzuca wartosc spoza listy (SettingKey.accepts, walidacja w SettingsService.update). Panel jest wygoda, bariera jest po stronie backendu: endpoint zapisu da sie wywolac z pominieciem panelu, a literowka w nazwie dostawcy wideo cicho przelaczalaby instancje w tryb NONE. Dopuszczalne wartosci ida do panelu w polu allowedValues.
• Kazde ustawienie o zamknietym zbiorze wartosci ma byc typu SELECT. Dopisanie wartosci do enuma bez dopisania jej do allowedValues sprawia, ze nie da sie jej wybrac.
• MEDIA pokazuje wybor pliku z biblioteki (MediaField, opakowanie MediaPicker): miniatura biezacego wyboru, wybor, wyczyszczenie i wgranie nowego. Wartoscia jest identyfikator pliku, a zaden uzytkownik panelu nie ma go skad wziac recznie.
• Logo i ikona instancji celowo tego nie uzywaja. APP_LOGO_URL i APP_FAVICON_URL maja wlasny edytor z kadrowaniem (ImageEditor), a ich wartoscia jest adres, nie identyfikator.

Numer certyfikatu

Wzor CERTIFICATE_NUMBER_FORMAT obsluguje {rok}, {miesiac}, {numer} i {prefiks}, gdzie prefiks pochodzi z CERTIFICATE_NUMBER_PREFIX.

• Pusty prefiks usuwa znacznik wraz z sasiadujacym separatorem. Samo podstawienie pustego ciagu dawaloby "/2026/1", czyli numer z wiszacym ukosnikiem. Numer trafia na dokument i sluzy do weryfikacji publicznej, wiec nie moze wygladac na uszkodzony tylko dlatego, ze instancja nie uzywa prefiksu. Sam prefiks zlozony ze spacji liczy sie jak brak prefiksu.
• Pilnuje tego CertificateNumberTest, ktory sprawdza takze warianty z myslnikiem i spacja jako separatorem.

Znaczniki czasu w encjach

Encja ustawia created_at sama, w @PrePersist. Wypelnianie go w kazdym miejscu tworzacym rekord z osobna wystarczy raz przeoczyc, zeby zapis konczyl sie naruszeniem NOT NULL. Zdarzylo sie to na OfferTopic przy kopiowaniu webinaru: encja jako jedyna nie miala @PrePersist, a wszystkie dotychczasowe miejsca tworzenia ustawialy znacznik recznie. Warunek if (createdAt == null) pozwala nadal podac wartosc jawnie, gdy jest potrzebna.

Lista webinarow: zakladki i sortowanie

/webinary ma dwie zakladki, Aktywne i Zakonczone, oraz sortowanie po kolumnach.

• Podzial idzie po endsAt, nie po statusie FINISHED. Nic w aplikacji tego statusu nie ustawia, wiec filtr po nim dawalby zawsze pusta liste. Ta sama regula obowiazuje na stronie publicznej, gdzie webinar po endsAt jest juz odbyty. Gdyby kiedys pojawil sie proces ustawiajacy FINISHED, warto to ujednolicic, ale wtedy swiadomie, nie przez podmiane filtru.
• Domyslne sortowanie to createdAt malejaco, czyli ostatnio dodane na gorze.
• Pole sortowania jest na bialej liscie (SORTABLE w kontrolerze). Nazwa pola trafia do zapytania JPA, wiec przekazanie parametru wprost pozwalaloby sortowac po polach spoza listy albo wywolac blad ujawniajacy budowe encji. Wartosc spoza listy cicho wraca do sortowania domyslnego, bez bledu.
• Kolumna "Zapisani" celowo nie jest sortowalna. Liczba zapisanych jest doliczana osobnym zapytaniem do juz pobranej strony, wiec baza nie potrafi po niej sortowac, a sortowanie samej biezacej strony wprowadzaloby w blad.
• Kolumna "Dodano" jest ukryta ponizej 2xl. Zmierzone: przy 1280px jej dolozenie rozpycha tabele ponad szerokosc panelu i kolumna akcji wymaga przewijania.
• Termin na liscie jest w dwoch liniach i bez nazwy strefy (formatDateTimeParts). W jednej linii z nazwa strefy kolumna zajmowala ponad 300px i wypychala akcje poza ekran. Strefa zostaje jawna tam, gdzie ma znaczenie: w formularzu webinaru, na liscie zapisanych i na stronie publicznej, gdzie uzytkownik moze byc w innej strefie niz webinar. Nie uzywac tu formatWithZone.
• Tabela przewija sie w poziomie wewnatrz wlasnego kontenera (overflow-x-auto). Bez tego kolumna akcji byla nieosiagalna przy waskim oknie. Strona nadal nie przewija sie w poziomie, zgodnie z zasada responsywnosci.

Samowywolanie metod transakcyjnych: test zamiast reguly

@Transactional na metodzie wolanej z tej samej klasy nie dziala, bo samowywolanie omija proxy Springa. Ten sam blad wystapil trzy razy (JwtService, OrderService, CourseCertificateMailer) i za kazdym razem ujawnil sie dopiero na uruchomionej instancji: kod kompiluje sie poprawnie i dobrze wyglada przy czytaniu. Sama regula w tym pliku nie zapobiegla, bo wymaga, zeby ktos o niej pamietal dokladnie w chwili pisania.

Pilnuje tego teraz TransactionalSelfInvocationTest.

• Czyta bajtkod, nie zrodla. Interesuje nas faktyczne wywolanie, a nie to, jak wyglada w tekscie. ASM pochodzi ze spring-core, ktore i tak jest w zaleznosciach: zadna biblioteka nie zostala dolozona.
• this.metoda() i self.metoda() maja w bajtkodzie tego samego wlasciciela, bo pole self jest typu tej samej klasy. Rozni je odbiorca wywolania, a ten lezy na stosie pod argumentami: this.f(x) to ALOAD 0, ALOAD 1, INVOKEVIRTUAL, a self.f(x) to ALOAD 0, GETFIELD self, ALOAD 1, INVOKEVIRTUAL. Patrzenie na ostatnia instrukcje daje wiec zla odpowiedz przy kazdej metodzie z argumentem: test musi sledzic stos operandow i cofnac sie o tyle pozycji, ile argumentow ma wolana metoda.
• Test zglasza wylacznie to, co zmienia zachowanie: REQUIRES_NEW (bez proxy nowa transakcja nie powstaje, a to cala jego rola) oraz zapis wolany z metody nietransakcyjnej (bez proxy nie ma transakcji wcale). Metoda readOnly wolana z innej metody transakcyjnej dolacza do istniejacej transakcji i jest nieszkodliwa; takich wywolan sa dziesiatki, wiec ich zglaszanie utopiloby prawdziwe znaleziska w szumie.
• Test zostal sprawdzony w obie strony. Pierwsza wersja dawala 12 falszywych alarmow, druga PRZEPUSZCZALA prawdziwy blad. Wyszlo to dopiero po celowym przywroceniu samowywolania: zielony test niczego nie dowodzi, dopoki nie zobaczy sie, jak czerwienieje na prawdziwym przypadku.
• Lista wyjatkow (ALLOWED) jest pusta i ma taka zostac. Wpis tam to swiadoma decyzja z uzasadnieniem, a nie sposob na uciszenie testu.

Audyt przy okazji znalazl dwa dotad niewykryte bledy:

• RecordingService: downloadFromProvider celowo nie jest transakcyjne (pobieranie trwa minutami), ale wolalo przez this cztery metody @Transactional. Zadna nie miala wlasnej transakcji, wiec zmiana stanu nagrania nie zapisywala sie wcale. Byly przy tym protected, czyli niewidoczne przez proxy CGLIB: podniesione do public.
• SummaryScheduler: planSummaries jest @Scheduled i nietransakcyjne, a wolalo queueSummary przez this. Wpisy w kolejce i znacznik summary_sent_at przestawaly byc atomowe, czyli dokladnie ten rozjazd, przed ktorym ostrzega sekcja o podsumowaniach.

Granica transakcji: encje nie opuszczaja serwisu

Encje JPA nigdy nie opuszczaja warstwy serwisu. Kontroler dostaje wylacznie obiekty widoku, skladane wewnatrz transakcji. Watki asynchroniczne i powiadomienia dostaja zwykle wartosci, nigdy encje.

• spring.jpa.open-in-view jest ustawione na false i ma takie zostac. Przy true sesja Hibernate zyje az do wyrenderowania odpowiedzi, wiec leniwe pole doczytuje sie po cichu i blad nie ujawnia sie w testach, tylko pozniej, gdy ktos zmieni mapowanie albo doda watek asynchroniczny. Wylaczone open-in-view sprawia, ze naruszenie granicy widac od razu.
• Objaw jest mylacy. LazyInitializationException poza transakcja daje blad 500, a front, ktory kazdy nieudany request tlumaczy jako wygasla sesje, pokazuje wylogowanie albo "Wymagane uwierzytelnienie". Szukanie takiego bledu w warstwie logowania nie ma sensu.
• Mapowanie encja -> widok robi metoda serwisu z @Transactional, nie statyczne View.of(entity) wolane z kontrolera. Metoda of sama w sobie jest w porzadku, ale wolno ja wolac tylko wewnatrz transakcji.
• @Transactional na metodzie wolanej z tej samej klasy nie dziala. Samowywolanie omija proxy Springa, wiec adnotacja na prywatnej metodzie pomocniczej albo na metodzie kontrolera wolanej przez this jest bez znaczenia. Gdy naprawde trzeba wywolac wlasna metode transakcyjna, wstrzykuje sie @Lazy referencje na samego siebie (tak robi SummarySender).
• Powiadomienia dostaja rekord z wartosciami. SalesNotifier przyjmuje OfferService.SubmitResult, nie Interaction. Watek @Async startuje po zamknieciu transakcji, wiec przekazana tam encja jest juz odlaczona i pierwsze leniwe pole wywala wysylke.
• Miejsca, w ktorych to juz raz zawiodlo, i tak samo zawiedzie znowu: MediaView (uploadedBy, webinar), InteractionView (autor), TaskView (webinar), OfferService.describe (zapis i webinar), SummaryData (wszystko).

Katalog ustawien: brak wartosci ma znaczyc wariant bezpieczniejszy

Kazdy klucz w SettingKey ma jawnie rozstrzygniete, co znaczy brak wartosci. Sluzy do tego pole Requirement z trzema wartosciami: HAS_DEFAULT (klucz ma wartosc domyslna), REQUIRED (bez konfiguracji funkcja nie dziala i tak ma byc), OPTIONAL_EMPTY (pusta wartosc jest poprawnym stanem docelowym).

• Powstalo po realnym bledzie. MAIL_SAFE_MODE przez piec krokow nie dzialal, bo nie mial wartosci domyslnej. Brak wpisu w bazie czytal sie przez Boolean.parseBoolean("") jako false, czyli tryb bezpieczny wylaczony, a raport twierdzil, ze jest wlaczony. Kod kompilowal sie i dobrze wygladal.
• Wartosc domyslna musi byc wariantem bezpieczniejszym. Brak konfiguracji nie moze prowadzic do wysylki na prawdziwe adresy, przyjecia platnosci, ujawnienia danych ani pominiecia zabezpieczenia. Lepiej, zeby cos nie zadzialalo.
• Typ BOOLEAN i INT ZAWSZE ma wartosc domyslna. Pusty napis czyta sie jako false, a Integer.parseInt("") wywala wyjatek w metodzie, ktora ma wlasnie obsluzyc uszkodzona wartosc. Ani jedno, ani drugie nie moze byc skutkiem braku wpisu w bazie.
• Wartosc domyslna SELECT musi byc na jego wlasnej liscie. Inaczej panel pokazuje liste, w ktorej biezaca wartosc nie istnieje.
• Klucz REQUIRED czyta sie przez SettingsService.getRequired, ktore rzuca MissingConfigurationException zamiast oddac pusty napis. Sklejenie linku z pustego prefiksu dawalo adres w rodzaju /w/szkolenie: w mailu martwy u kazdego odbiorcy, a wygladajacy na wyslany poprawnie. Dotyczylo to MailService i InvitationSender, czyli takze linku wypisania, ktory musi dzialac z powodow prawnych.
• Gdzie brak linku jest lepszy niz blad, zwracamy null. SummaryService pomija odnosnik do nagrania i materialow, gdy nie ma adresu publicznego: podsumowanie bez linku nadal ma sens, podsumowanie z linkiem donikad nie.
• Pilnuje tego SettingDefaultsTest, sprawdzajac takze, ze tryby bezpieczne sa domyslnie wlaczone, a funkcje o realnych skutkach (AUTOPAY_ENABLED, SMS_ENABLED, SALES_SMS_ENABLED, VIDEO_DELETE_AFTER_DOWNLOAD) domyslnie wylaczone. Test zostal sprawdzony w obie strony: po dopisaniu klucza bez wartosci domyslnej faktycznie czerwienieje i wywala build.

Wypis konfiguracji przy starcie

SettingsStartupReport wypisuje po starcie stan ustawien krytycznych: oba tryby bezpieczne wraz z adresami zastepczymi, limity godzinowe, APP_PUBLIC_URL, dane SMTP, dostawce wideo i tryb Autopay.

• Po to, zeby stan bylo widac bez zagladania do bazy. Blad MAIL_SAFE_MODE przetrwal piec krokow glownie dlatego, ze poznanie stanu faktycznego wymagalo swiadomego zapytania bazy i wiedzy, czego szukac.
• Sekrety wylacznie jako "ustawiony" albo "BRAK". Log trafia do terminala, do plikow i czesto do systemu zbierania logow, wiec wpisanie tam klucza API oznacza jego wyciek do miejsca, ktorego nikt nie traktuje jak sejfu.
• Ostrzezenia ida na poziomie WARN i nazywaja skutek, nie ustawienie: wylaczony tryb bezpieczny mowi "poczta idzie do PRAWDZIWYCH odbiorcow", Autopay w trybie produkcyjnym mowi o prawdziwych pieniadzach, a Jitsi bez JWT o pokoju otwartym dla kazdego, kto zna adres.
• ApplicationReadyEvent, nie @PostConstruct: ustawienia czytaja z bazy, ktora przy tworzeniu beanow moze nie miec jeszcze wykonanych migracji Flyway.
• Wypis nie ma polskich znakow, zgodnie z regula dotyczaca logow.

Tryb bezpieczny wysylki

MAIL_SAFE_MODE i SMS_SAFE_MODE, domyslnie wlaczone, kieruja cala wysylke na jeden adres z MAIL_SAFE_RECIPIENT / SMS_SAFE_RECIPIENT. Do tego bezpiecznik ilosciowy: MAIL_RATE_LIMIT_PER_HOUR (100) i SMS_RATE_LIMIT_PER_HOUR (20).

• Powstalo po realnym incydencie. Zadanie podsumowan potraktowalo webinary z danymi testowymi jako zakonczone i wyslalo 12 wiadomosci przez produkcyjny SMTP klienta, w tym 10 na nieistniejace adresy @example.test. Dane testowe z terminem w przeszlosci wystarcza, zeby scheduler ruszyl.
• Domyslnie wlaczony, i to jest swiadome. Swiezo postawiona instancja ma NIE wysylac do prawdziwych ludzi, dopoki ktos nie zdecyduje inaczej. Odwrotna domyslna wartosc sprawia, ze kazda kopia produkcji zaczyna od wysylania maili do uczestnikow z bazy.
• Jeden punkt egzekwowania: MailService.deliver. Wysylka jest rozproszona po szesciu klasach, wiec przekierowanie dokladane w kazdej z osobna oznaczaloby, ze nowa sciezka domyslnie omija zabezpieczenie. Nigdy nie wolac sender.send(...) wprost, zawsze przez deliver. Dla SMS rownowaznikiem jest SmsService.send.
• Wpis w notifications zachowuje prawdziwego odbiorce, nie zastepczego. Dziennik dokumentuje zamiar wysylki; podmiana adresu sprawilaby, ze po wylaczeniu trybu nie da sie odtworzyc, kto co dostal.
• Tryb wlaczony bez ustawionego adresu wstrzymuje wysylke, zamiast przepuscic ja do prawdziwego odbiorcy. Cicha wysylka przy wlaczonym zabezpieczeniu jest najgorszym z mozliwych zachowan: administrator jest przekonany, ze nic nie wychodzi.
• Limit daje QUEUED, nigdy FAILED. Wiadomosc ma pojsc, tylko pozniej, wiec RateLimitExceededException jest lapany osobno od zwyklych bledow. Wpis juz bedacy w kolejce zostaje nietkniety, a wysylka natychmiastowa dostaje markQueued z scheduled_at, zeby scheduler ja podjal.
• Prefiks SMS bez ogonkow. Tekst prefiksu wlicza sie do limitu 160 znakow, a diakrytyki przelaczaja bramke na UCS-2, gdzie limit spada do 70.
• Pilnuje tego SafeDeliveryTest, w tym przypadek "tryb wlaczony, brak adresu" sprawdzajacy, ze wiadomosc nie poszla do prawdziwego odbiorcy.

Przekrojowy ekran certyfikatow

Trasa /kursy/certyfikaty, endpointy /api/admin/certificates/**. Jedna lista dla calej instancji, obejmujaca certyfikaty za kursy i za webinary.

• Ekran sluzy PRZEGLADANIU I OBSLUDZE, nie wydawaniu. Wydawanie zostaje na karcie kursu i karcie webinaru, gdzie widac kontekst: kto ukonczyl, kto byl obecny, komu dokument sie nalezy. Tutaj tego kontekstu nie ma, wiec byloby wydawaniem na slepo.
• Jedno zapytanie z UNION, nie dwa listy scalane w pamieci. Ekran pokazuje liste posortowana po dacie wydania i stronicowana; dwa osobne zapytania trzeba by scalac i sortowac po stronie aplikacji, a wtedy paginacja przestaje dzialac: nie da sie wziac dwudziestej piatej strony z dwoch list, nie pobierajac ich w calosci.
• Filtr zrodla niesie DWIE wartosci: identyfikator i to, czy chodzi o kurs. Kursy i webinary maja wlasne sekwencje, wiec sam identyfikator mieszalby dokumenty o tym samym numerze z obu tabel.
• Przedzial dat obejmuje CALY dzien koncowy. Uzytkownik wpisujacy "do 31 grudnia" oczekuje, ze certyfikat wydany tego dnia o 14:00 sie zmiesci, wiec to idzie do zapytania przesuniete o dobe, z porownaniem ostrym.
• PONOWNA WYSYLKA SIEGA PO PLIK ZE SKLADU, NIGDY NIE RENDERUJE NA NOWO. W wierszu zapisane sa numer i data, ale tytul zrodla, liczba godzin, szablon i logo juz nie: ponowne renderowanie wzieloby ich biezace wartosci, wiec odbiorca dostalby ten sam numer z inna trescia niz dokument, ktory ma w teczce, a weryfikacja publiczna potwierdzalaby cos innego, niz trzyma w reku pracodawca. Doszlaby druga rzecz: renderowanie moze sie nie powiesc (uszkodzony wlasny szablon organizatora), a ponowna wysylka jest operacja wsparcia, wykonywana zwykle wtedy, gdy cos juz poszlo nie tak.
• Brak pliku w skladzie NIE generuje zastepczego dokumentu. Wiadomosc idzie z samym odnosnikiem, a odpowiedz niesie withAttachment = false i komunikat, zeby wsparcie wiedzialo, co odbiorca faktycznie dostal. Wygenerowanie innego pliku pod tym samym numerem byloby gorsze niz brak zalacznika.
• Uniewaznionego certyfikatu nie wysylamy. Odbiorca dostalby dokument, ktory nie potwierdza juz niczego.
• Uniewaznienie z tego ekranu WYMAGA NOTATKI, inaczej niz z karty kursu i webinaru: tam widac, czego dokument dotyczyl, tutaj nie. Dokument mogl juz trafic do pracodawcy, wiec po miesiacu musi dac sie ustalic, dlaczego przestal byc wazny. Samo uniewaznienie robi CertificateService.revoke: to ta sama operacja, nie druga kopia.
• Filtr zrodel pokazuje wylacznie kursy i webinary z wlaczonymi certyfikatami. Reszta nie ma czego pokazac, a dluga lista wyboru z pozycjami bez wynikow utrudnia szukanie.
• CAST(:x AS ...) przy KAZDYM parametrze opcjonalnym, takze w zapytaniu zliczajacym. Sprawdzone na zywo: lista bez filtru i kazdy filtr osobno.

Nawigacja: zadna pozycja nie jest juz planned

Po dodaniu ekranu certyfikatow wszystkie dwanascie pozycji menu prowadzi do istniejacych widokow. Flaga planned zostala w typie NavItem, bo przyda sie przy nastepnym widoku budowanym etapami, ale nie ma juz zadnego uzycia.

• Zdjecie flagi to zmiana w DWOCH miejscach: wpis w navigation.ts i trasa w App.tsx. Sprawdzenie, ze kazda pozycja ma trase, robi sie porownaniem wszystkich wartosci to: z deklaracji z path= w App.tsx.
• Kazda pozycja menu jest teraz JEDNOLINIJKOWA. Wczesniej trzy byly sformatowane wieloliniowo i podmiana jednolinijkowa ominela jedna z nich: ekran Postepy dzialal, a pozycja menu byla wyszarzona. Wieloliniowe zostaly wylacznie obiekty obszarow (webinary, akademia), ktore maja po piec pol i inaczej sie nie da.

Certyfikaty ukonczenia kursu

Rozszerzenie istniejacego mechanizmu (V26), a nie drugi mechanizm. Kolumny course_id i enrollment_id w certificates, endpointy /admin/courses/{id}/certificates/**, szablon certificate/course.html, mail course-completed.

• JEDNA TABELA, DWA ZRODLA. Certyfikat z kursu to ten sam dokument co z webinaru: ten sam numer z tej samej puli, ten sam plik w skladzie, ta sama weryfikacja publiczna i to samo uniewaznienie. Druga tabela oznaczalaby dwie numeracje, dwie sciezki weryfikacji i dwa miejsca do poprawienia przy kazdej zmianie regulaminu.
• Dokladnie jedno zrodlo, wymuszone CHECKiem (ck_certificates_owner): albo webinar z rejestracja, albo kurs z zapisem, nigdy oboje. Ta sama zasada co przy autorze interakcji. Bez tego blad w kodzie dawalby dokument bez wlasciciela albo z dwoma, a weryfikacja publiczna nie wiedzialaby, co on potwierdza. Sprawdzone na zywo: baza odrzuca oba przypadki.
• webinar_id i registration_id musialy stac sie nullowalne. Wiersze istniejace maja je wypelnione i takie zostaja, czego pilnuje CHECK.
• Numeracja jest WSPOLNA i taka ma zostac. Numer sluzy do weryfikacji publicznej, wiec ma byc unikalny w calej instancji. Licznik, blokada wiersza i formatNumber pozostaja w CertificateService; CourseCertificateService siega po nextNumber() przez @Lazy referencje.
• {typ} we wzorze numeru zostal ROZWAZONY I ODRZUCONY. Nie dodaje nic do unikalnosci, a tworzy realne ryzyko: administrator dopisujacy znacznik po wydaniu pierwszych dokumentow dostaje dwa numery roznice sie wylacznie nim, przy wspolnym liczniku, a certyfikaty juz lezace w teczkach przestaja pasowac do biezacego wzoru. Zrodlo widac na samym dokumencie (tytul kursu kontra tytul webinaru) i w weryfikacji publicznej (forCourse).
• Osobny szablon certificate/course.html. Dokument mowi co innego: nie "wzial udzial w szkoleniu", tylko "ukonczyl kurs", i moze podac wynik sprawdzianu. Uklad, kolory i typografia sa celowo takie same: to ten sam dokument tej samej instytucji, a nie druga marka.
• Wlasny szablon organizatora dziala w obu zrodlach. Zmienne webinarTitle i webinarDate sa dostepne takze przy kursie, obok courseTitle i completedDate: szablon napisany kiedys dla webinaru nie pokazuje pustych miejsc po przeniesieniu na kurs. Tresc przechodzi przez ten sam HtmlSanitizer co tresc strony.
• Wynik quizu to NAJLEPSZE zdane podejscie, nie ostatnie: kursant mogl podchodzic kilka razy, a dokument ma pokazywac wynik, ktorym zaliczyl. Kurs bez quizu daje null i certyfikat po prostu nie podaje procentu; zero wygladaloby jak oblany test.
• Wydanie automatyczne dzieje sie w TEJ SAMEJ transakcji co zmiana statusu na COMPLETED. Zaliczenie bez dokumentu i dokument bez zaliczenia sa jednakowo zle. Blad wydania nie cofa zaliczenia: kursant zrobil swoje, a brakujacy dokument administrator wyda recznie.
• Mail kolejkuje sie dopiero PO zatwierdzeniu transakcji (afterCommit). Wpis powstajacy w tej samej transakcji niosl by wiadomosc o certyfikacie, ktorego przy wycofaniu w bazie nie ma.
• afterCommit wola metode PRZEZ PROXY (@Lazy self). @Transactional na metodzie wolanej z tej samej klasy nie dziala, a tutaj bylo to szczegolnie grozne: afterCommit biegnie po zamknieciu transakcji, wiec bez wlasnej transakcji zapis konczyl sie bledem "no transaction is in progress" i mail nie trafial do kolejki wcale. Zdarzylo sie to realnie i wylapal to dopiero test na dzialajacej instancji, bo kompilacja i testy jednostkowe tego nie widza.
• "Dokladnie raz" pochodzi z bazy: unikalny indeks czesciowy uq_notifications_course_certificate na (enrollment_id, template). Dotychczasowe indeksy opieraly sie na webinar_id, ktore przy kursie jest nullem, a NULL-e w PostgreSQL nie koliduja, wiec gwarancja by zniknela.
• Szablon course-completed dopisany do NOT_FOR_REMINDER_SENDER, ale NIE do TEMPLATES: ma wlasny wysylacz (CourseCertificateSender), a nie SummarySender. Pomylenie tych list konczy sie oznaczeniem wiadomosci jako FAILED, zanim wlasciwy wysylacz ja zobaczy.
• Zalacznik PDF idzie przez TEN SAM MimeMessageHelper, ktory zbudowal tresc. Drugi helper na tej samej wiadomosci tworzy pusty multipart/related i nadpisuje wypelniony, przez co wysylka konczy sie bledem "Empty multipart" dopiero przy zapisie do strumienia. Ta sama pulapka co przy zalaczniku ICS.
• Plik do zalacznika bierzemy ze SKLADU, nie renderujemy na nowo. Certyfikat jest dokumentem: zalacznik ma byc dokladnie tym samym plikiem, ktory kursant pobierze z pulpitu. Brak pliku nie blokuje wiadomosci, bo niesie ona takze odnosnik.
• Dostep do pliku sprawdza WLASCICIELA ZAPISU, nie udzial w kursie. belongsToContact porownuje kontakt zapisu z zalogowanym kursantem: inaczej kazdy kursant pobralby certyfikaty wszystkich kolegow z grupy i poznal ich dane. Sprawdzone na zywo: obcy kursant tego samego kursu dostaje 404.
• Kursant idzie sesja, uczestnik webinaru tokenem. Konto Akademii nie ma tokenu zapisu z maila, bo nie przechodzilo przez formularz webinaru. Przy okazji naprawiony istniejacy blad: link do certyfikatu webinaru na pulpicie kursanta byl budowany bez tokenu i pobranie konczylo sie 404 mimo zalogowania. Adres sklada teraz backend, bo tylko on zna token.
• Wydanie recznie bez ukonczenia kursu WYMAGA NOTATKI. Bez niej po miesiacu nie da sie ustalic, dlaczego dokument powstal i kto o tym zdecydowal. Warunek jest w serwisie, nie w walidacji pola, bo zalezy od drugiego pola (force).
• Weryfikacja publiczna obsluguje oba zrodla jedna odpowiedzia. subjectTitle niesie tytul webinaru albo kursu, a forCourse pozwala stronie dobrac etykiete. Zwraca nadal minimum: numer, tytul, date, imie z inicjalem i waznosc. Pilnuje tego CourseCertificateOwnerTest, sprawdzajac strukture rekordu, zeby dopisanie adresu e-mail zlamalo test od razu.
• Pulpit kursanta ma JEDNA sekcje na oba zrodla. Kursant nie mysli kategoriami "to bylo wydarzenie, a to kurs": ma jedno miejsce ze wszystkimi dokumentami, a zrodlo rozroznia odznaka.
• Pilnuje tego CourseCertificatePdfTest, ktory czyta tekst z gotowego pliku PDF i sprawdza, ze polskie znaki tam sa, ze dokument mowi o ukonczeniu, a nie o udziale, oraz ze kurs bez quizu nie pokazuje wyniku.

Certyfikaty uczestnictwa

Tabele certificates i certificate_counters (V16), plik PDF w MinIO, renderowanie przez OpenHTMLtoPDF.

• Certyfikat to dokument, nie widok danych. Plik powstaje raz i lezy w skladzie. Wydany dzis ma wygladac tak samo za rok, niezaleznie od tego, czy ktos zmienil tytul webinaru, szablon albo logo. Generowanie na nowo przy kazdym pobraniu sprawialoby, ze dokument w teczce uczestnika rozni sie od tego, ktory pobierze pracodawca.
• Czcionka musi byc osadzona w pliku. DejaVu Sans lezy w resources/fonts/, w repozytorium, zeby build byl powtarzalny. Bez osadzenia polskie znaki znikaja u odbiorcy, ktory jej nie ma, i "Wiśniewski" staje sie "Winiewski". Certyfikat z bledem w nazwisku jest bezuzyteczny.
• Nie deklarowac czcionki przez @font-face w CSS. Rodzina jest rejestrowana w kodzie przez PdfRendererBuilder.useFont. Deklaracja @font-face z adresem wzglednym przykrywa ta rejestracje: renderer probuje pobrac plik wzgledem baseUri (pustego, bo dokument nie siega po siec), nie znajduje go i podstawia czcionke zastepcza. Objawia sie to tym, ze kazdy ogonek w PDF zamienia sie w krzyzyk. Zdarzylo sie to realnie.
• Rozmiar strony podaje @page w szablonie, nie kod Javy: OpenHTMLtoPDF czyta go stamtad, a ustawienie w Javie nie ma wplywu na uklad.
• HTML przechodzi przez jsoup przed renderowaniem. Renderer wymaga poprawnego XML, a pojedynczy niezamkniety znacznik w tresci wlasnej organizatora wywracalby generowanie calego dokumentu.
• Numer nadawany pod blokada wiersza (certificate_counters, SELECT ... FOR UPDATE), w osobnej transakcji REQUIRES_NEW. Dokladnie ten sam wzorzec co limit miejsc: bez blokady dwa rownoczesne wydania dostalyby ten sam numer, a numer sluzy do weryfikacji publicznej.
• Licznik w osobnej tabeli, nie max(number). Numer zawiera separatory i format konfigurowalny przez administratora, wiec wyciaganie z niego liczby byloby zawodne po kazdej zmianie wzoru.
• Numer w parametrze, nie w sciezce. Domyslny wzor to {rok}/{numer}, czyli 2026/1; ukosnik rozbilby sciezke na dwa segmenty i weryfikacja zawsze dawalaby 404. Trasa frontu uzywa z tego samego powodu wildcardu /certyfikat/*.
• Dostep do pliku jest wezszy niz przy nagraniach. Nagranie jest wspolne dla webinaru, wiec tam wystarcza token dowolnego uczestnika. Certyfikat to dokument jednej osoby, z jej imieniem i nazwiskiem, wiec token musi wskazywac wlasnie ja (CertificateService.belongsToToken). Sama przynaleznosc do webinaru pozwalalaby kazdemu uczestnikowi pobrac certyfikaty wszystkich pozostalych i poznac ich dane. Wykryte przy sprawdzaniu na zywo.
• Weryfikacja publiczna zwraca minimum: numer, tytul, date, imie z pierwsza litera nazwiska i informacje o waznosci. Nigdy nie wolno dopisac tu adresu e-mail, pelnego nazwiska ani linku do pliku: endpoint jest otwarty dla calego internetu.
• Uniewaznienie ustawia revoked_at, nie kasuje wiersza ani pliku. Dokument mogl juz trafic do teczki uczestnika albo do pracodawcy, wiec weryfikacja ma pokazac "niewazny", a nie "nie znaleziono". Uniewazniony certyfikat znika za to ze strony uczestnika i z maila: link do dokumentu bez waznosci wprowadzalby w blad.
• Wydanie automatyczne dzieje sie PRZED kolejkowaniem podsumowania. Mail niesie link do pobrania, wiec dokument musi juz istniec, gdy wiadomosc powstaje. Blad wydawania nie moze zablokowac podsumowania.
• Automat wydaje wylacznie uczestnikom z attended. Certyfikat dla osoby bez odnotowanej obecnosci jest decyzja organizatora, a nie automatu; panel pyta o nia wprost przez force.
• Dwa silniki Thymeleaf wymagaja @Primary. Autokonfiguracja Springa wstrzykuje SpringTemplateEngine do thymeleafViewResolver i wymaga jednoznacznego kandydata: bez @Primary na mailTemplateEngine kontekst nie wstaje. autowireCandidate = false nie jest rozwiazaniem, bo wyklucza bean takze z wstrzykiwania przez @Qualifier.
• Uzywac SpringTemplateEngine, nie czystego TemplateEngine. Czysty silnik wylicza wyrazenia przez OGNL, ktorego Spring Boot nie dolacza: NoClassDefFoundError: ognl/PropertyAccessor przy pierwszym renderowaniu.
• Pilnuje tego CertificatePdfTest, ktory czyta tekst z gotowego pliku PDF i sprawdza, ze polskie znaki tam sa, takze w szablonie wlasnym organizatora.

Platnosci Autopay

Tabele orders i payment_notifications (V24). Endpoint ITN pod /api/webhooks/autopay/itn, panel w obszarze Akademia, pozycja Zamowienia.

• ITN wymaga publicznej domeny z waznym certyfikatem, wiec pelnego przeplywu nie da sie sprawdzic na localhost: operator sam laczy sie z naszym serwerem. Lokalnie sprawdzone jest wszystko, co dzieje sie po odebraniu komunikatu. Lista rzeczy do sprawdzenia po wdrozeniu jest w README.
• Adresy srodowisk sa zaszyte w kodzie, nie w ustawieniach. Pomylka oznaczalaby przyjmowanie prawdziwych pieniedzy na srodowisku testowym albo transakcje testowe na produkcji, ktore nigdy sie nie rozlicza. Wybor idzie przez AUTOPAY_MODE, ktore jest lista zamknieta.
• Skrot: wartosci pol rozdzielone |, na koncu klucz wspoldzielony. Puste i nieprzekazane pola opcjonalne sa pomijane RAZEM Z SEPARATOREM. To najczestsze zrodlo bledow w tej integracji: wstawienie samej kreski daje inny skrot, a bramka odrzuca zadanie bez podania przyczyny. Pilnuje tego AutopayHashTest na przykladzie wprost z dokumentacji.
• Powrot kursanta z bramki NICZEGO nie potwierdza. To zwykle przekierowanie przegladarki, ktore da sie wywolac recznie wpisujac adres. Dostep nadaje wylacznie komunikat ITN ze statusem SUCCESS, po weryfikacji podpisu, identyfikatora serwisu, kwoty i waluty.
• FAILURE NIE odbiera dostepu, gdy wczesniej byl SUCCESS. Ten sam OrderID moze miec kilka transakcji, kazda z wlasnym remoteID: nieudana proba karta, potem udany przelew. FAILURE dotyczacy innej proby nie jest cofnieciem platnosci, a odebranie dostepu zabraloby kurs osobie, ktora zaplacila. Dokumentacja opisuje ten przypadek wprost.
• Logika biznesowa wykonuje sie wylacznie przy PIERWSZYM SUCCESS. Operator ponawia notyfikacje az do potwierdzenia, wiec powtorki sa normalnym trybem pracy. Kolejne komunikaty potwierdzamy, ale nie powtarzamy akcji.
• PENDING i FAILURE potwierdzamy bez zmiany dostepu. Bez potwierdzenia bramka ponawialaby komunikat w nieskonczonosc.
• Kazdy komunikat trafia do dziennika, takze odrzucony. Wpis powstaje przed weryfikacja, wiec odrzucenie nie kasuje sladu. Przy sporze o platnosc to jedyny dowod na to, co bramka przyslala i kiedy.
• Wolanie bramki jest POZA transakcja zapisu zamowienia. Gdyby bylo w srodku, wyjatek z bramki wycofalby transakcje razem z zamowieniem, a numer przepadlby mimo ze zostal juz wyslany na zewnatrz: kursant dostalby blad, a w panelu nie byloby sladu, ze cos probowal kupic. Zdarzylo sie to realnie przy pierwszym uruchomieniu. Sluzy do tego @Lazy referencja na samego siebie, bo @Transactional na metodzie wolanej z tej samej klasy nie dziala.
• Awaria bramki zostawia zamowienie w NEW, gotowe do ponowienia na tym samym numerze. Nie ma sciezki zapasowej z formularzem: druga droga platnosci oznaczalaby drugi format podpisu do utrzymania.
• Parser ITN ma twardo wylaczone XXE. Endpoint jest otwarty, bo operator nie ma jak sie uwierzytelnic inaczej niz skrotem, wiec parser dostaje dokumenty od nieuwierzytelnionego nadawcy: bez tego spreparowany komunikat odczytalby pliki serwera albo wymusil zadania wychodzace.
• order_number jest unikalny NA ZAWSZE. Trafia do operatora jako OrderID; ponowne uzycie skierowaloby cudza notyfikacje do niewlasciwego kursanta.
• Zamowienie jest dokumentem finansowym. Kurs i kontakt wiaza sie przez ON DELETE SET NULL, a nie kaskade: zamowienie przezywa skasowanie kursu. Kwota jest przepisana w chwili zlozenia, wiec pozniejsza zmiana ceny jej nie rusza.
• Kwoty porownuje sie wartoscia, nie tekstem. "490.00" i "490.0" to ta sama kwota, a porownanie napisow odrzucaloby poprawna platnosc przez sam zapis.
• Kurs darmowy zapisuje od reki, platny dopiero po ITN. Zakladanie zamowienia na zero zlotych oznaczaloby przeprowadzanie kursanta przez bramke po nic, a zapis przed platnoscia dawalby dostep osobie, ktora nie zaplacila.
• Filtr IP jest opcjonalny i domyslnie wylaczony. Adresy operatora bywaja zmieniane, a wpisanie nieaktualnych zablokowaloby wszystkie platnosci. Glowna bariera jest podpis. Komunikat z niedozwolonego adresu i tak trafia do dziennika.
• Reczne nadanie dostepu wymaga notatki. Bez niej po miesiacu nie da sie ustalic, czy pieniadze wplynely i kto to sprawdzil.

Quiz konczacy kurs

Tabele quizzes, quiz_questions, quiz_answers, quiz_attempts, quiz_attempt_answers (V23). Endpointy /api/admin/courses/{id}/lessons/{id}/quiz/** oraz /api/academy/lessons/{id}/quiz/**.

• Quiz nalezy do lekcji typu QUIZ, nie do kursu. Ma wtedy swoje miejsce w programie: widac, w ktorym momencie wypada, i przesuwa sie razem z reszta. Jedna lekcja to jeden quiz, czego pilnuje unikalny indeks.
• POPRAWNE ODPOWIEDZI NIE OPUSZCZAJA SERWERA PRZED KONCEM PODEJSCIA. Widok kursanta (StudentAnswerView, StudentQuestionView) nie ma pola correct ani wyjasnienia w typie: to nie jest ukrywanie warunkowe, tylko osobny rekord. Gdyby oba widoki byly jednym typem z polem ustawianym warunkowo, wystarczyloby raz przeoczyc warunek, zeby klucz wyszedl w zwyklym JSON-ie. Pilnuje tego QuizSecurityTest, sprawdzajac strukture typu i zserializowany JSON. Test zostal zweryfikowany celowym przeciekiem.
• Zestaw pytan losowany raz, przy starcie, i zapisany w quiz_attempts.question_ids. Odswiezenie strony nie zmienia testu, a ponowny start zwraca to samo podejscie zamiast bledu: kursant wracajacy z telefonu ma zobaczyc ten sam zestaw i pozostaly czas.
• Zapisany zestaw jest jedynym zrodlem prawdy przy ocenianiu. Odpowiedz na pytanie spoza niego jest odrzucana, wiec podstawienie cudzego identyfikatora niczego nie daje. Odpowiedz nalezaca do innego pytania takze: inaczej dalo by sie wskazac poprawna odpowiedz z sasiedniego pytania.
• Limit czasu liczy sie od started_at, po stronie serwera. Przegladarka moze klamac o uplywie czasu, wiec jej zegar sluzy wylacznie do pokazania. Podejscie po czasie zostaje zamkniete z wynikiem z odpowiedzi zapisanych do tej pory, niezaleznie od tego, co przyszle klient.
• Odpowiedzi zapisywane na biezaco, a nie dopiero przy zakonczeniu: kursant, ktoremu padnie przegladarka, nie traci calego testu, a limit czasu ma z czego policzyc wynik.
• Pytanie pominiete liczy sie jako bledne, bo mianownikiem jest liczba pytan w zestawie, a nie liczba udzielonych odpowiedzi. Inaczej kursant odpowiadajacy na jedno pytanie z dziesieciu mialby sto procent. answer_id rowne null odroznia jednak pominiecie od braku wiersza, wiec widac, ktore pytania minal.
• quiz_attempt_answers.correct wyliczane przy zapisie odpowiedzi, a nie przy ocenianiu: zmiana klucza po fakcie nie zmienia juz wystawionej oceny.
• Jedno podejscie w toku na pare quiz-zapis, wymuszone unikalnym indeksem czesciowym. Bez tego dwie karty przegladarki zalozylyby dwa podejscia z roznymi zestawami pytan.
• Podejscia porzucone zamyka zadanie @Scheduled. Kursant, ktory zamknal karte, nie przysle juz zadnego zadania, a jego podejscie blokowaloby kolejne.
• Odstep miedzy podejsciami liczy sie od ZAKONCZENIA poprzedniego, nie od jego startu: inaczej dlugi test sam wyczerpywalby odstep.
• Regula "dokladnie jedna odpowiedz poprawna i minimum dwie odpowiedzi" nie jest CHECKiem w bazie. Warunek dotyczy zbioru wierszy, a PostgreSQL widzi przy sprawdzaniu jeden wiersz; wyzwalacz oznaczalby druga implementacje tej samej reguly, rozjezdzajaca sie z ta w serwisie. Regula siedzi w QuizService przy zapisie i jest sprawdzana ponownie przy publikacji kursu: pytanie moglo stac sie niepoprawne przez skasowanie odpowiedzi obok.
• pass_threshold_percent rowne null oznacza dziedziczenie progu z kursu, a nie prog zerowy. Prog zerowy jest ustalona wartoscia: quiz zaliczany przy kazdym wyniku to swiadoma decyzja. Rozstrzyga Quiz.effectiveThreshold.
• question_count rowne null oznacza wszystkie aktywne pytania, wiec dopisanie pytania od razu powieksza test. Liczba wieksza niz pula jest odrzucana przy zapisie: test krotszy niz zapowiedziany nie dalby zadnego sygnalu.
• Pytanie wylaczone (active = false) zostaje w bazie, ale nie trafia do losowania. Kasowanie pytania uzytego w zakonczonych podejsciach zabieraloby im tresc.
• show_correct_answers warto wylaczyc przy quizie powtarzanym: inaczej pierwsze podejscie sluzy do zebrania klucza, a drugie do jego przepisania.
• Import CSV pomija bledny wiersz, a nie przerywa calosci. Plik z setka pytan i jedna literowka ma wniesc dziewiecdziesiat dziewiec pytan. Format: tresc;odpowiedz;*poprawna;#wyjasnienie, separatorem srednik.
• Warunek zaliczenia kursu: wszystkie lekcje wymagane ukonczone oraz kazdy quiz w lekcji wymaganej zdany. Quiz w lekcji nieobowiazkowej nie blokuje zaliczenia. Wtedy enrollments.status przechodzi na COMPLETED i ustawia sie completed_at. Zdanie quizu oznacza jego lekcje jako ukonczona.
• Statystyki licza sie z podejsc zakonczonych: trwajace nie maja wyniku, a wliczanie ich zanizaloby srednia. Pytania sortowane od najczesciej mylonych, bo to one wymagaja poprawy tresci albo kursu.
• Podglad w panelu pokazuje pytania bez klucza, dokladnie tak jak zobaczy je kursant: pytanie oczywiste dla autora bywa niejasne dla odbiorcy.

Zarzadzanie kursami w panelu

Endpointy /api/admin/courses/**, ekrany pod /kursy w obszarze Akademia. Bez czesci publicznej, bez zapisow kursantow i bez quizu: te dochodza osobno.

• Publikacja wymaga co najmniej jednej lekcji. Kurs bez lekcji wygladalby publicznie jak pusta strona. Ta sama zasada co przy webinarze, ktorego nie da sie opublikowac bez terminu.
• Archiwizacja zamiast kasowania. Kurs znika z oferty, ale zapisani zachowuja dostep: kurs, za ktory ktos zaplacil, nie moze zniknac dlatego, ze przestal byc oferowany.
• Kolejnosc zmienia sie przez przekazanie CALEJ listy identyfikatorow (PUT .../modules/order, PUT .../modules/{id}/lessons/order), a nie przez pojedyncze przesuwanie. Przy przeciaganiu i tak znamy docelowy uklad, a zapis "przesun o jeden" wymagalby tylu zadan, ile pozycji przeskoczyl element. Zapis idzie w jednej transakcji: polowicznie zapisana kolejnosc dawalaby dwa moduly na tej samej pozycji.
• Lista do zmiany kolejnosci musi zawierac dokladnie te same identyfikatory. Lista krotsza cicho zostawilaby czesc pozycji ze stara kolejnoscia, a obca pozycja wywrocilaby zapis wyjatkiem o pustej referencji.
• Modul i lekcja musza nalezec do kursu z adresu. Sama znajomosc identyfikatora nie moze pozwalac na zmiany w cudzym programie, wiec requireModule i requireLesson sprawdzaja przynaleznosc, a nie tylko byt.
• Przeniesienie lekcji miedzy modulami idzie przez zmiane moduleId w edycji, nie przez upuszczenie. Zmiana modulu i kolejnosci naraz mylilaby sie z samym przestawieniem, a lekcja ladowalaby w nieoczekiwanym miejscu.
• Adres wideo wylacznie http i https, sprawdzane w serwisie. javascript: wykonalby sie w kontekscie naszej strony, a data: pozwolilby podstawic dowolny dokument pod nasza domena. Ta sama regula co przy target_url banera.
• Postep procentowy liczy sie WYLACZNIE z lekcji wymaganych. Materialy dodatkowe nie wchodza ani do licznika, ani do mianownika: gdyby wchodzily, dolozenie jednego bonusu obnizaloby postep wszystkim, ktorzy juz skonczyli kurs. Kurs bez lekcji wymaganych daje 0%, a nie dzielenie przez zero. Zaokraglenie idzie w dol, zeby 99,7% nie pokazywalo sie jako ukonczone. Pilnuje tego CourseProgressTest.
• Kopiowanie kursu przepisuje program, nie postep. Przechodza moduly, lekcje, opis, okladka, cennik i ustawienia certyfikatu. Nie przechodza zapisy ani postep: oznaczalyby kursantow zapisanych na kurs, ktorego nie zaczeli. Kopia jest zawsze DRAFT z zamknietymi zapisami.
• Pliki lekcji sa wspoldzielone z kopia, nie kopiowane. Inaczej niz przy materialach webinaru: tam plik bywa podmieniany per wydarzenie, a tu lekcja wskazuje nagranie z biblioteki, ktora jest wspolna z zalozenia. Kopiowanie gigabajtowego nagrania przy kazdej kopii kursu byloby kosztem bez pokrycia.
• Kolumny "Zapisani" i "Lekcje" nie sa sortowalne. Obie liczby powstaja osobnym zapytaniem zbiorczym do juz pobranej strony, wiec baza nie potrafi po nich sortowac. Ta sama regula co przy kolumnie "Zapisani" na liscie webinarow.
• Eksport CSV nie jest stronicowany i escapuje wartosci zaczynajace sie od =, +, -, @, tak samo jak eksport zapisow na webinar.
• Przeciaganie korzysta z natywnego HTML5 drag and drop, bez biblioteki. Swiadoma decyzja: dziala w kazdej przegladarce, nic nie dochodzi do package.json i kod przenosi sie miedzy platformami bez zaleznosci.
• Przyciski gora i dol nie sa dodatkiem. Natywne przeciaganie jest nieosiagalne z klawiatury, a na ekranie dotykowym niewygodne. Bez tych przyciskow osoba nieuzywajaca myszy nie zmienilaby kolejnosci w ogole. Kazdy ma etykiete aria-label mowiaca, co przesuwa, bo sama strzalka nic czytnikowi ekranu nie mowi.
• Pola lekcji zaleza od jej rodzaju, a wartosci pol nieuzywanych nie sa czyszczone przy przelaczaniu: ktos, kto pomylil sie w wyborze i wraca, nie traci wpisanej tresci. Do bazy i tak idzie tylko to, co pasuje do rodzaju.
• Lekcja QUIZ jest na razie pozycja bez zawartosci, z informacja wprost w oknie edycji. Pytania, odpowiedzi i wyniki dostana wlasny model.

Kursanci i postepy w panelu

Ekrany /kursy/kursanci, /kursy/kursanci/:id i /kursy/postepy, endpointy pod /api/admin/academy/**, statystyki kursu jako zakladka na jego karcie.

• BEZ PODGLADU HASLA I BEZ LOGOWANIA SIE JAKO KURSANT. Haslo jest skrotem BCrypt i nie da sie go odczytac, a wejscie na cudze konto sprawiloby, ze slad w dzienniku nie odroznia dzialania kursanta od dzialania administratora: przy sporze o dostep do platnego kursu to jedyny dowod. Wsparcie dostaje zamiast tego reset hasla i ponowny link potwierdzajacy, czyli tyle, ile potrzeba, zeby kogos odblokowac bez przejmowania jego tozsamosci.
• Kursant to kontakt z haslem (password_hash IS NOT NULL), zgodnie z modelem kont. Lista nie pokazuje wpisow marketingowych, mimo ze leza w tej samej tabeli.
• Osobne repozytorium StudentAdminRepository, a nie dopisanie do ContactRepository: tamto obsluguje baze marketingowa, a te zapytania dotycza waskiego podzbioru z innymi filtrami i licznikami.
• CAST(:x AS text) przy KAZDYM parametrze opcjonalnym, takze CAST(:x AS boolean) i CAST(:x AS bigint). Bez tego lista przestaje dzialac dokladnie wtedy, gdy filtr nie jest uzywany. Sprawdzone na zywo: lista bez filtru, kazdy filtr osobno i wartosc spoza bialej listy sortowania.
• Liczniki kursow i certyfikatow NIE sa sortowalne. Powstaja osobnym zapytaniem zbiorczym do juz pobranej strony, wiec baza nie ma po czym sortowac. Ta sama regula co przy kolumnie "Zapisani" na liscie webinarow. Sortowanie idzie po nazwisku, adresie, dacie rejestracji i ostatnim logowaniu, z bialej listy w kontrolerze.
• Znacznik czasu z zapytania natywnego wymaga konwersji. Sterownik oddaje timestamptz jako Instant, a nie OffsetDateTime; rzutowanie wprost daje ClassCastException dopiero na dzialajacej instancji, bo kompilator widzi tam Object. Objaw jest mylacy: blad 500 front tlumaczy jako wygasla sesje i pokazuje "Wymagane uwierzytelnienie". Sluzy do tego asMoment. Zdarzylo sie to realnie przy pierwszym uruchomieniu tego ekranu.
• Ostatnia aktywnosc to GREATEST ze zmiany postepu lekcji i startu podejscia do quizu. Kursant rozwiazujacy test jest aktywny, choc zadnej lekcji wtedy nie domyka; liczenie samego lesson_progress.updated_at pokazywaloby go jako porzuconego.
• Prog bezczynnosci jest ustawieniem (ACADEMY_INACTIVITY_DAYS, domyslnie 14), a nie liczba w kodzie: przy kursie tygodniowym tydzien ciszy znaczy co innego niz przy rocznym. Front pobiera prog z backendu i nie powtarza go u siebie.
• Kurs UKONCZONY nie jest "nieaktywny". Kursant nie ma juz nic do zrobienia, wiec brak ruchu jest tam stanem naturalnym, a nie sygnalem do reakcji.
• Reczne zapisanie na kurs WYMAGA NOTATKI. Zapis omija platnosc i akceptacje regulaminu, wiec po miesiacu musi dac sie wyjasnic, czy kursant zaplacil przelewem, czy dostal dostep przez pomylke. Warunek jest w serwisie, nie w walidacji pola.
• Zgody pokazujemy z CALA historia i wersjami. Sa dopisywane, nigdy nadpisywane, wiec kursant ma ich kilka na ten sam typ; obowiazujaca jest oznaczona, bo bez tego nie da sie odczytac stanu biezacego z samej listy.
• Wszystkie statystyki licza sie w bazie, zapytaniami agregujacymi (FILTER, LATERAL, CTE), tak samo jak przy statystykach webinaru.
• Zdawalnosc quizu rowna null oznacza kurs bez sprawdzianu, a nie zero: zero sugerowaloby, ze nikt nie zdal. Ta sama zasada co przy cenie null oznaczajacej kurs darmowy.
• "Przestali na lekcji" to co innego niz "nie ukonczyli jej". Liczymy kursantow, ktorzy doszli do lekcji i nie ukonczyli ANI JEJ, ANI ZADNEJ POZNIEJSZEJ: lekcja, ktora ktos minal i wrocil do niej pozniej, nie jest miejscem porzucenia. Bez tej roznicy liczba nic nie znaczy.
• Wykresy ladowane leniwie (@mui/x-charts), tak samo jak przy statystykach webinaru: sekcja importuje wykresy statycznie, a strona nadrzedna laduje sekcje przez lazy. Kolory podane wprost, bo biblioteka nie czyta klas Tailwinda.
• Zdjecie flagi planned to zmiana w DWOCH miejscach: wpis w navigation.ts i trasa w App.tsx. Przy Postepach flaga zostala za pierwszym podejsciem, bo wpis byl sformatowany wieloliniowo i nie zlapala go podmiana jednolinijkowa. Ekran dzialal, a pozycja menu byla wyszarzona; wylapal to dopiero test w przegladarce.

Model kursow Akademii

Tabele courses, course_modules, lessons, enrollments, lesson_progress (V22). Encje, repozytoria i enumy. Kontrolery i widoki dochodza osobno.

• Hierarchia: kurs -> modul -> lekcja. Modul jest warstwa posrednia, a nie ozdoba: kurs bez podzialu to lista kilkudziesieciu lekcji, w ktorej nie widac struktury, a przeniesienie calego bloku wymaga przenumerowania wszystkiego.
• Jedna tabela na wszystkie rodzaje lekcji. Nagranie, tekst, plik, webinar i sprawdzian maja ten sam cykl zycia, te sama kolejnosc i ten sam postep. Osobne tabele oznaczalyby piec razy powtorzony ten sam zestaw kolumn i piec zapytan przy skladaniu jednego programu.
• webinar_id wylacznie przy lekcji typu WEBINAR, co wymusza ograniczenie CHECK. Bez niego literowka w kodzie przypielaby wydarzenie do lekcji tekstowej. To realizuje ustalenie, ze webinar moze byc lekcja kursu.
• Skasowanie webinaru odpina lekcje, nie kasuje jej (ON DELETE SET NULL). Wydarzenie moze zniknac, ale program kursu ma zostac caly: lekcja wyrwana ze srodka zmienialaby numeracje i psula postep kursantow.
• Brak ceny (price_gross IS NULL) oznacza kurs darmowy, a nie cene zerowa. To dwie rozne decyzje: kurs celowo bezplatny i kurs, ktoremu ceny jeszcze nie ustalono. Sluzy do tego Course.isFree().
• Dwa zrodla wideo w lekcji, w osobnych polach. media_id to plik we wlasnym skladzie, external_video_url to adres zewnetrzny. Przy jednym polu nie dalo by sie odroznic identyfikatora pliku od adresu.
• enrollment_open to intencja administratora, nigdy zapisywana automatycznie. Dokladnie ta sama regula co przy webinarze.
• Postep wisi na zapisie, nie na kontakcie. Po wypisaniu i ponownym zapisie widac, ze to nowe podejscie, a nie dalszy ciag poprzedniego.
• Jeden zapis na pare kurs-kontakt i jeden wiersz postepu na pare zapis-lekcja, wymuszone unikalnymi indeksami. Sprawdzenie w kodzie nie wystarcza: dwie karty przegladarki przechodza je jednoczesnie, a odtwarzacz wysylajacy sygnal co kilkanascie sekund zakladalby nowy wiersz przy kazdym. DataIntegrityViolationException jest tu spodziewany.
• Do progu zaliczenia licza sie wylacznie lekcje wymagane (required). Material dodatkowy nie moze decydowac o certyfikacie.
• Dostep sprawdza Enrollment.grantsAccess(), nie sam status. Status EXPIRED ustawia zadanie w tle, wiec miedzy jego przebiegami wiersz jest jeszcze ACTIVE mimo minionej daty. Ukonczenie kursu nie odbiera dostepu do materialow.
• access_expires_at rowne null to dostep bezterminowy. Brak daty i data w przyszlosci to dwie rozne rzeczy.
• Kategoria jest tekstem, nie tabela slownikowa. Nie wiadomo jeszcze, czy kategorie beda mialy wlasne strony i kolejnosc; tabela na zapas kosztuje join przy kazdym listowaniu, a jej dodanie pozniej jest prosta migracja.
• QUIZ jest w ograniczeniu CHECK od poczatku, mimo ze obslugi nie ma: dodanie jej nie bedzie wymagalo migracji zmieniajacej typ kolumny. Pytania, odpowiedzi i wyniki dostana wlasne tabele. Platnosci tak samo: tutaj sa wylacznie pola cennika (price_gross, currency), a nie fakt zaplaty. Nie zakladamy z gory ani modelu pytan, ani modelu rozliczenia.
• Pilnuje tego CourseModelTest, ktory sprawdza takze liste bez filtru, zgodnie z regula, ze nowy test listy zaczyna sie od tego przypadku.

Podzial menu panelu na obszary

Menu ma przelacznik obszaru (Webinary, Akademia), pod nim pozycje wybranego obszaru, a na dole osobna grupe pozycji wspolnych dla instancji.

• Cala nawigacja jest deklaracja w lib/navigation.ts. Obszar, trasa, ikona i wymagana rola sa danymi, a komponent menu tylko je renderuje. Dodanie pozycji to zmiana jednej linii, a nie dopisanie warunku w JSX. Dzieki temu regula "kto to widzi" siedzi w jednym miejscu i da sie ja sprawdzic wzrokiem, zamiast szukac po isAdmin && rozsypanych po kodzie.
• Rola jako lista (roles), nie flaga adminOnly. Rol moze przybyc, a wtedy flaga wymagalaby przepisania kazdego uzycia.
• Pozycja planned jest wyszarzona i nie jest linkiem. Widok jeszcze nie istnieje, wiec klikniecie prowadziloby do pustego ekranu. Zdjecie flagi po dodaniu widoku jest zmiana jednego slowa.
• Wybor obszaru przezywa zamkniecie przegladarki (localStorage), takze gdy zostal wymuszony trasa: inaczej powrot po restarcie pokazywalby inny obszar niz ostatnio.
• Wejscie na trase drugiego obszaru przelacza obszar, zeby menu zgadzalo sie z zawartoscia. Sciezki wspolne (Ustawienia, Kontakty) nie naleza do zadnego obszaru i zostawiaja wybor bez zmian: inaczej wejscie w Ustawienia przerzucaloby uzytkownika na obszar domyslny.
• Zaleznoscia efektu przelaczajacego obszar jest wylacznie sciezka, nigdy area. Ze stanem na liscie zaleznosci efekt wykonuje sie ponownie zaraz po recznym przelaczeniu i cofa je do obszaru wynikajacego z trasy. Objaw jest mylacy: przycisk wyglada na niedzialajacy, chociaz stan zmienia sie poprawnie i natychmiast wraca. Zdarzylo sie to realnie.
• Trasy kursow w panelu ida pod /kursy, nie /akademia. Ten drugi prefiks nalezy juz do publicznej czesci kursanta (logowanie, rejestracja, potwierdzenie adresu), wiec panel wszedlby mu w droge.

Strona glowna: pusta sekcja i tresc startowa

Sekcje strony glownej (prowadzacy, opinie, FAQ, webinary, cennik) sa ukrywane, gdy nie maja tresci. Dla goscia to poprawne, dla administratora nie.

• Gosc nie widzi pustej sekcji. Naglowek "Opinie kursantow" nad niczym wyglada gorzej niz brak sekcji.
• ADMIN i MODERATOR widza w jej miejscu placeholder (AdminSectionHint) z informacja, czego brakuje, i odnosnikiem do panelu. Bez tego administrator nie ma jak zauwazyc, ze cos jest do uzupelnienia: strona nie rozni sie od kompletnej, a swieza instancja wyglada na zepsuta. Placeholder nie jest renderowany dla goscia wcale, a nie ukrywany stylem: nie ma go takze w zrodle strony.
• Pusta lista kursow i webinarow zostaje widoczna dla goscia z komunikatem "pojawia sie wkrotce", a administrator dostaje pod nim odnosnik do utworzenia pierwszej pozycji (AdminEmptyHint).
• Brak kursow platnych ukrywa cennik takze administratorowi. To nie jest tresc do uzupelnienia, tylko skutek tego, ze instancja oferuje wylacznie szkolenia bezplatne: placeholder sugerowalby, ze czegos brakuje.

Tresc startowa zaklada PageSectionBootstrap, tym samym wzorcem co pierwsze konto administratora.

• Zakladamy WYLACZNIE pytania FAQ, i to o dzialanie platformy, a nie o branze klienta: jak dziala zapis, czym jest certyfikat, czy kurs ma termin. Te odpowiedzi sa prawdziwe na kazdej instancji.
• NIE zakladamy opinii ani prowadzacych. Wymyslona opinia jest nieprawda o nieistniejacej osobie i predzej czy pozniej trafi na produkcje, bo nikt jej nie usunie: wyglada jak tresc, a nie jak zaslepka.
• Kazdy wpis ma flage is_sample (V27) i znacznik "przyklad" widoczny wylacznie dla rol panelu. Edycja wpisu zdejmuje flage: od tej chwili tresc jest decyzja czlowieka.
• Warunkiem ponownego zalozenia jest ustawienie HOME_SECTIONS_SEEDED, a nie pustka w tabeli. Pierwsza wersja sprawdzala samo count() > 0 i przykladowe pytania wracaly przy kazdym restarcie po tym, jak administrator je skasowal: jedynym sposobem, zeby sie ich pozbyc, byloby zostawienie jednego wpisu. Znacznik siedzi w ustawieniach wlasnie po to, zeby przezyl skasowanie tabeli tresci. Wylapal to test na uruchomionej instancji, bo z czytania kodu warunek wyglada poprawnie.

Uklad strony glownej wedlug makiety

Makiety: docs/Akademia Wodociagowca - Wariant 1a.html i 1b.html. Sa to pakiety samorozpakowujace sie: tresc siedzi w JSON-owym stringu w ostatnich liniach pliku, wiec do porownania trzeba ja najpierw wydobyc, a nie ogladac grep-em po znacznikach.

• Sekcje maja naprzemienne tla (Band): biale, szare, ciemne granatowe przy prowadzacych, szare przy cenniku. Bez tego strona byla plaska i nie bylo widac granic sekcji. Tlo idzie na pelna szerokosc okna, tresc zostaje w kontenerze: dlatego AcademyLayout ma tryb bleed, ktory oddaje children bez wlasnego opakowania. W kontenerze pas koloru urywalby sie na 1200 px i wygladal jak przypadkowy prostokat.
• Hero jest dwukolumnowe (1.1fr / 1fr): tresc po lewej, panel wizualny po prawej. Panel jest ozdoba, wiec ponizej lg znika calkiem, a nie zjezdza pod tresc: na telefonie zabieralby ekran, nic nie wnoszac.
• Cztery liczniki: godziny materialu, kursanci, ukonczone szkolenia, kursy. Godziny licza sie z duration_minutes lekcji z kursow opublikowanych, z pominieciem lekcji bez podanej dlugosci: null znaczy tam "nie wiem", a nie "zero minut".
• Zdawalnosci z makiety NIE MA. Policzona z kilku podejsc jest przypadkowa, a przy zerze zdanych zniechecalaby. Wroci, gdy bedzie co usredniac.
• Opinie i FAQ stoja obok siebie w dwoch kolumnach, tak jak w makiecie.
• Prowadzacy sa na ciemnym tle (gradient-depth), kafelki z inicjalami albo zdjeciem, tekst wprowadzajacy po lewej.

Karta webinaru na stronie glownej nie zapisuje

Makieta pokazuje w karcie webinaru pole adresu i przycisk "Zapisz sie". Tak sie nie da, i to nie jest kwestia wygody:

• registrations.first_name i last_name maja NOT NULL, a endpoint oznacza je @NotBlank: zapis z samym adresem zostanie odrzucony,
• zgoda na regulamin musi byc zapisana z wersja tresci, wiec trzeba pokazac te tresc, a nie tylko checkbox.

Rozwazone byly dwa wyjscia. Checkbox przy polu odpada, bo i tak brakuje imienia i nazwiska: karta urosla by do czteropolowego formularza wyzszego niz sama karta, a regula zapisu (limit miejsc pod blokada wiersza, wersjonowanie zgod, stany zamkniete) zostalaby zaimplementowana drugi raz obok tej na stronie webinaru.

Wybrano przeniesienie adresu: karta niesie go parametrem ?email= na strone webinaru, gdzie formularz startuje z wypelnionym polem. Przycisk mowi "Przejdz do zapisu", a nie "Zapisz sie": przycisk, ktory nie robi tego, co obiecuje, jest gorszy niz jedno klikniecie wiecej. Pod polem jest zdanie uprzedzajace, czego zabraknie na nastepnym ekranie.

Stopka i znak instancji

• Stopka jest widoczna zawsze, takze przy pustej konfiguracji. Poprzednia wersja renderowala sie poprawnie, ale bez ustawien kurczyla sie do paska 45 px z jednym zdaniem: technicznie byla, wizualnie jej nie bylo. Uklad wedlug wariantu 1a (ciemne tlo, trzy kolumny, pasek praw autorskich), bo miesci odnosniki serwisowe i dane spolki; wariant 1b ma stopke jednolinijkowa, ktora wypycha te dane do tresci strony.
• Pusty adres regulaminu ukrywa sam odnosnik, nie cala stopke.
• Brak logo pokazuje sama nazwe marki, bez grafiki zastepczej. Wczesniej przy pustym APP_LOGO_URL pojawiala sie kropla w kolorze marki: wygladala jak logo klienta, choc nim nie byla, wiec instancja bez wgranego logo prezentowala sie cudzym znakiem.

Liczniki na stronie glownej licza to, co gosc widzi

Licznik na stronie publicznej jest obietnica: gosc, ktory widzi "12 webinarow", spodziewa sie ich na liscie.

• Webinary: opublikowane Z TERMINEM W PRZYSZLOSCI (countUpcoming). Wczesniej liczylo wszystkie PUBLISHED, wiec instancja z jednym zakonczonym webinarem pokazywala w naglowku "1 webinar", a zaraz pod spodem pusta sekcje nadchodzacych: ta sama strona przeczyla sama sobie. Warunek musi byc ten sam co w findUpcoming.
• Kursanci: konta z POTWIERDZONYM adresem. Konto bez potwierdzenia nie ma dostepu do materialow, wiec nie jest kursantem, tylko proba rejestracji. Bez tego warunku liczbe widoczna dla kazdego goscia dalo sie zawyzyc z zewnatrz rejestracjami na zmyslone adresy.
• Kursy i lekcje: wylacznie z kursow opublikowanych.
• Zero sie nie pokazuje. Licznik "0 kursow" na stronie zachecajacej do nauki chwali sie pustka. Filtrowanie jest przed renderowaniem, nie w samym komponencie: siatka grid-cols-4 zostawialaby po ukrytym liczniku pusta kolumne. Gdy znikna wszystkie, znika tez kreska nad nimi.

Publiczna czesc Akademii

Trasy /akademia (strona glowna, kursy, webinary, cennik), /kurs/:slug, /kurs/:slug/nauka, /kurs/:slug/zakup i /kurs/:slug/platnosc. Endpointy publiczne pod /api/public/academy/**, kursanta pod /api/academy/**.

• Tresc sekcji statycznych trzyma tabela page_sections (V25), nie app_settings. Prowadzacy, opinia i pytanie FAQ to POWTARZALNE REKORDY o kilku polach, a app_settings trzyma jedna wartosc pod jednym kluczem. Upchniecie ich tam wymagaloby albo wlasnego formatu ("imie|rola|opis;..."), co lamie zasade "zaden format techniczny nie moze byc tym, co uzytkownik wpisuje recznie", albo JSON-a w polu tekstowym, co odbiera walidacje. Doszlaby jeszcze sztywna liczba pozycji: czterej prowadzacy to albo cztery klucze na pole (EXPERT_1_NAME ... EXPERT_4_BIO), albo lista w jednej wartosci, a dodanie piatego wymagaloby wdrozenia.
• Wartosci naprawde pojedyncze zostaja w app_settings (ACADEMY_HERO_TITLE, ACADEMY_FOOTER_TEXT, ACADEMY_TERMS_URL): jeden napis pod jednym kluczem, nie ma czego numerowac. Panel edytuje jedno i drugie w zakladce Ustawienia -> Strona glowna.
• WIDOK PUBLICZNY LEKCJI NIE MA POLA Z TRESCIA. PublicLessonView nie zawiera contentHtml ani mediaId w typie, tak samo jak widok kursanta w quizie nie ma pola correct. Uzycie tu CourseDtos.LessonView z panelu oznaczaloby, ze cala tresc platnego kursu jest w zwyklym JSON-ie, zanim ktokolwiek za niego zaplaci. Pilnuje tego PublicAcademySecurityTest, sprawdzajac strukture typu i zserializowany JSON; test zostal zweryfikowany celowym przeciekiem.
• Flaga preview jest sprawdzana przy pobieraniu tresci, nie tylko przy skladaniu programu. Identyfikator lekcji jest w adresie, wiec bez tego znajomosc samego numeru otwieralaby dowolna lekcje. Sprawdzamy takze przynaleznosc lekcji do kursu ze sciezki: inaczej dalo by sie obejrzec zapowiedz cudzego kursu przez podstawiony slug.
• Stan przycisku akcji rozstrzyga backend (CourseAction), nie przegladarka. Skladanie go we froncie z ceny, zapisu i zamowienia byloby druga implementacja reguly zapisu, rozjezdzajaca sie z ta po stronie serwera. Zapis z aktywnym dostepem wygrywa ze wszystkim: kursant, ktory kupil kurs, wchodzi do niego takze po zamknieciu zapisow i po archiwizacji.
• Kurs ARCHIVED jest widoczny, ale bez mozliwosci zapisu. Adres mogl trafic do materialow albo do wyszukiwarki, wiec 404 po zdjeciu z oferty wygladaloby na awarie. DRAFT daje 404, tak samo jak przy webinarach.
• PROG UKONCZENIA WIDEO SPRAWDZA SERWER. Przegladarka przysyla liczbe obejrzanych sekund, a nie decyzje "ukonczone": inaczej jedno podstawione zadanie zaliczaloby caly kurs, a przy kursie z certyfikatem oznaczaloby to dokument wystawiony za nic. Prog jest ustawieniem (ACADEMY_VIDEO_COMPLETE_PERCENT, domyslnie 90), liczonym z dlugosci lekcji zapisanej w bazie. Lekcja bez podanej dlugosci nie domyka sie sama: nie ma do czego porownac, a zgadywanie oznaczaloby zaliczanie po kilku sekundach albo nigdy. Pilnuje tego LessonProgressRulesTest, wolajac prawdziwa metode serwisu, a nie kopie wzoru.
• Lekcja ze sprawdzianem nie da sie oznaczyc przyciskiem. Zalicza sie wylacznie zdaniem quizu, inaczej dalo by sie ominac warunek zaliczenia kursu.
• Postep liczy sie WYLACZNIE z lekcji wymaganych, ta sama metoda (CourseEnrollmentService.percent) co lista w panelu. Metoda jest public wlasnie po to: dwie kopie rozjechalyby sie przy pierwszej poprawce.
• Warunek zaliczenia kursu siedzi w CourseCompletionService, w jednym miejscu. Kurs domyka sie z dwoch stron: po zdaniu quizu i po oznaczeniu ostatniej lekcji w odtwarzaczu. Wczesniej regula byla prywatna metoda QuizAttemptService; zostawienie jej tam oznaczaloby druga kopie w serwisie postepu i dwa rozne warunki zaliczenia tego samego kursu.
• Kurs bez lekcji wymaganych nie zalicza sie sam. Inaczej zapis na kurs zlozony z samych materialow dodatkowych bylby ukonczony w chwili zapisania.
• Obsluga naglowka Range jest wspolna (RangeResponder). Nagrania webinarow i wideo lekcji musza przewijac sie tak samo, a druga kopia stu linii parsowania zakresow rozjechalaby sie przy pierwszej poprawce.
• Plik lekcji ma wlasna kontrole dostepu, osobna od FileAccessGuard. Tamten zna wylacznie zapisy na webinary i widocznosc nagrania; tutaj warunkiem jest zapis na kurs zawierajacy te lekcje i aktywny dostep. Doklejanie tego do guarda oznaczaloby jedna metode odpowiadajaca na dwa rozne pytania.
• Token kursanta idzie do pliku TAKZE parametrem ?token=. Element video pobiera plik wlasnym zadaniem, do ktorego przegladarka nie pozwala dolozyc naglowka Authorization. Ta sama droga co przy nagraniach webinaru. Naglowek ma pierwszenstwo, gdy zadanie przeszlo przez filtr kursanta.
• Odmowa dostepu do pliku i lekcji daje 404, nie 403, tak samo jak przy nagraniach: przy 403 dalo by sie sprawdzic, ktore kursy i pliki istnieja.
• Biezaca lekcja jest w adresie (?lekcja=), a nie w stanie komponentu: dzieki temu da sie ja odswiezyc, wrocic do niej przyciskiem wstecz i podeslac linkiem na inne urzadzenie.
• Klucz zapytania o kurs zawiera identyfikator kursanta. Bez tego po zalogowaniu strona pokazywalaby przycisk z pamieci podrecznej goscia, czyli "Zaloguj sie, zeby sie zapisac" osobie juz zalogowanej.
• Strona powrotu z bramki NICZEGO nie potwierdza. To zwykle przekierowanie przegladarki, ktore da sie wywolac recznie, wiec ekran nie mowi "zaplacono", tylko odpytuje serwer co piec sekund i czeka na ITN. Odpytywanie zatrzymuje sie po nadaniu dostepu i po dziesieciu minutach: zakladka zostawiona na noc nie ma odpytywac bez konca.
• Cennik pokazuje ceny FAKTYCZNYCH kursow, a nie planow abonamentowych. Makieta proponowala trzy pakiety miesieczne, ale platforma rozlicza sie za kurs: jedno zamowienie, jedna platnosc, dostep bezterminowy. Cennik obiecujacy abonament, ktorego nie da sie kupic, wprowadzalby w blad.
• Liczniki w naglowku licza sie z bazy, a liczba kursantow to kontakty z zalozonym kontem, nie wszystkie kontakty: w bazie marketingowej sa takze osoby, ktore nigdy sie nie zarejestrowaly.
• Osobny layout (AcademyLayout), nie PublicLayout. Tamten jest waski (max-w-2xl) i zaprojektowany pod jeden formularz zapisu z linku w mailu; strona glowna pokazuje siatke kursow i potrzebuje max-w-container. Szerokosc ustawia sie raz, w layoucie.
• Publiczna czesc Akademii ladowana jest leniwie, tak samo jak wykresy i biblioteki wideo. Panel i Akademia to dwie rozne aplikacje dla dwoch roznych osob; bez podzialu glowny pakiet rosl z 859 kB do 1734 kB.
• Ikona nie zastepuje etykiety tekstowej. Komponent Icon ma na stale aria-hidden, wiec sama klodka przy lekcji platnej nie mowi czytnikowi ekranu niczego. Etykieta idzie tekstem (sr-only sm:not-sr-only). Wykryte przy sprawdzaniu na zywo.
• Pusty adres regulaminu UKRYWA odnosnik w stopce, zamiast prowadzic pod pusta sciezke: odnosnik donikad jest gorszy niz jego brak.

Konta kursantow (Akademia)

Kolumny konta dolozone do contacts (V21), endpointy /api/academy/**, pulpit kursanta pod /moje-konto.

• Kursant to kontakt z haslem, a nie czwarta tabela z ludzmi. W bazie sa juz trzy miejsca opisujace osobe: users (panel), registrations (zapis na jedno wydarzenie) i contacts (baza marketingowa). Kursant to ta sama osoba co kontakt: dostaje zaproszenia, ma zgody i wlasne wypisanie. Granica jest jedna kolumna: password_hash IS NULL to zwykly wpis marketingowy, password_hash IS NOT NULL to kursant.
• contacts i users to dwa rozne swiaty uprawnien i dwa niezalezne hasla. Ta sama osoba moze miec oba konta na jeden adres; zmiana hasla w panelu nie rusza konta kursanta i odwrotnie. Wspolne haslo oznaczaloby, ze wyciek hasla kursanta otwiera panel administracyjny.
• Token niesie pole typ i to ono egzekwuje granice. Obie tabele maja wlasne sekwencje identyfikatorow, wiec kursant o id 7 i administrator o id 7 to dwie rozne osoby. Filtr panelu bierze subject wprost i szuka po nim w users, wiec bez tego pola podpisany token kursanta otworzylby /api/admin/** kontu, ktore nigdy nie mialo tam wstepu. Pilnuje tego StudentTokenTest, ktory sprawdza obie strony granicy.
• Podpis tokenu (signWith) musi zostac we wspolnym budowniczym. Przy wydzielaniu wspolnej czesci obu tokenow latwo go zgubic, a wtedy biblioteka wydaje token z naglowkiem alg=none: kazde zadanie konczy sie 401, a sam token da sie ulozyc bez znajomosci sekretu. Zdarzylo sie to realnie.
• Filtry rejestruje sie wzgledem UsernamePasswordAuthenticationFilter. Podanie tam wlasnej klasy filtra jako punktu odniesienia nie dziala: lancuch nie ma takiej pozycji, filtr do niego nie trafia i kazde zadanie kursanta konczy sie 401 mimo poprawnego tokenu. Zdarzylo sie to realnie.
• Rejestracja na zajety adres daje te sama odpowiedz co sukces i mail o istniejacym koncie, dokladnie tak jak przy zapisach na webinar. Haslo nie jest przy tym nadpisywane: inaczej znajomosc samego adresu pozwalalaby przejac cudze konto przez formularz rejestracji.
• Adres istniejacy jako kontakt bez hasla jest uzupelniany, nie odrzucany. Osoba, ktora dostawala od nas maile albo zapisala sie na webinar, ma moc zalozyc konto na ten sam adres, bez powstawania drugiego kontaktu.
• Bez potwierdzenia adresu logowanie dziala, ale dostep do kursow nie (Contact.hasCourseAccess). Inaczej wystarczyloby podac cudzy adres, zeby dostac sie do jego materialow.
• Token resetu hasla wygasa po godzinie i jest jednorazowy. Link zostaje w skrzynce na zawsze, wiec token bez terminu waznosci dziala jak drugie, trwale haslo. Odebranie linku dowodzi dostepu do skrzynki, wiec reset przy okazji potwierdza adres.
• Odpowiedz na prosbe o reset jest taka sama dla adresu istniejacego i nieistniejacego, inaczej formularz sluzylby do sprawdzania, kto ma konto.
• Uczestnictwo laczy sie z kontem po adresie e-mail, nie kluczem obcym. Zapisy powstaly przed kontami i istnieja takze dla osob, ktore konta nigdy nie zaloza; dopisywanie im teraz contact_id wymagaloby migracji danych historycznych i rozstrzygniecia, co zrobic z adresami bez dopasowania.
• Dotychczasowe wejscie tokenem z maila zostaje nietkniete. Konto jest wygoda dla osob, ktore chca miec wszystko w jednym miejscu, a nie nowym warunkiem dostepu. Pulpit pokazuje ten sam token zapisu, ktory kursant ma w mailu, a kontrole dostepu do plikow nadal robi FileAccessGuard.
• Adres istniejacy w obu swiatach pokazuje wybor sciezki (alsoStaff w odpowiedzi logowania). Nie decydujemy za uzytkownika: administrator zapisany na webinar ma dostac sie i do panelu, i do wlasnego pulpitu. Wejscie do panelu wymaga osobnego zalogowania, bo hasla sa niezalezne.
• Zgody kursanta zapisuje ContactService.recordConsent, to samo wejscie co dla panelu. Zgody sa dopisywane, nigdy nadpisywane, a "ma zgode" znaczy najnowsza zgode danego typu.
• Wiadomosci Akademii ida przez MailService.deliver, jak cala reszta poczty: inaczej nowa sciezka domyslnie omijalaby tryb bezpieczny i limit godzinowy. Kazda zostawia wpis w notifications z prawdziwym odbiorca.
• Token kursanta ma wlasny klucz w localStorage (akademia.token). Wspolny klucz oznaczalby, ze zalogowanie sie do Akademii wyrzuca administratora z panelu w drugiej karcie.
• Komentarz blokowy /* */ nie moze sie zagniezdzac w migracji. Blok wewnatrz ALTER TABLE zamyka komentarz zewnetrzny przedwczesnie, PostgreSQL zglasza "unterminated /* comment", a cala migracja nie robi nic, mimo ze Flyway zapisuje ja jako wykonana. W jednym poleceniu uzywac wylacznie komentarzy liniowych --. Zdarzylo sie to realnie przy V21.

Kontakty i zaproszenia

Tabele contacts, contact_groups, contact_group_members, invitations (V15). Domyka pierwszy etap sciezki: najpierw informacja z linkiem, potem rejestracja.

• Kontakt to nie zapis na webinar. Kontakt zyje niezaleznie od wydarzen: dostaje zaproszenia na kolejne webinary, ma wlasne zgody i wlasne wypisanie. Zapis dotyczy jednego wydarzenia. Dlatego kontakty sa osobnym dzialem panelu, a nie zakladka webinaru.
• Adres jest tozsamoscia kontaktu, bez wzgledu na wielkosc liter. Unikalny indeks funkcyjny na lower(email): "Jan@Firma.pl" i "jan@firma.pl" to ta sama skrzynka, wiec import nie zaklada dwoch kontaktow, a wypisanie obejmuje oba zapisy.
• Zgody kontaktow leza w tej samej tabeli consents, z nullowalnym contact_id i ograniczeniem CHECK na dokladnie jednego wlasciciela. Jedna tabela, bo to ta sama rzecz: oswiadczenie osoby z trescia, wersja i data. Osobna oznaczalaby dwa miejsca do sprawdzenia przy kazdym pytaniu "czy wolno wyslac".
• "Ma zgode" znaczy najnowsza zgode. Zgody sa dopisywane, nigdy nadpisywane, wiec kontakt ma ich kilka. Wyraza to DISTINCT ON (contact_id) ... ORDER BY granted_at DESC w zapytaniu natywnym. W JPQL sie nie da: limit w podzapytaniu nie nalezy do gramatyki i aplikacja nie wstaje. To nie jest kwestia stylu, tylko jedyny dzialajacy sposob.
• unsubscribed_at jest osobno od zgody, mimo ze wypisanie ja cofa. Zgody daja slad rozliczalny, a ta kolumna daje jednoznaczna i tania odpowiedz na pytanie "czy wolno mu cokolwiek wyslac", bez szukania najnowszej zgody kazdego kontaktu przy kazdej wysylce.
• Wypisanie wymaga dwoch krokow: GET pokazuje, POST wykonuje. Samo otwarcie linku nie moze wypisywac, bo skanery poczty i podglad linkow w kliencie odwiedzaja adresy z wiadomosci automatycznie.
• Wypisanie dotyczy marketingu, nie obslugi zapisanego webinaru. Potwierdzenie, przypomnienie i podsumowanie ida dalej: to obsluga zamowionej uslugi. Strona wypisania mowi to wprost, zeby uczestnik nie sadzil, ze traci powiadomienia o wydarzeniu, na ktore sam sie zapisal.
• Import ma podglad przed wykonaniem. Pomylka w mapowaniu kolumn oznaczalaby setki kontaktow z nazwiskiem w polu firmy, a odkrecanie tego recznie kosztuje wielokrotnie wiecej niz jedno spojrzenie na piec przykladowych wierszy.
• Duplikat aktualizuje, nie tworzy drugiego, i uzupelnia zamiast zastepowac. Plik importu bywa ubozszy niz to, co juz mamy: pusta kolumna nie moze wyczyscic telefonu wpisanego wczesniej recznie.
• Import nie przywraca wypisanych. Zgoda z importu omija kontakt z unsubscribed_at: to najprostsza droga do wysylania wbrew wyraznej odmowie.
• Zapis na webinar dopisuje kontakt ze zrodlem REGISTRATION, przenoszac zgode marketingowa, gdy uczestnik ja wyrazil. Odmowa przy zapisie nie cofa wczesniejszej zgody kontaktu: to dwa osobne oswiadczenia. Blad tej synchronizacji nie moze wywrocic zapisu, wiec jest lapany i logowany.
• Zaproszenia ida przez istniejaca kolejke notifications, wiec tryb bezpieczny, limit godzinowy, ponawianie i slad bledu dzialaja tak samo jak przy reszcie poczty. Zaproszenie na cala baze to najwiekszy jednorazowy ruch w aplikacji, wiec bezpiecznik zadziala tu najczesciej.
• Nowy szablon z wlasnym wysylaczem dopisuje sie do SummaryScheduler.NOT_FOR_REMINDER_SENDER, a do TEMPLATES tylko wtedy, gdy ma go obsluzyc SummarySender. Te dwie listy sa rozne: pierwsza mowi, czego ReminderSender ma nie dotykac, druga co bierze SummarySender. Pomylenie ich sprawia, ze zaproszenia zostaja oznaczone FAILED, zanim wlasciwy wysylacz je zobaczy.
• Jedno zaproszenie na pare (webinar, kontakt), czego pilnuje unikalny indeks. Wysylka powtorzona po dolozeniu kontaktow do grupy nie moze zaprosic drugi raz tych, ktorzy juz dostali wiadomosc.
• Warunki sprawdzane ponownie tuz przed wysylka. Miedzy zakolejkowaniem a wyslaniem kontakt mogl sie wypisac, a zaproszenie do kogos, kto wlasnie zrezygnowal, jest dokladnie tym, czemu wypisanie ma zapobiegac.
• Podglad liczby odbiorcow pokazuje liczbe PO odfiltrowaniu wypisanych, bez zgody i juz zaproszonych. Liczba wybranych kontaktow bez tego filtru wprowadzalaby w blad przed nieodwracalna wysylka.
• Link zaproszenia niesie ?zaproszenie={id}, a backend sprawdza, czy zaproszenie dotyczy tego webinaru: identyfikator jest w adresie, wiec kazdy moze go podmienic, a bledne powiazanie zafalszowaloby skutecznosc innej wysylki.
• markRegistered ma REQUIRES_NEW. Jest wolane z afterCommit, czyli po zamknieciu transakcji zapisu; bez nowej transakcji zmiana nie zapisuje sie wcale, a zaproszenie zostaje bez registered_at mimo udanego zapisu.
• Skutecznosc liczona po wyslanych, nie po zakolejkowanych: zaproszenie, ktore nie wyszlo, nie mialo szansy przyniesc zapisu.
• Kazda wiadomosc marketingowa ma stopke z linkiem wypisania. Maile transakcyjne jej nie maja i nie podlegaja wypisaniu.

Obecnosc i statystyki

Tabela attendance_sessions (V14). Flaga registrations.attended wyliczana z sumy sesji, nigdy wpisywana recznie.

• Sesja, a nie flaga. Ludzie wchodza i wychodza, traca polaczenie, wracaja z telefonu. Dopiero suma sesji mowi, ile ktos naprawde byl obecny, i pozwala narysowac wykres obecnosci w czasie.
• Dwie drogi rejestracji, jedna tabela. Webhook dostawcy o wejsciu i wyjsciu oraz sygnal z przegladarki co minute. Roznia sie wylacznie polem source, wiec statystyki nie musza wiedziec, skad dane pochodza. Sygnal z przegladarki dziala takze w trybie NONE, gdzie zadnego dostawcy nie ma.
• Sygnal idzie istniejacym polaczeniem WebSocket (/app/heartbeat), nie osobnym zadaniem HTTP: polaczenie i tak jest otwarte przez cale spotkanie, a osobne zadanie wymagaloby wlasnego uwierzytelnienia przy kazdym strzale. Tozsamosc pochodzi z sesji, tak samo jak przy czacie.
• Sygnal przedluza sesje, nie zaklada nowej. Idzie co minute, wiec nowa sesja przy kazdym dawalaby setki wierszy na uczestnika. Chroni przed tym takze unikalny indeks czesciowy na jedna otwarta sesje: uczestnik z dwoma otwartymi kartami nie liczy sie podwojnie.
• Sesje porzucone zamyka zadanie @Scheduled. Przegladarka zamknieta bez wylogowania nie wysyla niczego, wiec bez tego sesja zostalaby otwarta na zawsze i zawyzala czas. Czas zamkniecia to ostatni sygnal, a nie chwila biezaca: uczestnik byl obecny do momentu, w ktorym przestal odpowiadac.
• ATTENDANCE_TIMEOUT_MINUTES musi byc wyrazne wiekszy niz odstep sygnalu. Przy jednej minucie chwilowa utrata polaczenia zamykalaby sesje i rozbijala obecnosc na dziesiatki kawalkow.
• Flaga attended jest przeliczana takze przy odczycie statystyk i przy eksporcie CSV. Sesja moze powstac droga, ktora nie przechodzi przez zamkniecie (import danych, webhook do wpisu utworzonego wczesniej), a przy sesji wciaz otwartej czas rosnie bez zadnego zdarzenia. Bez tego liczba obecnych na ekranie rozjezdza sie z kolumna w pliku.
• Wszystkie statystyki licza sie w bazie, zapytaniami agregujacymi: FILTER do licznikow, generate_series do wykresu obecnosci i do zapisow dziennych. Wczytanie kilkuset uczestnikow i kilkuset wiadomosci do pamieci tylko po to, zeby je policzyc, jest zauwazalnie wolniejsze.
• generate_series daje takze dni i minuty zerowe. Bez tego dzien bez zapisow znikalby z wykresu, a linia laczylaby punkty ponad luka i sugerowala ciaglosc, ktorej nie bylo.
• Wykres obecnosci konczy sie na chwili biezacej, gdy webinar jeszcze trwa: rysowanie do przyszlego endsAt dawaloby dluga linie zer.
• @mui/x-charts jest ladowane leniwie (lazy + Suspense), bo wazy wiecej niz cala reszta panelu, a jest potrzebne na dwoch ekranach. Bez podzialu kazde wejscie do panelu pobieraloby wykresy: glowny pakiet urosl z 795 kB do 1294 kB. Kolory wykresow sa podane wprost, bo biblioteka nie czyta klas Tailwinda; musza odpowiadac tokenom z tailwind.config.js.
• Ekran glowny panelu to /, nie lista webinarow. Pokazuje wylacznie rzeczy, na ktore mozna zareagowac: co sie zbliza i co czeka na obsluge. Pozycja menu ma end, inaczej podswietlalaby sie na kazdym ekranie.

Nagrania i materialy we wlasnym skladzie

Tabele recordings i materials (V13), pliki w MinIO, serwowane przez backend.

• Wlasny sklad, bo adresy u dostawcy wygasaja. Nagranie ma zyc dluzej niz umowa z dostawca, wiec plik trafia do wolumenu objetego kopia zapasowa. Pola recording_url i materials_url zostaja jako alternatywa dla instancji trzymajacych pliki poza systemem (dysk sieciowy, YouTube).
• Pierwszenstwo ma wlasny sklad. Mail podsumowujacy i powiadomienie o nagraniu najpierw szukaja nagrania READY o widocznosci innej niz PRIVATE, a dopiero gdy go nie ma, siegaja po recording_url. Kolejnosc jest w jednym miejscu: SummaryService.recordingLinkFor.
• MinIO zostaje niewystawiony na zewnatrz. Pliki ida przez /api/public/recordings/{id} i /api/public/materials/{id}, wiec kazde pobranie przechodzi przez kontrole widocznosci, a klucz obiektu nie opuszcza serwera. Serwowanie wprost z MinIO dawaloby dostep kazdemu, kto pozna adres, z pominieciem reguly widocznosci.
• Obsluga naglowka Range jest wymogiem, nie dodatkiem. Bez niej przewijanie nagrania nie dziala: przegladarka prosi o zakres bajtow, a serwer oddajacy zawsze calosc zmusza ja do pobierania pliku od poczatku przy kazdym skoku. Zakres otwarty (bytes=0-) jest ograniczany do 4 MB na odpowiedz, zeby jedno zadanie nie zajelo watku na caly czas pobierania dwugigabajtowego pliku. Zakres poza plikiem musi dawac 416 z prawdziwym rozmiarem, nie 200 z caloscia.
• Widocznosc: PRIVATE, REGISTERED (domyslna), PUBLIC. Domyslnie REGISTERED, a nie PUBLIC: nagranie zawiera wypowiedzi uczestnikow i pytania z imionami, wiec udostepnienie go calemu internetowi musi byc swiadoma decyzja. Regula siedzi w jednym miejscu (FileAccessGuard) i obsluguje oba rodzaje plikow: rozdzielenie jej oznaczaloby, ze poprawka w jednym omija drugie.
• Token musi dotyczyc TEGO webinaru. Wazny token z innego webinaru nie otwiera nagrania, a token po rezygnacji przestaje dzialac natychmiast: zapis jest sprawdzany przy kazdym zadaniu, a nie raz na sesje.
• Odmowa daje 404, nie 403. Istnienie pliku o danym identyfikatorze samo w sobie jest informacja: przy 403 dalo by sie sprawdzic, ktore webinary maja nagrania. Z tego samego powodu webhook ze zlym sekretem dostaje 404.
• Uzywac NotFoundException, nie ResponseStatusException. Ten drugi nie ma handlera w ApiExceptionHandler, wiec wraca do warstwy Security i wychodzi jako 401, czyli front pokazuje wylogowanie zamiast "nie znaleziono".
• Typ nagrania z sygnatury bajtowej (VideoTypeDetector), nigdy z rozszerzenia ani naglowka od klienta. Dopuszczone MP4 i WEBM, bo tylko te odtwarza element video bez dodatkowych bibliotek.
• Przy materialach lista zablokowanych rozszerzen, nie biala lista. Obrazek w tresci strony jest osadzany, wiec tam obowiazuje biala lista. Material jest pobierany i moze byc dowolnym dokumentem roboczym, ktorego nie da sie z gory przewidziec. Chronia go dwa zabezpieczenia niezalezne od nazwy pliku: Content-Disposition: attachment i nosniff przy kazdym serwowaniu.
• Pliki ida strumieniowo, nigdy przez byte[]. FileStorageService.putStream i openRange; wariant z tablica bajtow trzyma caly plik w pamieci sterty, wiec nagranie 2 GB przewrociloby aplikacje.
• Limity musza byc spojne w trzech miejscach: RECORDING_MAX_SIZE_MB (ustawienie), spring.servlet.multipart.max-file-size (kontener) i client_max_body_size w nginx. Zbyt niski ktorykolwiek z nich daje blad 413 albo 500 zamiast czytelnego komunikatu.
• Webhook /api/webhooks/video/{provider} jest otwarty, bo dostawca nie ma konta w panelu. Uwierzytelnia go VIDEO_WEBHOOK_SECRET, porownywany w czasie stalym. Pusty sekret odrzuca wszystkie zgloszenia: brak konfiguracji nie moze oznaczac braku kontroli.
• Webhook odpowiada 200 od razu, pobiera w tle. Dostawcy ponawiaja zgloszenie, gdy nie dostana odpowiedzi w kilka sekund, a pobranie trwa minutami. Przed podwojnym pobraniem chroni unikalny indeks uq_recordings_provider_id oraz stan DOWNLOADING.
• VIDEO_DELETE_AFTER_DOWNLOAD jest domyslnie wylaczone. Kasowanie u dostawcy jest nieodwracalne, wiec administrator wlacza je dopiero, gdy sprawdzi, ze pobieranie dziala.
• Sciezki nagran u dostawcy i we wlasnym skladzie sa rozne. /admin/webinars/{id}/provider-recordings pokazuje, co dostawca ma u siebie, /admin/webinars/{id}/recordings co mamy my. Wczesniej obie byly takie same i kontekst Springa nie wstawal z bledem "Ambiguous mapping".
• Pilnuje tego FileAccessTest: kazdy poziom widocznosci, token z obcego webinaru, token po rezygnacji oraz plik wykonywalny podszywajacy sie pod MP4.

Powiadomienie o nagraniu

POST /admin/webinars/{id}/notify-recording, wywolywane przyciskiem w zakladce "Po webinarze". Osobna wysylka, bo nagranie czesto pojawia sie po podsumowaniu.

• Osobno od podsumowania, bo podsumowania nie da sie powtorzyc. Idzie automatycznie godzine po zakonczeniu, a montaz trwa dluzej; summary_sent_at blokuje ponowne wyslanie i slusznie, bo uczestnik nie ma dostac dwa razy tej samej wiadomosci.
• Dokladnie raz na odbiorce, z bazy. Unikalny indeks czesciowy uq_notifications_recording_recipient (V12), dokladnie tak jak przy przypomnieniach i podsumowaniach. DataIntegrityViolationException jest spodziewany i oznacza "juz zakolejkowane".
• Tylko uczestnicy CONFIRMED, tak samo jak przy podsumowaniu.
• Szablon recording-available musi byc w SummaryScheduler.TEMPLATES. Bez tego ReminderSender bierze go jako "wszystko poza podsumowaniami", odrzuca jako wpis bez powiazanej reguly i oznacza FAILED, zanim SummarySender zdazy go wyslac. Nowy szablon dopisuje sie do tej jednej listy.
• Przycisk dziala na zapisanym adresie nagrania, nie na tresci pola: inaczej powiadomienie niosloby link sprzed edycji.

Podsumowanie po webinarze

Zadanie @Scheduled znajduje webinary zakonczone wczesniej niz SUMMARY_DELAY_MINUTES temu (domyslnie 60) i bez znacznika webinars.summary_sent_at, po czym kolejkuje maile: uczestnikom podziekowanie z lista zadan i linkami, prowadzacemu zestawienie.

• Wpisy trafiaja do istniejacej kolejki notifications, nie do osobnego mechanizmu. Dzieki temu ponawianie, statusy i slad bledu dzialaja tak samo jak przy potwierdzeniach i przypomnieniach, a administrator oglada wszystko w jednym miejscu.
• Znacznik summary_sent_at ustawia sie w tej samej transakcji, co wpisy. Rozdzielenie tych dwoch krokow daje albo podsumowanie wyslane dwa razy, albo cisze, zaleznie od tego, gdzie przerwie sie przebieg.
• Sam znacznik nie wystarcza, "dokladnie raz" pochodzi z bazy. Znacznik jest sprawdzany na poczatku przebiegu, a ustawiany na koncu, wiec dwa rownolegle przebiegi przechodza kontrole jednoczesnie i oba kolejkuja komplet wpisow. Zdarzylo sie to realnie: dwa webinary dostaly po dwa komplety utworzone w odstepie 17 milisekund. Chroni przed tym dopiero unikalny indeks czesciowy uq_notifications_summary_recipient na (webinar_id, template, recipient), dokladnie tak jak przy przypomnieniach. DataIntegrityViolationException przy wstawianiu jest spodziewana i oznacza "juz zakolejkowane".
• Kazdy wpis zapisuje sie w osobnej transakcji (SummaryQueueWriter, REQUIRES_NEW przez osobny komponent, bo samowywolanie omija proxy). Zapis calej partii jednym saveAll sprawialby, ze kolizja na jednym odbiorcy wycofuje podsumowania wszystkich pozostalych.
• Pilnuje tego SummaryTest.concurrentRunsDoNotDuplicate, ktory pusza osiem rownoleglych przebiegow na tym samym webinarze.
• Kolejka jest wspolna, wysylacze sa dwa, i kazdy bierze wylacznie swoje szablony. SummarySender bierze SummaryScheduler.TEMPLATES, ReminderSender bierze wszystko poza ta lista. Bez tego wykluczenia ReminderSender lapal zestawienie prowadzacego, odrzucal je jako "wpis kolejki bez powiazanego zapisu" i oznaczal FAILED, zanim SummarySender zdazyl je wyslac. Nowy szablon podsumowania dopisuje sie do tej jednej listy, nie do warunkow w obu zapytaniach.
• Osobny wysylacz, a nie rozszerzenie ReminderSender. Tamten wymaga powiazanego zapisu, a zestawienie dla prowadzacego zadnego nie ma, i pomija webinary zakonczone, a podsumowanie idzie wlasnie po zakonczeniu.
• Podsumowanie dostaje tylko uczestnik ze statusem CONFIRMED. Osoba, ktora zrezygnowala, nie ma dostac maila po wydarzeniu.
• Zestawienie prowadzacego zawiera dane kontaktowe, wiec idzie wylacznie na adresy z ustawien (SALES_NOTIFICATION_EMAIL, MAIL_CONTACT_RECIPIENT), nigdy na adres wziety z formularza czy z zapytania.
• Tresc sprawdza sie renderowaniem szablonu w tescie, nie wysylka. SummaryMailBuilder ma wydzielone renderParticipant i renderHost zwracajace Rendered, wiec SummaryTest oglada gotowy tekst bez SMTP. Test pilnuje takze, ze w wyniku nie ma nierozwinietych ${...} ani th:, czyli ze uczestnik nie dostanie surowego szablonu.
• Godzina w mailu jest przeliczona na strefe webinaru (atZoneSameInstant), nie podana jako surowe UTC.

Ekran spotkania

/spotkanie/:token to jeden ekran: wideo i wszystkie interakcje razem. Trasa jest wspolna dla uczestnika i prelegenta, bo organizator nie musi pamietac, ktory link komu wyslal; front probuje kolejno obu endpointow.

• Dwa etapy: przedpokoj i sala. MeetingLobby pokazuje tytul, termin i imie z zapisu do potwierdzenia, dopiero potem wchodzi sie na sale. Link otwiera sie bez logowania, wiec bez tego ekranu osoba z przekazanym linkiem zaczyna wystepowac pod cudzym nazwiskiem, nie majac szansy tego zauwazyc. Prelegent widzi to samo z oznaczeniem roli, bez ograniczenia okna czasowego.
• Pasek akcji jest nad panelem, nie w zakladce. Prosba o glos i przyciski oferty musza byc osiagalne niezaleznie od tego, co uczestnik oglada: schowane w zakladce sa bezuzyteczne dokladnie wtedy, gdy sa potrzebne.
• Zapytanie ofertowe otwiera sie w oknie, bez opuszczania sali. Po wyslaniu przycisk pokazuje potwierdzenie: bez widocznej zmiany uczestnik klika trzeci raz, a handlowiec dostaje trzy zgloszenia od tej samej osoby. Kolejne zapytanie wymaga swiadomego klikniecia w "Wyslij kolejne".
• "Prosze o kontakt" to ten sam endpoint, bez pola tresci. Uczestnik w trakcie webinaru czesto nie ma pomyslu, co napisac, a wymuszanie tresci konczy sie tym, ze nie wysyla nic. Tresc jest podstawiana zdaniem mowiacym wprost, o co chodzi. Zgoda CONTACT_SALES jest wymagana tak samo w obu trybach: uproszczenie dotyczy tego, ile uczestnik pisze, a nie tego, na co sie zgadza.
• Licznik przy zakladce pokazuje nowe pozycje od ostatniego zajrzenia, a nie laczna liczbe wpisow. Laczna liczba przy czacie rosnie caly czas i po kwadransie nie niesie zadnej informacji.
• W trybie NONE nadal nie przekierowujemy. Zamiast osadzonego wideo jest przycisk otwierajacy join_url w nowej karcie, a panel interakcji zostaje u nas. To jest sedno tego trybu: bez dostawcy platforma dalej ma sens.

Zgloszenia do zabrania glosu

Tabela speak_requests (V17), kolejka w panelu prowadzenia, temat WebSocket /topic/webinars/{id}/speak.

• Osobna tabela, nie kolejny typ w interactions. Zgloszenie nie jest wypowiedzia: nie ma tresci, nie idzie na czat, nie trafia do archiwum. Ma za to wlasny cykl zycia, ktorego zadna interakcja nie ma.
• Glos wynika z uprawnien u dostawcy, nie ze zgloszenia. Przyznanie ustawia registrations.room_role na SPEAKER, a mikrofon otwiera dopiero uprawnienie nadane przez serwer pokoju. Gdyby wystarczal stan w przegladarce, podmiana odpowiedzi pozwalalaby mowic bez zgody moderatora.
• Przy LiveKit uprawnienia zmienia na zywo SERWER (RoomPermissionSync, updateParticipant), bez ponownego wejscia na sale. Wczesniej zmiana szla wylacznie przez nowy token i przemontowanie sali w przegladarce: odebranie glosu dzialalo tylko u klienta, ktory posluchal zdarzenia, a kazda zmiana gasila obraz i dzwiek na chwile. Odebranie najpierw wycisza sciezke (mutePublishedTrack), potem zmienia uprawnienia.
• Sala LiveKit ma staly key. Nowy token nadal jest pobierany, ale na polaczonej sali podmiana nic nie robi; sluzy ponownemu wejsciu po zerwaniu.
• Mikrofon wlacza sie sam po przyznaniu glosu (MicOnGrant), raz na przyznanie i dopiero po nadaniu uprawnienia przez serwer. Otwarty mikrofon dla calej sali tego nie robi, bo tam nikt o glos nie prosil.
• canPublish=true z pusta lista zrodel znaczy u LiveKit "wszystkie zrodla". Kazda rola publikujaca ma jawna liste; pilnuje tego RoomPermissionTest, sprawdzony w obie strony.
• Zgloszenie i rola zmieniaja sie w jednej transakcji. Rozdzielenie daje uczestnika z rola SPEAKER i bez zgloszenia w kolejce (mikrofon otwarty, prowadzacy nie wie dlaczego) albo odwrotnie.
• Jedno zgloszenie w toku na uczestnika, wymuszone unikalnym indeksem czesciowym na statusach PENDING i GRANTED. Sprawdzenie w kodzie nie wystarcza: dwie karty przegladarki przechodza je jednoczesnie. DataIntegrityViolationException jest spodziewany i oznacza "juz zglosil".
• Odmowa przed przyznaniem to DECLINED, odebranie po przyznaniu to REVOKED. Prowadzacy ma w historii widziec, czy uczestnik w ogole doszedl do glosu.
• Wycofanie przyznanego glosu takze cofa role, inaczej mikrofon zostaje otwarty mimo rezygnacji uczestnika.
• Kolejka sortuje sie po czasie zgloszenia, najstarsze na gorze, i pokazuje, od kiedy ktos czeka. To regula, a nie estetyka: przy innym porzadku uczestnik czekajacy piec minut widzi, jak mowi ktos zgloszony przed chwila.
• Pilnuje tego SpeakRequestTest, w tym dziesiec rownoczesnych zgloszen.

Indywidualna zgoda na kamere i ekran

Kolumny registrations.camera_allowed i screen_allowed (V32), przelaczniki w karcie "Na sali", endpoint POST /admin/webinars/{id}/room/participants/{rid}/publish.

• Trzy niezalezne prawa, nie jedna rola (PublishRights: mikrofon, kamera, ekran). Kombinacji jest osiem, a enum rol na kazda oznaczalby, ze latwo przeoczyc, ktora odziedziczyla za duzo. RoomRole zostaje dla dostawcow znajacych tylko role (closestRole, nigdy PRESENTER).
• Zgoda na jedno zrodlo nie otwiera innego. Sam ekran to nie kamera, sama kamera to nie mikrofon. Pilnuja tego PublishRightsTest (uprawnienia na zywo) i PublishRightsTokenTest (lista zrodel w podpisanym tokenie), oba sprawdzone w obie strony.
• Prawa licza sie w jednym miejscu (VideoService.participantRights) dla tokenu i dla zmiany na zywo. Zgoda indywidualna jest niezalezna od trybow sali: wylaczenie "wideo dla wszystkich" nie odbiera kamery osobie, ktorej dano ja osobno.
• Tylko przy LiveKit. Wylacznie tam serwer egzekwuje osobno kazde zrodlo; przy innych dostawcach panel nie pokazuje tych przelacznikow.
• Kolejnosc: zapis, serwer pokoju, zdarzenie. Zdarzenie PUBLISH_CHANGED sluzy przegladarce do pokazania komunikatu i pobrania aktualnego biletu na wypadek ponownego wejscia; samo uprawnienie zmienil juz serwer.
• Uczestnik z prawem do ekranu dostaje ostrzezenie, ze sala zobaczy wszystko, co pokaze, lacznie z powiadomieniami. Przycisku udostepniania nie da sie przechwycic (to pasek LiveKit), wiec ostrzezenie wisi, dopoki zgoda trwa.
• Pasek sterowania LiveKit pokazuje przyciski wedlug canPublishSources, wiec uczestnik z samym ekranem widzi tylko przycisk ekranu.
• Glos bez zgloszenia idzie PRZEZ KOLEJKE, nie przez sama role (SpeakRequestService.setVoice): powstaje od razu przyznane zgloszenie albo zostaje przyznane oczekujace. Sama rola w bazie dawalaby mikrofon, ktorego nie widac w kolejce, bez napisu "Masz glos" u uczestnika i bez automatycznego wlaczenia mikrofonu. Uczestnik rozpoznaje zdarzenie jako swoje po numerze zapisu z sesji (mine), bo lokalnie nie ma zgloszenia.

Moderacja wyrazow

Tabela moderation_words (V31), ekran /moderacja-wyrazow, endpointy /admin/moderation-words/**, filtr WordFilter.

• Trafienie WSTRZYMUJE, nigdy nie kasuje. Wiadomosc czatu albo pytanie uczestnika z trafieniem dostaje status NEW i moderation_hit, widzi je tylko panel prowadzenia, a prowadzacy publikuje albo odrzuca. Lista slow nie rozumie kontekstu, wiec falszywe trafienie ma kosztowac jedno klikniecie.
• Filtr dziala na serwerze, przed publikacja (InteractionService.postChat i postQuestion). Wiadomosci prowadzacych nie sa filtrowane.
• Wiadomosc i wpis przechodza przez TA SAMA normalizacje: bez ogonkow i wielkich liter, cyfry na litery, powtorzenia zwiniete, rozstrzelenia sklejone. Wpis podaje sie w zwyklej pisowni. Nie dopisywac wariantow typu "kurw4".
• Tryb CONTAINS tylko dla rdzeni, ktore nie wystepuja w zwyklych slowach. "dup" jako fragment trafialby w "duplikat", "ciot" w "ciotka": takie wpisy sa WORD. WordFilterTest czyta slownik wprost z migracji i sprawdza obie strony, takze slownictwo wodociagowe; sprawdzony w obie strony.
• Slownik w pamieci, uniewazniany PO zatwierdzeniu zmiany. Uniewaznienie w trakcie transakcji pozwalaloby rownoleglej wiadomosci wczytac stara wersje na stale.
• Awaria filtru przepuszcza wiadomosc i loguje blad: czat, ktory przestaje dzialac przez filtr, jest gorszy niz chwila bez filtru.
• fullChatHistory zawiera NEW, bo tam leza wiadomosci wstrzymane. Publiczne chatHistory nadal zwraca wylacznie APPROVED.

Obecni na sali w panelu prowadzenia

Karta "Na sali" (RoomParticipants), endpointy /admin/webinars/{id}/room/participants.

• Przy LiveKit lista pochodzi z serwera pokoju (RoomServiceClient.listParticipants), a nie z naszej bazy. Tylko serwer wie, kto faktycznie odbiera obraz, i tylko tam widac polaczenia spoza zapisu (klient z kluczem API, pozostalosc po tescie). Przy pozostalych dostawcach zrodlem sa sygnaly obecnosci; pole source mowi, ktore odpowiedzialo. Awaria serwera pokoju przelacza na sygnaly, nie wywraca karty.
• Ukryci uczestnicy (Egress) nie sa osobami i nie trafiaja na liste.
• Usuniecie uczestnika z zapisu to BLOKADA plus wyrzucenie po stronie serwera. Samo wyrzucenie nic nie daje, bo wrocilby tym samym linkiem. Zdarzenie BANNED wyprowadza wylacznie posluszna przegladarke: bot albo wlasny klient zostawaly na sali, dlatego removeParticipant wola takze blokada z czatu.
• Prowadzacego (spk-) nie da sie usunac. Przy liscie dwustu osob omylkowe klikniecie jest realne, a webinar zostalby bez obrazu.
• Zablokowany nie pisze na czacie. Interceptor STOMP sprawdza blokade tylko przy CONNECT, wiec postChat sprawdza ja przy kazdej wiadomosci.
• Lista jest odpytywana co 10 sekund, bo wejscie i wyjscie widzi serwer wideo, a nie nasz backend: nie ma zdarzenia do rozeslania. Paginacja i wyszukiwanie po stronie backendu; liczniki dotycza calej sali, nie wyniku wyszukiwania.

Tryb otwartego mikrofonu

Kolumna webinars.open_mic (V18), przelacznik w panelu prowadzenia.

• Flaga, a nie kolejny tryb obok chat_mode. To decyzja zero-jedynkowa: albo kazdy moze mowic od razu, albo trzeba poprosic o glos.
• Domyslnie wylaczony, i to jest swiadome. Otwarty mikrofon na webinarze dla stu osob oznacza sto otwartych mikrofonow naraz. Ma sens przy warsztacie dla kilkunastu osob, wiec prowadzacy wlacza go swiadomie. Wlaczenie pyta o potwierdzenie, wylaczenie nie: otwarcie mikrofonow calej sali jest slyszalne natychmiast i trudno to cofnac po fakcie.
• Decyzja zapada przy wydawaniu tokenu (VideoService.joinAsParticipant), a nie w przegladarce: samo odblokowanie przycisku niczego nie daje, bo dostawca odrzuci publikacje bez uprawnienia w tokenie.
• Rola w zapisie zostaje nietknieta. Tryb podnosi uprawnienie wylacznie w wydawanym tokenie, wiec wylaczenie go zamyka mikrofony wszystkim, ale nie odbiera glosu osobom, ktorym przyznano go indywidualnie: ich uprawnienie wynika z room_role.
• Wlaczenie nie kasuje kolejki. Prowadzacy wlacza tryb na czas dyskusji i wylacza przed dalsza czescia prezentacji; skasowanie zgloszen odbieraloby miejsce osobom czekajacym od kwadransa. Przy wlaczonym trybie kolejka jest nieaktywna, a nie nieaktualna.
• Wideo zostaje wylaczone takze w tym trybie. RoomRole.SPEAKER to canPublishVideo=false, wiec otwarty mikrofon nie moze wlaczyc nikomu kamery.
• Przelaczenie zmienia uprawnienia calej sali po stronie serwera (RoomPermissionSync.syncWebinar, w tle, z pominieciem osob bez zmiany) i idzie tematem speak, zeby przegladarki pobraly aktualny token na wypadek ponownego wejscia.

Sygnal dzwiekowy w panelu prowadzenia

• Skladany w WebAudio, nie wczytywany z pliku. Chodzi o jeden krotki ton, a plik oznaczalby zasob do wgrania i sciezke do utrzymania.
• Domyslnie wlaczony, wylaczalny, wybor zapamietany w przegladarce. Zapytanie ofertowe jest zgloszeniem, ktorego prowadzacy najbardziej nie chce przegapic, a w trakcie mowienia nie patrzy na panel.
• Stan przelacznika czytany z referencji, nie ze stanu Reacta. Efekt WebSocketu widzi wartosc z chwili podlaczenia, wiec przelacznik nie dzialalby bez zerwania polaczenia.
• Przegladarki blokuja dzwiek do pierwszej interakcji uzytkownika, wiec blad jest tu spodziewany i pomijany.

Banery i reklamy w sali

Tabele banners i banner_events (V19), kolumna interactions.source_banner_id. Dzial /banery dla ADMIN i zakladka na karcie webinaru.

• Baner globalny i baner webinaru to jedna tabela. webinar_id rowne null oznacza baner instancji. Ten sam cykl zycia, te same statystyki i to samo okno czasowe, wiec osobna tabela oznaczalaby dwa razy ten sam zestaw kolumn. Panel uzywa tego samego komponentu (BannerSection), parametryzowanego webinarem, dokladnie tak jak OfferSection.
• Grafika wylacznie z biblioteki mediow. Baner wskazuje media_id, nigdy adres. Obcy obrazek na sali ujawnia adresy IP wszystkich uczestnikow wlascicielowi obcego serwera i pozwala ich sledzic miedzy webinarami.
• target_url tylko http i https. javascript: wykonalby sie w kontekscie naszej strony, a data: pozwolilby podstawic dowolny dokument pod nasza domena. Bariera jest w BannerService, bo endpoint zapisu da sie wywolac z pominieciem panelu.
• content_html czyszczone tym samym HtmlSanitizer co tresc strony. Do bazy trafia wylacznie wersja oczyszczona, wiec front nie czysci jej drugi raz.
• Dwa warianty okna czasowego, bo dwa rozne pytania. starts_at/ends_at to "od kiedy do kiedy kampania trwa", sensowne przy banerze globalnym. show_from_minute/show_to_minute to "w ktorej minucie prezentacji", odporne na zmiane terminu webinaru. Oba obowiazuja jednoczesnie, gdy oba sa ustawione.
• Wybor banerow robi baza, nie przegladarka. Oddanie wszystkich banerow i odsianie ich we froncie oznaczaloby, ze uczestnik widzi w zrodle strony kampanie, ktora ma ruszyc za tydzien.
• Front odpytuje okresowo, nie czeka na WebSocket. Baner "od 40. minuty" zmienia stan, bo mija czas, a nie dlatego, ze ktos cos kliknal: nie ma zdarzenia do rozeslania. Serwer musialby pilnowac zegara osobno dla kazdego webinaru, co jest wieksza maszyneria niz jedno lekkie zapytanie na minute.
• Odstep rotacji wraca razem z banerami, nie przez /public/config. Tamten endpoint jest jawny dla calego internetu i kazde pole trzeba tam dopisywac swiadomie; BANNER_ROTATION_SECONDS jest potrzebne wylacznie na sali.
• Rotacja jest per miejsce, nie per sala. Baner boczny i pas pod wideo nie musza zmieniac sie w tej samej chwili.
• OVERLAY musi dac sie zamknac, bo jako jedyny zaslania obraz. Zamkniety nie wraca do konca sesji.
• Prelegent nie dostaje banerow: reklama jest kierowana do uczestnikow, a prowadzacemu zabieralaby miejsce na obraz.

Zliczanie zdarzen banera

• IMPRESSION raz na uczestnika i baner, co wymusza unikalny indeks czesciowy uq_banner_events_impression. Baner rotuje i wraca na ekran wielokrotnie, wiec liczenie kazdego pojawienia sie zawyzaloby statystyke kilkudziesieciokrotnie i czynilo klikalnosc bezuzyteczna. CLICK celowo nie ma takiego indeksu: powtorne klikniecie jest realnym zainteresowaniem.
• Zapis idzie przez BannerEventWriter, ktory NAJPIERW SPRAWDZA, czy wpis istnieje. To odwrotna kolejnosc niz przy podsumowaniach i wymaga wyjasnienia: naruszenie ograniczenia oznacza transakcje jako rollback-only zanim wyjatek do nas dotrze, wiec samo zlapanie DataIntegrityViolationException konczy sie UnexpectedRollbackException przy zatwierdzaniu, czyli bledem 500 zamiast cichego pominiecia. Dotyczy to takze REQUIRES_NEW: nowa transakcja jest wlasna, ale rownie skutecznie zepsuta. Wyjatek zostaje wylacznie jako zabezpieczenie wyscigu. Zdarzylo sie to realnie i wylapal to test.
• registration_id jest nullowalne, bo zdarzenie moze pochodzic od prelegenta, ktory nie ma wiersza w registrations.

Baner a zapytanie ofertowe

• offer_topic_id wylacznie przy banerze webinaru. Tematy naleza do konkretnego wydarzenia (offer_topics.webinar_id NOT NULL), wiec baner globalny wskazywalby temat cudzego webinaru. Pilnuje tego ograniczenie CHECK w bazie i walidacja w serwisie, ktora sprawdza takze, czy temat nalezy do tego webinaru: bez tego znajomosc samego identyfikatora pozwalalaby skierowac zapytanie do niewlasciwego handlowca.
• Klikniecie otwiera formularz oferty w oknie paska akcji, a nie wlasne okno banera: tam juz jest obsluga zgody i stan po wyslaniu, a drugie takie okno oznaczaloby dwie kopie tej samej logiki.
• Temat z banera jest podstawiany, ale nie wymuszany. Uczestnik moze go zmienic: baner mowi, czego zapytanie prawdopodobnie dotyczy, ale to uczestnik wie, o co chce zapytac. Podstawiamy go tylko, gdy taki temat nadal istnieje w tym webinarze: lista mogla sie zmienic po utworzeniu banera.
• interactions.source_banner_id jest jedynym wiarygodnym sladem, skad przyszlo zapytanie. Liczenie po zbieznosci tematu mieszaloby zapytania z banera z tymi wyslanymi z zakladki Oferta i zawyzaloby skutecznosc reklamy. ON DELETE SET NULL, bo zapytanie ma przetrwac skasowanie kampanii.

Statystyki banerow

• Sekcja obejmuje banery webinaru ORAZ globalne, bo uczestnik widzi jedne i drugie; pominiecie globalnych oznaczaloby, ze polowa reklam nie ma statystyki.
• Bez filtru okna czasowego i bez filtru aktywnosci (findActiveForStats). Statystyka opisuje to, co sie wydarzylo, wiec skutecznosc zakonczonej kampanii ma byc widoczna wtedy, gdy jest potrzebna do oceny.
• Klikalnosc liczy backend, w BannerView i w StatsService. Liczenie jej w przegladarce oznaczaloby drugie miejsce, ktore moze sie rozjechac. Baner bez wyswietlen ma zero, a nie wartosc udajaca pomiar.
• Zapytania i zdarzenia ida zapytaniami zbiorczymi (countEventsByBannerIds, countOffersByBanner), a nie po dwa na kazdy baner: ten sam wzorzec co przy liczbie zapisanych na liscie webinarow.

Interakcje w trakcie spotkania

Czat i pytania w jednej tabeli interactions, wspolnej dla wszystkich zgloszen uczestnika. TASK_SIGNUP i OFFER_REQUEST sa juz w ograniczeniu CHECK, mimo ze obsluga dojdzie pozniej: ich dodanie nie bedzie wymagalo migracji zmieniajacej typ.

• Jedna tabela, nie cztery. Czat, pytanie, zapis na zadanie i zapytanie ofertowe maja tego samego autora, tresc, status i czas. Osobne tabele oznaczalyby czterokrotnie powtorzony ten sam zestaw kolumn i indeksow.
• Autor to albo registration_id, albo speaker_id, nigdy oba. Wymusza to CHECK w bazie: blad w kodzie dawalby zgloszenia bez autora albo z dwoma, a jedno i drugie psuje moderacje.
• Uwierzytelnienie WebSocket przy CONNECT, nie przy kazdej wiadomosci. Token zapisu idzie raz w naglowku, wynik zostaje w sesji. Wiadomosc niesie sama tresc: gdyby niosla identyfikator autora, kazdy podalby sie za kogo innego.
• Prowadzacy nie ma tokenu zapisu, bo nie jest uczestnikiem. Laczy sie naglowkiem X-Panel-Token z tym samym JWT co przy zwyklych zadaniach panelu.
• enableSimpleBroker musi obejmowac takze /queue. Komunikaty do jednej osoby (limit tempa, odmowa pisania) ida na /user/queue/errors; bez tego prefiksu broker po cichu je porzuca i uczestnik nie wie, dlaczego wiadomosc nie poszla.
• Autor prezentowany jako imie i pierwsza litera nazwiska, nigdy adres e-mail. Czat widza wszyscy obecni, a adres pozwalalby zaczepiac ich poza platforma.
• Tresc uczestnika czyszczona PlainTextSanitizer, czyli Safelist.none(): zaden znacznik nie przechodzi. Adresy zostaja czytelnym tekstem, ale nie sa klikalne - klikalny link na czacie to najprostsza droga do rozeslania phishingu calej sali.
• Glosy w osobnej tabeli z unikalnym indeksem na parze. Licznik przy pytaniu nie powstrzymalby jednej osoby przed wielokrotnym glosowaniem. DataIntegrityViolationException przy wyscigu jest spodziewana i oznacza "juz glosowal", a nie blad.
• Pytanie ze statusem NEW nie wychodzi w publicznym API. To jedyna bariera przed pokazaniem niezatwierdzonej tresci; panel prowadzacego ma osobny temat moderacji.
• Usuniecie wiadomosci to status REJECTED, nie skasowanie wiersza. Moderator ma miec slad, co usunal.
• Widok do rozeslania sklada sie w transakcji (InteractionService.view). Autor jest pobierany leniwie, wiec mapowanie encji poza transakcja konczy sie LazyInitializationException, czyli bledem 500 zamiast wiadomosci na czacie.
• W trybie NONE strona spotkania nie przekierowuje automatycznie. Obraz jest w zewnetrznym narzedziu, ale czat i pytania zostaja u nas; wyrzucenie uczestnika odcieloby go od nich, a wielu klientow zostaje na tym trybie na stale.

Zadania i zapytania ofertowe

Oba typy korzystaja z tabeli interactions. TASK_SIGNUP i OFFER_REQUEST byly w ograniczeniu CHECK od poczatku, wiec ten krok nie wymagal zmiany typu kolumny. Nowe tabele opisuja tylko to, czego w zgloszeniu nie ma: tasks i offer_topics.

• task_id wypelniane wylacznie dla TASK_SIGNUP, wymuszone ograniczeniem CHECK. Bez niego literowka w kodzie przypielaby wiadomosc czatu do zadania.
• Limit miejsc pod blokada wiersza zadania (findByIdForUpdate), dokladnie tak samo jak przy zapisie na webinar. Chroni to TaskCapacityTest, gdzie 10 rownoczesnych zgloszen na 3 miejsca konczy sie dokladnie trzema wierszami.
• Wycofanie to status REJECTED, nie skasowanie wiersza. Miejsce wraca do puli, bo licznik pomija REJECTED, a prowadzacy zachowuje slad, ze ktos sie zglosil i wycofal. Powrot po wycofaniu ozywia istniejacy wiersz: unikalny indeks nie pozwala na drugi.
• Zapytanie ofertowe nigdy nie trafia na strumien publiczny. Nie ma endpointu, ktory zwracalby cudze zapytania: ida wylacznie na temat moderacji i mailem do handlowca. Sprawdza to offers_test, ktory oglada wszystkie cztery zakladki drugiego uczestnika.
• Bez zgody CONTACT_SALES zapytania nie da sie wyslac. Zgoda jest sprawdzana przed zapisem czegokolwiek, zapisywana z wersja tresci i dopisywana, nigdy nadpisywana: kazde zapytanie ma wlasny slad zgody.
• Telefon z zapytania nie nadpisuje numeru z zapisu. Osobna kolumna contact_phone: nadpisanie tamtego zmienialoby odbiorce przypomnien SMS.
• Temat zapytania kopiowany jako tekst, a nie wskazywany kluczem obcym: lista tematow moze sie zmienic, a zapytanie sprzed miesiaca ma dalej mowic, czego dotyczylo.
• Powiadomienie handlowca jest asynchroniczne, a SubmitResult niesie zwykle wartosci, nie encje: wysylka idzie na osobnym watku, gdzie sesji Hibernate juz nie ma.
• Zapytania maja osobny licznik w panelu prowadzenia, wyraznie oddzielony od pytan: to kontakt handlowy, a nie pytanie do prowadzacego.
• Eksport CSV zawiera wersje zgody i date jej wyrazenia, bo to one dokumentuja podstawe kontaktu. Wartosci zaczynajace sie od =, +, -, @ sa poprzedzane apostrofem.

Dostawcy wideo: co gwarantuje serwer, a co tylko interfejs

To jest najwazniejsza tabela w tym pliku, jesli chodzi o wideo. Roznica miedzy dostawcami nie jest kwestia wygody, tylko tego, czy uprawnienia sa egzekwowane, czy jedynie deklarowane.

Dostawca	Uprawnienia egzekwuje	Rozroznia audio/wideo	Nagrywanie
LIVEKIT	serwer, na podstawie podpisanego tokenu	tak (CanPublishSources)	wymaga kontenerow Egress i Redis
DAILY	serwer	tak	pobierane od dostawcy po zakonczeniu
JITSI z JWT	serwer, ale tylko role moderatora	nie	reczne wgranie pliku
JITSI bez JWT	nikt: pokoj otwarty	nie	reczne wgranie pliku
NONE	nie dotyczy, obraz poza platforma	nie dotyczy	reczne wgranie pliku

• Nagrywanie przez Egress nie jest zweryfikowane end-to-end. Potwierdzone jest wszystko, co do niego prowadzi: Egress laczy sie z Redisem, przyjmuje zadanie, dolacza do pokoju i zestawia media po UDP, a szablon sie wykonuje. Proces zatrzymuje sie na tym, ze szablon nie subskrybuje zadnej sciezki i nie wola START_RECORDING, wiec Egress przerywa nagranie z kodem 412. Do domkniecia potrzebny jest publikujacy uczestnik w tej samej sieci co Egress, czego nie da sie zestawic na Docker Desktop przy jednym NODE_IP. Reczne wgranie pliku dziala i pozostaje droga awaryjna.
• Egress zostaje w sieci Compose. Nigdy network_mode: host na Docker Desktop: kontener trafia wtedy do sieci maszyny wirtualnej, jego kandydaci ICE maja puste adresy IP, serwer odrzuca je jako [filtered], a polaczenie konczy sie failed. network_mode: bridge jest rownie zly: odlacza kontener od sieci Compose i przestaje on widziec redis oraz livekit po nazwie.
• Sam profil livekit bez Egress i Redisa NIE nagrywa. Serwer LiveKit przyjmuje zadanie nagrania i przekazuje je Egress przez Redisa; bez tych dwoch uslug zadanie nie ma odbiorcy, a nagrywanie konczy sie timeoutem przy poprawnie dzialajacym serwerze i dzialajacych spotkaniach. Oba kontenery sa w tym samym profilu, wiec instancja bez wideo ich nie uruchamia.
• Egress uruchamia prawdziwa przegladarke i otwiera nia strone szablonu. Domyslny szablon pobiera z internetu, wiec instancja w sieci zamknietej nie nagra niczego; dlatego wskazujemy wlasny (/nagrywanie we froncie). Szablon musi zawolac window.START_RECORDING(), inaczej Egress przerywa nagranie z kodem 412 "Start signal not received".
• Przy LiveKit uczestnik bez prawa publikacji nie wlaczy kamery, chocby podmienil kod strony albo wszedl wlasnym klientem: serwer odrzuci strumien. SPEAKER dostaje CanPublishSources(["microphone"]), wiec brak "camera" na tej liscie jest jedynym miejscem, w ktorym zabraniamy obrazu. Pilnuje tego ProviderTokenTest.
• Przy Jitsi bez JWT role sa umowne. Pokoj jest otwarty dla kazdego, kto zna adres, a ukrycie przycisku kamery w interfaceConfigOverwrite to jedyne, co dzieli uczestnika od publikacji. Wystarczy otworzyc ten sam pokoj wprost na domenie Jitsi, zeby to obejsc. Panel ostrzega o tym wprost przy wyborze dostawcy, bo to nie jest szczegol konfiguracji.
• Jitsi nie ma odpowiednika uprawnienia "publikuj tylko audio". Serwer rozroznia wylacznie moderatora, wiec VIEWER i SPEAKER dostaja tam identyczny token, a roznice robi w calosci interfejs. Kto potrzebuje gwarancji, wybiera LiveKit.
• Nazwa pokoju Jitsi zawiera slug, nie samo id. Przy otwartym serwerze nazwa do odgadniecia oznacza obcych ludzi na szkoleniu.
• Nagrywanie Jitsi wymaga komponentu Jibri, ktorego nie zakladamy: to osobna usluga z wlasna przegladarka na kazde nagranie. Implementacja zwraca pusta liste, a nie wyjatek: brak nagran u dostawcy to normalny stan i nie moze wywracac ekranu w panelu.

Wybor dostawcy: dwie kolumny, nie jedna

webinars.video_provider i webinars.room_provider to dwie rozne rzeczy i pomylenie ich kosztuje otwarty, platny pokoj u dostawcy, o ktorym nikt juz nie pamieta.

• video_provider to wybor administratora. Null oznacza "uzyj dostawcy z ustawien instancji", dzieki czemu zmiana jednego ustawienia pociaga za soba wszystkie webinary, ktore niczego nie wybraly.
• room_provider to stan faktyczny: u kogo pokoj zostal zalozony. Ustawiane przez kod, nigdy przez czlowieka.
• Rozbieznosc jest sygnalem, nie bledem. Znaczy "zmieniono dostawce, pokoj wciaz stoi u poprzedniego". Panel pyta wtedy o potwierdzenie i zamyka stary pokoj (POST /admin/webinars/{id}/video-provider/migrate).
• Rozstrzyganie siedzi w VideoProviderFactory, w jednym miejscu. Trzy metody odpowiadaja na trzy rozne pytania: forWebinar (kto ma obslugiwac), ofExistingRoom (u kogo pokoj faktycznie stoi), instanceDefault (dostawca instancji).
• Operacje na istniejacym pokoju ida do providerOfRoom, nie providerFor. Dotyczy zamykania pokoju, nagran i webhookow. Uzycie tam wybranego dostawcy zamknelo by pokoj u kogos, kto go nie ma, a prawdziwy zostalby otwarty.
• Odpowiedz POST /room podaje dostawce tego webinaru, nie instancji. Bylo odwrotnie i panel pokazywal nieprawde przy webinarze z wlasnym wyborem.

LiveKit: wydajnosc i nagrywanie

• Subskrypcja ograniczona do aktywnych mowcow jest wymogiem, nie strojeniem. Przy otwartym mikrofonie i stu uczestnikach kazda przegladarka odbieralaby sto strumieni audio naraz, a ruch rosnie liniowo z liczba uczestnikow. adaptiveStream wstrzymuje strumienie spoza kadru, dynacast wylacza warstwy, ktorych nikt nie oglada, a LIVEKIT_ACTIVE_SPEAKERS ogranicza liczbe odbieranych mowcow.
• Egress pisze prosto do naszego MinIO przez API zgodne z S3, wiec nie ma etapu pobierania od dostawcy. forcePathStyle jest obowiazkowe: MinIO nie obsluguje adresowania po nazwie kubelka w domenie.
• Wpis w recordings powstaje od razu, ze statusem DOWNLOADING, a nie dopiero po webhooku: panel ma pokazac "nagrywanie trwa", a nie pusta liste przez cale szkolenie.
• LIVEKIT_URL jest adresem WebSocket (wss://), bo taki potrzebuje przegladarka. API serwera slucha pod tym samym adresem po HTTP, wiec kod zamienia schemat zamiast wymagac dwoch ustawien opisujacych to samo miejsce.
• Zakladanie pokoju nie wysyla zadnego zadania. LiveKit i Jitsi tworza pokoj przy pierwszym wejsciu z waznym tokenem. Sprawdzamy za to konfiguracje przy zakladaniu, zeby administrator zobaczyl brak klucza wtedy, a nie dowiedzial sie o nim od uczestnika minute przed startem.

Biblioteki wideo we froncie ladowane leniwie

@livekit/components-react i @jitsi/react-sdk sa ladowane przez lazy, tak samo jak @mui/x-charts. Bez podzialu glowny pakiet rosl z 859 kB do 1552 kB, a biblioteki sa potrzebne wylacznie na sali: panel i strona zapisu otwieraja sie znacznie czesciej niz spotkanie.

Nie budujemy wlasnego interfejsu wideo. VideoConference z LiveKit daje uklad kafelkow, aktywnego mowce i wybor urzadzen. Nasze zostaje to, czego dostawca nie ma: czat, pytania, zadania, zapytania ofertowe, banery i pasek akcji.

Profil livekit w Compose

Serwer LiveKit i coturn sa w profilu livekit, wylaczonym domyslnie: instancja w trybie NONE albo na Jitsi nie ma uruchamiac zbednych uslug. Wlaczenie: docker compose --profile livekit up -d.

• Nagrywanie to osobne uslugi. Profil livekit zawiera cztery kontenery: serwer, coturn, Redis i Egress. Same spotkania dzialaja bez dwoch ostatnich; nagrywanie bez nich nie dziala wcale.
• use_external_ip: true nadpisuje NODE_IP. Przy uruchomieniu lokalnym serwer rozglasza publiczny adres lacza i media sie nie zestawiaja, mimo ze uczestnik wchodzi do pokoju i widzi liste obecnych. Do testow na jednej maszynie trzeba ustawic false.
• Wersja serwera musi nadazac za livekit-client. Klient 2.22 laczy sie sciezka /rtc/v1, ktorej serwer 1.8 nie zna: sala wyglada na dzialajaca, ale nie plynie ani obraz, ani dzwiek. Obraz przypiety do v1.13.
• Port UDP 7882 musi byc otwarty. To glowna droga audio i wideo. Bez niego uczestnicy dolacza do pokoju i zobacza liste obecnych, ale nie beda sie slyszec: to najczestsza przyczyna zgloszenia "wideo nie dziala" przy poprawnie skonfigurowanym serwerze.
• Jeden port UDP dla wszystkich (udp_port, tryb mux), NIGDY zakres. Przy port_range_start/end serwer rezerwuje osobny port na kazde polaczenie. Zakres 50000-50100 konczyl sie po okolo 50 uczestnikach: test z 200 botami wszedl dokladnie w 49, a log serwera pokazal kandydata UDP tylko przy 52 polaczeniach i TCP przy wszystkich 204. Przegladarka wchodzi wtedy po TCP (zacinajacy sie obraz przy utracie pakietow), klient bez ICE-TCP nie wchodzi. Zmienna UDP_PORT z zakresem nie wlaczala muxa: przegrywala z zakresem z pliku, a wczesniejsza analiza wziela ja za dzialajacy mux. Rozstrzyga log: connectionType i kandydaci [local] przy wejsciu uczestnika.
• coturn dziala w network_mode: host, bo TURN musi widziec prawdziwe adresy IP. Za NAT-em Dockera rozdawalby uczestnikom adresy wewnetrzne kontenera, pod ktore nikt z zewnatrz sie nie polaczy.
• Jitsi nie ma go w Compose. Zakladamy serwer zewnetrzny, wskazywany domena: wlasny Jitsi to kilkanascie uslug i osobne wdrozenie, a meet.jit.si dziala bez konfiguracji.

Warstwa wideo

Kontakt z dostawca przechodzi przez interfejs VideoProvider, a implementacje wybiera ustawienie VIDEO_PROVIDER. Na start dwie: NONE i DAILY.

• Tryb NONE jest rownoprawny, nie awaryjny. Instancja bez dostawcy ma w pelni obslugiwac webinary: organizator wkleja link w join_url, a uczestnik jest tam przekierowywany. Wielu klientow zostanie przy tym na stale, wiec nie wolno tego traktowac jak zaslepki ani wymagac konfiguracji dostawcy.
• Uprawnienia wynikaja z tokenu u dostawcy, nie z interfejsu. Ukrycie przycisku kamery niczego nie zalatwia: uczestnik moze podmienic kod strony albo wejsc wlasnym klientem. RoomRole przeklada sie na permissions.canSend w tokenie. Wideo uczestnika jest domyslnie wylaczone, takze po podniesieniu do SPEAKER. Kamere i ekran daje wylacznie prowadzacy (PublishRights).
• RegistrationRoomRole (VIEWER, SPEAKER) jest celowo wezszy niz RoomRole: uczestnik z zapisu nigdy nie dostaje uprawnien moderatora. Ma je wylacznie prelegent z webinar_speakers, wchodzacy wlasnym linkiem. Pilnuje tego RoomRoleTest, ktory sprawdza kazda wartosc enuma.
• Prelegent nie jest wierszem w registrations. Nie przechodzi przez formularz i nie wyraza zgod, wiec mieszanie tych dwoch rzeczy zafalszowaloby liczbe zapisanych i statystyki zgod.
• Prelegent wchodzi bez ograniczenia okna czasowego, bo musi sprawdzic sprzet przed uczestnikami. Uczestnik wchodzi od ROOM_OPEN_BEFORE_MINUTES przed startem do ROOM_OPEN_AFTER_MINUTES po koncu.
• Pokoj zamkniety daje 409 wraz z terminem otwarcia, a nie 403: uczestnik ma prawo wejsc, tylko jeszcze nie teraz. Front pokazuje odliczanie i sam odswieza strone.
• room_provider jest zapisany przy webinarze. Zmiana VIDEO_PROVIDER w ustawieniach nie moze uniewaznic pokoi zalozonych u poprzedniego dostawcy.
• Brak klucza API zglaszany jest przed wyslaniem zadania. Administrator ma dostac komunikat mowiacy, co ustawic, a nie blad 401 z biblioteki HTTP.
• Strona /spotkanie/:token probuje kolejno endpointu uczestnika i prelegenta, bo organizator nie powinien pamietac, ktory link komu wyslal.
• Pokoj jest osadzany gotowym komponentem dostawcy w iframe. Wlasnego interfejsu wideo jeszcze nie budujemy, tak samo jak czatu i pytan.

Szczegoly webinaru

Ikona oka w wierszu listy otwiera /webinary/:id w nowej karcie. Strona ma zakladki: Tresc strony, Zapisani, Zapytania ofertowe, Historia czatu.

• Wszystko, co nalezy do jednego webinaru, jest jego zakladka. To regula obowiazujaca kazde powiazanie, nie decyzja o jednym ekranie. Dane opisujace konkretne wydarzenie (zapytania ofertowe, czat, w przyszlosci zadania, nagrania, frekwencja) trafiaja tutaj, a nie na osobny ekran globalny. Uzytkownik pracuje webinarami, wiec szukajac czegokolwiek o wydarzeniu wchodzi w to wydarzenie.
• Ekran zbiorczy moze istniec obok, ale nie zamiast. /zapytania zostaje dla handlowca, ktory obsluguje zapytania ze wszystkich webinarow naraz i nie chce wchodzic w kazde z osobna. Oba miejsca pokazuja ten sam komponent (OfferSection), parametryzowany webinarem: obsluga zapytania wyglada tak samo niezaleznie od drogi dojscia, a poprawka nie wymaga zmiany w dwoch plikach. Przy zakladce konkretnego webinaru znika filtr po webinarze i nazwa webinaru przy pozycji, bo jedno i drugie powtarza to, co jest w naglowku strony.
• Historia czatu to archiwum, nie podglad na zywo. Bez WebSocketu: archiwum sie nie zmienia, a otwarte polaczenie po zakonczonym webinarze byloby utrzymywane bez powodu. Panel prowadzenia (/webinary/:id/prowadzenie) zostaje osobno, bo tam liczy sie biezaca moderacja, a nie czytanie zapisu rozmowy.
• Archiwum czatu pokazuje takze wiadomosci usuniete przez moderatora, wyraznie oznaczone. Usuniecie to status REJECTED wlasnie po to, zeby zostal slad; archiwum bez tych wiadomosci gubiloby jedyne miejsce, w ktorym ten slad widac. Sluzy do tego InteractionService.fullChatHistory, osobne od chatHistory dokladnie tak samo, jak allQuestions jest osobne od publicQuestions. Nie wolno podpiac fullChatHistory pod endpoint publiczny: uczestnik ma widziec wylacznie APPROVED.
• Liczniki przy zakladkach pochodza z WebinarView, a nie z osobnych zapytan przy wejsciu na strone. offerCount jest doliczany tym samym wzorcem co registeredCount: jedno zapytanie zbiorcze na cala strone listy (countOffersByWebinarIds), zeby nie robic N+1. Z tego samego powodu, co przy "Zapisani", kolumna "Zapytania" nie jest sortowalna.
• Zapytania odrzucone nie licza sie do licznika. Licznik ma mowic, ile jest do obslugi albo obsluzonych, a nie ile kiedykolwiek przyszlo.
• To osobna strona pod wlasnym adresem, nie okno modalne. Dzieki temu da sie ja zostawic obok listy, odswiezyc, dodac do zakladek i podeslac linkiem.
• Ikona jest linkiem <a target="_blank">, nie przyciskiem. Tylko wtedy dzialaja srodkowy przycisk myszy, Ctrl+klik i menu kontekstowe przegladarki. rel="noopener" odcina nowej karcie dostep do window.opener.
• Trasa /webinary/:id jest po /webinary/nowy, ale kolejnosc i tak nie decyduje: React Router 6 wyzej ocenia segment staly niz parametr. Sprawdzone testem, zeby zmiana kolejnosci tras w przyszlosci nie przeslonila formularza.
• Podglad tylko czyta. Nie ma tu zadnego zapisu ani nowego endpointu: okno korzysta z GET /admin/webinars/{id}/registrations, czyli tego samego, co pelna lista zapisanych. Dzieki temu sprawdzenie, kto sie zapisal, nie wymaga otwierania formularza edycji i nie grozi przypadkowa zmiana.
• Tresc jest oczyszczona przy zapisie na backendzie, wiec dangerouslySetInnerHTML dostaje to samo, co strona publiczna. Nie czyscimy jej drugi raz w przegladarce.
• Zgody: pokazujemy tylko najnowsza kazdego typu. Zgody sa dopisywane, nigdy nadpisywane, wiec po ponownym zapisie jest ich kilka i pokazanie wszystkich mylilo by co do stanu biezacego.
• Lista zapisanych w oknie jest stronicowana tak samo jak pelna, a link "Pelna lista i eksport CSV" prowadzi tam, gdzie mozna pobrac calosc.

Formularz webinaru w zakladkach

/webinary/:id/edycja i /webinary/nowy sa podzielone na zakladki: Podstawowe, Tresc strony, Termin, Zapisy, Przypomnienia. Wczesniej wszystko bylo na jednej dlugiej stronie.

• Zakladki przelaczaja widocznosc, nie trasy. Formularz zostaje jeden, z jednym przyciskiem zapisu, wiec przejscie miedzy zakladkami nie gubi niezapisanych zmian i nie wymusza zapisywania po kawalku. Nie zamieniac tego na zagniezdzone trasy.
• Blad walidacji na nieaktywnej zakladce musi byc widoczny. Zakladka z bledem dostaje kropke, a proba zapisu przeskakuje na pierwsza wadliwa. Bez tego komunikat "Formularz zawiera bledy" wskazywalby na pole, ktorego nigdzie nie widac. Pilnuje tego lista fields przy kazdej zakladce w TABS.
• Edytor tresci odtwarza sie z form.contentHtml przy ponownym zamontowaniu, wiec odmontowanie przy zmianie zakladki nie kasuje niezapisanej tresci.
• Pasek zakladek przewija sie w poziomie wewnatrz wlasnego kontenera, tak samo jak w ustawieniach.

Tresc strony zapisu i pliki

Publiczna strona zapisu ma tresc budowana w edytorze wizualnym (TipTap), zapisywana w webinars.content_html. Pliki wstawiane w tresc leza w media_files plus MinIO.

• description i content_html to dwie rozne rzeczy. description to krotki opis bez znacznikow: zajawka Open Graph dla robotow i tresc maili. content_html to dluga tresc strony. Nie mieszac ich i nie zastepowac jednego drugim.
• HTML jest czyszczony na backendzie przy kazdym zapisie, przez HtmlSanitizer (jsoup, biala lista). Do bazy trafia wylacznie wersja oczyszczona, oryginal jest odrzucany. Endpoint zapisu mozna wywolac z pominieciem edytora, wiec ograniczenia we froncie sa dla wygody, nie dla bezpieczenstwa. Chroni to HtmlSanitizerTest.
• Biala lista, nigdy czarna. Wycinanie "tego, co niebezpieczne" pomija warianty w rodzaju <SCRIPT >, <svg onload> czy javascript:. Dozwolone jest tylko to, co wypisane: znaczniki tresci, a[href] z protokolami http/https/mailto, img[src] wylacznie z prefiksem /api/public/media/, oraz class ograniczona do czterech klas wyrownania.
• Obrazek tylko z wlasnego serwera. Adres bezwzgledny do obcego hosta jest usuwany: obcy obrazek na stronie ujawnia adresy IP odwiedzajacych i pozwala ich sledzic.
• Wyrownanie jako klasa, nie style. Atrybut style nie przechodzi przez biala liste, wiec front zamienia style="text-align:..." z TipTapa na klase (alignStyleToClass). Bez tego wyrownanie znikaloby przy kazdym zapisie.
• Typ pliku z sygnatury bajtowej, nigdy z rozszerzenia ani z naglowka od klienta (ImageTypeDetector). Plik z HTML-em nazwany zdjecie.png z naglowkiem image/png jest odrzucany. Przy serwowaniu Content-Type pochodzi z bazy, plus nosniff.
• Klucz obiektu w MinIO jest losowy. Nazwa oryginalna sluzy tylko do pokazania w bibliotece i nigdy nie jest czescia sciezki: moze zawierac ../ i znaki sterujace. Klucz nie wychodzi w API.
• Nigdy base64 w tresci. Obrazek idzie na /api/admin/media, a do tresci trafia adres /api/public/media/{id}.
• MediaView sklada sie w transakcji. uploadedBy i webinar sa pobierane leniwie, wiec mapowanie encji poza transakcja konczy sie LazyInitializationException, czyli bledem 500, ktory front pokazuje jako wylogowanie.
• Limit rozmiaru to ustawienie MEDIA_MAX_SIZE_MB (domyslnie 5). Limit w application.yml jest tylko twardym zabezpieczeniem kontenera, nie regula biznesowa.
• Formularz zapisu zawsze na dole strony, tresc nad nim. Pusta tresc oznacza strone dokladnie taka jak dotychczas.
• Wyglad tresci daje @tailwindcss/typography (klasa prose), dzieki czemu nie trzeba dopuszczac style ani pisac wlasnego CSS. Obrazek szerszy niz ekran jest ograniczany prose-img:max-w-full, a kontener ma overflow-x-auto.

Paginacja list

Kazdy widok z lista ma paginacje, domyslnie 25 wierszy na strone. Nowa lista bez paginacji to blad, nie brakujaca funkcja.

• Paginacja jest po stronie backendu (Pageable, Page<T>), nie filtrowaniem pobranej juz calosci w przegladarce. Endpointy: /admin/webinars, /admin/webinars/{id}/registrations, /admin/users. Rozmiar strony jest ograniczony do 100 (Math.min(size, 100)), zeby ?size=100000 nie omijalo limitu.
• Rozmiar strony trzyma jedna stala PAGE_SIZE w components/Pagination.tsx. Nie wpisywac liczby w poszczegolnych ekranach.
• Eksport CSV celowo nie jest stronicowany. registrations(...) zwraca strone, ale export(...) korzysta z findByWebinarIdOrderByCreatedAtDesc bez Pageable, bo plik ma zawierac wszystkich zapisanych, a nie biezaca strone. Nie ujednolicac tych dwoch sciezek.
• Zmiana filtru cofa na pierwsza strone. Bez tego uzytkownik stojacy na stronie 2 po zawezeniu wyniku widzi pusta tabele i wyglada to jak brak danych.
• Klucz zapytania zawiera numer strony (['users', page]), ale uniewaznianie po ['users'] dalej dziala, bo TanStack Query dopasowuje po prefiksie.

Interfejs user friendly

Panel obsluguje zwykly uzytkownik, nie programista. Zaden format techniczny nie moze byc tym, co uzytkownik wpisuje recznie.

• Zadnych skladni rozdzielanych dwukropkiem, list po przecinku ani surowych identyfikatorow w polach. Zamiast tego osobna kontrolka na kazda wartosc.
• Czas podajemy w jednostkach, w ktorych mysli uzytkownik (dni, godziny, minuty), a przeliczenie na wartosc techniczna robi kod.
• Przy kazdym wyborze pokazujemy skutek zwyklym zdaniem, np. "Zostanie dodane przypomnienie 7 dni przed, wysylane przez SMS".
• Dodawanie i usuwanie pozycji przyciskiem, nigdy przez edycje ciagu znakow.
• Nazwa klucza (DEFAULT_REMINDERS) moze byc podpisem pomocniczym, ale nie moze byc jedynym opisem pola.

Szerokosc stron

Zadna strona panelu nie ustawia wlasnej szerokosci. Robi to raz Layout, kontenerem max-w-container (1200px z tailwind.config.js). Strona zaczyna sie od <div className="space-y-4">, bez mx-auto max-w-*.

• Wlasne max-w na stronie to blad, nie decyzja projektowa. Cztery ekrany (/uzytkownicy, /ustawienia, /webinary/nowy, podglad webinaru) mialy max-w-3xl albo max-w-4xl i byly zauwazalnie wezsze niz /webinary i /kontakty. Przy przechodzeniu miedzy nimi tresc skakala na boki.
• Szerokosc strony i szerokosc pola to dwie rozne decyzje. Pole tekstowe rozciagniete na 1200px jest gorsze niz waskie: oko gubi poczatek nastepnego wiersza, a krotka wartosc (godzina, limit miejsc) w bardzo szerokim polu wyglada na zepsuta.
• Limit czytelnosci siedzi w komponencie Field (max-w-2xl), nie w poszczegolnych formularzach. Nowy ekran dostaje go automatycznie, zamiast zaczynac od pola przez caly monitor. Pole w siatce sm:grid-cols-2 i tak dostaje polowe szerokosci, wiec limit go nie dotyka.
• wide na Field jest furtka dla pol, ktore z natury potrzebuja miejsca: edytor tresci, dluga tresc zgody, tabela w polu. Nie uzywac go do zwyklego pola tekstowego.
• Wyjatki spoza panelu zostaja: logowanie (max-w-sm), strony publiczne (max-w-2xl w PublicLayout) i okna modalne maja wlasna, wezsza miare, bo nie sa ekranami roboczymi panelu.

Okna modalne

Kazde okno modalne w panelu uzywa komponentu Modal (components/Modal.tsx). Nie budowac naklatki od nowa w miejscu uzycia.

• Okno jest tym samym elementem interfejsu co karta na stronie, wiec ma ten sam wyglad: rounded-lg, border-slate-100, naglowek i odstepy jak w Card (px-4 py-4 sm:px-5, tresc p-4 sm:p-5). Wczesniej kazde okno bralo wlasne wartosci i przy przechodzeniu miedzy nimi widac bylo rozjazd: inne zaokraglenie, inny kolor przycienienia, inne odstepy.
• Naklatka ma odstep od brzegu ekranu na kazdym rozmiarze (p-4 sm:p-6). Wczesniej bylo p-0 na telefonie i formularz dotykal krawedzi: okno wygladalo na uciete, nie bylo widac, gdzie sie konczy, a zaokraglone rogi kolidowaly z wycieciem ekranu.
• Przycienienie tla to bg-navy-900/40, z drugiej farby systemu HydroNexis. Nie bg-slate-900/50 ani inne odcienie dobierane osobno w kazdym oknie.
• Przewija sie tresc wewnatrz okna, nie strona pod spodem. Naglowek z tytulem i przycisk zamkniecia zostaja widoczne, a dlugi formularz importu nie zabiera uzytkownikowi kontekstu. Wysokosc to calc(100vh-2rem), czyli dokladnie tyle, ile zostaje po odstepie naklatki.
• Escape zamyka okno, a tlo strony nie przewija sie pod naklatka. Jedno i drugie siedzi w Modal, a nie w kazdym uzyciu z osobna: dopisywane recznie wystarczy raz przeoczyc, zeby jedno okno zachowywalo sie inaczej niz reszta.
• Klikniecie w tlo zamyka okno, klikniecie w samo okno nie. Rozstrzyga to event.target === event.currentTarget, nie stopPropagation na panelu.
• Okno rezygnacji na stronie publicznej ma wlasny znacznik, ale te sama naklatke i ramke. Nie uzywa Modal, bo celowo nie ma przycisku zamkniecia w naglowku: rezygnacja z udzialu ma wymagac wyboru jednego z dwoch przyciskow, a nie dac sie wywolac przypadkowym zamknieciem.

System projektowy

Interfejs jest zgodny z systemem projektowym HydroNexis: C:/Users/pzatorski/Documents/Z_SD/z_companies/hydronexis/HydroNexis_DesignSystem/ (readme.md, tokens/, components/). Tokeny sa przepisane do frontend/tailwind.config.js, komponenty do frontend/src/components/ui.tsx i Icon.tsx.

• Kolory z logo: Hydro Azure #2C8ABD glowny, navy #23415B druga farba, aqua #8AC4DC akcent uzywany oszczednie. Neutralne chlodne slate, nigdy cieple szarosci.
• Semantyka operacyjna jest pierwszorzedna: ok, warn, alarm, info. Odznaki statusow korzystaja z tonow (<Badge tone="ok">), nie z dowolnych klas kolorow.
• IBM Plex Mono z tabular-nums (klasa hx-data) do terminow, liczb i identyfikatorow.
• Ruch spokojny: duration-fast, ease-standard, bez odbic i sprezyn.
• Widoczny pierscien fokusu 3px. Nie usuwac, to wymog dostepnosci.
• Bez emoji w interfejsie produktu. Ikony wylacznie przez komponent Icon.

Responsywnosc

Kazdy ekran ma dzialac na telefonie, a kazdy webinar ma dac sie obsluzyc z urzadzenia mobilnego. Widok mobilny jest podstawowy, nie wersja zapasowa.

• Zadnych tabel z min-w-[...]. Taka tabela rozpycha strone i wymusza poziome przewijanie na telefonie. Uklad: lista kart do lg, tabela od lg w gore.
• Pola dotykowe minimum 44px, glowne przyciski 48-52px.
• Pola formularza 16px na telefonie (text-base sm:text-sm), inaczej iOS powieksza widok przy wejsciu w pole.
• Marginesy bezpieczne przy wycieciu ekranu: pb-safe, pt-safe.
• Weryfikacja przy kazdej zmianie interfejsu: 320px bez poziomego przewijania.

Budowanie backendu

Maven jest instalowany systemowo. Nie dodajemy mvnw ani mvnw.cmd. Ta sama konwencja obowiazuje w platformie HelpDesk i chcemy jednego sposobu budowania w obu projektach.

Wersje frontendu

Zostajemy przy React 18, Vite 6 i TypeScript 5.6, mimo ze generator proponuje nowsze. Powod: wspolna baza wzorcow z istniejaca platforma. Podniesienie wersji nastapi kiedys w obu projektach jednoczesnie, nigdy w jednym.

React Router i nawigacja

Zostajemy przy React Router 6.30.6. Znane CVE dotyczace open redirect nie dotyczy nas, bo trasy sa statyczne.

Obowiazuje za to twarda zasada bezpieczenstwa: do <Link to> oraz do navigate() nigdy nie trafia wartosc pochodzaca z URL, z odpowiedzi API ani od uzytkownika, chyba ze zostala wczesniej zwalidowana jako sciezka wzgledna zaczynajaca sie od pojedynczego ukosnika. Jesli w kodzie pojawi sie potrzeba nawigacji na podstawie danych zewnetrznych, uzyj funkcji walidujacej i odrzucajacej wszystko, co zawiera schemat, dwa ukosniki lub backslash.

Stan projektu

Sekcje aktualizowac po kazdym kolejnym kroku.

Zrobiony jest szkielet aplikacji:

• docker compose z czterema uslugami: postgres, minio, backend, frontend
• endpoint GET /api/health zwracajacy status i wersje
• Spring Security w trybie permitAll, bez JWT
• proxy /ws przygotowane w nginx, bez obslugi po stronie backendu

Zrobiony jest model danych modulu zapisow:

• migracja V1__init.sql z tabelami: app_settings, users, webinars, registrations, consents, notifications
• encje JPA, kolumny timestamptz mapowane na OffsetDateTime
• enumy jako osobne typy Java, w bazie varchar z ograniczeniem CHECK
• repozytoria Spring Data
• ograniczenia w bazie: unikalny slug webinaru, unikalna para (webinar_id, email), unikalny confirmation_token, kasowanie kaskadowe zapisow i zgod wraz z webinarem

Zrobiona jest warstwa konfiguracji i wysylka powiadomien:

• SettingsService z odczytem: baza, zmienna srodowiskowa, wartosc domyslna. Cache w pamieci uniewazniany przy zapisie, bez restartu aplikacji
• katalog kluczy w enumie SettingKey z opisem, typem i wartoscia domyslna
• klucze typu PASSWORD nigdy nie wracaja w API, zwracana jest tylko flaga valueSet
• GET/PUT /api/admin/settings, puste pole przy kluczu PASSWORD oznacza brak zmiany
• POST /api/admin/settings/test-email i test-sms, zwracaja pelny komunikat bledu
• MailService buduje JavaMailSender z biezacych ustawien przy kazdej wysylce
• szablony Thymeleaf w resources/templates/mail, wersja HTML i tekstowa
• SmsService wolajacy bramke send_sms_api.php
• NotificationService wysylajacy asynchronicznie, kazda wysylka zapisana w notifications ze statusem SENT albo FAILED i pelna trescia bledu
• IcsGenerator na ical4j, zalacznik invite.ics z METHOD:REQUEST, VTIMEZONE i stalym UID

Zrobiona jest logika webinarow i zapisow:

• /api/admin/webinars: lista z filtrem po statusie i paginacja (z liczba zapisanych), szczegoly, tworzenie, edycja, publish, cancel, lista zapisanych, eksport CSV
• /api/public/webinars/{slug}: dane dla strony zapisu, tylko PUBLISHED, reszta daje 404, bez joinUrl i bez statusu, z informacja o wolnych miejscach i trescia zgod
• /api/public/webinars/{slug}/register: zapis uczestnika
• /api/public/registrations/{token} i .../cancel: podglad wlasnego zapisu i rezygnacja
• slug generowany z tytulu, polskie znaki transliterowane, konflikty rozstrzygane sufiksem liczbowym
• migracja V2__consent_texts.sql z trescia zgod i CONSENT_VERSION

Reguly, ktorych nie wolno zepsuc przy zmianach

• Intencja administratora a dostepnosc miejsc to dwa rozne stany. Kolumna registration_open trzyma wylacznie intencje administratora i nigdy nie jest zapisywana automatycznie. Faktyczna dostepnosc liczy RegistrationAvailability z intencji, terminu, liczby miejsc i statusu. Dzieki temu po rezygnacji uczestnika zapisy wracaja do stanu ustawionego przez administratora, a nie otwieraja sie same. W API administracyjnym sa oba pola: registrationOpen (intencja) i effectivelyOpen wraz z closedReason.
• Limit miejsc: findBySlugForUpdate ma @Lock(PESSIMISTIC_WRITE). Sprawdzenie limitu i zapis sa w jednej transakcji pod blokada wiersza webinaru. Bez tego rownoczesne zadania przekraczaja limit. Chroni to RegistrationConcurrencyTest, ktory bez blokady zapisuje 40 osob na 10 miejsc.
• Brak enumeracji uczestnikow: przy probie zapisu na juz zapisany adres API zwraca te sama odpowiedz co przy sukcesie i wysyla mail already-registered. Nigdy nie wolno zwracac bledu o istniejacym adresie, bo pozwalalby sprawdzac, kto jest zapisany.
• Ponowny zapis po rezygnacji jest dozwolony, status wraca na CONFIRMED. Regula wyzej dotyczy tylko zapisow aktywnych (PENDING, CONFIRMED).
• Zgody sa dopisywane, nigdy nadpisywane. Ponowny zapis tworzy nowe rekordy consents, stare zostaja jako slad rozliczalny. Zapisywane sa wszystkie typy zgod, takze odmowa.
• joinUrl nie trafia do publicznego API. Tylko do maila potwierdzajacego i do podgladu wlasnego zapisu po tokenie, i tylko gdy zapis nie jest anulowany.
• CSV: wartosci zaczynajace sie od =, +, -, @ sa poprzedzane apostrofem, zeby Excel nie wykonal tresci z formularza.

Zrobione jest uwierzytelnianie:

• POST /api/auth/login, refresh, GET /me, POST /change-password
• filtr JWT przed UsernamePasswordAuthenticationFilter, hasla BCrypt
• /api/admin/** wymaga roli ADMIN lub MODERATOR, /api/admin/settings/** i /api/admin/users/** wylacznie ADMIN
• /api/admin/users: lista, tworzenie, edycja, dezaktywacja, reset hasla
• licznik nieudanych logowan per e-mail (prog 5) i per IP (prog 20), blokada 15 minut
• migracja V3__users_login_metadata.sql: last_login_at, must_change_password
• pierwsze konto administratora tworzone przy starcie z ADMIN_EMAIL i ADMIN_PASSWORD, a gdy hasla nie podano, losowane i wypisane raz w logu

Reguly bezpieczenstwa, ktorych nie wolno zepsuc

• JWT_SECRET wylacznie ze zmiennej srodowiskowej. Nie ma go w SettingKey ani w application.yml i nie wolno go tam dodawac. Klucz podpisujacy nie moze byc edytowalny przez panel, ktory sam jest nim chroniony. Brak sekretu albo sekret krotszy niz 32 znaki zatrzymuje start aplikacji, bez wartosci domyslnej.
• Flaga active sprawdzana przy kazdym zadaniu. JwtAuthenticationFilter wczytuje uzytkownika z bazy, a nie odtwarza go z tokenu. Dzieki temu konto dezaktywowane natychmiast traci dostep. Nie wolno tego zamieniac na odczyt roli z tokenu dla oszczednosci zapytania.
• Jeden komunikat dla wszystkich bledow logowania. Zle haslo, nieznany adres, konto nieaktywne i blokada licznikiem daja identyczna odpowiedz 401. Rozne komunikaty pozwalalyby ustalic, ktore konta istnieja i ktore sa aktywne.
• Ostatni aktywny administrator jest chroniony. Nie mozna dezaktywowac wlasnego konta ani odebrac roli ADMIN, gdy nie ma innego aktywnego administratora.
• Swagger domyslnie wylaczony, otwierany tylko przez SWAGGER_ENABLED=true.

Zrobiony jest panel administracyjny:

• logowanie, token w pamieci aplikacji i w localStorage, interceptor axios dokladajacy naglowek, przy 401 wylogowanie i powrot na strone logowania
• uklad z lewa nawigacja, nazwa marki z ustawien, pozycje menu zalezne od roli
• ekrany: lista webinarow z filtrem i paginacja, formularz webinaru, lista zapisanych z eksportem CSV, ustawienia podzielone na podstrony, zarzadzanie uzytkownikami
• TanStack Query z uniewaznianiem cache po mutacjach, style wylacznie Tailwind, wlasny komponent powiadomien

Reguly frontendu

• Daty zawsze w strefie webinaru, z jawnym oznaczeniem. Pole datetime-local nie zna stref, wiec zonedInputToIso dolicza przesuniecie strefy webinaru dla konkretnej daty, z uwzglednieniem czasu letniego. Nie wolno tego zamieniac na new Date(value).
• Sekrety w ustawieniach: pole zawsze puste, oznaczenie "ustawione" przy zapisanej wartosci, puste pole nie trafia do zadania. Po wyslaniu formularza pole sekretu jest czyszczone, bo backend nigdy nie zwraca wartosci i wypelnione pole sugerowaloby stan zapisany.
• Ukrycie pozycji menu dla MODERATORA to wygoda, nie zabezpieczenie. Regula po stronie backendu jest zrodlem prawdy, RequireAdmin tylko oszczedza uzytkownikowi bledu 403.
• Eksport CSV idzie przez axios jako blob, bo endpoint wymaga naglowka Authorization. Zwykly link go nie doklada.

Podzial ustawien na podstrony

/ustawienia to trasa nadrzedna z SettingsLayout i wlasna nawigacja, a kazdy obszar ma wlasny adres: grafika, email, sms, przypomnienia, zgody, oraz trasa indeksowa z ustawieniami aplikacji. Wczesniej wszystko bylo na jednej stronie i trzeba bylo dlugo przewijac.

• RequireAdmin siedzi na trasie nadrzednej, nie na kazdej podstronie z osobna. Dzieki temu nie da sie dodac nowej podstrony ustawien bez ochrony.
• Zakladka indeksowa ma end, inaczej NavLink podswietlalby ja na kazdej podstronie.
• Pasek zakladek przewija sie w poziomie wewnatrz wlasnego kontenera (overflow-x-auto), wiec na telefonie nie rozpycha dokumentu. Nie zamieniac na zawijanie do wielu linii.
• Wszystkie podstrony korzystaja z jednego zapytania ['settings'] przez useSettings, wiec przechodzenie miedzy zakladkami nie odpytuje serwera od nowa.
• SettingsSection ma dwa gniazda na tresc dodatkowa: intro nad polami (opis formatu) i children pod przyciskiem zapisu (blok testu wysylki). Objasnienie pod przyciskiem czytaloby sie jak poczatek nastepnej sekcji.
• DEFAULT_REMINDERS i REMINDER_TOLERANCE_MINUTES istnialy w SettingKey, ale nie byly edytowalne w panelu. Podzial dal im wlasna zakladke "Przypomnienia".

Domyslny harmonogram przypomnien

/ustawienia/przypomnienia nie pokazuje formatu zapisu. Zamiast jednego pola tekstowego EMAIL:1440:reminder,EMAIL:60:reminder jest lista przypomnien z przyciskami dodawania i usuwania, wybor odstepu z gotowych wartosci albo wlasny w dniach, godzinach lub minutach.

• Format zapisu (kanal:minuty:szablon) zostaje bez zmian, bo to kontrakt backendu i ReminderRuleService.parse go czyta. Zmienil sie wylacznie sposob pokazywania. parseDefaultReminders i formatDefaultReminders w lib/reminders.ts robia tlumaczenie w obie strony. Pozycja nieczytelna jest pomijana tak samo jak w backendzie, zeby literowka w bazie nie wysypala ekranu.
• Etykiety odstepow pochodza z describeOffset, takze te w liscie wyboru. Wpisane recznie rozjezdzaly sie z lista pozycji: "24 godziny przed" kontra "1 dzien przed" dla tej samej wartosci 1440.
• lib/reminders.ts jest wspolny dla ustawien i dla harmonogramu konkretnego webinaru, zeby oba ekrany nazywaly ten sam odstep tak samo.
• Pole template zostaje w modelu, bo backend go wymaga, ale nie jest pokazywane: istnieje dzisiaj jeden szablon reminder, a nazwa pliku nic uzytkownikowi nie mowi.

Edytor grafiki instancji

ImageEditor sluzy do wgrania logo i ikony karty przegladarki. Po wczytaniu widac caly plik, niezaleznie od proporcji i rozmiaru, a na nim ramke kadru.

• Proporcje kadru sa dowolne. Uchwyty naroznikow zmieniaja oba wymiary, uchwyty na srodkach bokow po jednym. Prop aspect jest wylacznie punktem wyjscia dla ramki startowej i przycisku "Sugerowane proporcje", nie ograniczeniem. Nie wolno przywracac wymuszania proporcji przy przeciaganiu: klienci maja logo pionowe i kwadratowe, a stale 3:1 obcinalo im znak. Blokade wlacza uzytkownik przelacznikiem "Zablokuj proporcje".
• Wynik zachowuje ksztalt zaznaczonego wycinka, a nie aspect. Rozmiar liczy outputSizeFor, gdzie outputWidth jest granica dla dluzszego boku, wiec wycinek pionowy nie urosnie w pionie bardziej niz poziomy w poziomie. Ta sama funkcja zasila etykiete pod plotnem i confirm(), zeby podgladany rozmiar nie rozjechal sie z zapisanym.
• BrandMark ogranicza tylko wysokosc logo (h-9 w-auto, object-contain). Ustawienie szerokosci sciska logo poziome i rozciaga pionowe.
• Rysowanie idzie przez requestAnimationFrame na referencjach, nie przez stan Reacta, inaczej przeciaganie gubi klatki. lockRatioRef dubluje stan przelacznika, bo w trakcie przeciagania domkniecie widzi nieaktualna wartosc stanu.

Zrobiona jest czesc publiczna:

• /w/:slug strona webinaru z formularzem zapisu, /zapis/:token wlasny zapis i rezygnacja
• osobny klient axios publicClient, bez interceptora autoryzacji
• publiczne API zwraca closedReason, brandName, a webinar odwolany i zakonczony sa pokazywane zamiast 404, zeby uczestnik z linkiem w mailu poznal powod
• GET /api/public/registrations/{token}/invite.ics do pobrania kalendarza

Reguly czesci publicznej

• Zgody nigdy nie sa zaznaczone domyslnie, takze ta wymagana. Zaznaczenie zgody za uzytkownika jest niedopuszczalne.
• Formularz jest ukrywany, nie blokowany, w kazdym stanie zamknietym.
• Komunikaty bledow z backendu pokazywane sa wiernie. Wlasny tekst pojawia sie tylko gdy odpowiedzi nie ma w ogole, np. przy braku polaczenia.
• Ekran potwierdzenia jest identyczny dla nowego i istniejacego zapisu, zgodnie z regula braku enumeracji uczestnikow.
• Zalacznik ICS doklada ten sam MimeMessageHelper, ktory zbudowal tresc. Drugi helper na tej samej wiadomosci tworzy pusty multipart/related i nadpisuje wypelniony, przez co wysylka konczy sie bledem "Empty multipart" dopiero przy zapisie do strumienia. Chroni to MailAttachmentTest, ktory wymusza writeTo.
• Sciezka linku w mailu musi odpowiadac trasie frontendu (/zapis/:token).

Harmonogram przypomnien

Tabela reminder_rules (offset w minutach przed startem, kanal, szablon, flaga wlaczenia) plus kolumna notifications.reminder_rule_id. Dwa zadania @Scheduled co minute: planowanie kolejki i wysylka.

• "Dokladnie raz" pochodzi z bazy, nie z kodu. Unikalny indeks czesciowy uq_notifications_rule_registration na (reminder_rule_id, registration_id). Sprawdzenie w kodzie tylko oszczedza zbedne proby: dwa rownolegle przebiegi moglyby przejsc je jednoczesnie. DataIntegrityViolationException przy wstawianiu jest oczekiwana i pomijana, nie jest bledem.
• Okno tolerancji (REMINDER_TOLERANCE_MINUTES, domyslnie 30) chroni przed wysylka wsteczna po restarcie. Przypomnienie spoznione bardziej nie idzie w ogole.
• Warunki sprawdzane dwa razy: przy planowaniu i tuz przed wysylka. Miedzy jednym a drugim uczestnik moze zrezygnowac, a organizator odwolac webinar. Rezygnacja dodatkowo kasuje zakolejkowane wpisy.
• SMS tylko za zgoda MARKETING_SMS i z numerem telefonu. Tresc bez znakow diakrytycznych, bo ogonki przelaczaja bramke na UCS-2, gdzie limit spada ze 160 do 70 znakow i jedna wiadomosc rozbija sie na kilka platnych czesci.
• Brak join_url nie blokuje przypomnienia. Wiadomosc idzie z informacja, ze link przyjdzie osobno, a w logu pojawia sie ostrzezenie, gdy do startu zostalo mniej niz 24 godziny.
• @EnableScheduling jest w SchedulingConfig. Bez niego metody @Scheduled sa ignorowane bez zadnego ostrzezenia i przypomnienia po prostu nie ida.

Jawna konfiguracja instancji

GET /api/public/config zwraca wylacznie brandName, publicUrl i timezone. Endpoint jest otwarty bez uwierzytelnienia, wiec wszystko, co zwraca, jest jawne dla calego internetu.

• Kazde pole jest wypisane recznie w PublicConfigController.config(). Nigdy nie wolno iterowac po SettingKey.values(), filtrowac po nazwie klucza ani po prefiksie APP_, ani zwracac calej mapy ustawien z pominieciem sekretow. Kazdy taki skrot sprawia, ze przyszle ustawienie wycieknie automatycznie, samym faktem nazwania go zgodnie ze wzorcem.
• Nowa wartosc pojawia sie w tej odpowiedzi wylacznie przez swiadome dopisanie linijki, po zastanowieniu sie, czy naprawde moze ja zobaczyc kazdy.
• Nigdy nie trafiaja tutaj dane SMTP, klucze bramki SMS, adresy kontaktowe, sekret JWT ani nic o typie PASSWORD. Pilnuje tego PublicConfigControllerTest, ktory sprawdza takze, ze kontroler nie siega po zaden klucz spoza listy.
• Panel i strony publiczne biora nazwe marki i adres publiczny z tego endpointu, nie z /admin/settings (niedostepnego dla moderatora) ani z adresu przegladarki. Wynik jest buforowany na czas sesji, a zapis ustawien uniewaznia go recznie.
• APP_PUBLIC_URL nie ma wartosci domyslnej. Adres http://localhost:8081 trafialby do linkow w mailach na produkcji i nic nie sygnalizowaloby bledu konfiguracji. Przy pustej wartosci panel pokazuje ostrzezenie i nie sklada adresu z pustego prefiksu.

Zrobione jest przygotowanie wdrozenia:

• docker-compose.prod.yml bez wystawionych portow bazy, MinIO i backendu, frontend nasluchuje wylacznie na 127.0.0.1
• .env.production.example z pustymi sekretami i komentarzem przy kazdym
• scripts/backup.sh i scripts/restore.sh, opis w README
• zajawka dla robotow komunikatorow: GET /api/preview/w/{slug} plus regula w nginx

Reguly wdrozenia i testow

• SSL i reverse proxy sa po stronie klienta. Aplikacja nasluchuje po HTTP wewnatrz sieci Dockera. Nie dodawac obslugi certyfikatow do obrazu.
• SMTP i bramka SMS konfigurowane sa wylacznie przez panel, nie przez zmienne srodowiskowe. .env.production.example celowo ich nie zawiera. Wartosci trafiaja do app_settings, dzieki czemu zmiana nie wymaga restartu ani dostepu do serwera.
• Obraz MinIO nie zawiera tar. Kopia i odtworzenie wolumenu ida przez pomocniczy kontener alpine podpiety do tego samego wolumenu. Wersja wolajaca tar w kontenerze MinIO tworzy puste archiwum bez zadnego bledu.
• Pula polaczen w testach jest mala celowo (maximum-pool-size: 20). max_connections bazy to 100, a uruchomiona aplikacja trzyma wlasna pule. Przy puli testowej rownej 50 kolejne konteksty Springa nie mialy juz z czego wziac polaczenia i przewracaly sie z bledem sorry, too many clients already. Trafialo to w losowa klase testowa, bo kolejnosc jest losowa, i wygladalo jak blad aplikacji, a nie jak wyczerpanie zasobu. Testom wspolbieznosci 20 wystarcza: sprawdzaja blokade wiersza, nie przepustowosc puli.
• Test dotykajacy app_settings musi oddac to, co zastal. Testy dzialaja na tej samej bazie co uruchomiona instancja, wiec przywracanie wartosci domyslnych zamiast zapamietanych kasuje administratorowi konfiguracje. Zdarzylo sie to realnie dwa razy: ProviderTokenTest i SettingSelectTest po kazdym mvn test zerowaly dostawce wideo i klucze LiveKit, przez co instancja przestawala miec skonfigurowane wideo. Wzorzec: zapamietac stan w @BeforeEach, oddac go w @AfterEach.
• Test sprzata TAKZE to, czego nie obejmuje kaskada. Usuniecie webinaru kasuje jego zapisy i zgody, ale nie kontakty: contacts nie ma klucza obcego do webinaru, bo kontakt zyje niezaleznie od wydarzenia. Zapis dopisuje osobe do bazy marketingowej (syncContact), wiec RegistrationConcurrencyTest zostawial 11 kontaktow na kazde uruchomienie; przez wiele przebiegow narosło ich 373 i zawyzaly licznik kursantow na stronie glownej, ktory liczy konta z potwierdzonym adresem. Test zapamietuje teraz uzyte adresy i kasuje je w @AfterEach, po liscie, a nie po wzorcu %@example.pl: wzorzec objalby dane demonstracyjne i rownolegly przebieg.
• Wyciek danych z testow sprawdza sie pomiarem, nie czytaniem kodu. Migawka licznikow tabel operacyjnych przed mvn test i po nim wskazuje winowajce w dwoch poleceniach; przegladanie testow po kolei dalo dwanascie podejrzanych, z ktorych naprawde przeciekal jeden. Testu pilnujacego tego automatycznie swiadomie NIE dodano: musialby byc ostatni w kolejnosci, ktora jest celowo losowa, i nie odroznilby wierszy z testu od danych dopisanych recznie na wspoldzielonej bazie.
• Testy nie moga uzywac deleteAll(). RegistrationConcurrencyTest musi dzialac na zatwierdzonych danych, wiec nie da sie go objac transakcja wycofywana. Zaklada wlasny webinar o losowym slugu i usuwa tylko jego. Kolejnosc testow jest losowa (junit-platform.properties), wiec zaden nie moze zalezec od danych innego.
• Zajawka dla botow nie moze ujawniac wersji roboczych. /api/preview/w/{slug} korzysta z tej samej reguly co publiczne API, wiec DRAFT daje 404.

Uwagi do kolejnych krokow

• /api/admin/** jest otwarte bez uwierzytelnienia, komentarz w SecurityConfig. Instancja nie moze byc wystawiona publicznie przed dodaniem JWT.
• Thymeleaf ma osobny silnik mailTemplateEngine z dwoma resolverami, HTML i TEXT. Domyslny resolver Springa parsuje wszystko jako HTML i na pliku .txt by sie wywrocil.