iBeer

1. Wprowadzenie

iBeer to zintegrowany ekosystem do zarządzania barami piwnymi. System składa się z dwóch głównych modułów:

• BeerBase — publiczna baza piw i browarów. Każdy może przeglądać katalog piw, czytać i wystawiać recenzje, oraz sprawdzać dostępność piw w barach.
• BMS (Bar Management System) — system zarządzania barem. Dostępny dla personelu baru. Umożliwia zarządzanie kranami, telewizorami, menu i asortymentem.

2. BeerBase — Przeglądanie piw

BeerBase to publiczna baza danych piw dostępna pod adresem /beerbase/. Każdy użytkownik może przeglądać katalog bez logowania.

Wyszukiwanie

Na stronie głównej BeerBase znajduje się pole wyszukiwania. Możesz szukać po:

• Nazwie piwa
• Stylu piwa (np. IPA, Lager, Stout)

Browary można filtrować osobnym filtrem (patrz poniżej).

Filtrowanie

Dostępne filtry pozwalają zawęzić wyniki:

Sortowanie

Wyniki można sortować po: dacie dodania, nazwie (A-Z / Z-A), ABV lub IBU.

Strona piwa

Kliknięcie na piwo otwiera jego kartę (/beers/{id}) ze szczegółami:

• Zdjęcie piwa
• Dane podstawowe: ABV, IBU, styl, gatunek
• Opis piwa (w języku polskim i angielskim)
• Dane techniczne: temperatura podawania
• Składniki: chmiele, słody, drożdże, dodatki (jeśli wprowadzone)
• Recenzje użytkowników z oceną gwiazdkową (1-5)
• Dostępność w barach — w których barach piwo jest aktualnie na kranie, wraz z ceną (preferowana cena za 0.5L)

3. BeerBase — Browary

Każdy browar zarejestrowany w systemie posiada własną stronę profilu. Profil browaru jest dostępny przez kliknięcie na nazwę browaru na karcie piwa lub w wynikach wyszukiwania.

Profil browaru

Strona browaru (/breweries/{id}) zawiera:

• Logo i opis browaru
• Pełną listę piw produkowanych przez browar

4. BeerBase — Recenzje i oceny

Zalogowani użytkownicy mogą oceniać piwa w systemie BeerBase.

Jak wystawić recenzję piwa

1. Przejdź na stronę piwa, które chcesz ocenić

2. Przewiń do sekcji „Recenzje"

3. Wybierz ocenę gwiazdkową (1-5 gwiazdek)

4. Napisz komentarz (min. 10 znaków, max 1000)

5. Kliknij „Dodaj recenzję"

Przeglądanie recenzji

Recenzje wyświetlane są na stronie każdego piwa z oceną gwiazdkową i komentarzem. Na stronie baru (/bars/{slug}) widoczne są recenzje lokalu wystawione przez użytkowników.

5. BeerBase — Profil użytkownika

Rejestracja

1. Przejdź do /beerbase/

2. Kliknij „Zaloguj się" lub „Zarejestruj się"

3. Podaj adres e-mail i hasło

4. Potwierdź rejestrację

Panel użytkownika

Po zalogowaniu masz dostęp do:

• Historii swoich recenzji
• Edycji profilu (zmiana e-mail, hasło)

6. Logowanie do BMS

System BMS jest dostępny pod adresem /bms-ts/. Aby uzyskać dostęp, potrzebujesz konta z przypisanym barem.

Jak się zalogować

1. Przejdź do /auth/ lub kliknij „Login" na stronie głównej

2. Wprowadź swój e-mail i hasło

3. Po zalogowaniu zostaniesz przekierowany do strony głównej iBeer, skąd możesz przejść do BMS

7. Franczyze i Fronty

iBeer obsługuje pojedyncze bary oraz franczyzy — grupy barów należących do jednej organizacji, współdzielących jeden magazyn produktów. Zrozumienie tego modelu jest kluczowe, bo Dashboard, Magazyn i uprawnienia zachowują się inaczej zależnie od tego, gdzie aktualnie jesteś.

Model: Magazyn + Fronty

