B BOL Team Tools wewnętrzne narzędzia zespołu
Narzędzie 01

BOL ADS API Dashboard

Instrukcja pierwszego uruchomienia aplikacji lokalnie albo przez Docker Compose.

Otwórz dashboard Przejdź do instrukcji
Stan obecny: aplikacja pobiera dane, uruchamia optymalizator, pokazuje rekomendacje i pozwala je zatwierdzać. Nie ma endpointu wykonującego zmiany live w bol.

1. Wymagania

  • dostęp do katalogu projektu api_bol,
  • uzupełniony plik .env,
  • Docker Desktop albo Python zgodny z projektem,
  • dostęp do kluczy Retailer API i Advertising API danego klienta.

Najprostsza opcja dla zespołu to Docker Compose. Uruchamia frontend, backend, worker i PostgreSQL jednym poleceniem.

2. Konfiguracja .env

Skopiuj plik przykładowy i uzupełnij wartości klienta:

copy .env.example .env

Wymagane zmienne dla jednego klienta:

BOL_CLIENT_ID=...
BOL_CLIENT_SECRET=...

BOL_ADVERTISING_CLIENT_ID=...
BOL_ADVERTISING_CLIENT_SECRET=...
Nie wklejaj kluczy do czatu, README, arkuszy ani frontendu. Plik .env nie powinien trafić do repozytorium.

3. Uruchomienie przez Docker Compose

Otwórz terminal w katalogu projektu i uruchom:

docker compose up --build

Po uruchomieniu:

  • GUI: http://127.0.0.1:8501
  • Backend: http://127.0.0.1:8000

Zatrzymanie aplikacji:

docker compose down

4. Uruchomienie lokalne bez Dockera

W PowerShell uruchom kolejno:

python -m pip install -r requirements.txt
alembic upgrade head
python cli.py gui:import-latest-results --client STAMAR
python -m uvicorn web.backend.main:app --host 127.0.0.1 --port 8000

W drugim oknie terminala:

streamlit run web/frontend/app.py --server.address=127.0.0.1 --server.port=8501

Jeżeli worker nie jest uruchamiany razem z aplikacją w trybie lokalnym, uruchom go w osobnym terminalu zgodnie z aktualnym README projektu.

5. Pierwszy import danych

Przed wejściem do dashboardu zaimportuj najnowszy eksport struktury i ostatni wynik optymalizatora: 

python cli.py gui:import-latest-results --client STAMAR

Import nie kopiuje całych plików XLSX do bazy. Zapisuje dane znormalizowane i ścieżki do artefaktów.

6. Role testowe

Użytkownik Rola Uprawnienia
viewer@example.localVIEWERtylko podgląd
analyst@example.localANALYSTuruchamianie analiz, REVIEWED
approver@example.localAPPROVERzatwierdzanie i odrzucanie
admin@example.localADMINkonfiguracja i pełny dostęp do MVP

Są to konta developerskie. Przy wdrożeniu zespołowym należy podłączyć firmowe logowanie OIDC.

7. Codzienny workflow

  1. Wybierz klienta Sprawdź, czy pracujesz na właściwym koncie i rynku.
  2. Odśwież dane W Jobs uruchom incremental performance refresh.
  3. Uruchom optimizer Worker pobierze job i zapisze wynik jako COMPLETED albo FAILED.
  4. Sprawdź Keyword Decisions Analyst oznacza sprawdzone rekordy jako REVIEWED.
  5. Sprawdź Search Terms Oddziel frazy chronione i niejednoznaczne od realnych kandydatów do negatywów.
  6. Zatwierdź rekomendacje Approver może zatwierdzić albo odrzucić rekord. Nadal nie powoduje to zmiany live.

8. Bezpieczeństwo

  • frontend nie ma dostępu do credentials,
  • brak endpointu live apply,
  • każda zmiana statusu trafia do audit log,
  • role są weryfikowane po stronie backendu,
  • worker wykonuje zadania z kolejki pojedynczo,
  • MUTATION_REQUESTS_SENT musi pozostać równe 0.

9. Typowe problemy

GUI nie otwiera się pod 127.0.0.1:8501

Sprawdź, czy proces Streamlit działa i czy port 8501 nie jest zajęty.

Backend zwraca błąd połączenia

Sprawdź proces Uvicorn, adres 127.0.0.1:8000 oraz ustawienia backend URL w frontendzie.

Brak danych po wejściu do GUI

Uruchom import najnowszych wyników i sprawdź, czy w katalogu output istnieje aktualny plan optymalizacji.

Job pozostaje w statusie PENDING

Najczęściej oznacza to, że worker nie działa albo nie ma połączenia z bazą.

Błąd 401 albo 403 z bol API

Sprawdź właściwy profil credentials i uprawnienia danego klienta. Nie próbuj obchodzić ograniczeń API.

Otwórz dashboard ADS Wróć do narzędzi