FAQ Tecniche ‐ Osservatorio ISTAT

FAQ Tecniche - Osservatorio ISTAT

🔧 Installazione e Setup

Q: Quale versione di Python devo usare?

A: Python 3.13.3 è la versione ufficialmente supportata e testata.

Q: Come installo le dipendenze?

A:

pip install -r requirements.txt
pip install -r requirements-dev.txt  # Per sviluppo

Q: L'installazione di pandas fallisce su Windows

A: Installa Microsoft Visual C++ Build Tools o usa conda:

conda install pandas numpy

Q: Come verifico che l'installazione sia corretta?

A: Esegui i test:

pytest tests/unit/test_config.py -v

🌐 API e Connessioni

Q: L'API ISTAT non risponde o è lenta

A:

• Verifica la connessione: python src/api/istat_api.py
• L'API ISTAT ha rate limiting (50 req/ora)
• Usa i dati cached quando possibile

Q: Come configuro PowerBI?

A:

1. Esegui: python scripts/setup_powerbi_azure.py
2. Configura le variabili d'ambiente in .env
3. Testa con: python src/api/powerbi_api.py

Q: Tableau Server non si connette

A:

• Verifica tableau_config.json
• Controlla credenziali OAuth
• Usa: python src/scrapers/tableau_scraper.py

📊 Dashboard e Dati

Q: La dashboard Streamlit non si avvia

A:

# Verifica versione Streamlit
streamlit --version  # Deve essere 1.45.0+

# Avvia in modalità debug
streamlit run dashboard/app.py --logger.level=debug

Q: I dati non si caricano nella dashboard

A:

• Controlla cache: file in data/cache/
• Verifica API ISTAT: python src/api/istat_api.py
• Fallback ai dati mock se API non disponibile

Q: Come genero dati di test?

A:

python scripts/generate_test_data.py
python scripts/test_ci.py --generate-data

🧪 Testing e CI/CD

Q: I test falliscono localmente

A:

# Test base
pytest tests/unit/ -v

# Con coverage
pytest --cov=src tests/ --cov-report=html

# Solo test veloci
pytest tests/unit/test_config.py tests/unit/test_logger.py -v

Q: Come eseguo solo i test CI?

A:

python scripts/test_ci.py --strategy quick
python scripts/test_ci.py --strategy minimal

Q: GitHub Actions fallisce

A:

• Verifica .github/workflows/test.yml
• Controlla logs CI per errori specifici
• Testa localmente prima di push

🔒 Sicurezza

Q: Come verifico la sicurezza del codice?

A:

# Security scan
bandit -r src/
safety check

# Pre-commit hooks
pre-commit run --all-files

Q: Rate limiting troppo restrittivo

A: Configura in src/utils/security_enhanced.py:

# Aumenta limiti per testing locale
ISTAT_RATE_LIMIT = 100  # Default: 50
POWERBI_RATE_LIMIT = 200  # Default: 100

📁 File e Directory

Q: Dove vengono salvati i file temporanei?

A: In temp/ con gestione automatica via TempFileManager

Q: Come pulisco i file temporanei?

A:

python scripts/cleanup_temp_files.py
python scripts/cleanup_temp_files.py --stats  # Statistiche

Q: I file convertiti dove finiscono?

A:

• Tableau: data/processed/tableau/
• PowerBI: data/processed/powerbi/
• Cache API: data/cache/

🐛 Problemi Comuni

Q: ImportError per moduli locali

A: Aggiungi il progetto al PYTHONPATH:

# Windows
set PYTHONPATH=%PYTHONPATH%;C:\path\to\Osservatorio

# Linux/Mac
export PYTHONPATH=$PYTHONPATH:/path/to/Osservatorio

Q: Errori di encoding su Windows

A: Usa UTF-8:

set PYTHONIOENCODING=utf-8
chcp 65001

Q: Memory error durante conversione

A:

• Processa file più piccoli
• Aumenta memoria virtuale
• Usa conversione batch

📧 Supporto

Per problemi non risolti:

1. Cerca negli Issues GitHub
2. Apri nuovo issue con template appropriato
3. Includi sempre: OS, Python version, stack trace completo