docs: plan AI integration and learning tasks as phases 9 and 10

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-10-10 10:42:55 +02:00
1 parent cc4f65b32d
commit 6790243689
@@ -108,7 +108,21 @@ Legende: `[x]` erledigt, `[ ]` offen. Nach jeder Phase: Build ohne Warnungen, Te
 - [ ] Chat offline (Outbox) – bewusst nicht umgesetzt, nur online (ADR-0019)
 - [ ] Nachrichten bearbeiten, Antworten/Zitate, Suche, frei wählbare Gruppen – bewusst nicht umgesetzt

-## Phase 9 – Härtung
+## 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
+
+## 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
+- [ ] 10b: KI-Erzeugung per Prompt (z. B. „20 Aufgaben Mathe, 3. Klasse, leicht bis schwer“) als Entwurf, Eltern prüfen/ändern vor dem Zuweisen, Mathe-Lösungen serverseitig nachrechnen
+- [ ] 10c: Papierlösung per Foto (Upload je Aufgabe/Blatt), Prüfung manuell durch Eltern, danach KI-Prüfung mit Sicherheitsangabe und Eltern-Bestätigung
+- [ ] Rechte `LearningManage`/`LearningSolve`: Kinder sehen nur eigene Blätter, nie Musterlösungen oder Prompts (serverseitig); Foto-Aufbewahrungsfrist
+
+## Phase 11 – Härtung
 - [ ] Content-Security-Policy (Basis-Header X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, HSTS sind seit Phase 1 aktiv)
 - [ ] Eigener SQL-Login mit minimalen Rechten statt `sa` für Api/MigrationService
 - [ ] Service-Worker-Cache-Version automatisch beim Build setzen
@@ -116,7 +130,7 @@ Legende: `[x]` erledigt, `[ ]` offen. Nach jeder Phase: Build ohne Warnungen, Te
 - [ ] Tests vervollständigen (Policies, ICS, Wiederholungen, Integration)
 - [ ] Barrierefreiheit (WCAG 2.1 AA), Performance (AOT/Trimming prüfen, Lazy Loading)

-## Phase 10 – Deployment
+## Phase 12 – Deployment
 - [ ] Finale `docker-compose.yml` (inkl. optionalem Caddy), `.env.example`
 - [ ] Backup-/Restore-Skripte
 - [ ] README: Voraussetzungen, Entwicklung, Konfiguration, Deployment, Update, Backup/Restore, Kalender-Abos
@@ -15,4 +15,4 @@
  ebenso realistisch bei schwachem Mobilfunk).

 ## Konsequenzen
