kuferweb dla TYPO3

kuferweb to most między branżowym systemem Kufer a publiczną stroną TYPO3

Uniwersytety ludowe, instytucje edukacyjne i akademie zarządzają swoją działalnością kursową od dekad w specjalistycznym oprogramowaniu, a w wielu domach to oprogramowanie nazywa się Kufer. Kufer odwzorowuje pełny cykl życia kursu: zarządzanie wykładowcami, planowanie kursów, rezerwacja sal, uczestnicy, rozliczenia, certyfikaty. Dla strony internetowej oznacza to standardowe zadanie: katalog kursów pielęgnowany w backoffice ma być widoczny na stronie TYPO3 w trybie dziennej aktualności, wraz z wyszukiwaniem z filtrami, widokami szczegółowymi i rejestracją online.

Grupa docelowa jest wyraźnie zarysowana: instytucje dokształcania z istniejącym mandantem Kufer, które prowadzą swoją stronę na TYPO3. Typowy jest uniwersytet ludowy z około 2500 kursami na semestr i pół tuzinem wykładowców, którzy sami pielęgnują swoje kursy w Kufer. Bez porządnej integracji katalog strony pozostaje przestarzały, podwójna pielęgnacja staje się stałym stanem, a zgłoszenia lądują w oddzielnym systemie, którego nikt nie lubi.

Typowe scenariusze zastosowania

Pierwszym scenariuszem jest automatycznie aktualizowany katalog kursów. Uniwersytet ludowy z 2500 kursami na semestr chce, żeby każde założenie kursu, każda zmiana ceny i każda zmiana wykładowcy była widoczna na stronie bez ręcznej ingerencji. Cogodzinne zadanie sync pobiera aktualne dane kursów z Kufer, zapisuje je w tabeli TYPO3 i aktualizuje wyszukiwanie. Redaktor nie pielęgnuje już kursów w backendzie TYPO3.

Drugim scenariuszem jest bezpośrednia rejestracja online. Instytucja edukacyjna z programami wsparcia chce prowadzić zainteresowanych bezpośrednio ze strony szczegółu kursu do procesu rejestracji, który w tle wywołuje API Kufer i rejestruje uczestnika w Kufer. TYPO3 służy jako frontend, Kufer pozostaje źródłem prawdy, a redakcja widzi nowy status rejestracji w swoim zwykłym interfejsie.

Trzecim scenariuszem jest wyszukiwanie z filtrami z branżowymi fasetami. Akademia z 40 dziedzinami i kilkoma tysiącami kursów chce pozwolić zainteresowanym na wyszukiwanie po kategoriach, miejscach, terminach, wykładowcach i klasach cenowych. Wyszukiwanie działa na stronie TYPO3 wobec lokalnego indeksu, który jest budowany z eksportu Kufer, wydajnie i niezależnie od dostępności aplikacji branżowej.

Czwartym scenariuszem jest wielojęzyczne wyjście kursów. Szkoła językowa z lokalizacjami w Polsce, Niemczech i Czechach pielęgnuje kursy w Kufer tylko po niemiecku i chce oferować na stronie wielojęzyczną prezentację dla zainteresowanych. Integracja przejmuje mapowanie na warianty językowe TYPO3, uzupełnia niemieckie pola Kufer o ręczne tłumaczenia w redakcji CMS i zapewnia, że zmiany w Kufer nie nadpisują lokalnych tłumaczeń.

Architektura techniczna

Integracje kuferweb w TYPO3 są prawie zawsze rozwojem niestandardowym, bo struktury danych wariują per mandant Kufer, a wersje API zmieniały się przez lata wielokrotnie. Standardowym podejściem jest smukłe rozszerzenie Extbase z trzema filarami: warstwą usługi, która enkapsuluje API Kufer, warstwą persystencji, która odzwierciedla kursy w tabelach TYPO3, i warstwą prezentacji, która udostępnia szablony Fluid dla listy, filtra i detalu.

Synchronizacja odbywa się przez zadanie TYPO3-Scheduler. Dla dużych katalogów zaleca się import delta, który przekazuje tylko kursy zmienione od ostatniego przebiegu. API Kufer zazwyczaj dostarcza znacznik czasu lub identyfikator zmiany per kurs, który jest używany do wykrywania delty.

Rejestracja online wymaga dodatkowej ścieżki API i porządnej obsługi błędów. API Kufer może przy wysokim obciążeniu odpowiadać wolno, dlatego rejestracje typowo działają asynchronicznie: formularz kładzie żądanie rejestracji w kolejce, proces worker przekazuje je do Kufer, a uczestnik otrzymuje mail potwierdzający, gdy tylko Kufer pokwituje rejestrację.

Częste problemy i rozwiązania

Pierwszym problemem jest rozbieżność pól między mandantami Kufer. Co w mandancie A nazywa się “Numer wydarzenia”, w mandancie B jest “Kodem kursu”, a w mandancie C “Numerem rezerwacji”. Rozwiązaniem jest konfigurowalne mapowanie pól w rozszerzeniu TYPO3, które jest dostosowywane per instalację i nie stoi twardo w kodzie.

Drugim problemem jest jakość danych w katalogu kursów. Redaktorki nie zawsze pielęgnują w Kufer pełne teksty, brakują krótkie opisy, obrazy nie są dołączone, grupy docelowe nie są zdefiniowane. Na stronie te luki pojawiają się jako puste pola. Rozwiązaniem jest warstwa walidacji przy synchronizacji, która oznacza niekompletne kursy w backendzie i wzywa redakcję do uzupełnienia.

Trzecim problemem jest logika anulowania i odwołań. Gdy kursy są anulowane w Kufer, mają zniknąć ze strony lub przynajmniej być oznaczone jako odwołane. Rozwiązaniem jest, aby anulowane kursy w sync wyraźnie ustawiać na status, który jest ukrywany na liście, i zaopatrywać stronę szczegółu w redirect do widoku kategorii.

Czwartym problemem jest wyświetlanie obłożenia w czasie rzeczywistym. Zainteresowani widzą na stronie “jeszcze 3 wolne miejsca”, mimo że rezerwacja w tle już przeszła na listę oczekujących. Rozwiązaniem jest, żeby wyświetlanie obłożenia nie czytać z cache sync, lecz przy każdym wywołaniu strony szczegółu wysłać mały live-call do Kufer, z agresywnym cache’owaniem (30-60 sekund) i fallbackiem na ostatnią znaną wartość cache, jeśli API nie odpowiada.

Migracja i kompatybilność wersji

Integracje kuferweb działają w TYPO3 v11, v12 i v13, o ile podłączenie API jest nowocześnie zbudowane. Najczęstszym punktem bólu nie jest wersja TYPO3, tylko wersja Kufer: gdy uniwersytet ludowy migruje swój mandant Kufer na nową wersję, okazjonalnie zmieniają się endpointy API i struktury danych, co wymaga justowania integracji TYPO3.

Gosign buduje integracje kuferweb na bazie aktualnego API Kufer, sprawdza przed rozpoczęciem projektu kompatybilność z mandantem klienta i ustawia integrację tak modułowo, żeby przyszłe upgrade API działały bez wielkoobszarowej przebudowy. Wspierane przez AI powstaje kod klienta API w godzinach zamiast dni, dzięki czemu wprowadzenie na większości projektów staje się realistyczne w dwóch do trzech sprintach.