feat: add planning JSON exchange

2026-08-17 02:04:29 +02:00
parent 50f3b2d6a9
commit 8efeb68e93
8 changed files with 797 additions and 2 deletions
@@ -0,0 +1,107 @@
+# LehrerApp-Austauschformat: Unterrichtseinheit
+
+Dieses Dokument beschreibt Version 1 des JSON-Formats `lehrerapp.unit-planning`.
+Es dient zum Austausch einer vollständigen Unterrichtseinheit einschließlich ihrer Stunden.
+
+## Grundregeln
+
+- Die Datei enthält reines UTF-8-JSON. Beim Import wird auch ein einzelner Markdown-Codeblock akzeptiert.
+- Datumswerte verwenden `JJJJ-MM-TT`, Uhrzeiten `HH:MM` oder `HH:MM:SS`.
+- Statuswerte sind `planned`, `active`, `completed` für Einheiten und `planned`, `conducted` für Stunden.
+- Interne IDs werden nicht übertragen. Der Import legt eine neue Einheit und neue Stunden in der aktuell geöffneten Lerngruppe an.
+- `context` hilft bei der Bearbeitung mit einer KI, wird beim Import aber nicht zur Zuordnung verwendet.
+- Unbekannte zusätzliche Felder werden ignoriert.
+
+## Beispiel
+
+```json
+{
+  "schema": "lehrerapp.unit-planning",
+  "version": 1,
+  "context": {
+    "group": "8a",
+    "subject": "Physik",
+    "gradeLevel": 8,
+    "unitTitle": null
+  },
+  "unit": {
+    "title": "Optik: Reflexion und Brechung",
+    "startDate": "2026-09-01",
+    "endDate": "2026-10-06",
+    "competencies": ["UF1", "E4"],
+    "status": "planned",
+    "notes": "Experimente in Kleingruppen",
+    "lessons": [
+      {
+        "date": "2026-09-01",
+        "lessonNumber": 3,
+        "topic": "Lichtausbreitung",
+        "startTime": "09:50:00",
+        "status": "planned",
+        "homework": "Aufgabe 2 beenden",
+        "reflection": null,
+        "phases": [
+          {
+            "name": "Einstieg",
+            "durationMinutes": 10,
+            "activity": "Impulsbild beschreiben und Vermutungen sammeln",
+            "material": "Beamer",
+            "shorthand": "Plenum",
+            "alternativePath": null
+          },
+          {
+            "name": "Erarbeitung",
+            "durationMinutes": 25,
+            "activity": "Versuch zur geradlinigen Lichtausbreitung",
+            "material": "Experimentierbox",
+            "shorthand": "GA",
+            "alternativePath": "Kurzversion"
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+## Felder
+
+### Dokument
+
+- `schema` (Pflicht): exakt `lehrerapp.unit-planning`
+- `version` (Pflicht): aktuell `1`
+- `context` (optional): `group`, `subject`, `gradeLevel` und optional `unitTitle`
+- `unit` (Pflicht): die zu importierende Einheit
+
+### Einheit
+
+- `title` (Pflicht, Text)
+- `startDate`, `endDate` (optional, Datum oder `null`); das Ende darf nicht vor dem Start liegen
+- `competencies` (Liste von Kompetenzcodes oder Freitexten)
+- `status` (optional, Standard `planned`)
+- `notes` (optional, Text oder `null`)
+- `lessons` (Liste, darf leer sein); Aufbau siehe Stundenformat unten
+
+### Stunde
+
+- `date` (Pflicht, Datum)
+- `lessonNumber` (optional, Ganzzahl 1–20 oder `null`)
+- `topic` (Pflicht, Text)
+- `startTime` (optional, Uhrzeit oder `null`)
+- `status` (optional: `planned` oder `conducted`, Standard `planned`)
+- `homework`, `reflection` (optional, Text oder `null`)
+- `phases` (Liste, darf leer sein)
+
+### Phase
+
+- `name`, `activity`, `material`, `shorthand` (Text; leere Werte sind erlaubt)
+- `durationMinutes` (Ganzzahl 0–180)
+- `alternativePath` (optional): lesbarer Name eines alternativen Verlaufs, z. B. `Kurzversion`. Beim Import wird ein vorhandener gleichnamiger Ablauf verwendet oder neu angelegt.
+
+## Hinweise für KI-Bearbeitung
+
+- JSON-Struktur, `schema` und `version` unverändert lassen.
+- Nur gültige ISO-Daten verwenden.
+- Phasendauern so wählen, dass ihre Summe zur verfügbaren Unterrichtszeit passt.
+- Keine IDs ergänzen; Beziehungen werden beim Import automatisch hergestellt.
+