SkrzynkaImpostora/zalozenia.md

Założenia biznesowe dla projektu Skrzynka Impostora Bot

1. Wprowadzenie

Celem projektu jest stworzenie kompleksowego bota Discordowego „Skrzynka Impostora Bot”, który umożliwi automatyczne wysyłanie przyjaznej, konfigurowalnej wiadomości powitalnej na wskazanym kanale (#witamy) i jej bieżącą aktualizację za pomocą panelu web.

2. Cele biznesowe

• Zwiększenie angażowania użytkowników poprzez automatyczne i atrakcyjne powitania.
• Usprawnienie komunikacji i skrócenie czasu wdrożenia nowych członków.
• Łatwe zarządzanie treścią wiadomości przez administratorów bez konieczności ingerencji w kod.

3. Zakres projektu

• Wersja 1.0 (etap pierwszy):

  1. Integracja bota z Discord API.
  2. Wysyłanie domyślnej wiadomości powitalnej na wskazany kanał #witamy.
  3. Panel web do edycji treści i konfiguracji kanału powitalnego.

• Funkcjonalności docelowe:

  • Obsługa wielu wariantów wiadomości (częściowo dzielona, carouseli, linki, emoji).
  • Harmonogramy wysyłki (poranne, wieczorne przypomnienia, rotacje sezonowe).
  • Wielojęzyczność.

4. Wymagania funkcjonalne

1. Konfiguracja kanału powitalnego
   • Możliwość wskazania przez panel web ID lub nazwy kanału.
   • Walidacja uprawnień bota.
2. Edytor wiadomości
   • Pole tekstowe z podglądem Discord Markdown.
   • Dynamiczne zarządzanie linkami (URL Discord, przyciski, embedy).
3. Publikacja wiadomości
   • Usuwanie / aktualizacja poprzedniej wersji.
   • Automatyczne wysyłanie po zapisaniu zmian.
4. Historia zmian
   • Rejestracja timestamp i użytkownika, który wprowadził modyfikacje.
5. Uprawnienia użytkowników
   • Role: administrator, edytor, przeglądający.

5. Wymagania niefunkcjonalne

• Wydajność: Wysłanie i aktualizacja < 500 ms.
• Skalowalność: Obsługa wielu serwerów jednocześnie.
• Dostępność: ≥ 99,5% czasu działania.
• Bezpieczeństwo: Autoryzacja użytkowników (JWT / OAuth2), ochrona przed XSS w edytorze.
• Łatwość utrzymania: Kod: JavaScript (Node.js), bazy danych SQL (PostgreSQL/MySQL).

6. Technologia i architektura

• Backend: Node.js + Express/Koa.
• Baza danych: SQL (PostgreSQL lub MySQL).
• Frontend panelu web: React lub Vue.
• Integracja Discord API: Biblioteka discord.js.
• Hosting: Cloud (Heroku, AWS, Azure).

7. Formatowanie wiadomości powitalnej

• Wsparcie Discord Markdown (nagłówki, listy, linki, kanały, wzmianki, emoji).
• Możliwość dzielenia treści na kilka embedów, jeśli przekracza limit znaków (2000).
• Wbudowane zmienne szablonowe (np. {{user}}, {{server}}, {{date}}).

8. Panel web

• Logowanie: OAuth2 Discord.
• Dashboard:
  • Wybór serwera (lista guilds).
  • Konfiguracja kanału powitalnego.
  • Edytor treści z live preview.
  • Historia wersji i rollback.

9. Zarządzanie danymi

• Tabele: Guilds, WelcomeChannels, Messages, Users, Revisions.
• Schematy relacyjne i indeksy na kolumnach ID oraz timestamp.

10. Interfejs Slash Commands

Bot obsługuje komendy slash w Discord:

• /skrzynka – komendy dla użytkowników (lista dostępnych funkcji).
• /skrzynka-adm – komendy administracyjne.

Komendy administracyjne:

• /skrzynka-adm set welcome <channel_id> – ustawia kanał, na którym będzie wyświetlana wiadomość powitalna.
• /skrzynka-adm welcome – wysyła wiadomość powitalną na skonfigurowanym kanale.
• /skrzynka-adm welcome update – aktualizuje istniejącą wiadomość powitalną z bazy.

Zarządzanie kanałem i treścią odbywa się przez panel web po zapisaniu zmian w bazie danych.

11. Kryteria akceptacji

• Bot poprawnie wysyła i aktualizuje wiadomość powitalną.
• Panel web pozwala edytować treść i wybór kanału.
• Przekroczenie limitów Discord (2000 znaków) jest obsłużone.
• Dokumentacja API i instrukcja użytkownika.

12. Rozwój w kolejnych etapach

• Rotacje i harmonogramy: Zaplanowane wysyłki.
• Wersje językowe: Automatyczne wykrywanie preferencji.
• Analizy: Statystyki odsłon i reakcji użytkowników.