W franczyzie występują dwa rodzaje „barów":

• 📦 Magazyn (warehouse) — centralny katalog produktów grupy. Tu definiujesz listę piw, ceny bazowe, dane BeerBase, synchronizację z POS. Magazyn nie ma własnych kranów, telewizorów ani playlist.
• 🛒 Front (front) — punkt sprzedaży (np. restauracja, kawiarnia). Front ma własne krany, TV, sekcje i playlisty, ale listę produktów pożycza z Magazynu grupy. Każdy front jest podpięty do jednej kasy POS (psid).

Pojedynczy bar (bez franczyzy) to tzw. legacy bar — ma w sobie wszystko (produkty + krany + TV), działa jak klasyczny iBeer sprzed wprowadzenia franczyz.

Role w franczyzie

Przełącznik kontekstu (bar selector)

Jeśli masz dostęp do więcej niż jednego baru/frontu, w headerze Dashboardu pojawia się lista rozwijana (obok tytułu). Pozwala ona przełączyć aktualny kontekst — po wyborze, wszystkie zakładki (Magazyn, Krany, TV) pokazują dane z wybranego miejsca. CEO korzysta z niej, żeby przeskakiwać: Magazyn → Restauracja → Kawa w tej samej grupie.

Widok „Fronty" (dla CEO)

Gdy jesteś w kontekście Magazynu i masz rolę franchise_owner, w pasku zakładek (po prawej) widać 🛒 Fronty. Kliknięcie otwiera dedykowaną stronę, gdzie:

• widzisz listę frontów w grupie (PoS ID, liczba kranów, status sync, ostatnia synchronizacja),
• klikasz „+ Dodaj front" aby utworzyć nowy punkt sprzedaży — kreator pobiera listę kas z POS i pozwala wybrać psid dla nowego frontu,
• z każdej karty frontu możesz przejść do jego magazynu (kontekst natychmiast się przełącza).

Ukrywanie produktu na wybranym froncie

Produkty żyją w Magazynie, ale nie każdy produkt musi być sprzedawany na każdym froncie (np. „Kawa" nie potrzebuje piwa z magazynu, a „Restauracja" tak). W Magazynie każdy produkt ma przełącznik widoczności per front — to znaczy, że CEO może jednym kliknięciem schować piwo na „norblin_kawa", zachowując je na „norblin_resto". Operator widzi tylko produkty niezukryte na swoim froncie.

8. Dashboard BMS

Po zalogowaniu widzisz główny panel z zakładkami. Zestaw zakładek zależy od kontekstu — pojedynczy bar / magazyn franczyzy / front sprzedaży pokazują różne podzbiory (patrz sekcja 7). Poniższa tabela listuje wszystkie możliwe zakładki; kolumna „Kontekst" mówi, gdzie zakładka jest dostępna.

Nawigacja w headerze umożliwia szybki dostęp do:

• 🏠 Strona główna — powrót do strony głównej iBeer
• 🎛️ Editor — edytor szablonów TV (zaawansowany). Ukryty w kontekście Magazynu.
• ⚙️ Ustawienia — ustawienia baru
• 🚪 Wyloguj — wylogowanie z systemu

W nagłówku wyświetlana jest nazwa aktualnego baru/frontu oraz — jeśli masz dostęp do więcej niż jednego — lista rozwijana do przełączania kontekstu. Przycisk 🌙/☀️ przełącza motyw jasny/ciemny. W prawym pasku zakładek, dla CEO w kontekście Magazynu, pokazuje się dodatkowy link 🛒 Fronty (opisany w sekcji 7).

9. Magazyn

Zakładka Magazyn służy do zarządzania produktami lokalnymi dostępnymi w Twoim barze.

Dodawanie produktu

1. Kliknij przycisk „+ Dodaj Piwo"

2. Wypełnij formularz: nazwa, styl piwa, browar, ABV

3. Ustaw ceny (0.5L, 0.3L, 0.2L)

4. Opcjonalnie: wgraj ikonę/grafikę produktu

5. Zapisz produkt

Import z BeerBase

