REC User Finder

Webapp preliminare per supportare Vaprioenergy nell'identificazione di potenziali utenti non domestici da coinvolgere nella comunita energetica.

L'app consente di:

• selezionare una delle tre aree ufficiali GSE di riferimento per Vaprioenergy;
• interrogare OpenStreetMap tramite Overpass per trovare potenziali utenze non domestiche;
• classificare negozi, uffici, PMI, servizi pubblici, scuole, sanita, sport, trasporti e altri grandi edifici non domestici;
• stimare la superficie dell'edificio quando OSM fornisce una geometria o un edificio associabile;
• escludere dalla mappa e dagli export gli enti presenti nella lista scarti configurabile;
• esportare una lista CSV/PDF per le successive verifiche manuali.

Nota: le aree GSE vengono caricate tramite il proxy backend /api/gse-area, usando il layer ArcGIS reale 2025-2027 AC_Comuni_2025/FeatureServer/0. Le tre aree configurate sono AC253E00019, AC001E01397 e AC001E01398; il lookup avviene per COD_AC, non per OBJECTID/FID.

Requisiti

• Node.js 24 LTS consigliato oppure Node.js 22 LTS;
• npm, incluso nell'installazione di Node.js;
• connessione Internet per interrogare GSE/ArcGIS, Overpass e, se abilitato, Wikidata.

Verificare le versioni installate:

node --version
npm --version

Esecuzione locale

Dalla cartella principale del progetto:

npm ci
npm test
npm start

L'output atteso e' simile a:

Server listening on http://localhost:3000

Aprire:

http://localhost:3000

Se la porta 3000 e' gia occupata, il server prova automaticamente la porta successiva e stampa l'URL corretto nel terminale. In alternativa puoi forzare una porta:

$env:PORT=3001; npm start

Test rapido

npm test

I test controllano:

• la sintassi del backend e del JavaScript frontend principale;
• il filtro delle grandi imprese e l'arricchimento dei dati;
• l'avvio reale del server e la rotta fallback della webapp.

Aggiornamento di una copia esistente

Se il progetto e' stato clonato con Git:

git pull
npm ci
npm test
npm start

Se il progetto e' stato scaricato come file ZIP, scaricare nuovamente la versione aggiornata e ripetere i comandi dalla nuova cartella.

Risoluzione dei problemi

Missing parameter name at index 1: *

La copia locale contiene una vecchia rotta wildcard non compatibile con Express 5. Aggiornare il repository con git pull, oppure scaricare nuovamente lo ZIP, quindi eseguire:

npm ci
npm test
npm start

La versione corretta usa la rotta nominata richiesta da Express 5:

app.get('/{*splat}', (req, res) => {
  res.sendFile(path.join(__dirname, 'webapp', 'index.html'));
});

npm test passa ma il server non parte

Verificare di avere aggiornato il repository. Il test di startup incluso nella versione corrente intercetta anche gli errori generati durante la registrazione delle rotte Express.

Controlli automatici

La repository usa GitHub Actions e Dependabot per tenere il codice sotto controllo:

• Node.js CI: esegue npm ci, build se presente e npm test con Node.js 22 e 24 su push e pull request verso main;
• CodeQL: analisi statica JavaScript per bug e problemi di sicurezza su push, pull request e ogni martedi mattina;
• Weekly Quality Check: esegue test e npm audit ogni lunedi mattina;
• Dependabot: apre pull request settimanali per aggiornamenti npm e GitHub Actions.

Modalita mock

Per evitare chiamate a Overpass durante demo o sviluppo:

USE_MOCK_OSM=true npm start

In PowerShell:

$env:USE_MOCK_OSM='true'; npm start

Di default l'app prova a usare Overpass reale.

Dati principali

• /api/gse-area: proxy backend per le geometrie ufficiali GSE.
• /api/osm-search: ricerca Overpass su target non domestici, spazi pubblici/collettivi e geometrie edificio.
• webapp/data/excluded-entities.json: lista configurabile di enti, insegne o operatori da scartare.
• webapp/data/enrichment/: dataset locali opzionali per arricchire nome, telefono, email e sito.
• webapp/data/cabins.json e webapp/data/areas.json: dati legacy non usati dalla UI principale.
• webapp/data/osm-mock.json: dati demo usati solo con USE_MOCK_OSM=true.

Lista scarti

Le comunita energetiche non includono grandi imprese. La definizione operativa usata dal filtro segue la soglia indicata per lo screening: oltre 250 dipendenti e oltre 50 milioni di fatturato.

OpenStreetMap di norma non pubblica dipendenti e fatturato dei singoli esercizi. Per questo l'app applica due controlli:

• se un record contiene dati espliciti di dipendenti/fatturato, li usa per escludere il target;
• altrimenti esclude i risultati che combaciano con la lista locale webapp/data/excluded-entities.json, basata su brand, insegna, network, nome, owner o operatore.

Per aggiungere un ente da scartare basta inserire una nuova regola in rules, ad esempio:

{ "label": "Nome Ente", "category": "Grande impresa", "reason": "Scarto manuale", "terms": ["nome ente"] }

Il filtro serve a rendere piu pulita la mappa e l'export, ma la qualificazione finale dell'impresa va verificata prima di contatti o valutazioni formali.

Target cercati

La ricerca Overpass include negozi, artigiani, uffici, turismo, ristorazione, aree produttive/commerciali, scuole, universita, sanita, servizi pubblici, biblioteche, centri civici, impianti sportivi, trasporti e altri edifici non domestici. I tetti grandi aumentano la priorita del target e vengono mantenuti anche quando il nome OSM e' incompleto.

Arricchimento contatti

Il backend prova ad arricchire ogni target con nome e contatti migliori:

• tag OSM (name, operator, brand, contact:*, website);
• Overture Places da file locale opzionale;
• IndicePA/enti pubblici da file locale opzionale;
• Wikidata via SPARQL per target pubblici, grandi tetti o record con nome generico.

Variabili utili:

ENABLE_CONTACT_ENRICHMENT=false   # disabilita tutto l'arricchimento
ENABLE_WIKIDATA_ENRICHMENT=false  # usa solo OSM e file locali
WIKIDATA_ENRICH_LIMIT=25          # limite richieste Wikidata per ricerca
WIKIDATA_TIMEOUT_MS=8000          # timeout singola richiesta Wikidata
ENRICHMENT_RADIUS_M=120           # raggio match locale/remoto
OVERTURE_PLACES_FILE=...          # GeoJSON Overture locale
INDICEPA_ENTITIES_FILE=...        # JSON enti pubblici locale

L'export include sia il nome usato per outreach sia i campi arricchiti e la relativa fonte.

Export

L'export usa un set fisso di colonne pensate per outreach CER, cosi resta semplice da usare e stabile tra CSV e PDF:

• cabina GSE;
• priorita e score 0-100;
• nome target migliore disponibile;
• superficie edificio stimata;
• categoria macro e sotto-categoria;
• indirizzo se disponibile;
• telefono, email e sito migliori disponibili;
• fonte del nome/arricchimento;
• motivo selezione;
• coordinate;
• livello di confidenza;
• note di verifica.

Il file CSV operativo viene nominato come longlist_CER_<COD_AC>_<data>.csv; il PDF resta un report sintetico per lettura rapida.

I dati OSM sono utili per screening preliminare, ma vanno verificati prima di qualsiasi contatto formale.