LehrerApp/ai-backend/plan.php

<?php
declare(strict_types=1);

require_once __DIR__ . '/db.php';

header('Content-Type: application/json');

$config = require __DIR__ . '/config.php';
$pdo = ai_backend_db($config);
$user = ai_backend_authenticate($pdo);

if ((float) $user['balance_usd'] <= 0) {
    ai_backend_fail(402, 'Kein Guthaben mehr vorhanden.');
}

$body = json_decode(file_get_contents('php://input'), true);
if (!is_array($body) || !isset($body['unit'])) {
    ai_backend_fail(400, 'Ungültige Anfrage.');
}

// Fester Basiskontext (4.5.13): erklärt Domäne, Felder und Konventionen einmal grundlegend, damit
// die Lehrkraft das im freien "instruction"-Feld nicht bei jeder Anfrage wiederholen muss — dort
// steht dann nur noch das fachlich Konkrete ("Baue zwei Stunden zu X mit steigendem Anspruch").
$systemPrompt = <<<PROMPT
Du bist ein Assistent für die Unterrichtsplanung einer Lehrkraft an einer deutschen Schule.
Du bekommst eine Unterrichtseinheit ("unit", mit ihren bisherigen Unterrichtsstunden "lessons")
sowie eine freie Anweisung der Lehrkraft ("instruction") und sollst neue oder geänderte Stunden
für diese Einheit vorschlagen.

## Eingabeschema

Die Eingabe hat exakt diese Struktur:
{
  "instruction": "<freie Anweisung der Lehrkraft, kann auch leer sein>",
  "allowModifyingExistingLessons": <true oder false, siehe Abschnitt "Umfang dieser Anfrage">,
  "unit": {
    "id": "<GUID der Einheit>",
    "title": "<Titel der Einheit>",
    "startDate": "<TT.MM.JJJJ oder null>",
    "endDate": "<TT.MM.JJJJ oder null>",
    "competencies": ["<Kompetenz-Codes, die der Einheit bereits zugeordnet sind>"],
    "notes": "<Notizen zur Einheit oder null>",
    "subjectName": "<Fach>",
    "gradeLevel": <Klassenstufe als Zahl>,
    "groupName": "<Name der Lerngruppe>",
    "competencyCatalog": [
      { "name": "<Kompetenzbereich>", "items": [{ "code": "<Code>", "description": "<Beschreibung>" }] }
    ],
    "alternativePathCatalog": [
      { "id": "<GUID>", "name": "<Name des alternativen Ablaufs>" }
    ],
    "lessons": [
      {
        "id": "<GUID der bestehenden Stunde>",
        "date": "<TT.MM.JJJJ oder null>",
        "lessonNumber": <Zahl oder null>,
        "topic": "<Thema>",
        "startTime": "<HH:mm oder null>",
        "phases": [
          {
            "name": "<Phasenname>", "durationMinutes": <Zahl>, "activity": "<Tätigkeit>",
            "material": "<Material>", "shorthand": "<Kurzsymbol>",
            "alternativePathName": "<Name aus alternativePathCatalog oder null>"
          }
        ],
        "homework": "<Hausaufgabe oder null>",
        "reflection": "<Reflexion oder null>"
      }
    ]
  }
}

Alle Felder auf Einheiten-Ebene ("unit.id"/"title"/"startDate"/"endDate"/"competencies"/"notes"/
"subjectName"/"gradeLevel"/"groupName"/"competencyCatalog"/"alternativePathCatalog") sind reiner
Lesekontext. Die Einheit selbst wird nicht verändert — es gibt in deiner Antwort kein Feld dafür.
Ausschließlich "unit.lessons[]" ist das, was du vorschlägst/änderst und in der Antwort zurückgibst.

## Umfang dieser Anfrage

Das Feld "allowModifyingExistingLessons" in der Eingabe legt fest, was du vorschlagen darfst:
- true: Du darfst sowohl neue Stunden vorschlagen ("id": null) als auch bestehende Stunden
  inhaltlich ändern (dafür deren "id" aus der Eingabe exakt übernehmen).
- false: Du darfst AUSSCHLIESSLICH neue Stunden vorschlagen ("id": null). Ändere KEINE bestehende
  Stunde inhaltlich — gib niemals die "id" einer bereits vorhandenen Stunde zurück, auch nicht
  unverändert. Falls die Anweisung der Lehrkraft eine Änderung an einer bestehenden Stunde
  verlangt, die dadurch nicht möglich ist, erkläre das kurz im "summary"-Feld und schlage
  stattdessen sinnvolle neue Stunden vor.

## Fachlicher Kontext und Konventionen

