1SanTi/survey-design-collector

Fragebogendesign und Generator für Online-Erfassungssysteme

Wandeln Sie eine „Fragebogenanforderung“ in ein sofort nutzbares Dreierpaket um:

1. Word-Fragebogen (professionell formatiert, druck- und verteilbar)
2. Online-Antwort-Website (per QR-Code auf dem Handy scannbar, keine Abhängigkeiten, sofort startbereit)
3. Backend-Daten-Dashboard (automatische Statistikgrafiken für jede Frage + Detailansicht + Export als Excel + Antwort-QR-Code)

Keine Drittanbieter-Abhängigkeiten (nur Python-Standardbibliothek), die Ausgabe kann auf jeden Computer kopiert und sofort ausgeführt werden.

---

Wann zu verwenden

• Der Benutzer gibt eine Audioaufnahme / Diktat / Text und fordert: „Erstelle einen Fragebogen“ / „Erstelle einen Fragebogen basierend auf der Audioaufnahme“.
• Der Benutzer hat bereits Fragen und möchte daraus einen Online-Fragebogen / Website zum Scannen und Antworten machen, der Daten automatisch sammelt.
• Der Benutzer möchte eine vollständige Lösung für eine „Umfrage + Backend-Statistik“.

---

Ausführungsablauf (SOP)

Schritt 1: Anforderung erfassen und verstehen

• Audio: Wandeln Sie die Audioaufnahme zuerst mit Sprache-zu-Text um (mit dem speech-to-text-Skill oder per fetch der Audiodatei). Extrahieren Sie: Fragebogenthema, Zielgruppe, Anzahl der Abschnitte (Dimensionen), konkrete Fragen pro Dimension, Fragetyp (Einfachauswahl/Mehrfachauswahl/Skala/Text).
• Text: Lesen Sie die vom Benutzer gegebene Gliederung direkt.
• Bei Unklarheiten (z.B. ob ein Abschnitt „Basisdaten“ hinzugefügt werden soll, für welche Einrichtung) entweder nach Konvention ergänzen und bei Übergabe erklären, oder beim Benutzer nachfragen.

Schritt 2: Fragebogenspezifikation questions.json schreiben

Halten Sie sich strikt an das Format in references/spec-format.md und schreiben Sie den Fragebogen als JSON:

• Top-Level: title, subtitle, intro (Einleitung), footer, scale_options (fünf Skalenstufen), sections.
• Jeder Abschnitt enthält questions[], jede Frage hat id, type, title, required, bei Auswahlfragen options.
• Fragetypen: single (Einfachauswahl) | multi (Mehrfachauswahl) | scale (Skala; Optionen aus scale_options) | text (Textfeld).
• allow_other: true fügt automatisch „Sonstiges (bitte angeben)“ hinzu; exclusive: ["nie benutzt"] bedeutet, dass diese Option sich mit anderen ausschließt.
• Empfehlung: Fügen Sie zu Beginn einen prägnanten Abschnitt „Basisdaten“ hinzu (z.B. Schulstufe / Fach / Berufserfahrung), um spätere Kreuzauswertungen zu ermöglichen.

Gestaltungshinweise: Formulieren Sie Fragen als Aussagen, vermeiden Sie suggestive Formulierungen; Optionen müssen vollständig und sich gegenseitig ausschließend sein; Skalenstufen einheitlich; Fragenanzahl so bemessen, dass sie in 3–5 Minuten zu beantworten ist.

Schritt 3: Dreierpaket mit einem Befehl generieren

python3 scripts/build_survey.py --spec questions.json --out <Ausgabeverzeichnis>
# Wenn die endgültige Antwort-URL bekannt ist, kann mit --url http://xxx/ direkt der QR-Code generiert werden

Ausgabe:

<Ausgabeverzeichnis>/
├── <Fragebogentitel>.docx          Word-Fragebogen mit professionellem Layout
└── Online-Fragebogen-System/
    ├── server.py                   Antwortseite + Backend + API (keine Abhängigkeiten)
    ├── questions.json              Fragen dieses Fragebogens
    ├── start_Windows.bat / start_Mac_Linux.sh    Ein-Klick-Start
    ├── make_qr.py                  Separater QR-Code-Generator
    ├── vendor/qrcode/              Integrierte QR-Code-Erzeugung
    └── Anleitung.md

