initial commit

1 files changed, 119 insertions, 0 deletions

diff --git a/Readme.md b/Readme.md
new file mode 100644
index 0000000..ab4a9c1
--- /dev/null
+++ b/Readme.md
@@ -0,0 +1,119 @@
+# Punktestand - zeigt den Punktestand für die Klassen eines Jahrgangs an
+
+Dieses Repository enthält den Quellcode und zusätzliche Werkzeuge, um eine Webseite, die den Punktestand von Klassen innerhalb eines Jahrgangs anzeigt, zu betreiben.
+
+```
+.
+├── config.php - Konfigurationsdatei
+├── config.php.sample - Beispiel Konfigurationsdatei
+├── dist
+│   └── ...
+├── index.css - CSS Code der das Aussehen der HTML-Elemente bestimmt
+├── index.js - Javascript Code der zum Zeichnen des Diagramms und zum Erstellen der Ereignisliste
+├── index.php - Einstiegspunkt der Webseite
+├── lade_daten.php - PHP-Datei die die lade_daten Funktion definiert
+├── Makefile - Makefile um alle Dateien an die richtige Stelle zu kopieren
+├── node_modules - Ordner in dem npm weitere Javascript Dateien ablegt
+│   └── ...
+├── package.json - npm Definition der Webseite
+├── package-lock.json - Versionen der verwendeten externen Javascript Dateien
+├── Readme.md - Diese Datei
+├── scripts - Hilfsprogramme
+│   └── erzeuge_jahrgang.py - 
+└── sql - SQL Dateien
+    ├── dummydaten.sql - Enthält einige Dummy Daten um die Webseite zu testen
+    └── init.sql - Enthält die Tabellen Definitionen
+```
+
+## Webseite
+
+Die Webseite verwendet PHP um bei einem Aufruf die passenden Daten auf dem Server aus der Datenbank zu laden und in die Webseite einzubetten. 
+Anschließend werden die Daten durch Javascript mit Hilfe der Bibliothek [chart.js](https://www.chartjs.org/) graphisch als Balkendiagramm angezeigt.
+Zusätzlich enthält die Webseite eine Liste aller Ereignisse die zu dem aktuellen Punktestand geführt haben.
+
+## Datenbank
+
+Die Webseite unterstützt theoretisch alle SQL kompatiblen Datenbanken die über den generischen PHP Datenbankenadapter [PDO](https://www.php.net/manual/en/book.pdo.php) verwendbar sind.
+Getestet ist allerdings nur [sqlite](https://sqlite.org/index.html) als Datenbank.
+
+### Schema
+
+Die Datenbank besteht aus zwei Tabellen:
+
+```sql
+CREATE TABLE Klasse (
+  Schuljahr TEXT,
+  Jahrgang INTEGER,
+  Bezeichner TEXT,
+  Farbe TEXT,
+  PRIMARY KEY(Jahrgang, Bezeichner, Schuljahr)
+);
+
+CREATE TABLE Ereignis (
+  Id INTEGER,
+  Schuljahr TEXT NOT NULL,
+  Jahrgang INTEGER NOT NULL,
+  Bezeichner TEXT NOT NULL,
+  Datum DATETIME,
+  Delta INTEGER NOT NULL,
+  Beschreibung TEXT,
+  PRIMARY KEY(Id AUTOINCREMENT),
+  FOREIGN KEY(Jahrgang, Bezeichner, Schuljahr)
+    REFERENCES Klasse(Jahrgang, Bezeichner, Klasse)
+);
+```
+
+### Wo kommen die Daten her?
+
+Die initiale leere Datenbank kann mit den SQL-Statements in der Datei `sql/init.sql` erzeugt werden.
+Um eine sqlite Datenbank namens `punktestand.sqlite` zu erzeugen, kannst du den Befehl `$ sqlite punktestand.sqlite < sql/init.sql` ausführen.
+
+Das Programm `scripts/erzeuge_jahrgang.py` hielt dabei alle Klassen eines Jahrgangs anzulegen.
+
+```bash
+$ scripts/erzeuge_jahrgang.py 2526 7 d | sqlite punktestand.sqlite
+```
+
+Der Befehl fügt die Klassen 7a bis 7d aus dem Schuljahr 2025/2026 der Tabelle `Klasse` in der sqlite Datenbank `punktestand.sqlite` hinzu.
+
+
+## Tüfeln und Basteln
+
+Dieses Repository ist für die Entwicklung mit einem UNIX-artigen System (Linux, MacOS) ausgelegt.
+Wenn du Schwierigkeiten mit einem Windows-System hast oder diese Anleitung ergänzen möchtest, kontaktiere mich gerne.
+
+Um an der Webseite zuarbeiten, kann der einfach in PHP integrierte Webserver verwendet werden.
+Dazu benötigst du PHP und ein geeignetes Datenbanksystem.
+Wichtig ist, dass die entsprechenden PHP Pakete zur Kommunikation mit dem Datenbanksystem installiert und aktiviert sind.
+
+Um eine sqlite Datenbank zu verwenden muss sowohl die `sqlite3` also auch `pdo_sqlite` extension in deiner `php.ini` Datei aktiviert sein.
+
+Du kannst alle Bestandteile der Webseite mit den folgenden Befehlen in den `dist`  Unterordner kopieren und diesen unter [`http://localhost:8080`](http://localhost:8080) erreichbar machen.
+
+```
+$ make
+...
+$ cd dist
+dist $ php -S localhost:8080
+```
+
+Dein Webbrowser lädt automatisch beim Aufruf von [`http://localhost:8080`](http://localhost:8080) die `index.php` Datei.
+
+Um deine Änderungen in Aktion zu sehen, musst du sie erneut in den `dist` Unterordner kopieren.
+Am leichtesten geht das mit dem enthaltenen Makefile und dem Befehl: `make`.
+
+## Lizenz
+
+Der Code der Webseite und alle zusätzlichen Materialien sind unter
+GPL-3.0-or-later verfügbar.
+
+Punktestand is free software: you can redistribute it and/or modify it under the
+terms of the GNU General Public License as published by the Free Software
+Foundation, either version 3 of the License, or (at your option) any later version.
+
+Punktestand is distributed in the hope that it will be useful, but WITHOUT ANY
+WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
+PARTICULAR PURPOSE. See the GNU General Public License for more details.
+
+You should have received a copy of the GNU General Public License along with
+Punktestand. If not, see <https://www.gnu.org/licenses/>.