Sojusze (Alliances)

Moduł Alliances zarządza sojuszami w grze Dark War Survival: tworzenie, usuwanie, członkostwo z hierarchią rang (R1–R5), tagi, integracja z rolami Discord i opcjonalnie z modułem Reaction Roles.

Włączanie modułu

1. Dashboard → Twój serwer → toggle Alliances
2. Kliknij Edit aby skonfigurować opcje modułu
3. Zapisz zmiany

Konfiguracja

Opcja	Typ	Domyślnie	Opis
max_alliances	number	10	Maksymalna liczba sojuszy na serwerze
max_members	number	50	Maksymalna liczba członków w sojuszu
auto_reaction_role	boolean	false	Automatyczna synchronizacja z Reaction Roles
reaction_role_index	number / null	null	Indeks panelu reaction roles do synchronizacji
management_roles	lista	[]	Role mogące zarządzać sojuszami (obok adminów)
r5_roles	lista	[]	Dodatkowe role dla liderów R5
r4_roles	lista	[]	Dodatkowe role dla oficerów R4

System rang

Ranga	Nazwa	Uprawnienia
R5	Lider	Wszystko: create (gdy R5 w jakimkolwiek sojuszu), invite, kick (wszyscy), promote, demote, transfer
R4	Oficer	Invite, kick (tylko R1–R3)
R3	—	Brak uprawnień zarządczych
R2	—	Brak uprawnień zarządczych
R1	—	Brak uprawnień zarządczych (domyślna ranga nowych członków)

System tagów

Każdy sojusz ma krótki tag (1–5 znaków alfanumerycznych):

• Użytkownik podaje: KNS
• System przechowuje: [KNS]
• Rola Discord: [KNS] Alliance Name

Tagi muszą być unikalne w obrębie serwera.

Dashboard — konfiguracja

Panel edycji Alliances w dashboardzie zawiera:

• Widok listy — karty wszystkich sojuszy z informacjami
• Widok szczegółowy — po kliknięciu sojuszu: lista członków, rangi, akcje
• Konfiguracja — max alliances, max members, management roles, auto-reaction-role

Komendy

/alliance create

Tworzy nowy sojusz.

Parametr	Wymagany	Opis
name	✅	Nazwa sojuszu (2–32 znaki: litery, cyfry, spacje, myślniki)
tag	✅	Krótki tag (1–5 znaków alfanumerycznych)
color	❌	Kolor roli hex (domyślnie #5865F2)

Wymagania: Administrator, management_roles, lub R5 w jakimkolwiek sojuszu.

Flow:

1. Walidacja nazwy i tagu
2. Sprawdzenie limitu sojuszy
3. Sprawdzenie duplikatów nazwy i tagu
4. Wstawienie rekordu do DB (z placeholder role_id)
5. Utworzenie roli Discord [TAG] Name z podanym kolorem
6. Aktualizacja rekordu z role_id
7. Dodanie twórcy jako R5
8. Nadanie roli twórcy
9. Opcjonalna synchronizacja z Reaction Roles
10. Log + odpowiedź

Rollback

Jeśli utworzenie roli Discord się nie powiedzie, rekord w bazie jest automatycznie usuwany (DB-first approach z rollback).

/alliance delete

Usuwa sojusz (tylko Administrator).

Parametr	Wymagany	Opis
name	✅	Nazwa sojuszu do usunięcia

Usuwa: rekord DB + alliance_members (CASCADE) + rolę Discord + cleanup reaction roles.

/alliance invite

Zaprasza użytkownika do sojuszu (R4/R5).

Parametr	Wymagany	Opis
member	✅	Użytkownik do zaproszenia

Dodaje z rangą R1. Użytkownik nie może być w innym sojuszu.

/alliance kick

Wyrzuca użytkownika z sojuszu (R4/R5).

Parametr	Wymagany	Opis
member	✅	Użytkownik do wyrzucenia

R4 może wyrzucić tylko R1–R3. R5 może wyrzucić wszystkich oprócz siebie.

/alliance leave

Opuszcza aktualny sojusz.

R5 nie może opuścić bez wcześniejszego /alliance transfer.

/alliance promote

Awansuje członka o 1 rangę (R5 only, max do R4).

Parametr	Wymagany	Opis
member	✅	Użytkownik do awansu

/alliance demote

Degraduje członka o 1 rangę (R5 only, min R1).

Parametr	Wymagany	Opis
member	✅	Użytkownik do degradacji

/alliance transfer

Przekazuje przywództwo innemu członkowi sojuszu (R5 only).

Parametr	Wymagany	Opis
member	✅	Nowy lider

Nowy lider → R5, stary lider → R4. Wykonywane w jednej transakcji DB.

/alliance info

Wyświetla informacje o sojuszu z listą członków pogrupowaną po rangach.

Parametr	Wymagany	Opis
name	❌	Nazwa sojuszu (domyślnie: własny sojusz użytkownika)

/alliance list

Lista wszystkich aktywnych sojuszy na serwerze z liczbą członków i liderem.

Nasłuchiwane zdarzenia

Zdarzenie	Akcja
on_member_remove	Usunięcie z sojuszu + auto-sukcesja R5
on_member_update	Integracja z Reaction Roles (dodanie/usunięcie roli sojuszu)

Auto-sukcesja (on_member_remove)

Gdy lider (R5) opuści serwer:

1. Usuwany z alliance_members
2. Jeśli pozostali członkowie → najwyższy rangą (R4 > R3 > R2 > R1, starszeństwo wg joined_at) awansowany na R5
3. Jeśli brak członków → sojusz oznaczony jako is_active = FALSE

Integracja z Reaction Roles (on_member_update)

Gdy auto_reaction_role = true i użytkownik zyska/straci rolę sojuszu przez Reaction Roles:

Dodanie roli:

• Jeśli w innym sojuszu → rola usunięta, log "rejected"
• Jeśli w tym samym sojuszu → idempotentne, ignorowane
• Jeśli nie w żadnym → dodany jako R1

Usunięcie roli:

• Usunięty z alliance_members

Logowanie

Akcje logowane przez Logs pod kategorią alliances:

• ⚔️ Alliance Created
• 🗑️ Alliance Deleted
• ➕ Member Added / Invited
• ➖ Member Removed / Kicked
• ⬆️ Member Promoted
• ⬇️ Member Demoted
• 👑 Leadership Transferred
• 🚪 Member Left / Departed Guild
• 💤 Alliance Deactivated
• 🚫 Reaction Role Rejected (multi-alliance conflict)

Baza danych

Tabela	Opis
alliances	id, guild_id, name, tag, role_id, color, is_active, created_at
alliance_members	id, alliance_id, user_id, rank, joined_at

Wskazówki

Best practices

• Ustaw max_members odpowiednio do rozmiaru serwera
• Włącz auto_reaction_role aby użytkownicy mogli sami dołączać do sojuszy
• Tagi powinny być krótkie i rozpoznawalne (np. KNS, DWS, ARC)
• Regularnie sprawdzaj czy liderzy R5 są aktywni — nieaktywni mogą blokować sojusze

ostrzeżenie

Usunięcie sojuszu jest nieodwracalne — rola Discord i wszystkie rekordy członków zostają trwale usunięte.