# eSesja Analytics API v2.0

REST API dla systemu analizy działalności radnych samorządowych.

## 🚀 Szybki start

### Wymagania
- Node.js >= 18.0.0
- MySQL >= 8.0
- Apache >= 2.4 (dla produkcji)

### Instalacja

1. **Sklonuj/skopiuj repozytorium**
```bash
cd /var/www/esesja-api
```

2. **Zainstaluj zależności**
```bash
npm install
```

3. **Konfiguracja**
```bash
cp .env.example .env
nano .env  # Edytuj konfigurację
```

4. **Uruchom (development)**
```bash
npm run dev
```

5. **Uruchom (production)**
```bash
npm start
# lub z PM2:
pm2 start ecosystem.config.js
```

## 📚 Dokumentacja

- **[INSTALLATION.md](./INSTALLATION.md)** - Pełna instrukcja instalacji na Ubuntu + Apache + MySQL
- **[API_DOCUMENTATION.md](./API_DOCUMENTATION.md)** - Dokumentacja wszystkich endpointów API

## 🏗️ Struktura projektu

```
esesja-api/
├── config/              # Konfiguracja (DB, Logger)
│   ├── database.js
│   └── logger.js
├── controllers/         # Logika biznesowa
│   ├── radniController.js
│   ├── glosowaniaController.js
│   ├── statystykiController.js
│   ├── posiedzeniaController.js
│   └── utilsController.js
├── middleware/          # Middleware (Security, Errors)
│   ├── security.js
│   └── errorHandler.js
├── routes/              # Definicje routingu
│   ├── radni.js
│   ├── glosowania.js
│   ├── statystyki.js
│   ├── posiedzenia.js
│   └── utils.js
├── .env.example         # Przykładowa konfiguracja
├── .gitignore
├── ecosystem.config.js  # Konfiguracja PM2
├── package.json
├── server.js            # Główny plik serwera
└── README.md
```

## 🔐 Bezpieczeństwo

API zawiera następujące zabezpieczenia:
- ✅ CORS - kontrola źródła requestów
- ✅ Helmet - zabezpieczenia nagłówków HTTP
- ✅ Rate Limiting - limit requestów
- ✅ Input Validation - walidacja danych wejściowych
- ✅ SQL Injection Protection - parametryzowane zapytania
- ✅ API Key (opcjonalny)

## 📊 Główne endpointy

### Radni
- `GET /api/radni` - Lista radnych
- `GET /api/radni/:id` - Profil radnego
- `GET /api/radni/:id/glosowania` - Głosowania radnego
- `GET /api/radni/:id/koalicje` - Z kim głosuje zgodnie
- `GET /api/radni/:id/zgodnosc-grupa` - Zgodność z ugrupowaniem

### Głosowania
- `GET /api/glosowania` - Lista głosowań
- `GET /api/glosowania/:id` - Szczegóły głosowania
- `GET /api/glosowania/:id/glosy` - Rozkład głosów
- `POST /api/glosowania/:id/udostepnij` - Utwórz link do udostępnienia

### Statystyki
- `GET /api/statystyki/dashboard` - Dashboard
- `GET /api/statystyki/ranking-frekwencji` - Ranking frekwencji
- `GET /api/statystyki/ranking-buntownikow` - Ranking buntowników
- `GET /api/statystyki/top-koalicje` - Top koalicje

### Posiedzenia
- `GET /api/posiedzenia` - Lista posiedzeń
- `GET /api/posiedzenia/:id/punkty` - Punkty porządku

### Pomocnicze
- `GET /api/utils/ugrupowania` - Lista ugrupowań
- `GET /api/utils/organy` - Lista organów
- `GET /api/utils/kadencje` - Lista kadencji

Pełna dokumentacja: [API_DOCUMENTATION.md](./API_DOCUMENTATION.md)

## 🛠️ Skrypty NPM

```bash
npm start          # Uruchom w trybie production
npm run dev        # Uruchom w trybie development (nodemon)
npm run pm2-start  # Uruchom przez PM2
npm run pm2-stop   # Zatrzymaj PM2
npm run pm2-restart # Restart PM2
npm run pm2-logs   # Pokaż logi PM2
```

## 📝 Przykład użycia

### cURL
```bash
curl https://api.twoja-domena.pl/api/radni
```

### JavaScript
```javascript
const response = await fetch('https://api.twoja-domena.pl/api/radni/1');
const data = await response.json();
console.log(data);
```

### Python
```python
import requests
response = requests.get('https://api.twoja-domena.pl/api/radni/1')
data = response.json()
```

## 🔧 Konfiguracja (.env)

```env
# Baza danych
DB_HOST=localhost
DB_USER=statystyki_user
DB_PASSWORD=your_password
DB_NAME=statystyki

# Serwer
API_PORT=3001
NODE_ENV=production

# CORS
ALLOWED_ORIGINS=https://twoja-domena.pl

# Rate Limiting
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX_REQUESTS=100
```

## 📈 Monitoring

### PM2
```bash
pm2 status            # Status procesów
pm2 logs esesja-api   # Logi na żywo
pm2 monit             # Monitor zasobów
```

### Logi aplikacji
```bash
tail -f /var/log/esesja-api/api-$(date +%Y-%m-%d).log
tail -f /var/log/esesja-api/error-$(date +%Y-%m-%d).log
```

## 🐛 Troubleshooting

### API nie startuje
```bash
pm2 logs esesja-api --err
mysql -u statystyki_user -p -e "SELECT 1"
```

### 502 Bad Gateway
```bash
pm2 restart esesja-api
sudo systemctl restart apache2
```

### CORS errors
Sprawdź `ALLOWED_ORIGINS` w pliku `.env`

## 🤝 Contributing

1. Fork projektu
2. Utwórz branch (`git checkout -b feature/AmazingFeature`)
3. Commit zmian (`git commit -m 'Add some AmazingFeature'`)
4. Push do brancha (`git push origin feature/AmazingFeature`)
5. Otwórz Pull Request

## 📄 Licencja

MIT License - zobacz plik [LICENSE](LICENSE)

## 👤 Autor

**Leszek**

## 🙏 Podziękowania

- Express.js
- MySQL
- PM2
- Apache

---

**Wersja:** 2.0.0  
**Data:** 2025-12-25