Schritt 4: Selbstprüfung (Pflicht)

• Öffnen Sie die generierte Datei Fragen/Online-Fragebogen-System/questions.json und prüfen Sie Fragen, Optionen und Pflichtfeldmarkierungen auf Richtigkeit.
• Starten Sie das System einmal für einen Smoke-Test:

  cd Online-Fragebogen-System && PORT=8123 python3 server.py &
  curl -s http://127.0.0.1:8123/ | head            # Antwortseite erreichbar
  curl -s -X POST http://127.0.0.1:8123/submit --data-urlencode "q1=..." # Antwort speichern
  curl -s http://127.0.0.1:8123/api/stats | head   # Statistik funktioniert
  

• Stellen Sie sicher, dass im Word-Dokument keine Frage oder Option durch einen Seitenumbruch getrennt wird (das Skript hat bereits keep-with-next gesetzt).

Schritt 5: Übergabe und Bereitstellungshinweise

Erklären Sie dem Benutzer:

• Die Verwendung der drei Komponenten; der QR-Code wird automatisch auf der Backend-Seite angezeigt (http://Computer-IP:8000/admin).
• Wie Lehrer darauf zugreifen: Im selben WLAN den QR-Code scannen und direkt antworten (am häufigsten in der Schule). Für den Zugriff aus dem öffentlichen Internet muss das System auf einem Server mit öffentlicher IP bereitgestellt werden.
• Details siehe references/deploy-guide.md (kann direkt wiederverwendet werden).
• Verwenden Sie provide_file, um den Word-Fragebogen und das gepackte „Online-Fragebogen-System“-Archiv an den Benutzer zu übergeben.

Schritt 6 (optional): Archivierung

Falls Archivierung gewünscht ist, legen Sie den Word-Fragebogen und das Systemarchiv mit dem upload-to-kb-Skill im angegebenen Wissensspeicher des Benutzers ab.

---

Wichtige Punkte und Erfahrungen

• Null-Abhängigkeiten als Kernvorteil: Nur Python-Standardbibliothek + integriertes vendor/qrcode; der Benutzer muss nichts mit pip installieren. Für die Word-Generierung wird lediglich python-docx auf dem erzeugenden System benötigt.
• Antwortseite als reines HTML-Formular + minimales JS: Die Übermittlung erfolgt per POST /submit, der Server prüft Pflichtfelder (fehlende Felder werden mit dem bereits eingegebenen Inhalt rot markiert zurückgegeben).
• QR-Code serverseitig als SVG generiert (/api/qr.svg?url=...), die Backend-Seite erzeugt den Code automatisch basierend auf der aktuellen Zugriffs-URL. Bei Netzwerkwechsel oder URL-Änderung wird der Code neu generiert – ohne Neupacken.
• Daten speichern in data/responses.db (SQLite): Backup = Kopie dieser Datei; Leeren = Löschen dieser Datei.
• Wenn die Seite im LAN nicht erreichbar ist: In 90% der Fälle blockiert die Windows-Firewall Python. Bitte den Benutzer anweisen, Python zuzulassen.
• Port-Konflikt: Verwenden Sie PORT=8080 python3 server.py, um den Port zu wechseln.

---

Verzeichnisstruktur

survey-design-collector/
├── SKILL.md
├── scripts/
│   ├── build_survey.py    Ein-Klick-Generierung (liest Spezifikation → Word + Website + QR-Code)
│   ├── spec_to_word.py    Erzeugt Word-Fragebogen aus questions.json
│   └── make_qr.py         Erzeugt QR-Code-PNG aus URL
├── assets/app/            Template für das Online-Fragebogen-System (server.py / Startskripte / vendor/qrcode)
└── references/
    ├── spec-format.md     Fragen-JSON-Spezifikation + Methode zur Audio-Transkription
    └── deploy-guide.md    Bereitstellungs- und Kundeninformationsvorlage