# Lernwerkzeuge in Stundentakt – Überblick

Ein **Lernwerkzeug** ist eine Webseite eines fremden Anbieters (Übungen, Simulationen, Programmierumgebungen,
Vokabeltrainer …), die Stundentakt als Baustein in den Unterricht einbindet. Das Werkzeug läuft auf seiner
eigenen Adresse; Stundentakt rahmt es ein oder öffnet es in einem eigenen Fenster und führt es nie selbst aus.
Gesprochen wird über HTTPS und JSON: Anmeldung per OAuth 2, danach die Werkzeug-API unter
`https://stundentakt.eu/api/v1/tools`.

Die Dateien dieser Doku:

| Datei | für wen |
|---|---|
| `/docs/developers/overview.md` (diese) | alle: Begriffe, was wohin gehört, Rollen, Datenschutz |
| `/docs/developers/quickstart.md` | Entwickler:in: vom leeren Ordner zum angedockten Werkzeug, mit kopierbarer Seite |
| `/docs/developers/recipes.md` | Entwickler:in: fertige Ausschnitte für Records, Ereignisse, Autorenmodus, Meine Kurse, Links, Anzeige, Fehler |
| `/docs/teachers/tools.md` | Lehrer:in und Redaktion: Werkzeug eintragen, einbauen, zuweisen, auswerten |
| `/docs/developers/reference.md` | Entwickler:in: der verbindliche Vertrag mit allen Routen, Feldern, Fehlern und Grenzen |

Maschinenlesbar: `/llms.txt`, `/llms-full.txt` (alle Dateien hintereinander) und
`/api/v1/tools/openapi.json` (OpenAPI 3.1).

## Was Stundentakt einem Werkzeug abnimmt

- **Konten und Anmeldung:** Lehrer:innen, Schüler:innen, Klassen, Schulen; Anmeldung mit Passwort,
  beste.schule, Klassencode oder Anmeldekarte. Das Werkzeug bekommt per OAuth ein Token für genau eine Person
  und braucht keine eigene Nutzerverwaltung.
- **Unterricht:** wer in welcher Klasse ist, welche Aufgabe wann offen ist (Fenster, Frist, „Nur ansehen“),
  wer die Antworten einer Klasse lesen darf.
- **Speicher:** Zwischenstand und Abgabe je Person und Aufgabe, eigene Daten der Person (Records) mit
  Freigabe an Klasse, Schule oder alle, Dateien einer Abgabe.
- **Auswertung:** Die Lehrer:in sieht Abgaben, Punkte und die gemeldeten Ereignisse ihrer Klasse in
  Stundentakt; das Werkzeug muss dafür keine eigene Lehrer:innen-Ansicht bauen (kann aber den Modus `review`
  anbieten).
- **Abo:** Welcher Plan die Person trägt, steht in `GET me`; ein Werkzeug rechnet nichts selbst ab.

## Begriffe

| Begriff | Bedeutung für ein Werkzeug |
|---|---|
| **Person** | wer das Token hält: eine Lehrer:in (`kind: user`) oder eine Schüler:in (`kind: member`). Erkennbar nur an ihrem Pseudonym bzw. Anzeigenamen (`alias`), nie an Name, E-Mail oder einer Nummer. |
| **Klasse** | eine Gruppe aus Lehrer:innen und Schüler:innen. Das Werkzeug sieht sie nie direkt, nur über eine Zuweisung. |
| **Medium** | ein Dokument aus Bausteinen (Arbeitsblatt, Kurs, Tafel, Lernwerkzeug …), gebaut von einer Lehrer:in. Adressiert per ULID (`document`). |
| **Baustein** | ein Teil eines Mediums. Ein Baustein vom Typ `tool` verweist auf genau ein eingetragenes Werkzeug und trägt dessen Aufgabe: `title`, `task` (JSON des Werkzeugs) und `hidden` (JSON, das nur die Autor:in und das Werkzeug in ihrer Hand sehen, z. B. Tests). Adressiert per ULID (`block`). |
| **Zuweisung** | ein Medium, freigegeben für eine Klasse, mit Fenster und Frist. Eine Zuweisung ohne Klasse entsteht, wenn ein Medium per Link oder öffentlich geteilt wird. Adressiert per ULID (`assignment`). |
| **Antwort** | was eine Person zu einem Baustein einer Zuweisung abgibt: `done`, `score`, `max_score`, `state`, Dateien. Je Person und Baustein gibt es eine; eine neue Abgabe ersetzt die alte. Daneben ein **Zwischenstand** (`draft.state`), den eine Abgabe löscht. |
| **Record** | freie Daten, die einer Person in einem Werkzeug gehören (eigene Programme, Vokabellisten, Einstellungen), in einer **Datenart** (`collection`), die das Werkzeug frei benennt. Privat, bis die Person sie freigibt. |
| **Ereignis** | eine Lernspur im Stil einer xAPI-Aussage: Verb (`run`, `error`, `step` …), optional Objekt, Ergebnis, Zeit. Mit Zuweisung zählt es in der Auswertung der Klasse, ohne Zuweisung gehört es nur Person und Werkzeug. |
| **Abo** | der Plan (`free`, `pro`, `premium`) des Teams, das die Person trägt, mit Schaltern und Speichergrenze; gelesen über `GET me`. |
| **ULID** | jede Kennung nach außen: 26 Zeichen Crockford-Base32 (Stundentakt schreibt sie klein). Interne Nummern gibt die API nie heraus. |

