DB Weather Banner

Banner meteo in tempo reale per eventi all'aperto — night glow, raduni di mongolfiere, manifestazioni sensibili al vento. Niente API key, niente SaaS, niente abbonamenti. Il meteo segue l'evento, non il sito.

Versione: 1.0.0
Autore: Davide Bertolino
Licenza: GPL v2 or later
Richiede: WordPress 5.8+, PHP 7.4+
GitHub: dadebertolino/db-weather-banner

---

Cosa fa

Mostra un banner con le condizioni meteo attuali del luogo dell'evento e uno stato di conferma automatico basato su soglie configurabili. Le coordinate non sono un'impostazione globale: vivono sul singolo evento, perché ogni night glow si svolge in un posto diverso.

🟢 Evento confermato — Prato di Mondovì · vento 4,2 km/h, cielo sereno · aggiornato alle 18:45

I dati arrivano da Open-Meteo — gratuita, senza chiave, senza registrazione — con cache indipendente per ogni località.

🚦 Stato evento automatico

• Confermato — tutti i valori sotto la banda di attenzione
• Da monitorare — almeno un valore tra l'80% e il 100% della soglia
• A rischio — almeno un valore oltre la soglia, con i motivi indicati nel banner (es. vento, raffiche)
• Isteresi: da "a rischio" non si torna a "confermato" in un solo passo — si passa per "da monitorare", niente sfarfallio a ogni refresh della cache

Lo stato automatico è attivo solo il giorno dell'evento (multi-giorno supportato): le condizioni attuali non dicono nulla di affidabile su un evento tra una settimana. Nei giorni precedenti il banner è puramente informativo, senza semaforo.

L'organizzatore può sempre forzare Confermato o Annullato dal meta box dell'evento, ignorando i dati meteo.

📍 Coordinate per evento

• Meta box "Meteo" su ogni evento DB Event Manager: coordinate, soglie personalizzate, override stato
• Nessuna modifica a DB Event Manager richiesta: il plugin scrive meta propri (_dbwb_*) e legge da DBEM data, luogo e stato di pubblicazione
• Soglie per evento: un glow in pianura tollera più vento di uno in collina — le soglie vuote usano i default globali
• Etichetta del banner presa dal campo Luogo di DBEM (fallback: titolo evento)

🔎 Rilevamento automatico dell'evento

Lo shortcode risolve le coordinate in cascata:

1. Coordinate esplicite nello shortcode (lat/lng)
2. event_id esplicito nello shortcode
3. Evento corrente, se il banner è in una pagina evento
4. Prossimo evento in calendario (inizio più vicino; a parità di data, ID più basso) — rilevati anche gli eventi multi-giorno in corso
5. Località di default del sito (Impostazioni), come ultimo fallback — utile in home quando il calendario è vuoto

💾 Cache e fallback silenzioso

• Transient per località: dbwb_weather_{hash}, chiave dalle coordinate arrotondate a 3 decimali (~100 m) — eventi in posti diversi hanno cache indipendenti
• Copia persistente dell'ultimo dato valido per località (max 20, rotazione automatica)
• Se l'API non risponde: ultimo dato valido con nota "(dato non recente)", oppure banner nascosto (configurabile) — mai un errore in pagina

♿ Accessibilità (WCAG 2.1 AA)

• Stato comunicato via testo, non solo colore (role="status", etichette esplicite)
• Colori con contrasto AA, palette dedicata per tema scuro (prefers-color-scheme)
• prefers-reduced-motion rispettato

---

Installazione

1. Scarica lo ZIP dall'ultima release
2. Carica in Plugin → Aggiungi nuovo → Carica plugin e attiva
3. Configura i default in Impostazioni → DB Weather Banner
4. Imposta le coordinate nel meta box Meteo degli eventi
5. Inserisci lo shortcode dove vuoi il banner

Gli aggiornamenti arrivano automaticamente nel pannello WordPress via GitHub Releases.

---

Shortcode

Banner automatico (evento corrente o prossimo in calendario):

[dbwb_banner]

Evento specifico:

[dbwb_banner event_id="123"]

Località manuale, senza plugin calendario:

[dbwb_banner lat="44.389" lng="7.821" label="Prato di Mondovì"]

Parametro	Valori	Default
event_id	ID evento	auto-rilevato
lat / lng	coordinate	dall'evento
label	etichetta località	luogo DBEM
style	pill, bar, card	pill
show_wind	true / false	true
show_temp	true / false	false
show_updated	true / false	true

---

Impostazioni

Impostazioni → DB Weather Banner — solo default globali, le coordinate vivono sugli eventi:

Opzione	Default
Soglia vento (km/h)	10
Soglia raffiche (km/h)	18
Soglia precipitazioni (mm/h)	0.5
Durata cache (minuti)	15
Adapter calendario	Auto-rileva
Se l'API non risponde	Ultimo dato valido
Refresh soft in pagina	Disattivo
Località di default del sito (lat/lng/etichetta)	Vuota (off)

---

Endpoint REST

GET /wp-json/dbwb/v1/status?event_id=123

{
  "event_id": 123,
  "event_title": "Night Glow Mondovì",
  "location": "Prato di Mondovì",
  "status": "confirmed",
  "label": "Evento confermato",
  "reasons": [],
  "wind_kmh": 4.2,
  "gusts_kmh": 7.1,
  "precipitation_mm": 0,
  "temperature_c": 21.3,
  "stale": false,
  "updated": "2026-07-08T18:45"
}

Pubblico, in sola lettura, nessun dato personale. Gli eventi non pubblicati rispondono 404, identico agli inesistenti. Il carico verso Open-Meteo è limitato dalla cache per località. Il refresh soft opzionale usa questo endpoint per aggiornare il banner senza ricaricare la pagina.

---

Struttura cartelle

db-weather-banner/
├── db-weather-banner.php              # Bootstrap, costanti, hook
├── readme.txt                         # Readme formato WordPress.org
├── inc/
│   ├── class-updater.php              # DB_GitHub_Updater (componente condiviso)
│   ├── class-dbwb-api.php             # Open-Meteo + cache per località + fallback
│   ├── class-dbwb-status.php          # Soglie → stato (banda watch, isteresi)
│   ├── class-dbwb-shortcode.php       # Risoluzione evento + rendering banner
│   ├── class-dbwb-admin.php           # Pagina impostazioni
│   ├── class-dbwb-rest.php            # GET /dbwb/v1/status
│   └── adapters/
│       ├── interface-dbwb-adapter.php # Contratto adapter
│       ├── class-dbwb-adapter-dbem.php    # DB Event Manager + meta box Meteo
│       └── class-dbwb-adapter-manual.php  # Coordinate da shortcode
├── assets/
│   ├── css/
│   │   ├── db-admin-ui.css            # Design system admin (condiviso)
│   │   ├── admin.css                  # Stili specifici admin
│   │   └── frontend.css               # Stili banner (caricato solo se shortcode presente)
│   └── js/
│       └── frontend.js                # Refresh soft opzionale via REST
└── tests/
    └── run-tests.php                  # Suite standalone (75 test, senza WordPress)

L'adapter isola il plugin dal sistema eventi: aggiungere il supporto a un altro calendario (es. The Events Calendar) significa scrivere una classe che implementa DBWB_Adapter, senza toccare il resto.

---

Note tecniche

• Zero dipendenze esterne critiche: nessuna API key, nessun servizio a pagamento, nessuna libreria JS
• Open-Meteo interrogata con timezone=auto: l'orario mostrato è quello della località dell'evento
• CSS e JS frontend caricati solo nelle pagine dove lo shortcode è presente
• Impostazioni e meta box: nonce + capability check (manage_options / edit_post), input sanitizzati per tipo (whitelist per le scelte, range per le coordinate, virgola decimale italiana accettata), output escapati
• Nessun dato personale trattato: non richiede integrazione con DB Privacy Hub
• Test: php tests/run-tests.php — suite standalone con stub WordPress, nessuna installazione richiesta

---

Roadmap

• [ ] 1.1 — Blocco Gutenberg nativo oltre allo shortcode
• [ ] 1.2 — Previsione oraria per la sera dell'evento (estende lo stato automatico oltre il giorno stesso)
• [ ] 1.3 — Notifica email all'organizzatore al cambio di stato
• [ ] 1.4 — Archivio meteo storico per evento (utile per scegliere le date future)
• [ ] Adapter The Events Calendar

---

Changelog

1.0.0

• Prima release: shortcode con stili pill/bar/card, coordinate e soglie per evento via adapter DB Event Manager (meta box "Meteo") o manuale, stato automatico solo il giorno dell'evento con banda "da monitorare" e isteresi, override manuale, cache transient per località con fallback persistente, endpoint REST pubblico, refresh soft opzionale, auto-updater GitHub

---

Licenza

GPL v2 or later. Sei libero di utilizzare, modificare e distribuire questo plugin.

---

Autore

Davide Bertolino 🌐 davidebertolino.it

Software libero, senza compromessi. Se ti è utile, una segnalazione bug o una stella su GitHub sono il miglior grazie.