docs: record learning task decisions and AI integration progress

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>

docs/ARCHITECTURE.md

@@ -85,6 +85,7 @@ Alle Zeitpunkte werden als UTC (`DateTimeOffset`/`DateTime` UTC) gespeichert und
 | Essen ✅ | `MealPlanEntry` (Date als `DateOnly`, MealType, DishName, Note, RecipeUrl, Ingredients, WishId, RowVersion, Soft Delete; eindeutig je Tag + Mahlzeit), `Dish` (Name, RecipeUrl, Ingredients, UseCount – für Autovervollständigung), `MealWish` (DishName, Note, Wunschtag/-mahlzeit, Status offen/übernommen/abgelehnt, Soft Delete) |
 | Aufgaben ✅ | `TodoTask` (Title, Notes, DueDate + DueTime → DueAt, ReminderMinutesBefore → RemindAt, Priority, Status inkl. „wartet auf Bestätigung“, Category, IsPrivate, IsChore, Points, NeedsApproval, AssignedToFamily, RecurrenceRule + RecurrenceMode, SeriesId/SeriesStart/SeriesIndex, CompletedBy/At, ApprovedBy/At, RowVersion, Soft Delete), `TaskAssignment`, `TaskChecklistItem`, `TaskHistoryEntry` (Verlauf), `PointsLedgerEntry` (Punktebuch). Kategorien kommen aus `FamilySettings.TaskCategories`; „wer/wann/genehmigt“ steht an der Aufgabe und im Verlauf (ADR-0014) |
 | Kalender ✅ | `FamilyCalendar` (Name, Color, IsDefault, Soft Delete), `CalendarPermission` (Rolle **oder** Benutzer → None/Read/WriteOwn/Write), `CalendarEvent` (Title, Location, Notes, IsAllDay, StartUtc, EndUtc, TimeZoneId, RecurrenceRule, ExceptionDates, Uid, PersonIds, ForWholeFamily, Sequence, RowVersion, Soft Delete; Overrides als eigene Zeile mit `SeriesMasterId` + `RecurrenceId`), `IcsFeed` (Owner, Scope, CalendarId, TaskMode, TokenHash, TokenPrefix, LastAccessAt, RevokedAt) – ADR-0015/0016 |
+| KI ✅ | `AiProviderConfig` (Name, Type Ollama/Claude/OpenAiCompatible, BaseUrl, Model, ApiKeyProtected, TimeoutSeconds, IsActive, AllowImages, Purposes, DailyLimitPerUser, RowVersion, Soft Delete), `AiUsage` (Person, Anbieter, Zweck, Dauer, Tokens, Erfolg/Fehlerart – ohne Inhalt) – ADR-0020 |
 | Chat ✅ | `ChatChannel` (Family / Direct), `ChatMember` (LastReadAt), `ChatMessage` (Text, HasImage), `ChatAttachment`, `ChatReaction` |
 | Betrieb | `AuditLogEntry` ✅ (ActorName, Action, TargetType/Id/Name, Details, CreatedAt), `PushSubscription` ✅ (UserId, Endpoint + Hash, P256dh, Auth, LastSuccessAt, FailureCount) |
 
