first commit
This commit is contained in:
373
bot/README.md
Normal file
373
bot/README.md
Normal file
@@ -0,0 +1,373 @@
|
||||
# 🎭 Skrzynka Impostora Bot
|
||||
|
||||
Kompleksowy bot Discord do zarządzania wiadomościami powaitalnymi z panelem web administracyjnym.
|
||||
|
||||
## 📋 Funkcjonalności
|
||||
|
||||
### ✨ Wersja 1.0
|
||||
- ✅ Integracja z Discord API (discord.js v14)
|
||||
- ✅ Slash commands (`/skrzynka`, `/skrzynka-adm`)
|
||||
- ✅ Panel web do zarządzania wiadomościami
|
||||
- ✅ Edytor z podglądem Discord Markdown
|
||||
- ✅ Autoryzacja OAuth2 Discord
|
||||
- ✅ Historia zmian wiadomości
|
||||
- ✅ Baza danych PostgreSQL
|
||||
|
||||
### 🚀 Planowane funkcjonalności
|
||||
- Wielojęzyczność
|
||||
- Szablony wiadomości
|
||||
- Harmonogramy wysyłki
|
||||
- Statystyki i analizy
|
||||
- System ról użytkowników
|
||||
|
||||
## 🛠️ Technologie
|
||||
|
||||
- **Backend**: Node.js, Express.js, discord.js
|
||||
- **Frontend**: React 18, React Router
|
||||
- **Baza danych**: PostgreSQL
|
||||
- **Autoryzacja**: JWT, OAuth2 Discord
|
||||
- **Styling**: Custom CSS (Discord-like)
|
||||
|
||||
## 📦 Instalacja
|
||||
|
||||
### Wymagania
|
||||
|
||||
**Dla Docker (Rekomendowane):**
|
||||
- Docker Desktop >= 4.0
|
||||
- Docker Compose v2
|
||||
- Konto Discord Developer
|
||||
|
||||
**Dla lokalnego uruchomienia:**
|
||||
- Node.js >= 18.0.0
|
||||
- PostgreSQL >= 12
|
||||
- npm >= 8.0.0
|
||||
- Konto Discord Developer
|
||||
|
||||
### 1. Sklonuj repozytorium
|
||||
```bash
|
||||
git clone <repository-url>
|
||||
cd skrzynka-impostora-bot
|
||||
```
|
||||
|
||||
### 2. Zainstaluj zależności
|
||||
```bash
|
||||
# Backend dependencies
|
||||
npm install
|
||||
|
||||
# Frontend dependencies
|
||||
cd frontend
|
||||
npm install
|
||||
cd ..
|
||||
```
|
||||
|
||||
### 3. Konfiguracja Discord Bot
|
||||
|
||||
1. Idź do [Discord Developer Portal](https://discord.com/developers/applications)
|
||||
2. Utwórz nową aplikację
|
||||
3. W sekcji "Bot" utwórz bota i skopiuj token
|
||||
4. W sekcji "OAuth2" dodaj redirect URI: `http://localhost:3001/auth/discord/callback`
|
||||
|
||||
### 4. Konfiguracja bazy danych
|
||||
|
||||
```bash
|
||||
# Utwórz bazę danych PostgreSQL
|
||||
createdb skrzynka_impostora
|
||||
|
||||
# Lub w psql:
|
||||
CREATE DATABASE skrzynka_impostora;
|
||||
```
|
||||
|
||||
### 5. Zmienne środowiskowe
|
||||
|
||||
Skopiuj `.env.example` do `.env` i wypełnij:
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
Edytuj `.env`:
|
||||
```env
|
||||
# Discord Bot Configuration
|
||||
DISCORD_TOKEN=your_discord_bot_token_here
|
||||
DISCORD_CLIENT_ID=your_discord_client_id_here
|
||||
DISCORD_CLIENT_SECRET=your_discord_client_secret_here
|
||||
|
||||
# Database Configuration
|
||||
DATABASE_URL=postgresql://username:password@localhost:5432/skrzynka_impostora
|
||||
DB_HOST=localhost
|
||||
DB_PORT=5432
|
||||
DB_NAME=skrzynka_impostora
|
||||
DB_USER=your_username
|
||||
DB_PASSWORD=your_password
|
||||
|
||||
# Web Panel Configuration
|
||||
JWT_SECRET=your_secure_random_string_here
|
||||
SESSION_SECRET=another_secure_random_string
|
||||
WEB_PORT=3001
|
||||
API_PORT=3000
|
||||
|
||||
# OAuth2 Configuration
|
||||
OAUTH2_REDIRECT_URI=http://localhost:3001/auth/discord/callback
|
||||
|
||||
# Environment
|
||||
NODE_ENV=development
|
||||
```
|
||||
|
||||
### 6. Inicjalizacja bazy danych
|
||||
|
||||
```bash
|
||||
# Uruchom migracje
|
||||
npm run db:migrate
|
||||
|
||||
# Opcjonalnie: dodaj przykładowe dane
|
||||
npm run db:seed
|
||||
```
|
||||
|
||||
### 7. Deploy komend Discord
|
||||
|
||||
```bash
|
||||
npm run deploy
|
||||
```
|
||||
|
||||
## 🚀 Uruchomienie
|
||||
|
||||
### 🐳 Przez Docker (Rekomendowane)
|
||||
|
||||
**Development:**
|
||||
```bash
|
||||
# Automatyczny skrypt (Linux/macOS)
|
||||
./scripts/dev-start.sh
|
||||
|
||||
# Automatyczny skrypt (Windows)
|
||||
scripts\dev-start.bat
|
||||
|
||||
# Lub ręcznie
|
||||
docker compose -f docker-compose.dev.yml up --build
|
||||
```
|
||||
|
||||
**Produkcja:**
|
||||
```bash
|
||||
# Skrypt deploy (Linux/macOS)
|
||||
./scripts/prod-deploy.sh
|
||||
|
||||
# Lub ręcznie
|
||||
docker compose up --build -d
|
||||
```
|
||||
|
||||
### 💻 Lokalnie (bez Docker)
|
||||
|
||||
### Development (równoczesne uruchomienie backend + frontend)
|
||||
```bash
|
||||
npm run dev
|
||||
```
|
||||
|
||||
### Osobno Backend i Frontend
|
||||
|
||||
**Backend:**
|
||||
```bash
|
||||
npm run dev:backend
|
||||
```
|
||||
|
||||
**Frontend:**
|
||||
```bash
|
||||
npm run dev:frontend
|
||||
```
|
||||
|
||||
### Produkcja
|
||||
```bash
|
||||
# Zbuduj frontend
|
||||
npm run build
|
||||
|
||||
# Uruchom serwer
|
||||
npm start
|
||||
```
|
||||
|
||||
## 📖 Użytkowanie
|
||||
|
||||
### 1. Zaproszenie bota na serwer
|
||||
|
||||
Użyj linku z odpowiednimi uprawnieniami:
|
||||
```
|
||||
https://discord.com/api/oauth2/authorize?client_id=YOUR_CLIENT_ID&permissions=2147484672&scope=bot%20applications.commands
|
||||
```
|
||||
|
||||
### 2. Konfiguracja kanału powitalnego
|
||||
|
||||
Na serwerze Discord użyj komendy:
|
||||
```
|
||||
/skrzynka-adm set-welcome channel:#witamy
|
||||
```
|
||||
|
||||
### 3. Zarządzanie przez panel web
|
||||
|
||||
1. Idź do `http://localhost:3001` (development)
|
||||
2. Zaloguj się przez Discord
|
||||
3. Wybierz serwer
|
||||
4. Edytuj wiadomość powitalną
|
||||
|
||||
### 4. Komendy Discord
|
||||
|
||||
**Komendy użytkownika:**
|
||||
- `/skrzynka info` - Informacje o bocie
|
||||
- `/skrzynka help` - Pomoc
|
||||
|
||||
**Komendy administracyjne:**
|
||||
- `/skrzynka-adm set-welcome <channel>` - Ustaw kanał powitalny
|
||||
- `/skrzynka-adm welcome` - Wyślij wiadomość powitalną
|
||||
- `/skrzynka-adm welcome-update` - Zaktualizuj wiadomość
|
||||
- `/skrzynka-adm status` - Status konfiguracji
|
||||
|
||||
## 🗄️ Struktura bazy danych
|
||||
|
||||
```sql
|
||||
-- Serwery Discord
|
||||
guilds (id, name, created_at, updated_at)
|
||||
|
||||
-- Kanały powitalne
|
||||
welcome_channels (id, guild_id, channel_id, channel_name, is_active, created_at, updated_at)
|
||||
|
||||
-- Wiadomości powitalne
|
||||
welcome_messages (id, guild_id, content, embed_data, message_id, is_active, created_at, updated_at)
|
||||
|
||||
-- Użytkownicy panelu
|
||||
users (id, discord_id, username, discriminator, avatar, email, role, is_active, last_login, created_at, updated_at)
|
||||
|
||||
-- Historia zmian
|
||||
message_revisions (id, message_id, content, embed_data, user_id, revision_number, created_at)
|
||||
|
||||
-- Uprawnienia użytkowników
|
||||
user_guild_permissions (id, user_id, guild_id, role, granted_by, created_at)
|
||||
```
|
||||
|
||||
## 🔧 Development
|
||||
|
||||
### Dostępne skrypty
|
||||
|
||||
```bash
|
||||
npm run start # Uruchom produkcyjnie
|
||||
npm run dev # Development (backend + frontend)
|
||||
npm run dev:backend # Tylko backend
|
||||
npm run dev:frontend # Tylko frontend
|
||||
npm run build # Zbuduj frontend
|
||||
npm run deploy # Deploy komend Discord
|
||||
npm run db:migrate # Migracja bazy
|
||||
npm run db:seed # Seed bazy danych
|
||||
|
||||
# Docker skrypty
|
||||
npm run docker:dev # Uruchom development w Docker
|
||||
npm run docker:dev:down # Zatrzymaj development Docker
|
||||
npm run docker:prod # Uruchom produkcję w Docker
|
||||
npm run docker:build # Zbuduj obraz Docker
|
||||
npm run docker:logs # Pokaż logi Docker
|
||||
```
|
||||
|
||||
### 🐳 Docker Development
|
||||
|
||||
**Dostępne usługi w trybie development:**
|
||||
- **Bot + API**: http://localhost:3000
|
||||
- **Panel Web**: http://localhost:3001
|
||||
- **PostgreSQL**: localhost:5433
|
||||
- **pgAdmin**: http://localhost:8080 (admin@skrzynka.local / admin)
|
||||
- **Redis**: localhost:6380
|
||||
|
||||
**Użyteczne komendy Docker:**
|
||||
```bash
|
||||
# Wyświetl logi konkretnej usługi
|
||||
docker compose -f docker-compose.dev.yml logs -f bot-dev
|
||||
|
||||
# Wejdź do kontenera bota
|
||||
docker compose -f docker-compose.dev.yml exec bot-dev sh
|
||||
|
||||
# Restart konkretnej usługi
|
||||
docker compose -f docker-compose.dev.yml restart bot-dev
|
||||
|
||||
# Wyczyść wszystko i rozpocznij od nowa
|
||||
docker compose -f docker-compose.dev.yml down -v
|
||||
docker compose -f docker-compose.dev.yml up --build
|
||||
```
|
||||
|
||||
### 🔄 Hot Reload
|
||||
|
||||
W trybie development Docker automatycznie:
|
||||
- Monitoruje zmiany w kodzie (volume mount)
|
||||
- Restartuje backend przy zmianach (nodemon)
|
||||
- Przebudowuje frontend na żywo
|
||||
- Automatycznie stosuje migracje bazy danych
|
||||
|
||||
### Struktura projektu
|
||||
|
||||
```
|
||||
├── backend/ # Serwer Node.js
|
||||
│ ├── index.js # Główny plik bota
|
||||
│ ├── deploy-commands.js # Deploy slash commands
|
||||
│ ├── commands/ # Slash commands
|
||||
│ ├── database/ # Zarządzanie bazą
|
||||
│ └── web/ # API serwer
|
||||
├── frontend/ # React aplikacja
|
||||
│ ├── src/
|
||||
│ │ ├── components/ # Komponenty React
|
||||
│ │ ├── pages/ # Strony aplikacji
|
||||
│ │ ├── services/ # API client
|
||||
│ │ └── hooks/ # React hooks
|
||||
│ └── public/ # Pliki statyczne
|
||||
├── database/ # Skrypty bazy danych
|
||||
├── shared/ # Współdzielone utilities
|
||||
└── .github/ # GitHub konfiguracja
|
||||
```
|
||||
|
||||
## 🔒 Bezpieczeństwo
|
||||
|
||||
- JWT tokens dla autoryzacji API
|
||||
- OAuth2 Discord dla logowania
|
||||
- Helmet.js dla zabezpieczeń HTTP
|
||||
- CORS protection
|
||||
- SQL injection protection (prepared statements)
|
||||
- Input validation (express-validator)
|
||||
|
||||
## 📊 Monitoring i Logi
|
||||
|
||||
Bot loguje ważne zdarzenia:
|
||||
- Startup/shutdown
|
||||
- Command execution
|
||||
- Database operations
|
||||
- API requests
|
||||
- Errors and warnings
|
||||
|
||||
## 🤝 Contribucje
|
||||
|
||||
1. Fork repository
|
||||
2. Utwórz feature branch (`git checkout -b feature/amazing-feature`)
|
||||
3. Commit changes (`git commit -m 'Add amazing feature'`)
|
||||
4. Push branch (`git push origin feature/amazing-feature`)
|
||||
5. Otwórz Pull Request
|
||||
|
||||
## 📄 Licencja
|
||||
|
||||
MIT License - zobacz plik `LICENSE`
|
||||
|
||||
## 🆘 Pomoc i wsparcie
|
||||
|
||||
- Sprawdź [Issues](../../issues) dla znanych problemów
|
||||
- Utwórz nowy Issue dla bugów lub feature requests
|
||||
- Przeczytaj dokumentację Discord.js: https://discord.js.org/
|
||||
|
||||
## 📈 Roadmap
|
||||
|
||||
### v1.1 - Zarządzanie
|
||||
- [ ] System ról użytkowników
|
||||
- [ ] Bulk operations
|
||||
- [ ] Advanced permissions
|
||||
|
||||
### v1.2 - Funkcjonalności
|
||||
- [ ] Message templates
|
||||
- [ ] Scheduled messages
|
||||
- [ ] Multiple languages
|
||||
|
||||
### v1.3 - Analytics
|
||||
- [ ] Usage statistics
|
||||
- [ ] User engagement metrics
|
||||
- [ ] Performance monitoring
|
||||
|
||||
---
|
||||
|
||||
Stworzono z ❤️ dla społeczności Discord
|
||||
Reference in New Issue
Block a user