buBailai/quickform-teaching-tool

QuickForm Interaktives Unterrichtstool erstellen – Skill

Übersicht

Dieser Skill hilft Lehrenden, schnell professionelle interaktive HTML-Unterrichtstools zu erstellen, die automatisch an die QuickForm-Datenerfassungsplattform angebunden werden und schließlich ein Datenanalyse-Dashboard generieren. Der gesamte Prozess erfolgt in 8 Schritten.

---

Schritt 1: QuickForm-Version und Konto bestätigen

Frage den Benutzer nach der verwendeten Version

Stelle dem Benutzer die Frage:

„Welche QuickForm-Version möchtest du verwenden?

• A. Offizielle Cloud-Version (https://quickform.cn)
• B. Lokale Version (Lokale Netzwerkinstallation)“

Offizielle Cloud-Version

1. Überprüfe, ob die Datei mit den Anmeldeinformationen ~/.claude/quickform_credentials.json existiert:

   cat ~/.claude/quickform_credentials.json 2>/dev/null
   

2. Wenn die Datei existiert und official.username und official.password enthält, verwende diese direkt, ohne erneut nachzufragen. Teile dem Benutzer mit: „Das zuletzt gespeicherte Konto wird verwendet: xxx“
3. Wenn sie nicht existiert, frage nach dem offiziellen Kontonamen und Passwort und speichere sie in der Cache-Datei:

   {
     "official": {
       "username": "vom Benutzer bereitgestellter Kontoname",
       "password": "vom Benutzer bereitgestelltes Passwort"
     }
   }
   

   Schreibe mit bash: echo '{"official":{"username":"xxx","password":"xxx"}}' > ~/.claude/quickform_credentials.json

Lokale Version

1. Standard-Konto: wst, Standard-Passwort: quickform (dies sind die werkseitigen Standardwerte für lokale Installationen, die unverändert bleiben)

2. Die lokale Adresse automatisch ermitteln (Versuche es in der folgenden Reihenfolge):

   Erster Schritt: Überprüfen, ob eine gespeicherte Adresse existiert

   cat ~/.claude/quickform_credentials.json 2>/dev/null
   

   Wenn das JSON bereits ein Feld local.base_url enthält, verwende es direkt und teile dem Benutzer mit: „Die zuletzt gespeicherte lokale Adresse wird verwendet: xxx“. Überspringe die nachfolgenden Prüfungen.

   Zweiter Schritt: Automatische Erkennung der lokalen IP + Port 5001 Wenn keine gespeicherte Adresse vorhanden ist, ermittle zuerst die lokale IP-Adresse des Rechners mit Python:

   import socket
   s = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
   s.connect(("8.8.8.8", 80))
   local_ip = s.getsockname()[0]
   s.close()
   print(local_ip)
   

   Erstelle daraus http://<local_ip>:5001 und überprüfe dann, ob die Adresse erreichbar ist:

   curl -s -o /dev/null -w "%{http_code}" http://<local_ip>:5001/
   

   • Bei Rückgabe von 200 oder 302: Teile dem Benutzer mit: „Lokale Adresse automatisch erkannt: http://<local_ip>:5001, wird verwendet“ und speichere sie in der Datei mit den Anmeldeinformationen.
   • Bei Verbindungsfehler: Fahre mit dem dritten Schritt fort.

   Dritter Schritt: Automatische Erkennung fehlgeschlagen – Benutzereingabe erforderlich

   Die automatisch erkannte Adresse http://<local_ip>:5001 ist nicht erreichbar. Bitte gib die Zugriffsadresse deiner lokalen QuickForm-Installation manuell ein
   (z. B. http://192.168.1.100:5001):
   

   Nach Eingabe durch den Benutzer erneut überprüfen. Bei Erfolg speichern.

   Speichere die Adresse in der Datei mit den Anmeldeinformationen:

   python3 -c "
   import json, os
   path = os.path.expanduser('~/.claude/quickform_credentials.json')
   try:
       d = json.load(open(path))
   except:
       d = {}
   d.setdefault('local', {})['base_url'] = 'http://endgültig_bestaetigte_adresse'
   json.dump(d, open(path, 'w'), ensure_ascii=False)
   print('Adresse gespeichert')
   "
   

3. Frage den Benutzer: „Ist der lokale QuickForm-Dienst bereits gestartet? Wenn nicht, starte ihn bitte zuerst.“

In allen nachfolgenden Schritten wird die Variable LOCAL_BASE_URL für die lokale Adresse verwendet (ermittelt aus dem obigen Prozess). Keine fest codierte IP verwenden.

---

Schritt 2: Design-Stil des Unterrichtstools festlegen

Stelle dem Benutzer die Frage (biete Optionen zur Orientierung an, erlaube aber auch freie Beschreibungen):

„Wähle den Design-Stil für das Unterrichtstool (Mehrfachauswahl oder eigene Beschreibung möglich):

1. 🎨 Schlicht und modern — Kartenlayout, frische Farben, geeignet für die meisten Szenarien
2. 🌈 Farbverlauf und bunt – Lebendige Verläufe, dynamische Effekte, ideal für aktive Klassen
3. 🌙 Dunkelmodus – Dunkler Hintergrund, fluoreszierende Farben, passend für technikorientierte Kurse
4. 🎠 Kinderfreundlich – Runde, niedliche Elemente, helle Cartoon-Farben, geeignet für die Grundschule (Unterstufe)
5. 📊 Akademisch und professionell – Sauber und strukturiert, datenorientiert, geeignet für Oberstufe oder Universität
6. 🖌️ Benutzerdefiniert – Beschreibe den gewünschten Stil“

Frage auch nach:

• Zielaltersgruppe / Klassenstufe (z. B. 3. Klasse Grundschule, 2. Klasse Mittelschule, Oberstufenschüler, Universitätsstudenten)
• Fach (z. B. Deutsch, Mathematik, Englisch, Naturwissenschaften, Informatik, Geschichte usw.)

---

Schritt 3: Detaillierte Anforderungen an das Unterrichtstool erfassen

Dieser Schritt erfordert ausreichend detaillierte Informationen, bevor mit der Entwicklung begonnen werden kann. Die folgenden drei Dimensionen müssen abgedeckt werden:

3.1 Anforderungen an die Interaktionsmethode

Es muss klar sein:

• Was ist die Kernfunktion des Unterrichtstools (Abstimmung / Umfrage / Quiz / Experimentprotokoll / Aufgabeneinreichung / Diskussion / spielerische Übung usw.)
• Wie interagieren die Schüler mit dem Tool (Anklicken von Optionen / Texteingabe / Drag & Drop / Zeichnen / Beantwortung mit Timer usw.)
• Ist eine sofortige Rückmeldung erforderlich (sofortige Anzeige von richtig/falsch oder Erklärung nach der Antwort)?

Wenn die Beschreibung des Benutzers vage ist, frage aktiv nach:

„Welche Aktionen sollen die Schüler auf dieser Seite ausführen? Was sehen sie, wenn sie fertig sind?“

3.2 Datenübermittlungsfelder

Jedes zu erfassende Feld muss definiert werden:

• Feldname (Englischer Key, für die API)
• Feldbedeutung (Chinesische Erklärung – hier ins Deutsche übersetzt)
• Feldtyp (Text / Zahl / Option / Zeit usw.)

Wenn der Benutzer keine Felder erwähnt, leite ihn an:

„Welche Informationen möchtest du von den Schülern sammeln? Z. B.: Name, Klasse, Antwortmöglichkeit, Punktzahl, Bearbeitungszeit usw. Bitte nenne sie einzeln.“

Beispiel für das Feldformat (dient als Referenz; die tatsächlichen Anforderungen des Benutzers haben Vorrang):

student_name: Schülername (Text)
class: Klasse (Text)
answer: Antwortmöglichkeit (A/B/C/D)
score: Punktzahl (Zahl)
duration: Bearbeitungszeit in Sekunden (Zahl)

3.3 Anforderungen an Datenanalyse / Visualisierungs-Dashboard

Es muss klar sein:

• Welche Diagramme werden gewünscht (Balkendiagramm / Tortendiagramm / Liniendiagramm / Wortwolke / Rangliste usw.)
• Datenstatistik-Dimensionen (Vergleich nach Klasse / Antwortverteilung / Richtigkeit / Durchschnittspunktzahl / Zeittrends usw.)
• Gesamtstil des Dashboards (übereinstimmend mit dem Unterrichtstool / eigenständiger Stil / Präsentationsstil für Projektion)
• Ist eine Echtzeitaktualisierung erforderlich?

Wenn die Informationen nicht ausreichen, frage nach:

„Welche Daten möchtest du der ganzen Klasse im Unterricht zeigen? Sollen die Schüler sehen, wo sie im Vergleich zur gesamten Klasse stehen?“

Bestätigung der Anforderungen

Nachdem die obigen drei Dimensionen erfasst wurden, erstelle eine Zusammenfassung der Anforderungen und zeige sie dem Benutzer zur Bestätigung an. Verwende folgendes Format:

📋 Zusammenfassung der Anforderungen zur Bestätigung

[Basisinformationen]
- QuickForm-Version: Offizielle Cloud-Version / Lokale Version
- Design-Stil: xxx
- Klassenstufe: xxx   Fach: xxx

[Interaktion des Unterrichtstools]
- Funktionstyp: xxx
- Interaktionsmethode: xxx
- Sofortige Rückmeldung: Ja / Nein

[Datenerfassungsfelder]
- field1: Bedeutung (Typ)
- field2: Bedeutung (Typ)
...

[Anforderungen an das Visualisierungs-Dashboard]
- Diagrammtypen: xxx
- Statistik-Dimensionen: xxx
- Echtzeitaktualisierung: Ja / Nein

Warte auf die Bestätigung des Benutzers, bevor du mit Schritt 4 fortfährst.

---

Schritt 4: Aufgabe in QuickForm erstellen

Erstelle basierend auf der in Schritt 1 gewählten Version die entsprechende QuickForm-Aufgabe.

Namenskonvention für Aufgaben: Benenne die Aufgabe nach dem Thema des Unterrichtstools, prägnant und klar (z. B. „Mathe-Additions- und Subtraktionsübung 3. Klasse“, „Chemie-PSE-Quiz Oberstufe“).

Offizielle Cloud-Version erstellen

curl -s -X POST https://quickform.cn/cli/add \
  -H "Content-Type: application/json" \
  -d '{"username":"<Kontoname>","password":"<Passwort>","task_name":"<Aufgabenname>","description":"<Kurzbeschreibung des Tools>"}'

Beispiel für eine erfolgreiche Antwort: {"success":true,"apiid":"k5egb0lbzi"}

• Dateneinreichungs-Endpunkt: https://quickform.cn/api/<apiid>
• Datenabruf-Endpunkt: https://quickform.cn/api/<apiid>/all

Lokale Version erstellen

Die lokale Version hat keine /cli/add-Schnittstelle. Verwende stattdessen eine Python-Session zum Anmelden und Erstellen der Aufgabe und extrahiere die echte API-ID aus der Aufgabenseite:

⚠️ Wichtig: Der API-Endpunkt der lokalen Version ist nicht die numerische Aufgaben-ID (wie /api/10), sondern eine vom System für jede Aufgabe generierte zufällige Zeichenfolge (wie /api/C9VaWGMQEZY). Diese muss nach dem Anmelden aus dem HTML der Aufgabendetailseite extrahiert werden. Die numerische ID kann nicht direkt zum Senden von Daten verwendet werden.

import urllib.request, urllib.parse, http.cookiejar, re

cj = http.cookiejar.CookieJar()
opener = urllib.request.build_opener(urllib.request.HTTPCookieProcessor(cj))

# 1. Anmelden
login_data = urllib.parse.urlencode({'username': 'wst', 'password': 'quickform'}).encode()
req = urllib.request.Request('<LOCAL_BASE_URL>/login', data=login_data)
req.add_header('Content-Type', 'application/x-www-form-urlencoded')
opener.open(req)

# 2. Aufgabe erstellen
task_data = urllib.parse.urlencode({'title': '<Aufgabenname>', 'description': '<Kurzbeschreibung des Tools>'}).encode()
req2 = urllib.request.Request('<LOCAL_BASE_URL>/create_task', data=task_data)
req2.add_header('Content-Type', 'application/x-www-form-urlencoded')
resp = opener.open(req2)
final_url = resp.geturl()  # Weiterleitung zu /task/<numerische_id>
numeric_id = re.search(r'/task/(\d+)', final_url).group(1)

# 3. Echte API-ID aus der Aufgabendetailseite extrahieren (zufällige Zeichenfolge, keine Zahl)
req3 = urllib.request.Request(f'<LOCAL_BASE_URL>/task/{numeric_id}')
resp3 = opener.open(req3)
html = resp3.read().decode('utf-8')
api_links = re.findall(r'/api/([a-zA-Z0-9\-_]+)', html)
real_api_id = list(set(api_links))[0]  # Echte API-ID

print(f„Numerische Aufgaben-ID: {numeric_id}“)
print(f„Echte API-ID: {real_api_id}“)

• Dateneinreichungs-Endpunkt: <LOCAL_BASE_URL>/api/<real_api_id>
• Datenabruf-Endpunkt: <LOCAL_BASE_URL>/api/<real_api_id>/all

Das data-Feld der Schnittstellenantwort der lokalen Version liegt im Format eines Python-Dict-Strings (einfache Anführungszeichen) vor. Bei der Analyse im HTML-Dashboard muss es in JSON konvertiert werden (einfache Anführungszeichen durch doppelte ersetzen).

Endpunkt-Informationen notieren

Notiere die folgenden Informationen für die nachfolgenden Schritte:

• SUBMIT_URL: Adresse des Dateneinreichungs-Endpunkts
• FETCH_URL: Adresse des Datenabruf-Endpunkts
• TASK_NAME: Aufgabenname

---

Schritt 5: Interaktive HTML-Seite für das Unterrichtstool entwickeln

Erstelle basierend auf allen gesammelten Anforderungen eine vollständige, einzelne HTML-Datei für das Unterrichtstool.

Technische Spezifikationen

Zwingend zu beachtende Prinzipien:

• Einzelne HTML-Datei, alle CSS- und JS-Ressourcen inline eingebunden
• Verwende CDNs, die vom chinesischen Festland aus zuverlässig erreichbar sind (siehe Liste unten)
• Datenübermittlungsadresse ist SUBMIT_URL
• Nach erfolgreicher Übermittlung klares Feedback für die Schüler (Erfolgsmeldung / Punktzahl / Erklärung)
• Die Seite muss sowohl auf dem Handy als auch auf dem Computer korrekt angezeigt werden (responsiv)

Empfohlene CDNs (vom chinesischen Festland aus erreichbar):

<!-- Tailwind CSS -->
<script src="https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4"></script>

<!-- ECharts-Diagramme (für Visualisierungsseiten) -->
<script src="https://cdn.jsdelivr.net/npm/echarts@5/dist/echarts.min.js"></script>

<!-- Font Awesome Icons -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@fortawesome/fontawesome-free@6/css/all.min.css">

<!-- Alpine.js für leichte Interaktivität -->
<script defer src="https://cdn.jsdelivr.net/npm/alpinejs@3/dist/cdn.min.js"></script>

Code-Vorlage für die Dateneinreichung:

async function submitData(formData) {
  try {
    const response = await fetch('SUBMIT_URL', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(formData)
    });
    const result = await response.json();
    return result;
  } catch (error) {
    console.error('Einreichung fehlgeschlagen:', error);
    return null;
  }
}

Qualitätsanforderungen an das Unterrichtstool

• Das Seitenthema ist klar und entspricht dem gewählten Design-Stil
• Die Schriftgröße ist für die Zielaltersgruppe angemessen (für Kinder größere Schrift)
• Interaktionselemente haben klares visuelles Feedback (Hover-Effekte, Klick-Animationen)
• Der Einreichungsbutton ist auffällig und der Einreichungsprozess ist einfach (wenige Schritte)
• Enthält einen Titel für das Unterrichtstool und eine kurze Bedienungsanleitung
• Alle Formularfelder entsprechen genau den in Schritt 3.2 definierten Feldern

Datei speichern

Speichere das generierte HTML im aktuellen Arbeitsverzeichnis. Namenskonvention: <Aufgabenname_Unterrichtstool>.html (Leerzeichen durch Unterstriche ersetzen)

---

Schritt 6: Automatisch 3 Testdatensätze einreichen

Generiere basierend auf der Feldstruktur des Unterrichtstools 3 realitätsnahe Testdatensätze und reiche sie ein.

Prinzipien für Testdaten:

• Die Daten sollten sich unterscheiden (nicht alle drei identisch)
• Die Daten sollten realistisch sein (echte Schülernamen, sinnvolle Notenverteilung)
• Verschiedene Szenarien abdecken (z. B. richtig beantwortet, falsch beantwortet, verschiedene Klassen)

Einreichungsmethode: Verwende curl, um die Datensätze nacheinander einzureichen

curl -s -X POST "SUBMIT_URL" \
  -H "Content-Type: application/json" \
  -d '{"field1":"value1","field2":"value2",...}'

Nach Abschluss teile dem Benutzer mit: „✅ 3 Testdatensätze erfolgreich eingereicht“

---

Schritt 7: Datenanalyse-Visualisierungs-Dashboard entwickeln

7.1 Testdatenstruktur abrufen

curl -s "FETCH_URL"

Lese die zurückgegebenen vollständigen JSON-Daten und verstehe die Datenstruktur (Feldnamen, Datentypen, Verschachtelungshierarchie).

Notiere die vollständige Datenstruktur als Referenz für die Entwicklung.

7.2 Visualisierungs-Dashboard HTML entwickeln

Entwickle das Dashboard basierend auf den folgenden Informationen:

• In Schritt 7.1 abgerufene tatsächliche Datenstruktur und Felder
• Vom Benutzer in Schritt 3.3 geäußerte Visualisierungswünsche
• Thema und Stil der Unterrichtstool-Seite (für Konsistenz sorgen)

Technische Spezifikationen:

• Einzelne HTML-Datei, gesamter Code inline
• Verwende ECharts (von cdn.jsdelivr.net) zur Darstellung der Diagramme
• Die Seite ruft beim Start automatisch Daten von FETCH_URL ab und rendert sie
• Für Echtzeitaktualisierung verwende setInterval, um alle 10-15 Sekunden zu aktualisieren
• Das Dashboard-Layout eignet sich für die Projektion (16:9-Format bevorzugt, eher große Schrift)

Das Dashboard muss Folgendes enthalten:

• Seitenkopf: Tool-Titel + aktuelle Datenstatistik-Übersicht (Teilnehmerzahl, Durchschnittspunktzahl und andere Kernkennzahlen)
• Hauptbereich: Die vom Benutzer gewünschten Diagramme (mit ECharts)
• Adresse der Datenquelle (kleine Schrift in der Fußzeile)

Code-Vorlage für den Datenabruf:

async function fetchData() {
  const response = await fetch('FETCH_URL');
  const data = await response.json();
  // Datenstruktur basierend auf den in Schritt 7.1 tatsächlich abgerufenen Inhalten verarbeiten
  return data;
}

Datei speichern

Namenskonvention: <Aufgabenname_DatenDashboard>.html

---

Schritt 8: Abschlussbericht

Nach Abschluss der Entwicklung gib dem Benutzer einen kurzen Bericht aus:

🎉 QuickForm Unterrichtstool-Entwicklung abgeschlossen!

📁 Generierte Dateien
  - Unterrichtstool-Seite: <Dateiname>.html
  - Datenanalyse-Dashboard: <Dateiname>.html

🔗 Endpunkt-Informationen
  - Dateneinreichung: SUBMIT_URL
  - Datenabruf: FETCH_URL

📊 Testdaten
  - 3 Testdatensätze eingereicht, können auf der Dashboard-Seite eingesehen werden

💡 Nutzungshinweise
  1. Teile die Unterrichtstool-Seite mit den Schülern (lokale Netzwerk- oder öffentliche Adresse)
  2. Nachdem die Schüler ihre Daten eingereicht haben, öffne das Daten-Dashboard, um die Ergebnisse in Echtzeit anzuzeigen
  3. Wenn du das Layout oder die Felder ändern möchtest, bearbeite die HTML-Dateien direkt

---

Referenzen

• QuickForm API-Dokumentation: Siehe references/quickform-api.md
• Beispiele für Visualisierungsdiagramme: Siehe references/echarts-examples.md
• In China verfügbare CDN-Liste: Siehe references/china-cdn.md