1SanTi/survey-design-collector

Générateur de conception de questionnaires et de système de collecte en ligne

Transformez une « demande de questionnaire » en un pack de trois prêt à l'emploi :

1. Questionnaire Word (mise en page standardisée, imprimable, distribuable)
2. Site web de réponse en ligne (réponse par scan de code QR, zéro dépendance, double-clic pour lancer)
3. Tableau de bord de données backend (graphiques statistiques automatiques pour chaque question + détails + export Excel en un clic + code QR de réponse)

L'ensemble du processus nécessite zéro dépendance tierce (uniquement la bibliothèque standard Python), et les livrables peuvent être copiés sur n'importe quel ordinateur et exécutés directement.

---

Quand utiliser

• L'utilisateur fournit un enregistrement audio / du texte / une transcription orale et demande « concevoir un questionnaire », « concevoir un questionnaire à partir d'un enregistrement ».
• L'utilisateur a déjà des questions et souhaite les transformer en questionnaire en ligne / site de réponse par scan de code avec agrégation automatique des données.
• L'utilisateur demande une solution complète « enquête par questionnaire + statistiques backend ».

---

Processus d'exécution (SOP)

Étape 1 – Obtenir et comprendre le besoin

• Enregistrement : utilisez d'abord la reconnaissance vocale pour transcrire l'audio en texte (avec le skill speech-to-text ou directement via fetch du fichier audio), puis extrayez : le thème du questionnaire, le public cible, le nombre de sections (dimensions), les questions spécifiques de chaque dimension, la préférence de type de question (choix unique / choix multiple / échelle / texte libre).
• Texte : lisez directement le plan fourni par l'utilisateur.
• En cas de doute (ex. ajouter une section « informations de base », pour quelle organisation), soit compléter par convention et le mentionner lors de la livraison, soit confirmer avec l'utilisateur.

Étape 2 – Rédiger le cahier des charges du questionnaire questions.json

Respectez strictement le format de references/spec-format.md pour rédiger le questionnaire en JSON :

• Niveau supérieur : title (titre), subtitle, intro (préambule), footer, scale_options (échelle à cinq niveaux), sections.
• Dans chaque section, questions[] avec pour chaque question : id, type, title, required ; les questions à choix contiennent options.
• Types de questions : single (choix unique) | multi (choix multiple) | scale (échelle, les options sont scale_options) | text (texte libre).
• allow_other: true ajoute automatiquement « Autre (précisez) » ; exclusive: ["jamais utilisé"] signifie que cette option est exclusive des autres.
• Recommandation : un questionnaire formel inclut généralement une section concise « Informations de base » (niveau / matière / ancienneté) pour faciliter les analyses croisées ultérieures.

Points de conception : les énoncés doivent être déclaratifs, éviter les biais ; les options doivent être exhaustives et mutuellement exclusives ; l'échelle doit être uniforme ; le nombre de questions doit permettre une réponse en 3 à 5 minutes.

Étape 3 – Générer le pack en un clic

python3 scripts/build_survey.py --spec questions.json --out <répertoire_de_sortie>
# Si l'URL finale de réponse est connue, ajoutez --url http://xxx/ pour générer directement le QR code

Livrables :

<répertoire_de_sortie>/  
├── <titre_questionnaire>.docx          Questionnaire Word formaté
└── Système de questionnaire en ligne/
    ├── server.py                       Page de réponse + backend + interface (zéro dépendance)
    ├── questions.json                  Questions du questionnaire
    ├── Lancement_Windows.bat / Lancement_Mac_Linux.sh    Lancement en un clic
    ├── make_qr.py                      Génération autonome de QR code
    ├── vendor/qrcode/                  Générateur de QR code intégré
    └── Mode_d_emploi.md

Étape 4 – Auto-vérification (obligatoire)

• Ouvrez questions.json dans le répertoire généré, vérifiez que les questions, options et marquages obligatoires sont corrects.
• Lancez le système pour un test de fumée :

  cd <Système de questionnaire en ligne> && PORT=8123 python3 server.py &
  curl -s http://127.0.0.1:8123/ | head            # Page de réponse accessible
  curl -s -X POST http://127.0.0.1:8123/submit --data-urlencode "q1=..." # Soumission réussie
  curl -s http://127.0.0.1:8123/api/stats | head   # Statistiques correctes
  

• Vérifiez que les questions et options ne sont pas coupées en deux pages dans le fichier Word (le script intègre déjà keep-with-next).

Étape 5 – Livraison et instructions de déploiement

Expliquez à l'utilisateur :

• Comment utiliser chaque élément du pack ; le QR code s'affiche automatiquement sur la page backend (http://IP_ordinateur:8000/admin).
• Comment les enseignants accèdent au système : scannez le code QR sur le même réseau WiFi (le plus courant en milieu scolaire) ; pour un accès public, il faut héberger sur un serveur avec une IP publique.
• Consultez references/deploy-guide.md pour les instructions complètes, réutilisables telles quelles.
• Utilisez provide_file pour livrer le questionnaire Word et l'archive compressée du « Système de questionnaire en ligne » à l'utilisateur.

Étape 6 (Optionnelle) – Archivage

Si nécessaire, utilisez le skill upload-to-kb pour enregistrer le questionnaire Word et l'archive système dans la base de connaissances spécifiée par l'utilisateur.

---

Points clés et astuces

• Zéro dépendance est l'avantage clé : seul Python standard + vendor/qrcode intégré sont utilisés, l'utilisateur n'a pas besoin d'installer de package pip ; la génération du Word nécessite python-docx (uniquement sur l'environnement de génération).
• La page de réponse utilise du HTML pur + un peu de JS : la soumission se fait via POST /submit, le serveur valide les champs obligatoires (les champs manquants sont signalés en rouge avec les réponses déjà saisies conservées).
• Le QR code est généré côté serveur en SVG en temps réel (/api/qr.svg?url=...), la page backend l'affiche automatiquement selon l'URL de l'utilisateur ; si le réseau change, le QR code se met à jour sans nécessiter de nouvelle compilation.
• Les données sont stockées dans data/responses.db (SQLite) : sauvegarde = copier ce fichier, effacement = supprimer ce fichier.
• Si l'accès local ne fonctionne pas, 90% du temps c'est le pare-feu de l'ordinateur qui bloque Python ; invitez l'utilisateur à autoriser Python.
• En cas de conflit de port, utilisez PORT=8080 python3 server.py pour changer de port.

---

Structure du répertoire

survey-design-collector/
├── SKILL.md
├── scripts/
│   ├── build_survey.py    Génération en un clic (lit spec → Word + site + QR code)
│   ├── spec_to_word.py    Génère le questionnaire Word à partir de questions.json
│   └── make_qr.py         Génère un QR code PNG à partir d'une URL
├── assets/app/            Template du système de questionnaire en ligne (server.py / scripts de lancement / vendor/qrcode)
└── references/
    ├── spec-format.md     Spécification de questions.json + méthode de transcription audio en questionnaire
    └── deploy-guide.md    Modèle d'instructions de déploiement et de communication externe