## Faustregel: was wohin gehört

| Die Daten … | gehören in … | Route |
|---|---|---|
| beschreiben eine Aufgabe, die eine Lehrer:in stellt | den Baustein (`task`, `hidden`, `display`) | `PUT blocks/{block}` (Modus `author`) |
| sind die Arbeit einer Person an dieser Aufgabe, noch nicht fertig | den Zwischenstand | `PUT assignments/{a}/blocks/{b}/draft` |
| sind ihr Ergebnis, das die Lehrer:in sehen soll | die Antwort | `POST assignments/{a}/blocks/{b}/response` |
| gehören nur der Person, unabhängig von einer Aufgabe | einen Record | `POST collections/{c}/records` |
| beschreiben, was beim Lernen passiert ist (ausgeführt, Fehler, Schritt) | ein Ereignis | `POST assignments/{a}/events` bzw. `POST events` |
| sind ein unveröffentlichter Entwurf einer Aufgabe | einen privaten Record (z. B. Datenart `drafts`), veröffentlicht wird per `PUT blocks/{block}` | siehe `/docs/developers/recipes.md` |

Ein Werkzeug legt keine Tabellen an und speichert nichts ohne Person: Stundentakt kennt nur diese Orte.

## Rollen und Modi

Stundentakt startet das Werkzeug mit seiner Start-Adresse und hängt Parameter an:

```
https://werkzeug.example/start?mode=learn&assignment=<ULID>&block=<ULID>&lang=de
```

| Modus | wer | Parameter | was das Werkzeug tut |
|---|---|---|---|
| `learn` | eine Schüler:in der Klasse, eine mitmachende Lehrer:in, auf dem Link auch eine angemeldete Person wie ein Gast | `assignment`, `block` | Aufgabe zeigen, Zwischenstand speichern, abgeben, Ereignisse melden |
| `review` | die Lehrer:in der Klasse | `assignment`, `block`, `response` | eine abgegebene Antwort nur lesend zeigen |
| `author` | die Lehrer:in, die das Medium baut | `document`, `block` | Titel, Aufgabe und versteckten Teil schreiben |

`lang` ist immer `de` oder `en`. Die Rolle der Person in einer Zuweisung steht in `me.role` der Antwort auf
`GET assignments/{a}`: `teacher` (leitet die Klasse), `student` oder `guest` (nimmt auf einem Link teil).

Anzeige: `inline` (Rahmen in der Seite von Stundentakt) oder `full` (Karte, die das Werkzeug in einem eigenen
Fenster öffnet). Der Eintrag gibt sie vor, jeder Baustein kann sie für sich überschreiben (`payload.display`). Beides ist derselbe Ablauf; Unterschiede in `/docs/developers/recipes.md`, „Rahmen oder eigenes Fenster“.

## Datenschutz

- **Pseudonym:** Eine Schüler:in heißt für das Werkzeug nur nach ihrem Pseudonym (`alias`), eine Lehrer:in nach
  ihrem Anzeigenamen („J. Muster“). Nie ein echter Name einer Schüler:in, nie eine E-Mail, nie eine interne
  Nummer. Ein Werkzeug fragt auch selbst nicht danach.
- **Gäste** (ohne Konto über einen geteilten Link) sind für Werkzeuge nicht angemeldet: kein Token, keine
  Records. `/oauth/authorize` antwortet `error=access_denied&reason=guest_not_supported`; das Werkzeug speichert
  für sie höchstens auf dem Gerät.
- **Lösungen:** Lösungen anderer Bausteine des Mediums sieht ein Werkzeug erst, wenn die App sie der Person zeigt
  (nach der Frist; die Lehrer:in der Klasse immer). Eigene Lösungen darf das Werkzeug in `hidden` oder bei sich
  halten; Stundentakt prüft keine Antwort nach.
- **Kein Token ist mehr als die Person:** Ein Token gilt für ein Werkzeug und eine Person und erreicht nur die
  Werkzeug-API. Werkzeug A liest nie die Records von Werkzeug B.
- **Löschen:** Wer Konto, Mitglied, Klasse oder den Werkzeug-Eintrag löscht, löscht Zwischenstände, Antworten,
  Records und Ereignisse mit.
- Arbeitsdaten (`state`, Records) erscheinen in keinem Export, keiner Auswertung und erreichen nie eine KI.