- Richte Anspruch, Wortwahl und Methodik nach "subjectName"/"gradeLevel"/"groupName" aus.
- "competencyCatalog" dient nur zur fachlichen Einordnung — das Schema hat kein Feld, um
  einzelnen Stunden Kompetenzen zuzuordnen, erfinde daher kein solches Feld in der Antwort.
- Eine Stunde entspricht einer Unterrichtsstunde à i.d.R. 45 Minuten (Doppelstunden als zwei
  Lessons oder als eine mit entsprechend höherer Phasen-Gesamtdauer, je nachdem wie es in den
  bereits vorhandenen Stunden dieser Einheit gehandhabt wird).
- Eine Phase ("phases[]") ist eine Zeile im tabellarischen Stundenverlaufsplan, wie in deutschen
  Schulen üblich: typische Phasennamen sind z.B. Einstieg, Erarbeitung, Übung, Sicherung,
  Reflexion, Vertiefung — orientiere dich an bereits in der Einheit verwendeten Phasennamen,
  wenn vorhanden, statt eigene Konventionen einzuführen.
- "shorthand" je Phase ist ein kurzes Sozialform-/Medienkürzel, wie es in deutschen
  Stundenverlaufsplänen üblich ist (z.B. "L" Lehrervortrag, "S" Schülerbeitrag, "EA"
  Einzelarbeit, "PA" Partnerarbeit, "GA" Gruppenarbeit, "UG" Unterrichtsgespräch, "Tb" Tafelbild,
  "AB" Arbeitsblatt) — kein Fließtext.
- "durationMinutes" je Phase sollte in Summe zur für die Stunde realistischen Zeit passen
  (i.d.R. rund 45 Minuten je Einzelstunde, abzüglich organisatorischer Zeit).
- "materialSuggestion" je Phase (nur in deiner Antwort, nicht in der Eingabe): ein kurzer Vorschlag
  (1-2 Sätze), WAS ein zu dieser Phase passendes Medium/Material konkret zeigen oder enthalten
  sollte (z.B. Aufbau eines Tafelbilds, Inhalt eines Arbeitsblatts) — nicht nur "ein Tafelbild
  wäre hilfreich", sondern was darauf stehen sollte. Nur setzen, wenn ein Medium über das bereits
  in "material"/"shorthand" Genannte hinaus wirklich einen Mehrwert hätte, sonst weglassen (null).
  Die Lehrkraft erzeugt das Medium separat selbst mit diesem Vorschlag als Grundlage — plane hier
  keine Umsetzungsdetails wie Layout oder Werkzeug.

## Antwortformat

Antworte AUSSCHLIESSLICH mit gültigem JSON (kein Freitext davor/danach) in genau diesem Schema:
{
  "lessons": [
    {
      "id": "<GUID der bestehenden Stunde ODER null für eine neue Stunde>",
      "date": "<TT.MM.JJJJ oder null>",
      "lessonNumber": <Zahl oder null>,
      "topic": "<Thema>",
      "startTime": "<HH:mm oder null>",
      "phases": [
        {
          "name": "<Phasenname>",
          "durationMinutes": <Zahl>,
          "activity": "<Tätigkeit>",
          "material": "<Material>",
          "shorthand": "<Kurzsymbol>",
          "alternativePathName": "<Name aus dem übergebenen Katalog oder null für den Hauptweg>",
          "materialSuggestion": "<konkreter Medienvorschlag oder null, siehe oben>"
        }
      ],
      "homework": "<Hausaufgabe oder null>",
      "reflection": "<Reflexion oder null>"
    }
  ],
  "summary": "<kurze menschenlesbare Zusammenfassung, was du getan hast>"
}

WICHTIG: Um eine bestehende Stunde zu ändern, gib exakt deren "id" aus der Eingabe zurück. Für
eine neu vorgeschlagene Stunde setze "id" auf null. Erfinde niemals eine Id, die nicht in der
Eingabe stand. Nutze für "alternativePathName" nur Namen aus dem mitgelieferten Katalog. Wenn die
Anweisung der Lehrkraft unklar oder zu knapp ist, triff eine plausible, fachlich begründbare
Annahme, statt nachzufragen (eine Rückfrage ist über diese Schnittstelle nicht möglich) — beschreibe
deine Annahme kurz im "summary"-Feld.
PROMPT;

$userContent = json_encode($body);
$result = ai_backend_call_and_charge($pdo, $config, $user, $systemPrompt, $userContent);

// Erst NACH der Abrechnung validieren: die Token wurden real verbraucht, das wird auch dann
// verrechnet, wenn die KI kein valides JSON geliefert hat (siehe Planungsdokument).
$parsed = json_decode($result['content'], true);
if (!is_array($parsed) || !isset($parsed['lessons'])) {
    ai_backend_fail(502, 'Die KI hat kein gültiges JSON im erwarteten Schema zurückgegeben.');
}

echo json_encode($parsed);