Home

Informacje ogólne

Bot do obsługi loterii mikołajkowej w pewnym serwisie mikroblogowym napisany w Pythonie. Bot jest podpięty pod konto użytkownika i reaguje na wiadomości tekstowe z prostymi komendami.

Fazy loterii

1. Uczestnicy zgłaszają się do udziału.
2. Zamknięcie listy i losowanie kto komu kupuje prezent.
3. Zbieranie potwierdzeń wysyłki i odbioru.
4. Zamknięcie loterii, gdy wszyscy otrzymają swoje prezenty.

Strona ta zawiera informacje dla administratora. Jeśli jesteś uczestnikiem i szukasz regulaminu oraz instrukcji, to kliknij tu.

Technikalia

Wymagania

• Python 3.x (w momencie pisania tego tekstu projekt był testowany na wersji 3.13),
• konto użytkownika w serwisie mikroblogowym,
• serwer do hostowania (przykładowy woorkbook Ansible konfigurujący Debiana jest w katlogu infra),
• (opcjonalnie) SQLite do ręcznej edycji bazy danych w razie potrzeby,
• (opcjonalnie) Supervisor do uruchamiania bota, restartów w razie błędów itd. (przykładowy plik konfiguracyjny w infra)

Funkcje

• zbieranie danych chętnych uczestników i zapisywanie ich w bazie,
• losowanie kto komu robi prezent,
• przesłanie danych użytkownika, któremu robi się prezent,
• zbieranie potwierdzeń wysyłki/odbioru,
• powiadomienie nadawcy/odbiorcy, że prezent został odebrany/wysłany,
• przekazanie linka do śledzenia przesyłki, gdy wysyłający go poda przy potwierdzeniu wysłania.

Tryby działania

Tryb działania ustawia się parametrem mode pliku konfiguracyjnym. Dopuszczalne wartości to xmpp i www.

XMPP

Bot może łączyć się z serwerem XMPP i czekać na wiadomości z powiadomieniami od bota serwisu mikroblogowego. W tym celu wymagane jest konto na serwerze XMPP. Tryb używany w pierwszych edycjach ale jako, że jabberowy bot serwisu nie zawsze działa, wprowadzony został też tryb www

WWW

Bot pobierający co pewien ustalony interwał i parsujący stronę WWW w poszukiwaniu wiadomości. Używany od kilku lat w ostatnich edycjach. Mniej interaktywny (użytkownik musi chwilę poczekać na odpowiedź) i zależny od kodu HTML (który zmienia się stosunkowo rzadko), ale kompletnie nie zależy od tego, czy powiadomienia XMPP działają, czy nie.

Obsługa loterii

Głównym punktem wejściowym jest bp.py.

Parametry

• bot - start bota nasłuchującego na komendy,
• draw - losowanie przydziału prezentów,
• send-assignments - wysłanie przydziałów po losowaniu

Obsługę można podzielić na następujące kroki

1. Wybór trybu bota, konfiguracja odpowiednich danych dostępowych
2. Start bota z otwartą listą użytkowników: bp.py bot (np. z użyciem Supervisor)
3. Zatrzymanie bota, gdy lista uczestników będzie kompletna
4. Losowanie kto komu wysyła prezent: bp.py draw
5. Wysłanie każdemu jego przydziału: bp.py send-assignments
6. Zamknięcie listy przez wpis w pliku konfiguracyjnym (participant_list_open = false). Tym samym przełączenie bota w tryb zbierania potwierdzeń wysyłki/odbioru.
7. Ponowny start bota, ale z zamkniętą listą użytkowników: bp.py bot (jak w 2)
8. Zakończenie loterii, gdy wszystkie prezenty dotrą do adresatów.

Komendy bota

Patrz: instrukcja uczestnika na Github Pages.

Informacje dodatkowe

• Licencja: GNU Affero General Public License v3.0
• Przez jakiś czas wersjonowałem wydania, ale od tego odszedłem. Najciekawszą informacją są tagi w repozytorium, którymi oznaczyłem jaka wersja kodu została użyta w danej edycji.
• Wszystkie teksty jakimi bot odpowiada użytkownikowi znajdują się w strings.toml.