# eSesja Analytics API v2.0 - Struktura Projektu ## 📁 Kompletna struktura katalogów ``` esesja-api/ │ ├── config/ # Konfiguracja aplikacji │ ├── database.js # Pool połączeń MySQL z automatic reconnect │ └── logger.js # Winston logger z rotacją plików │ ├── controllers/ # Logika biznesowa (główne funkcje API) │ ├── radniController.js # 12 funkcji dla endpointów radnych │ │ ├── getAllRadni() # Lista radnych z filtrowaniem │ │ ├── getRadnyById() # Profil radnego │ │ ├── getRadnyGlosowania() # Głosowania radnego z paginacją │ │ ├── getRadnyProfilGlosowania() # Statystyki za/przeciw/wstrzymujący │ │ ├── getRadnyFrekwencja() # Obecności na posiedzeniach │ │ ├── getRadnyFrekwencjaCzas() # Frekwencja w czasie (miesięcznie) │ │ ├── getRadnyZgodnoscGrupa() # Zgodność z ugrupowaniem │ │ ├── getRadnyKoalicje() # Z kim głosuje zgodnie (Top 10) │ │ ├── getRadnyOponenci() # Z kim nie głosuje (Top 10) │ │ ├── getRadnyGlosowaniaSamotne() # Głosowania gdzie był jedynym │ │ ├── getRadnyGlosowaniaKluczowe() # Głosy decydujące │ │ └── getRadnyGlosowaniaBuntownicze() # Głosowania przeciw grupie │ │ │ ├── glosowaniaController.js # 6 funkcji dla głosowań │ │ ├── getAllGlosowania() # Lista z zaawansowanym filtrowaniem │ │ ├── getGlosowanieById() # Szczegóły głosowania │ │ ├── getGlosowanieGlosy() # Rozkład głosów (z grupowaniem) │ │ ├── getGlosowanieZalaczniki() # Załączniki PDF │ │ ├── createShareLink() # Generowanie linku do udostępnienia │ │ └── getSharedGlosowanie() # Pobieranie przez link (bez CORS) │ │ │ ├── statystykiController.js # 9 funkcji statystycznych │ │ ├── getDashboard() # Główny dashboard │ │ ├── getRankingFrekwencji() # Ranking obecności │ │ ├── getRankingBuntownikow() # Radni głosujący w mniejszości │ │ ├── getRankingLojalistow() # Radni głosujący w większości │ │ ├── getNajbardziejKontrowersyjne() # Top kontrowersyjne głosowania │ │ ├── getNajbardziejJednomyslne() # Top jednomyślne głosowania │ │ ├── getAktywnoscOrganow() # Statystyki Rada vs Komisje │ │ ├── getFrekwencjaCzas() # Frekwencja w czasie │ │ └── getTopKoalicje() # Top pary radnych │ │ │ ├── posiedzeniaController.js # 4 funkcje dla posiedzeń │ │ ├── getAllPosiedzenia() # Lista z filtrowaniem │ │ ├── getPosiedzenieById() # Szczegóły posiedzenia │ │ ├── getPosiedzeniePunkty() # Punkty porządku │ │ └── getPosiedzenieObecnosci() # Lista obecności │ │ │ └── utilsController.js # 4 funkcje pomocnicze │ ├── getUgrupowania() # Lista ugrupowań │ ├── getOrgany() # Lista organów (Rada/Komisje) │ ├── getKadencje() # Lista kadencji │ └── getSystemStats() # Podstawowe statystyki systemu │ ├── middleware/ # Middleware (zabezpieczenia, błędy) │ ├── security.js # 4 funkcje zabezpieczeń │ │ ├── checkOrigin() # Weryfikacja CORS (dozwolone domeny) │ │ ├── checkApiKey() # Weryfikacja API Key (opcjonalny) │ │ ├── blockDirectAccess() # Blokada bezpośrednich requestów │ │ └── validateInput() # Walidacja input (SQL injection) │ │ │ └── errorHandler.js # 3 funkcje obsługi błędów │ ├── notFound() # Handler 404 │ ├── errorHandler() # Główny handler błędów │ └── asyncHandler() # Wrapper dla async funkcji │ ├── routes/ # Definicje routingu │ ├── radni.js # 12 routów dla radnych │ ├── glosowania.js # 6 routów dla głosowań │ ├── statystyki.js # 9 routów dla statystyk │ ├── posiedzenia.js # 4 routy dla posiedzeń │ └── utils.js # 4 routy pomocnicze │ ├── .env.example # Przykładowa konfiguracja środowiskowa ├── .gitignore # Git ignore (node_modules, .env, logi) ├── ecosystem.config.js # Konfiguracja PM2 (cluster mode, 2 instancje) ├── package.json # Zależności npm i skrypty ├── server.js # Główny plik serwera Express ├── test-api.sh # Skrypt testowy (bash) │ └── Dokumentacja/ ├── QUICK_START.md # Szybki start (10 minut) ├── INSTALLATION.md # Pełna instrukcja instalacji ├── API_DOCUMENTATION.md # Dokumentacja endpointów └── README.md # Ogólne informacje ``` ## 📊 Statystyki projektu - **Pliki źródłowe:** 24 - **Linie kodu (szacunkowo):** ~3500 - **Endpointy API:** 35 - **Kontrolery:** 5 - **Middleware:** 2 - **Routery:** 5 ## 🔧 Główne technologie | Technologia | Wersja | Cel | |-------------|--------|-----| | Node.js | >= 18.0.0 | Runtime | | Express | 4.18.2 | Framework HTTP | | MySQL2 | 3.6.5 | Driver bazy danych | | Winston | 3.11.0 | Logowanie | | Helmet | 7.1.0 | Zabezpieczenia HTTP | | express-rate-limit | 7.1.5 | Ograniczenie requestów | | PM2 | (globalny) | Process manager | | Apache | >= 2.4 | Reverse proxy | ## 🛡️ Zabezpieczenia zaimplementowane 1. **CORS Protection** - Tylko dozwolone domeny 2. **Rate Limiting** - 100 req/15min 3. **Helmet** - Zabezpieczenia nagłówków HTTP 4. **Input Validation** - Walidacja przed SQL 5. **Parametrized Queries** - Ochrona przed SQL Injection 6. **API Key** - Opcjonalny dodatkowy klucz 7. **Error Handling** - Bezpieczne komunikaty błędów 8. **Request Logging** - Monitorowanie requestów ## 📈 Funkcjonalności API ### Moduł Radnych (12 endpointów) - Podstawowe informacje o radnych - Historia głosowań z paginacją - Analiza profilu głosowania (za/przeciw/wstrzymujący) - Statystyki frekwencji (ogólne i w czasie) - Zgodność z własnym ugrupowaniem - Analiza koalicji (z kim głosuje zgodnie) - Identyfikacja oponentów - Głosowania samotne (jedyny za/przeciw) - Głosowania kluczowe (decydujący głos) - Głosowania buntownicze (przeciw grupie) ### Moduł Głosowań (6 endpointów) - Lista z zaawansowanym filtrowaniem - Szczegółowe informacje o głosowaniu - Rozkład głosów (lista lub grupowanie) - Załączniki do głosowania - System udostępniania (generowanie linków) - Publiczny dostęp do udostępnionych głosowań ### Moduł Statystyk (9 endpointów) - Dashboard główny - Rankingi frekwencji - Ranking "buntowników" i "lojalistów" - Najbardziej kontrowersyjne głosowania - Najbardziej jednomyślne głosowania - Aktywność organów (Rada vs Komisje) - Frekwencja w czasie - Top koalicje (pary radnych) ### Moduł Posiedzeń (4 endpointy) - Lista posiedzeń z filtrowaniem - Szczegóły posiedzenia - Punkty porządku - Lista obecności ### Moduł Pomocniczy (4 endpointy) - Lista ugrupowań - Lista organów - Lista kadencji - Statystyki systemu ## 🚀 Wydajność ### Optymalizacje: - **Connection Pooling** - Reużycie połączeń MySQL (max 10) - **Query Optimization** - Indeksy i optymalne JOINy - **Compression** - Gzip dla odpowiedzi - **Cluster Mode** - PM2 w trybie cluster (2 instancje) - **Caching** - Możliwość dodania Redis - **Slow Query Logging** - Automatyczne wykrywanie wolnych zapytań ### Limity: - Max 100 requestów na 15 minut - Max 100 wyników na stronę (paginacja) - Timeout połączenia MySQL: 60s - Body limit: 10MB ## 📝 Pliki konfiguracyjne ### .env (produkcja) ```env DB_HOST=localhost DB_USER=statystyki_user DB_PASSWORD=*** DB_NAME=statystyki API_PORT=3001 NODE_ENV=production ALLOWED_ORIGINS=https://twoja-domena.pl RATE_LIMIT_WINDOW_MS=900000 RATE_LIMIT_MAX_REQUESTS=100 ``` ### ecosystem.config.js (PM2) ```javascript { instances: 2, // Cluster mode exec_mode: 'cluster', max_memory_restart: '500M', autorestart: true, watch: false } ``` ## 🔍 Monitoring i Logi ### Lokalizacje logów: - **Aplikacja:** `/var/log/esesja-api/api-YYYY-MM-DD.log` - **Błędy:** `/var/log/esesja-api/error-YYYY-MM-DD.log` - **PM2:** `/var/log/esesja-api/pm2-*.log` - **Apache:** `/var/log/apache2/esesja-api-*.log` ### Rotacja logów: - Winston: Daily rotation, 14 dni - PM2: Automatic rotation - Apache: Systemowy logrotate ## 🎯 Zalecane następne kroki 1. **Frontend** - Integracja React z API 2. **Solr** - Dodanie wyszukiwania pełnotekstowego 3. **Cache** - Redis dla często używanych danych 4. **Monitoring** - Grafana + Prometheus 5. **Backup** - Automatyczne backupy MySQL 6. **CDN** - CloudFlare dla statyki 7. **Tests** - Unit testy + Integration testy ## 📞 Wsparcie Dokumentacja: - `QUICK_START.md` - Instalacja w 10 minut - `INSTALLATION.md` - Pełna instrukcja (Ubuntu + Apache) - `API_DOCUMENTATION.md` - Wszystkie endpointy z przykładami - `README.md` - Ogólne informacje --- **Autor:** Leszek **Wersja:** 2.0.0 **Data:** 2025-12-25 **Licencja:** MIT