SkrzynkaImpostora/bot/README.md

# 🎭 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