Zamiast ręcznie tworzyć produkt, możesz zaimportować piwo z bazy BeerBase:

1. Kliknij „🍺 Import z BeerBase"

2. Wyszukaj piwo po nazwie

3. Wybierz piwo z listy wyników

4. Produkt zostanie dodany do Twojego magazynu z danymi z BeerBase

Edycja produktu

Kliknij ✏️ przy produkcie, aby otworzyć modal edycji. Dostępne pola:

Dodatkowe akcje na każdym produkcie:

• 🔔 Zasugeruj zmiany — wyślij sugestię edycji do BeerBase (do zatwierdzenia przez admina)
• ⬇️ Nadpisz z BeerBase — pobierz aktualne dane piwa z bazy BeerBase
• 🗑️ — usuń produkt

10. Krany

Zakładka Krany pozwala zarządzać fizycznymi kranami w barze i przypisywać do nich piwa.

Dodawanie kranu (na razie na sztywno)

1. Kliknij „➕ Dodaj kran"

2. Podaj numer kranu i nazwę

3. Kran pojawi się na liście jako pusty

Przypisywanie piwa do kranu

1. Znajdź pusty kran na liście

2. Kliknij „Podepnij beczkę"

3. Wybierz piwo z magazynu (lub wyszukaj)

4. Potwierdź wybór

5. Piwo pojawi się na kranie i na ekranach TV (na TV w sekcji "Krany")

Aby odpiąć piwo z kranu, kliknij przycisk „✕" na karcie kranu.

Tryby pracy kranów

Każdy kran może pracować w jednym z dwóch trybów:

• MANUAL (żółta etykieta) — piwo przypisane ręcznie, nie podlega automatycznej synchronizacji POS
• AUTO (szara etykieta) — piwo synchronizowane automatycznie z systemu POS

Przełącznik „🔄 POS Sync" w nagłówku zakładki włącza/wyłącza globalną synchronizację z systemem kasowym.

Statusy kranów

Karta kranu jest oznaczona kolorami informującymi o stanie:

• Zielona ramka — piwo poprawnie połączone z BeerBase
• Czerwona ramka — piwo nie połączone z BeerBase lub pusty kran w POS
• Żółta ramka — tryb manualny z rozbieżnością danych POS

Zamiana piwa z jednego kranu na drugi

1. Na kranach musi być włączony tryb MANUAL

2. Znajdź kran z piwem, które chcesz przenieść

3. Złap za numer kranu i przesuń (cały czas trzymając za numer) na kran, z tym drugim piwem

4. Upuść.

11. Telewizory & Signage

Zarządzanie ekranami TV wyświetlającymi menu piw w barze.

Dodawanie telewizora w edytorze

1. Przejdź do edytora TV

2. Kliknij „➕ Dodaj TV" w panelu po lewej stronie

3. Wymyśl nazwę i wybierz orientację i rozmiar ekranu, zapisz

4. Przypisz playlistę do telewizora w panelu po lewej stronie

5. Upewnij się że wybrana playlista, zawiara jakąś sekcję z jakimiś produktami

6. Zapisz i otwórz link wewnętrzny/publiczny TV na urządzeniu docelowym

Signage — publiczny link

Każdy telewizor może mieć publiczny link (URL), który wyświetla menu bez logowania. Przydatne do wyświetlania na fizycznych ekranach:

• Link wewnętrzny (signage) — wymaga sieci wewnętrznej
• Link publiczny — dostępny z internetu, nie wymaga logowania

12. Sekcje & Playlisty

Sekcje