-Updates des Service Workers erfordern ein Hochzählen der Cache-Version (Automatisierung im Build: Phase 9).
+Updates des Service Workers erfordern ein Hochzählen der Cache-Version (Automatisierung im Build: Phase 11).
@@ -0,0 +1,48 @@
+# ADR-0020: KI-Anbindung – gemeinsame Schnittstelle, Anbieter per Admin-Einstellung
+
+* Status: vorgeschlagen (Phase 9)
+* Datum: 2026-10-10
+
+## Kontext
+Lernaufgaben (ADR-0021) sollen von einer KI erzeugt und ausgewertet werden. Die Anbindung soll später auch für andere Bereiche nutzbar sein
+(z. B. Essensvorschläge, Zusammenfassungen) und im Admin-Bereich konfiguriert werden. Gewünschte Anbieter: Ollama, Claude, Perplexity;
+Copilot ist ausdrücklich ein Wunsch, hat aber keine offene API für Dritt-Apps (siehe unten).
+
+## Entscheidung
+1. **Eigene schmale Abstraktion** im Api-Projekt (Feature `Features/Ai`), nicht ein Framework: `IAiProvider` mit
+   `CompleteAsync(AiRequest, ct)` → `AiResponse`. `AiRequest` enthält Systemanweisung, Nachrichten (Text und optional Bilder),
+   gewünschtes JSON-Schema für strukturierte Antworten, Token-/Zeitlimit. Fachlogik (Aufgaben erzeugen, Foto prüfen) kennt nur diese Schnittstelle
+   und nie einen konkreten Anbieter.
+2. **Anbieter (Phase 9):**
+   * **Ollama** (`/api/chat`, lokal im Heimnetz; Bilder nur mit Vision-Modell, z. B. `qwen2.5vl`, `llava`).
+   * **Claude** (Anthropic Messages API, Bilder und strukturierte Ausgabe unterstützt).
+   * **Perplexity** über die **OpenAI-kompatible** Chat-Completions-Schnittstelle. Derselbe Adapter bedient später jeden OpenAI-kompatiblen Dienst
+     (Azure OpenAI, GitHub Models, LM Studio, vLLM). Perplexity ist auf Recherche ausgelegt und für Foto-Prüfung nur eingeschränkt geeignet;
+     die Fähigkeiten stehen je Anbieter in `AiCapabilities` (Text, Bilder, strukturierte Ausgabe), die UI bietet nur Passendes an.
+   * **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).
+   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.
+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.
+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).
+8. **Tests:** Adapter gegen einen Fake-HTTP-Server (Anfrageformat, Fehler, Zeitüberschreitung, kaputte JSON-Antwort); Fachlogik gegen einen
+   `FakeAiProvider`. Integrationstests nutzen nie echte Anbieter.
+
+## Folgen
+* Ein weiterer Admin-Bereich („KI“) mit Anbieterliste, Zweck-Zuordnung und Verbindungstest.
+* Neue Permission `AiUse` (Admin/Familie voll, Kind/Gast keine) mit Policy und Unit-Tests je Matrixzelle (ADR-0008).
+* Kosten und Datenabfluss liegen in der Verantwortung des Admins; die Oberfläche macht beides sichtbar (Hinweis, Tageslimits, Audit).
+
+## Offene Fragen
+Modell-Empfehlungen je Anbieter (Rechnen/Lesen von Handschrift), Umgang mit Anbieter-Ausfall (Fallback-Anbieter?), Streaming (nicht nötig, solange Aufgaben als Ganzes erzeugt werden).
@@ -0,0 +1,56 @@
+# ADR-0021: Lernaufgaben – manuell oder per KI, digital oder auf Papier
+
+* Status: vorgeschlagen (Phase 10)
+* Datum: 2026-10-10
+
+## Kontext
+Eltern wollen Kindern Lernaufgaben geben: manuell erstellt oder von einer KI nach Prompt erzeugt („20 Aufgaben Mathe für einen Drittklässler – von leicht
+bis schwer“). Das Kind löst digital in der App oder auf Papier (Foto); die Lösung prüfen Eltern oder die KI. Grundlage ist die KI-Anbindung (ADR-0020).
+Lernaufgaben sind **kein** Teil der Familienaufgaben (ADR-0014): eigene Entität, aber optional mit einer Familienaufgabe/einem Ämtchen verknüpfbar
+(„Übungsblatt erledigt“ → Punkte, Eltern-Bestätigung wiederverwenden).
+
+## Entscheidung
+1. **Modell:**
+   * `LearningSet` (Übungsblatt): Titel, Fach, Klassenstufe, Schwierigkeitsverlauf, Zielperson (Kind), Fälligkeit, Status
+     (Entwurf → Zugewiesen → In Arbeit → Abgegeben → Geprüft), Quelle (`Manual` | `Ai`), bei KI der verwendete Prompt/Anbieter/Modell.
+   * `LearningItem` (Aufgabe): Reihenfolge, Frage (Text, bei Mathe optional als Formel-Text), Antworttyp (`Number`, `Text`, `SingleChoice`, `Paper`),
+     Musterlösung, Hinweis/Erklärung, Schwierigkeitsstufe, Punkte.
+   * `LearningAttempt` (Bearbeitung): je Aufgabe die Kinderantwort (digital) und/oder Foto-Verweis, Bewertung (`Correct`, `Partial`, `Wrong`, `Open`),
+     Bewerter (`Auto`, `Ai`, `Parent`), Begründung, Zeitstempel. Wiederholungen werden als weitere Versuche gespeichert.
+   * `LearningPhoto`: Foto der Papierlösung (Datenbank wie ADR-0009/0019, PNG/JPEG/WebP ≤ 5 MB, Typ aus Signatur, nur für Kind, Eltern, Admin abrufbar,
+     nach Prüfung und Aufbewahrungsfrist löschbar).
+2. **Erzeugung:**
+   * **Manuell:** Editor für Übungsblätter und Aufgaben (Eltern); Aufgaben aus früheren Blättern wiederverwendbar.
+   * **Per KI:** Eltern geben Prompt (Freitext) plus optionale Felder (Fach, Klassenstufe, Anzahl, Schwierigkeit). Die Anwendung baut daraus eine feste
+     Systemanweisung (Antwort ausschließlich als JSON nach Schema: Frage, Antworttyp, Lösung, Hinweis, Stufe) und lässt die KI nur diese Struktur füllen.
+     Das Ergebnis erscheint **als Entwurf**: Eltern sehen, ändern und streichen Aufgaben, bevor sie zugewiesen werden. Nichts geht ungeprüft an Kinder.
+     Mathe-Lösungen werden, wo möglich, **serverseitig nachgerechnet** (Zahlenantworten einfacher Ausdrücke), Abweichungen markiert.
+3. **Lösen digital:** Kind sieht Aufgaben einzeln oder als Liste (Kinderansicht wie bei Ämtchen), antwortet je nach Typ; Zahlen/Auswahl werden **ohne KI**
+   sofort automatisch bewertet (Toleranz/Normalisierung für Zahlen, Komma/Punkt), Freitext geht an die Prüfung. Zwischenstände werden gespeichert.
+4. **Lösen auf Papier:** Kind fotografiert (Kamera/Datei), lädt ein Foto je Aufgabe oder je Blatt hoch. Prüfung:
+   * **Manuell:** Eltern sehen Foto neben Aufgabe und Musterlösung und bewerten.
+   * **Per KI:** nur wenn ein Anbieter mit Bildfähigkeit zugeordnet und „Bilder erlaubt“ aktiv ist (ADR-0020, Punkt 5); die KI liefert je Aufgabe
+     erkannte Antwort, Bewertung, Begründung und eine **Sicherheitsangabe**. Niedrige Sicherheit oder unleserliche Schrift → „Eltern prüfen“.
+   * KI-Bewertungen sind **Vorschläge**: standardmäßig bestätigen Eltern; die Einstellung „KI-Bewertung gilt direkt“ ist optional und je Blatt wählbar.
+5. **Rechte (neue Permissions in der Matrix):** `LearningManage` (Blätter anlegen/zuweisen/prüfen, KI nutzen): Admin/Familie voll;
+   `LearningSolve` (eigene Blätter lösen, Fotos hochladen): Kind eingeschränkt auf eigene, Gast keine. Kinder sehen **nie** Musterlösungen und
+   Prompts und nur ihre eigenen Blätter; serverseitig erzwungen (404 für fremde).
+6. **Punkte/Ämtchen (optional):** Ein Blatt kann Punkte vergeben (Anteil richtiger Aufgaben); Gutschrift über das vorhandene Punktebuch nach Elternbestätigung
+   (kein Doppelzählen, Rückbuchung beim erneuten Öffnen wie bei Ämtchen).
+7. **Datenschutz/Sicherheit:** Fotos und Antworten von Kindern verlassen das Heimnetz nur zu Anbietern mit ausdrücklicher Freigabe; die Prompts enthalten keine
+   Namen; Aufbewahrungsfrist für Fotos einstellbar (Standard 30 Tage nach Prüfung); KI-Ausgaben werden als Text angezeigt (kein HTML); Audit-Eintrag je
+   KI-Aufruf (ADR-0020).
+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).
+
+## 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.
+
+## Phasenschnitt
+* Phase 9: KI-Anbindung (ADR-0020) inklusive Admin-Einstellungen, Testbarkeit, Audit, Tageslimits.
+* Phase 10a: Lernaufgaben manuell + digital lösen + automatische Bewertung + Elternprüfung.
+* Phase 10b: KI-Erzeugung (Entwurf-Assistent).
+* 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?
@@ -3,7 +3,7 @@ namespace FamilyPlanner.Web;
 internal static class SecurityHeaders
 {
    /// <summary>
-    /// Grundlegende Security-Header. Eine vollständige Content-Security-Policy folgt in Phase 9 (Härtung),
+    /// Grundlegende Security-Header. Eine vollständige Content-Security-Policy folgt in Phase 11 (Härtung),
    /// sobald alle Inline-Skripte des Blazor-Hosts per Hash/Nonce erfasst sind.
    /// </summary>
    public static IApplicationBuilder UseSecurityHeaders(this IApplicationBuilder app) =>