System modułów (Cogs)

ArcBot jest zbudowany w architekturze modularnej. Każda funkcjonalność jest odrębnym modułem (cog), który można niezależnie włączać i wyłączać per-serwer.

Czym jest Cog?

Cog (skrót od "cogwheel" — trybik) to samodzielny moduł bota zawierający:

• Komendy slash (np. /ban, /poll)
• Nasłuchiwanie zdarzeń (np. dołączenie członka)
• Zadania cykliczne (np. sprawdzanie wygasłych ankiet)
• Konfigurację przechowywana w bazie danych

Dostępne moduły

Administracja

Moduł	Opis
Settings	Ustawienia serwera (język, kolor, dashboard users) — zawsze włączony
Moderation	Ban, kick, mute, warn, clear, setnick, role

Społeczność

Moduł	Opis
Welcome	Wiadomości powitalne i pożegnalne
Reaction Roles	Self-assign role przez przyciski, dropdown, reakcje
Suggestions	System sugestii z głosowaniem
Polls	Ankiety z przyciskami i timerem
Duel Reminder	Codzienne przypomnienia o strategii pojedynku
Schedule Events	Planowane wydarzenia z przypomnieniami

Narzędzia

Moduł	Opis
Logs	Konfigurowalne logowanie akcji
Translation	Tłumaczenie wiadomości (DeepL) i transkrypcja audio (Groq Whisper)
Message Builder	Tworzenie i wysyłanie embedów z szablonów

Dark War Survival

Moduł	Opis
Alliances	Zarządzanie sojuszami z rangami R1–R5
Presidents	System prezydenta serwera
Armory	Rotacja zbrojowni z przypisaniami do sojuszy

Włączanie i wyłączanie modułów

Przez dashboard

1. Otwórz dashboard → Twój serwer
2. W siatce modułów znajdź kafelek odpowiedniego modułu
3. Kliknij przełącznik (toggle)
4. Gotowe — zmiana jest natychmiastowa

Co się dzieje po włączeniu?

1. Konfiguracja jest zapisywana w bazie danych (enabled_cogs)
2. Bot wykrywa zmianę w ciągu 5 sekund (config polling)
3. Komendy związane z modułem są synchronizowane z Discord API
4. Komendy pojawiają się w menu slash na serwerze

Co się dzieje po wyłączeniu?

1. Moduł jest usuwany z enabled_cogs
2. Bot wykrywa zmianę w ciągu 5 sekund
3. Komendy znikają z menu slash
4. Eventy (np. on_member_join dla Welcome) przestają reagować
5. Konfiguracja modułu nie jest usuwana — po ponownym włączeniu wszystkie ustawienia są zachowane

wskazówka

Wyłączenie modułu nie kasuje jego konfiguracji. Możesz bezpiecznie wyłączyć moduł "na chwilę" i włączyć go ponownie z tymi samymi ustawieniami.

Config Polling — jak bot wykrywa zmiany?

ArcBot używa mechanizmu pollingu do synchronizacji konfiguracji:

1. Co 5 sekund bot sprawdza w bazie danych, czy zmieniła się kolumna updated_at jakiejkolwiek konfiguracji
2. Jeśli wykryje zmianę, aktualizuje cache w pamięci
3. Jeśli zmieniła się lista enabled_cogs, emituje zdarzenie on_config_update
4. To zdarzenie powoduje resynchronizację komend dla danego serwera

Dashboard → Użytkownik klika toggle
    ↓
API → Aktualizuje `enabled_cogs` + `updated_at` w DB
    ↓ (max 5 sekund)
Bot → Config polling wykrywa zmianę `updated_at`
    ↓
Bot → Aktualizuje cache, emituje `on_config_update`
    ↓
Bot → Synchronizuje komendy dla danego serwera
    ↓
Discord → Komendy pojawiają się / znikają w menu slash

Czas propagacji

Między kliknięciem toggle'a w dashboardzie a pojawieniem się komendy na serwerze mija zazwyczaj 5–10 sekund. To czas potrzebny na: zapis do DB + polling + sync z Discord API.

Moduł "Settings" — pseudo-cog

Kafelek Settings w dashboardzie jest specjalny:

• Nie ma przełącznika — jest zawsze włączony
• Nie zawiera komend slash
• Zarządza ustawieniami serwera: język, domyślny kolor embeda, lista dashboard_users

Zabezpieczenie przed wykonaniem wyłączonych komend

Nawet gdyby komenda pozostała w cache Discord po wyłączeniu modułu, dekorator @guild_cog_enabled blokuje jej wykonanie:

1. Sprawdza enabled_cogs z cache ConfigManager
2. Jeśli moduł nie jest włączony → CheckFailure z przetłumaczonym komunikatem
3. Użytkownik widzi efemeralną wiadomość "Ten moduł jest wyłączony"

Konfiguracja modułów

Każdy moduł przechowuje swoją konfigurację w kolumnie cog_settings (JSONB) tabeli guild_configs:

{
  "moderation": {
    "moderation_roles": ["123456789"],
    "warning_threshold": 3,
    "dm_on_action": true,
    "auto_delete_warnings_days": 0
  },
  "welcome": {
    "welcome": { "enabled": true, "channel_id": "...", "type": "embed", ... },
    "goodbye": { "enabled": true, "channel_id": "...", ... }
  },
  "logs": {
    "moderation": { "enabled": true, "channel_id": "...", "color": "#5865F2" },
    "welcome": { "enabled": false, "channel_id": null, "color": "#22C55E" }
  }
}

Edycja konfiguracji

1. W dashboardzie kliknij Edit na kafelku modułu
2. Zmień ustawienia
3. Pasek UnsavedBar pojawi się na dole ekranu
4. Kliknij Save aby zapisać lub Cancel aby cofnąć zmiany

ostrzeżenie

Nie zamykaj strony bez zapisania zmian! Dashboard ostrzeże Cię migającym paskiem, ale zmiany zostaną utracone.

Uprawnienia Discord wymagane przez moduły

Każdy moduł deklaruje listę uprawnień Discord, których potrzebuje do działania:

Moduł	Wymagane uprawnienia bota
Moderation	ban_members, kick_members, moderate_members, manage_messages, manage_nicknames, manage_roles
Welcome	send_messages, embed_links
Logs	send_messages, embed_links
Reaction Roles	manage_roles, send_messages, add_reactions
Suggestions	send_messages, embed_links, create_public_threads, add_reactions
Polls	send_messages, embed_links
Message Builder	send_messages, embed_links
Translation	— (wymaga klucza API DeepL)
Alliances	manage_roles
Presidents	manage_roles
Armory	manage_roles
Duel Reminder	send_messages
Schedule Events	send_messages, manage_messages

wskazówka

Jeśli bot nie ma wymaganego uprawnienia, akcja zakończy się błędem "Missing permission". Upewnij się, że rola bota ma odpowiednie uprawnienia na kanałach, na których ma działać.