Sekcja to grupa produktów wyświetlana na TV (np. „Piwa Kraftowe", „Cidry", „Bezalkoholowe").

1. Przejdź do zakładki Sekcje

2. Kliknij „➕ Dodaj sekcję" i podaj nazwę

3. Dodaj produkty do sekcji

4. Ustaw kolejność produktów (przeciągnij i upuść)

5. Skonfiguruj widoczność elementów (tytuł, grafika, ABV, cena)

Playlisty

Playlista to kolekcja sekcji wyświetlana na jednym telewizorze.

1. Przejdź do zakładki Playlist

2. Kliknij „➕ Dodaj playlistę"

3. Przypisz sekcje do playlisty

4. Przypisz playlistę do telewizora (w zakładce Telewizory lub Edytor)

13. Edytor szablonów

Zaawansowany edytor do projektowania wyglądu ekranów TV. Dostępny w nawigacji jako 🎛️ Editor.

Interfejs edytora

Projektowanie wyglądu TV

1. Wybierz telewizor z dropdown na sidebarze

2. Kliknij „Zarządzaj sekcjami" — przeciągnij sekcje do playlisty

3. Włącz „Edytor szablonów" — pojawi się panel z kodem

4. Edytuj HTML (struktura) i CSS (wygląd) w zakładkach

5. Podgląd aktualizuje się automatycznie

6. Kliknij „🔄 Odśwież TV" aby wysłać zmiany na podłączone ekrany

Konfiguracja layoutu (TV poziome)

Dla telewizorów w orientacji poziomej (1920x1080) możesz konfigurować układ osobno dla sekcji i produktów:

Szablony i pliki CSS

Możesz tworzyć wiele szablonów HTML i plików CSS:

• ➕ — nowy plik szablonu
• ✎ — zmień nazwę pliku
• ❐ — skopiuj jako nowy plik
• 🗑 — usuń plik
• Przypisz — przypisz wybrany CSS do sekcji

14. Ustawienia baru

Strona ustawień dostępna przez ⚙️ Settings w nawigacji. Pozwala skonfigurować wygląd i integracje baru.

Główne sekcje ustawień

Konfiguracja POS

Jeśli bar korzysta z systemu kasowego (np. iZZyRest), możesz skonfigurować automatyczną synchronizację:

1. Przejdź do Ustawienia → Synchronizacja z POS

2. Wybierz typ: iZZyRest API v3

3. Podaj URL API, login i hasło

4. Kliknij „🔗 Testuj połączenie" aby sprawdzić

5. Zaznacz „Włącz automatyczną synchronizację"

6. Kliknij „💾 Zapisz konfigurację"

15. Integracja BeerBase + BMS

BeerBase i BMS współpracują ze sobą. Oto kluczowe scenariusze:

Scenariusz 1: Nowe piwo na kranie (zielony „+")

Gdy na kranie pojawia się piwo, którego nie ma jeszcze w BeerBase:

1. Przejdź na stronę baru w BeerBase (/bars/nazwa-baru)

2. Najedź kursorem na kran z nieznanym piwem — pojawi się zielony przycisk „+"

3. Kliknij „+" — system przekieruje do formularza nowego piwa

4. Piwo zostanie automatycznie utworzone w BeerBase (lub dopasowane do istniejącego, jeśli nazwa już istnieje)

5. Otwiera się modal edycji — dodaj zdjęcie, ABV, opis

6. Po zapisaniu piwo jest automatycznie przypisywane do kranu w BMS

Scenariusz 2: Import istniejącego piwa

1. W zakładce Magazyn kliknij „🍺 Import z BeerBase"

2. Wyszukaj piwo po nazwie

3. Wybierz — produkt trafi do Twojego magazynu z danymi z BeerBase

4. Przejdź do Krany i przypisz importowany produkt

Scenariusz 3: Synchronizacja barów

Dane o dostępności piw w barze (na kranach) są automatycznie widoczne na stronie baru w BeerBase. Klienci widzą, co aktualnie jest na kranie.

16. Administracja systemu

Sekcja dla administratorów systemu iBeer.

Baza danych (zakładka 💾)

Zakładka „Baza danych" w dashboardzie BMS pozwala przeglądać strukturę i dane tabel. Każdy bar ma osobny schemat w PostgreSQL (bar_norblin, bar_X itd.).

Historia zmian (zakładka 📜)

Dziennik wszystkich zmian w systemie: kto, co i kiedy zmienił. Przydatne do audytu i debugowania.

Zarządzanie wieloma barami

Administratorzy mogą zarządzać wieloma barami. Każdy bar to osobny tenant z własnym schematem bazy danych (bar_{slug}).

Panel administratora (Admin Hub)

Panel admin (/admin/) zapewnia dostęp do:

• Zarządzania użytkownikami — tworzenie, edycja, weryfikacja, przypisywanie ról (user, admin, bar_user)
• Przypisywania użytkowników do barów (afiliacje z rolami: member, owner, manager)
• Zarządzania barami — tworzenie, edycja danych, ustawienia
• Wiadomości systemowych — tworzenie ogłoszeń widocznych dla użytkowników

BeerBase Admin

W BeerBase pod /beerbase/admin/ dostępne są:

• Zarządzanie bazą piw (dodawanie, edycja, konsolidacja duplikatów)
• Zarządzanie browarami i ich weryfikacja
• Zarządzanie barami i afiliacjami użytkowników
• Przeglądanie i zatwierdzanie sugestii użytkowników (sugestie z BMS i od użytkowników)
• Import piw z arkuszy kalkulacyjnych (wieloetapowy kreator: upload → mapowanie kolumn → podgląd → import)
• Eksport danych piw do CSV
• Logi audytu (pełna historia zmian z timestampami)

17. Rozwiązywanie problemów

Typowe problemy i rozwiązania

TV nie wyświetla zmian

1. Sprawdź czy TV jest podłączony (wskaźnik w edytorze)

2. Kliknij „🔄 Odśwież TV" w edytorze

3. Jeśli nie pomaga — odśwież stronę na fizycznym TV (F5)

Dane POS nie synchronizują się

1. Sprawdź zakładkę Sync Status — czy status jest „aktywny"?

2. Kliknij „⚡ Synchronizuj teraz"

3. Sprawdź Ustawienia → Synchronizacja POS — kliknij „🔗 Testuj połączenie"

4. Jeśli test się nie udaje — sprawdź URL API i dane logowania

Ten sam produkt na dwóch kranach / TV (konflikt aliasów POS)

W magazynie obok nazwy produktu pojawiają się dwa (lub więcej) badge'y kranów z czerwoną obwódką — oznacza to, że jeden lokalny produkt jest przypisany do wielu kranów, mimo że w POS na tych kranach stoją różne piwa/cydry. Auto‑sync w takiej sytuacji wykrywa konflikt, wypisuje ostrzeżenie w logach i pomija drugi kran (nie nadpisuje przypisania), ale TV/menu wciąż pokazuje ten sam produkt na obu miejscach.

Rozwiązanie — krok po kroku

1. W Magazyn znajdź produkt z dwoma (lub więcej) czerwonymi badge'ami kranów.

2. Ustal, który z tych kranów naprawdę należy do tego produktu (porównaj z tym, co stoi fizycznie / co POS pokazuje w zakładce Sync Status). Ten kran zostaw.

3. Dla pozostałych kranów (które POS raportuje pod inną nazwą) kliknij „➕ Nowy produkt" i utwórz osobny produkt o nazwie zgodnej z POS (np. Cydr Bursztynowy Jabłko). Uzupełnij browar / styl / ceny.

4. Otwórz edycję nowo utworzonego produktu. Przewiń do sekcji Aliasy POS i kliknij „+". Z listy wybierz nazwę POS, która ma być mapowana na ten produkt — albo wpisz ją ręcznie, jeśli POS akurat jej nie zwraca (np. piwo wyczerpane).

5. Poczekaj ~20 s na kolejny cykl auto‑sync — kran przełączy się na nowy produkt, czerwone obwódki znikną, konflikt zostanie rozwiązany.

System działa wolno / wyświetla stare dane

1. Przejdź do Ustawienia → Zarządzanie pamięcią lokalną

2. Kliknij „🗑️ Wyczyść cache"

3. Odśwież stronę (Ctrl+Shift+R)

Restart serwisów Docker

Migracja bazy danych

Jeśli schemat bazy wymaga aktualizacji:

1. BeerBase: sudo docker exec beerbase_dev npx drizzle-kit push

2. Sprawdź schemat: sudo docker exec postgres_db psql -U bms -d ibeer_db -c "\dn"

FAQ — Najczęściej zadawane pytania