@@ -112,6 +113,7 @@ oder **None (–)**. Die Api registriert je Permission eine Policy `Permission:<
 | `EventsEdit` | F | F | R | – | nur eigene Termine |
 | `FamilyChat` | F | F | F | – ² | |
 | `DirectMessages` | F | F | R | – | nur an Familienmitglieder |
+| `AiUse` | F | F | – | – | KI-Funktionen nutzen (ADR-0020) |
 | `UserManagement`, `CalendarManagement`, `SettingsManagement`, `AuditLogView` | F | – | – | – | |
 
 ¹ `F`, wenn „Gäste dürfen die Einkaufsliste ergänzen/abhaken“ aktiviert ist. ² `F`, wenn „Gäste dürfen den Familienchat nutzen“ aktiviert ist.
@@ -150,6 +152,7 @@ Das UI bekommt die wirksamen Berechtigungen über `/api/auth/me` und blendet anh
 | Admin – Kalender ✅ | `GET/POST /api/admin/calendars`, `PUT/DELETE /api/admin/calendars/{id}` |
 | ICS-Feed | `GET /ics/{token}.ics` (öffentlich, Token-gesichert, ETag/Last-Modified) |
 | Chat ✅ | `GET /api/chat/channels`, `POST /api/chat/direct`, `GET /api/chat/channels/{id}/messages?before=&take=`, `POST …/messages`, `POST …/images` (Multipart), `POST …/read`, `DELETE /api/chat/messages/{id}`, `PUT /api/chat/messages/{id}/reactions`, `GET /api/chat/attachments/{id}` (ADR-0019) |
+| KI ✅ | Admin: `GET/POST /api/admin/ai/providers`, `PUT/DELETE …/{id}`, `POST …/{id}/test`, `GET /api/admin/ai/usage`; Eltern: `GET /api/ai/status` (ADR-0020) |
 | Dashboard ✅ | `GET /api/dashboard` (alle Kacheln der Rolle in einem Request, ADR-0018) |
 | Hubs | `/hubs/live` (Live-Updates: Einkauf ✅, Essenplan ✅, Aufgaben ✅, Termine ✅, Chat ✅ inkl. Hub-Methode `Typing`; das Dashboard lädt bei diesen Ereignissen neu) |
 | Betrieb | `/health`, `/alive` |

docs/ROADMAP.md

@@ -109,12 +109,13 @@ Legende: `[x]` erledigt, `[ ]` offen. Nach jeder Phase: Build ohne Warnungen, Te
 - [ ] Nachrichten bearbeiten, Antworten/Zitate, Suche, frei wählbare Gruppen – bewusst nicht umgesetzt
 
 ## Phase 9 – KI-Anbindung (ADR-0020)
-- [ ] Gemeinsame Schnittstelle `IAiProvider` (Text, Bilder, strukturierte JSON-Antwort, Zeit-/Größenlimits), Fähigkeiten je Anbieter
-- [ ] Adapter: Ollama (lokal), Claude (Anthropic), OpenAI-kompatibel (Perplexity; später Azure OpenAI / GitHub Models als Ersatz für „Copilot“, der keine offene API hat)
-- [ ] Admin-Bereich „KI“: Anbieter anlegen/ändern/aktivieren, Basis-URL, Modell, API-Schlüssel (verschlüsselt, nie zurück an den Client), Zweck-Zuordnung, „Bilder erlaubt“ (Opt-in je Anbieter), Verbindungstest
-- [ ] Permission `AiUse` (Admin/Familie), Policy + Unit-Test je Matrixzelle; Tageslimits, Rate Limiting, Audit je Aufruf (ohne Inhalt)
-- [ ] Antworten validieren (Schema + fachliche Regeln, ein Wiederholungsversuch), Fehler verständlich melden
-- [ ] Tests: Adapter gegen Fake-HTTP-Server, `FakeAiProvider` für Fachlogik, Admin-API/UI
+- [x] Gemeinsame Schnittstelle `IAiProvider` (Text, Bilder, strukturierte JSON-Antwort) mit anbieterunabhängigem `AiRequest`/`AiResponse`; Zugriff für Fachfunktionen nur über `AiService`
+- [x] Adapter: Ollama (`/api/chat`, Bilder als Base64, Schema über `format`), Claude (Messages API, Bilder, erzwungener Werkzeugaufruf für das Schema), OpenAI-kompatibel (Perplexity; später Azure OpenAI / GitHub Models als Ersatz für „Copilot“, der keine offene API hat; Bilder als Data-URL, Schema über `response_format`)
+- [x] Admin-Bereich „KI“ (Tab unter Verwaltung): Anbieter anlegen/ändern/löschen/aktivieren, Adresse, Modell, API-Schlüssel (mit Data Protection verschlüsselt, nie zurück an den Client, ersetzen/entfernen), Zeitlimit, Tageslimit je Person, Zweck-Zuordnung (je Zweck genau ein Anbieter), „Bilder erlaubt“ (Opt-in; Heimnetz-Adressen brauchen es nicht), Verbindungstest, Nutzungsübersicht
+- [x] Adress-Prüfung (nur http/https, keine Zugangsdaten, Cloud-Metadaten/Link-Local gesperrt, Klartext nur im Heimnetz, Claude nur https), Foto-Prüfung ohne Rückfall auf den Standard-Anbieter
+- [x] Permission `AiUse` (Admin/Familie) + Matrix-Test, Verwaltung nur Admin (`SettingsManagement`); `GET /api/ai/status` für Eltern (steuert später, welche KI-Knöpfe sichtbar sind)
+- [x] Tageslimit, Nutzungsprotokoll `AiUsage` (ohne Inhalt: Person, Zweck, Anbieter, Modell, Dauer, Tokens, Erfolg/Fehlerart), Audit-Log für Anbieter-Änderungen, eigener HttpClient ohne Standard-Resilienz, Zeitlimit je Anbieter, höchstens ein Wiederholungsversuch bei unbrauchbarer Antwort, Fehlermeldungen ohne Schlüssel/Anbietertext; Migration `Phase9Ai`
+- [x] Tests: Unit (Adressen/Heimnetz/Schlüsselpflicht/Limits/Zwecke/Validator, Adapter gegen Fake-Handler inkl. Fehlerübersetzung und JSON-Extraktion), bUnit (Verwaltung, Dialog, Test, Nutzung, Löschen), Integration (Rechte, Validierung, Schlüsselschutz, Zweck-Übernahme, Verbindungstest gegen Fake-Anbieter inkl. Timeout, OpenAI-Format, Tageslimit + Protokoll)
 
 ## Phase 10 – Lernaufgaben (ADR-0021)
 - [ ] 10a: Übungsblätter manuell anlegen/zuweisen, Kind löst digital (Zahl/Auswahl/Text), automatische Bewertung ohne KI, Elternprüfung, Kinderansicht, Dashboard-Kachel, optional Punkte über das Punktebuch

docs/adr/0020-ki-anbindung.md

@@ -1,6 +1,6 @@
 # ADR-0020: KI-Anbindung – gemeinsame Schnittstelle, Anbieter per Admin-Einstellung
 
-* Status: vorgeschlagen (Phase 9)
+* Status: akzeptiert (Phase 9; Anbieter Ollama, Claude, Perplexity bestätigt, Bilder-Opt-in bestätigt)
 * Datum: 2026-10-10
 
 ## Kontext
@@ -22,17 +22,23 @@ Copilot ist ausdrücklich ein Wunsch, hat aber keine offene API für Dritt-Apps
    * **Copilot:** Microsoft 365 Copilot und GitHub Copilot haben keine offene Chat-API für eigene Anwendungen. Über den OpenAI-kompatiblen Adapter ist
      **Azure OpenAI** bzw. **GitHub Models** anschließbar; das ersetzt „Copilot“ funktional. Ein eigener Copilot-Adapter entfällt.
 3. **Konfiguration im Admin-Bereich** (Entität `AiProviderConfig`, nicht in `FamilySettings`): Name, Typ, Basis-URL, Modell, Zeitlimit,
-   aktiv, „Bilder erlaubt“ (Opt-in, siehe 5), **Zweck-Zuordnung** (welcher Anbieter für Aufgaben-Erzeugung, welcher für Foto-Prüfung, Standard).
+   aktiv, „Bilder erlaubt“ (Opt-in, siehe 5), **Zweck-Zuordnung** (welcher Anbieter für Aufgaben-Erzeugung, welcher für Foto-Prüfung, Standard; je Zweck genau einer). Ohne eigene Zuordnung
+   nimmt ein Zweck den Standard-Anbieter – **außer die Foto-Prüfung**: sie braucht eine ausdrückliche Wahl, weil ein Standard-Anbieter ohne Vision-Modell Fotos nicht sehen könnte.
    Mehrere Anbieter parallel; Test-Button („Verbindung prüfen“) mit einer Mini-Anfrage.
 4. **API-Schlüssel** werden nie im Klartext gespeichert oder an den Client gesendet: verschlüsselt mit Data Protection (Schlüssel liegen bereits in der
    Datenbank, ADR-0001/Phase 1), die Admin-Oberfläche zeigt nur „gesetzt/nicht gesetzt“ und erlaubt Ersetzen. Optional Vorbelegung über
    Umgebungsvariablen/Aspire-Parameter (`Ai__Providers__…`), die in der Oberfläche als „aus Konfiguration“ gelten.
 5. **Datenschutz:** Cloud-Anbieter (Claude, Perplexity, Azure/GitHub) erhalten **standardmäßig nur Text**. Fotos von Kinder-Heften gehen nur an Anbieter,
-   bei denen der Admin „Bilder erlaubt“ ausdrücklich aktiviert hat (Hinweistext: Daten verlassen das Heimnetz); Ollama ist als lokal gekennzeichnet und
-   davon ausgenommen. Prompts enthalten keine Namen, Konten oder Familiendaten, nur Fach, Klassenstufe, Aufgabentext und Antwort.
+   bei denen der Admin „Bilder erlaubt“ ausdrücklich aktiviert hat (Hinweistext: Daten verlassen das Heimnetz). „Lokal“ bestimmt die **Adresse**, nicht der Typ:
+   Loopback, private Netze, `.local`/`.lan`/`.internal` und Hostnamen ohne Punkt (z. B. Docker-Dienstnamen) gelten als Heimnetz und sind vom Opt-in ausgenommen. Prompts enthalten keine Namen, Konten oder Familiendaten, nur Fach, Klassenstufe, Aufgabentext und Antwort.
+5a. **Adressen:** nur `http`/`https`, keine Zugangsdaten/Query/Fragment in der URL; Claude nur über `https`; Adressen im Link-Local-Bereich (169.254.0.0/16,
+   Cloud-Metadaten) und `0.0.0.0` werden abgelehnt; Klartext-`http` nur im Heimnetz.
 6. **Missbrauchs- und Kostenschutz:** nur Eltern/Admin lösen KI-Aufrufe aus (Policy `AiUse`, neue Permission in der Matrix – Kinder nie direkt);
-   Limits je Tag und Person, Zeit- und Größenlimits, Rate Limiting; jeder Aufruf wird im Audit-Log (Zweck, Anbieter, Modell, Dauer, Tokens, Erfolg –
-   ohne Inhalt) protokolliert.
+   Tageslimit je Person und Anbieter (`DailyLimitPerUser`, 0 = unbegrenzt), Zeit- und Größenlimits; jeder Aufruf wird in einem eigenen **Nutzungsprotokoll**
+   (`AiUsage`: Person, Zweck, Anbieter, Modell, Dauer, Tokens, Erfolg/Fehlerart, mit/ohne Bilder – ohne Inhalt) festgehalten, das auch die Tageslimits zählt und im
+   Admin-Bereich einsehbar ist. Das allgemeine Audit-Log bleibt administrativen Aktionen vorbehalten (Anbieter anlegen/ändern/löschen).
+6a. **HTTP:** eigener HttpClient ohne die Standard-Resilienz (30-s-Gesamtlimit und automatische Wiederholungen passen nicht zu KI-Antworten);
+   das Zeitlimit je Anbieter (5–300 s) wird über den Abbruch-Token erzwungen, Wiederholungen entscheidet `AiService` (höchstens einmal bei unbrauchbarer Antwort).
 7. **Robustheit:** Antworten sind **nie vertrauenswürdig**. Strukturierte Ausgabe wird gegen das Schema und fachliche Regeln validiert
    (Anzahl, Länge, Typen), Fehlversuche werden einmal wiederholt, sonst mit verständlicher Meldung abgelehnt; KI-Text wird beim Anzeigen
    wie jeder Benutzertext behandelt (kein HTML). Netzwerkfehler und Timeouts führen nie zu halben Datenständen (erst validieren, dann speichern).

docs/adr/0021-lernaufgaben.md

@@ -1,6 +1,6 @@
 # ADR-0021: Lernaufgaben – manuell oder per KI, digital oder auf Papier
 
-* Status: vorgeschlagen (Phase 10)
+* Status: akzeptiert (Phase 10; Entscheidungen der Rückfragen am 2026-10-10 eingearbeitet)
 * Datum: 2026-10-10
 
 ## Kontext
@@ -43,8 +43,26 @@ Lernaufgaben sind **kein** Teil der Familienaufgaben (ADR-0014): eigene Entität
 8. **UI:** Seite „Lernen“ (Kinderansicht: offene Blätter, Fortschritt; Elternansicht: Blätter verwalten, Prüf-Warteschlange, KI-Entwurf-Assistent),
    Dashboard-Kachel „Lernen“ (offene/zu prüfende Blätter), Live-Updates über `user:{id}`, alles Smartphone-tauglich (Kamera-Upload, große Touch-Ziele).
 
+9. **Fächer und Stufen:** zunächst nur **Mathe und Deutsch**, **Klasse 1–6** (Auswahllisten; weitere Fächer später ohne Datenmodelländerung, da Fach ein Text aus einer Liste ist).
+10. **Punktesystem:** Jedes Blatt vergibt Punkte (je Aufgabe Punkte nach Schwierigkeit, Gesamtpunkte des Blatts einstellbar). Gutschrift im vorhandenen Punktebuch
+    (ADR-0014) erst nach Eltern-Bestätigung der Bewertung, anteilig nach erreichten Punkten; bei Wiederholung zählt nur die **beste Wertung** einmal
+    (Differenz wird gebucht), Rückbuchung beim erneuten Öffnen/Korrigieren wie bei Ämtchen.
+11. **Wiederholen (einstellbar je Blatt):** `MaxAttempts` (1 = einmalig, n = bis zu n Versuche, 0 = unbegrenzt); Voreinstellung in den Familieneinstellungen.
+    Jeder Versuch wird gespeichert; ob das Kind nach dem Versuch die Musterlösung sieht, ist je Blatt einstellbar („Lösungen nach Abgabe zeigen“).
+12. **Zeitlimit (einstellbar je Blatt):** `TimeLimitMinutes` (leer = kein Limit). Der Server hält Start und Ablauf fest (nicht der Client); nach Ablauf werden nur
+    bis dahin gespeicherte Antworten gewertet, spätere Speicherungen werden mit 409 abgelehnt. Eine kleine Toleranz (Netzverzögerung) ist fest eingebaut.
+13. **Test-/Prüfungs-Emulation:** Ein Blatt kann als **Prüfung** laufen (`Mode = Exam`, Gegenstück: `Practice`):
+    * fester Start („Prüfung beginnen“ startet die Uhr, Fortsetzen nach Unterbrechung innerhalb der Zeit möglich),
+    * Zeitlimit sichtbar als Countdown, Fortschrittsanzeige, **keine Sofort-Rückmeldung** je Aufgabe (Bewertung erst nach Abgabe),
+    * keine Hinweise und keine Musterlösung während der Prüfung, Aufgabenreihenfolge optional gemischt,
+    * Abgabe-Bestätigung („Wirklich abgeben?“), automatische Abgabe bei Ablauf,
+    * Ergebnis mit Note nach einstellbarem Notenschlüssel (Standard: Schulnoten 1–6 nach Prozentpunkten) und Punkten;
+      Papier-Prüfungen: Foto-Abgabe innerhalb des Zeitfensters.
+    Im Übungsmodus (`Practice`) gibt es Sofort-Rückmeldung und Hinweise.
+
 ## Bewusst nicht Teil des ersten Schnitts
-Offline-Lösen, Sprachausgabe/Diktat, Lernstatistiken über Wochen, Adaptive Schwierigkeit, Formeleditor (Aufgaben bleiben Text), Auswertung mehrerer Kinder im Vergleich.
+Offline-Lösen, Sprachausgabe/Diktat, Lernstatistiken über Wochen, Adaptive Schwierigkeit, Formeleditor (Aufgaben bleiben Text), Auswertung mehrerer Kinder im Vergleich,
+Überwachung gegen Schummeln (die Emulation ist ein Übungsrahmen, keine Fernprüfung).
 
 ## Phasenschnitt
 * Phase 9: KI-Anbindung (ADR-0020) inklusive Admin-Einstellungen, Testbarkeit, Audit, Tageslimits.
@@ -53,4 +71,4 @@ Offline-Lösen, Sprachausgabe/Diktat, Lernstatistiken über Wochen, Adaptive Sch
 * Phase 10c: Papierlösung mit Foto (manuelle Prüfung), danach KI-Prüfung.
 
 ## Offene Fragen
-Welche Fächer/Schulstufen zuerst (Vorschlag: Mathe und Deutsch, Klasse 1–6)? Sollen Kinder Aufgaben wiederholen dürfen? Soll es Zeitlimits je Blatt geben?
+Notenschlüssel für Deutsch-Diktate/Freitext (Standard-Schulnoten reichen für Punkte-basierte Wertung zunächst).