MASTER-PROMPT – DRUPAL MODUL „NES SPRIT“
============================================================
ZIEL
----
Baue bzw. repariere das Drupal-11-Modul „NES Sprit“ für eine
Spritpreisübersicht in Bad Neustadt. Das Modul soll vollständig
installierbar sein und auf einem normalen HostEurope Shared Webhosting
laufen.
WICHTIG:
- Drupal 11
- PHP 8.x
- HostEurope Shared Hosting
- KEIN Drush
- KEIN Composer
- Installation/Update per FTP + Drupal-Oberfläche
- Keine Root-/Server-/Docker-Annahmen
- Modul muss als ZIP ausgeliefert werden
- Nach Änderungen immer eine neue Versionsnummer vergeben
- Bestehende Funktionalität niemals unnötig entfernen
============================================================
AKTUELLER STAND
============================================================
Modulname:
NES Sprit
Aktuelle Version:
0.10.8
Drupal-Modulverzeichnis:
modules/nes-sprit/
Hauptseite:
/nes-sprit
Konfiguration:
/admin/config/media/nes-sprit
Tankstellen-Inhaltstyp:
nes_sprit_station
Label: Tankstelle
Historische Preise werden NICHT als Nodes gespeichert,
sondern in einer eigenen Datenbanktabelle:
nes_sprit_price
Wichtige Felder:
station_id
fuel_type
price
recorded_at
Dadurch bleiben Preisänderungen historisch erhalten.
============================================================
DIE 5 TANKSTELLEN
============================================================
1. BayWa Bad Neustadt
Marke: BayWa
Adresse: Donsenhaug 2, 97616 Bad Neustadt
2. JET Bad Neustadt
Marke: JET
Adresse: Schweinfurter Straße 29, 97616 Bad Neustadt
3. Shell Bad Neustadt
Marke: Shell
Adresse: Schweinfurter Straße 36, 97616 Bad Neustadt
4. tankpoint Bad Neustadt
Marke: tankpoint
Adresse: Donsenhaug 1, 97616 Bad Neustadt
5. W. Dorst Bad Neustadt
Marke: W. Dorst
Adresse: Meininger Straße 49, 97616 Bad Neustadt
============================================================
KRAFTSTOFFARTEN
============================================================
Es gibt genau diese vier Kraftstoffarten:
e10
super
super_plus
diesel
Diesel ist standardmäßig ausgewählt.
Die URL
/nes-sprit?fuel=e10
/nes-sprit?fuel=super
/nes-sprit?fuel=super_plus
/nes-sprit?fuel=diesel
muss jeweils die korrekten Preise und die passende
Preisentwicklung anzeigen.
============================================================
PREISABRUF
============================================================
Primäre strukturierte Quelle:
Tankerkönig API
Tankerkönig kann mehrere Tankstellen in einem Request abfragen
(maximal 10 Stationen).
Persönlicher API-Key wird über die Konfiguration verwaltet.
Weitere Abrufquellen/Fallbacks existieren insbesondere für:
JET
Shell
BayWa
Der Parser für Shell und BayWa wurde bereits robust gemacht.
Preisabrufe müssen weiterhin auf normalem HostEurope Shared Hosting
funktionieren.
Keine serverseitigen Spezialdienste voraussetzen.
============================================================
HAUPTSEITE /nes-sprit
============================================================
Die Hauptseite zeigt:
- kurze Preisübersicht
- aktuelle Preise der fünf Tankstellen
- günstigsten aktuellen Preis entsprechend markieren
- Preisentwicklung als ECharts-Diagramm
- Kraftstoffauswahl über URL ?fuel=
- Zeitraum-Auswahl über Buttons
Die früher vorhandene blaue Einführungsbox wurde bewusst entfernt.
Ebenso wurde die frühere zusätzliche „Tankstellen“-Sektion unten
auf der Hauptseite entfernt.
NICHT WIEDER EINFÜGEN, außer ausdrücklich gewünscht.
============================================================
KOMPAKTER PREIS-BLOCK
============================================================
Es existiert außerdem ein kompakter Block für die Spritpreise.
Eigenschaften:
- Dropdown zur Kraftstoffauswahl
- Standard: Diesel
- eine Preiszeile je Tankstelle
- „Bad Neustadt“ wird im Block aus den Tankstellennamen entfernt
- günstigster Preis bekommt einen hellgrünen Hintergrund
- Preise ändern sich dynamisch beim Wechsel des Kraftstoffs
Beispielhafte Darstellung:
Tankstelle Preis
BayWa 1,xxx €
JET 1,xxx €
Shell 1,xxx €
tankpoint 1,xxx €
W. Dorst 1,xxx €
Der günstigste Preis wird optisch grün hervorgehoben.
============================================================
ECHARTS / PREISENTWICKLUNG
============================================================
Für die Diagramme wird Apache ECharts verwendet.
Es gibt auf der Hauptseite UND auf jeder Tankstellen-Nodeseite
folgende fünf Zeitraum-Schaltflächen:
Stunden | Tage | Woche | Monat | Jahr
Aktuelle Zeiträume:
Stunden = letzte 24 Stunden
Tage = letzte 3 Tage
Woche = letzte 7 Tage
Monat = letzte 30 Tage
Jahr = letzte 365 Tage
Die Darstellung der Zeitachse muss sich abhängig vom gewählten
Zeitraum dynamisch anpassen.
============================================================
ZEITACHSEN
============================================================
Stunden:
Darstellung ungefähr:
14:00 17:00 20:00 23:00
Format:
HH:MM
höchste Beschriftungsdichte
Tage:
Format:
DD.MM. HH:MM
Woche:
Format:
Wochentag + Datum
beispielsweise:
Mo 14.09.
Di 15.09.
Mi 16.09.
Monat:
Format:
DD.MM.
deutlich verdichtete Beschriftung
Jahr:
Format:
Monat + Jahr
beispielsweise:
Okt 2025
Dez 2025
Feb 2026
Apr 2026
...
stärkste Verdichtung
Die Achse muss nicht jeden einzelnen Datenpunkt beschriften.
ECharts soll abhängig vom Zeitraum eine sinnvolle Anzahl
von Beschriftungen anzeigen.
hideOverlap verwenden, damit sich Beschriftungen nicht überlagern.
============================================================
DIAGRAMM-DARSTELLUNG
============================================================
Die Darstellung darf ebenfalls abhängig vom Zeitraum angepasst werden.
Grundidee:
Stunden:
größte Punkte
stärkste Linien
Tage:
etwas kleiner
Woche:
nochmals kleiner
Monat:
deutlich kompakter
Jahr:
kleinste/kompakteste Darstellung
Die Datenpunkte selbst dürfen NICHT gelöscht werden.
Es wird lediglich die Darstellung verdichtet.
============================================================
HAUPTSEITE – DIAGRAMM
============================================================
Das Dashboard-Diagramm zeigt die Preisentwicklung der Tankstellen
für den aktuell gewählten Kraftstoff.
Die Tankstellen werden als einzelne Linien dargestellt.
Aktuell ausgewählter Kraftstoff kommt aus:
?fuel=
Beispiel:
/nes-sprit?fuel=diesel
zeigt ausschließlich die Diesel-Preisentwicklung.
Die serverseitige Auswahl und die JavaScript-Auswahl müssen
konsistent sein.
Wichtig:
Es gab bereits einen Fehler, bei dem
?fuel=e10
?fuel=super
?fuel=super_plus
?fuel=diesel
fälschlicherweise dieselben Preise zeigten.
Dieser Fehler wurde in Version 0.10.6 behoben.
NICHT WIEDER EINBAUEN.
============================================================
TANKSTELLEN-NODE
============================================================
Auf der Node-Seite einer Tankstelle:
Aktuelle Spritpreise
danach:
Preisentwicklung – [Tankstellenname]
Das Diagramm zeigt alle vier Kraftstoffarten:
E10
Super
Super Plus
Diesel
Danach bleibt die vorhandene Tabelle:
Preisentwicklung / letzte Abrufe
bestehen.
Auch auf der Node-Seite gibt es:
Stunden | Tage | Woche | Monat | Jahr
mit derselben dynamischen Zeitachsenlogik wie auf dem Dashboard.
============================================================
JAVASCRIPT
============================================================
Die zentrale Datei ist:
js/nes-sprit.js
Darin existiert bereits sinngemäß:
RANGES = {
hours: 24h,
days: 3 Tage,
week: 7 Tage,
month: 30 Tage,
year: 365 Tage
}
Außerdem gibt es Funktionen für:
rangeSince()
filterPoints()
addRangeHandlers()
getTimeAxis()
getSeriesStyle()
getChartGrid()
Diese Logik soll bei Weiterentwicklung erhalten bleiben.
============================================================
CSS
============================================================
Aktuelle Diagrammklassen:
.nes-sprit-chart
.nes-sprit-station-chart
.nes-sprit-chart-range
Preis-Hervorhebung:
.nes-sprit-cheapest-text
Günstigster Preis im Block:
.nes-sprit-fuel-price.nes-sprit-cheapest-text
Der günstigste Preis erhält einen hellgrünen Hintergrund.
============================================================
DRUPAL CACHE
============================================================
Die Dashboard-Ausgabe berücksichtigt:
url.query_args:fuel
und hat aktuell:
max-age 0
Die Kraftstoffauswahl darf nicht durch Drupal-Caching
falsch dargestellt werden.
Wenn JavaScript geändert wird:
Library-Version erhöhen, damit Browser/Drupal das neue JS laden.
Beispiel:
0.10.8
0.10.9
0.10.10
...
============================================================
WICHTIGE FRÜHERE FEHLER
============================================================
Nicht erneut verursachen:
1. Drupal-11-Config-Schema-Fehler
Bei:
field_nes_source_type
muss das Schema die Allowed Values als einfache
value => label-Zuordnung definieren.
NICHT verschachtelte Arrays verwenden.
2. Constructor-DI-Fehler
PriceFetcher darf nicht versehentlich einen Logger dort erwarten,
wo die DB-Verbindung injiziert wird.
3. Fuel Query Bug
?fuel= muss tatsächlich die passende Kraftstoffart laden.
4. Veraltetes JavaScript
Nach JS-Änderungen Library-Version erhöhen.
5. Keine unnötige Entfernung bestehender Funktionalität.
============================================================
INSTALLATION / UPDATE
============================================================
Da HostEurope Shared Hosting verwendet wird:
1. ZIP entpacken
2. Ordner
nes_sprit
nach
modules/
hochladen
3. Bei Update den vorhandenen Modulordner ersetzen,
sofern keine individuellen Änderungen darin vorgenommen wurden.
4. Drupal-Cache leeren.
KEIN:
drush cr
voraussetzen.
Keine Composer-Befehle voraussetzen.
============================================================
ENTWICKLUNGSREGELN
============================================================
Wenn dieses Projekt später weiterentwickelt wird:
- Immer zuerst den vorhandenen Stand analysieren.
- Keine komplette Neuentwicklung, wenn nur eine Funktion geändert wird.
- Bestehende Datenbankstruktur erhalten.
- Historische Preise niemals unnötig löschen.
- Bestehende URLs erhalten.
- Bestehende Konfigurationspfade erhalten.
- Bestehende Node-Funktionalität erhalten.
- Drupal-11-kompatiblen Code schreiben.
- Dependency Injection sauber verwenden.
- Twig escapen.
- SQL über Drupal Database API.
- JavaScript Drupal.behaviors + once verwenden.
- Keine externen Abhängigkeiten einbauen, die Composer benötigen,
sofern nicht ausdrücklich vereinbart.
- ECharts weiterhin verwenden.
- Keine Servertechnik voraussetzen, die HostEurope Shared Hosting
nicht bereitstellt.
============================================================
VERSIONIERUNG
============================================================
Aktueller Ausgangspunkt:
NES Sprit 0.10.8
Bei der nächsten Änderung:
0.10.9
Danach:
0.10.10
usw.
Jede neue Version muss in mindestens den relevanten Dateien
aktualisiert werden:
nes_sprit.info.yml
nes_sprit.libraries.yml
Wenn eine ZIP-Version erzeugt wird:
nes_sprit-X.Y.Z.zip
============================================================
AUSLIEFERUNG
============================================================
Wenn ich sage:
„Baue die nächste Version“
dann:
1. aktuellen Stand verwenden
2. gewünschte Änderung umsetzen
3. Syntax/Struktur prüfen
4. ZIP erzeugen
5. Versionsnummer erhöhen
6. kurze Änderungsübersicht geben
7. direkten Download-Link zur ZIP bereitstellen
8. kurze Update-Anleitung geben
Keine unnötig langen Erklärungen.
============================================================
WICHTIGSTER GRUNDSATZ
============================================================
NES Sprit ist inzwischen ein funktionierendes Drupal-11-Modul.
Nicht wieder bei null anfangen.
Der bekannte stabile Stand ist:
Version 0.10.8
mit:
- 5 Tankstellen
- 4 Kraftstoffarten
- Tankerkönig API
- Fallback-Abrufquellen
- aktueller Preisübersicht
- günstigster Preis Hervorhebung
- Preis-Historie
- Dashboard-Diagramm
- Tankstellen-Diagramm
- Stunden
- Tage
- Woche
- Monat
- Jahr
- dynamischer ECharts-Zeitachse
- dynamischer Punkt-/Liniengröße
- Kraftstoffauswahl per URL
- kompakter Spritpreis-Block
- Drupal-11-Kompatibilität
- HostEurope-Shared-Hosting-Kompatibilität
Wenn ich diesen Prompt später wieder sende, sollst du diesen
Stand als verbindliche technische Ausgangsbasis betrachten und
die Arbeit exakt dort fortsetzen.