1SanTi/survey-design-collector

Survey Design & Online Collection System Generator

Transform a survey requirement into a ready-to-use three-piece system:

1. Word Questionnaire (professionally formatted, printable, distributable)
2. Online Survey Website (accessible via QR code scan, zero dependencies, double-click to run)
3. Backend Data Dashboard (auto-generated charts per question, response details, one-click Excel export, survey QR code)

The entire workflow uses zero third-party dependencies (only Python standard library), and the output can be copied to any computer and run directly.

---

When to Use

• The user provides a recording / dictation / text and asks to "design a survey" or "design a survey based on the recording."
• The user already has questions and wants to create an online survey / QR-code survey site with automatic data aggregation.
• The user needs a complete solution: "survey + backend statistics."

---

Execution Flow (SOP)

Step 1: Understand the Requirements

• Recording: First, transcribe the recording into text (using speech-to-text skill or directly fetching the audio file). Extract: survey topic, target audience, number of sections (dimensions), specific questions per section, and question type preferences (single choice / multiple choice / scale / fill-in-the-blank).
• Text: Read the user's outline directly.
• If something is unclear (e.g., whether to add a "Basic Information" section, or the target organization), either follow convention, note your assumption in the delivery, or confirm with the user.

Step 2: Write the Survey Specification questions.json

Strictly follow the format in references/spec-format.md, write the survey as JSON:

• Top level: title, subtitle, intro (preamble), footer, scale_options (five scale levels), sections.
• Under each section, questions[] where each question has id, type, title, required, and options for choice-based questions.
• Question types: single (single choice) | multi (multiple choice) | scale (Likert scale, using scale_options) | text (fill-in-the-blank).
• allow_other: true automatically adds an "Other (please specify)" option; exclusive: ["None of the above"] makes that option mutually exclusive with others.
• Suggestion: Formal surveys usually add a concise "Basic Information" section (e.g., grade level / subject / years of teaching experience) to facilitate cross-analysis later.

Design Principles: Use declarative statements for question stems, avoid leading questions; ensure options are exhaustive and mutually exclusive; keep the scale levels consistent; limit the number of questions to take about 3–5 minutes to complete.

Step 3: Generate the Three-Piece System

python3 scripts/build_survey.py --spec questions.json --out <output directory>
# If the final survey URL is known, add --url http://xxx/ to generate the QR code directly

Output structure:

<output directory>/
├── <Survey Title>.docx          # Formatted Word questionnaire
└── OnlineSurveySystem/
    ├── server.py                # Survey page + backend + API (zero dependencies)
    ├── questions.json           # Survey questions for this project
    ├── 启动_Windows.bat / 启动_Mac_Linux.sh    # One-click launchers
    ├── make_qr.py               # Standalone QR code generator
    ├── vendor/qrcode/           # Built-in QR code generation library
    └── 使用说明.md               # User manual

Step 4: Self-Check (Mandatory)

• Open the generated OnlineSurveySystem/questions.json and verify all questions, options, and required flags are correct.
• Start the system once for a smoke test:

  cd OnlineSurveySystem && PORT=8123 python3 server.py &
  curl -s http://127.0.0.1:8123/ | head            # Check if the survey page loads
  curl -s -X POST http://127.0.0.1:8123/submit --data-urlencode "q1=..." # Submit a test response
  curl -s http://127.0.0.1:8123/api/stats | head   # Verify stats work
  

• Open the Word document and ensure question stems and options are not split across pages (the script uses keep-with-next formatting).

Step 5: Delivery & Deployment Instructions

Explain to the user:

• How to use each of the three deliverables; the QR code appears automatically on the admin page (http://computer-ip:8000/admin).
• How teachers access it: On the same Wi-Fi, they scan the QR code to answer (most common in schools). For public internet access, deploy on a server with a public IP.
• Refer to references/deploy-guide.md for text you can reuse directly.
• Use provide_file to deliver the Word document and the zipped "Online Survey System" package to the user for download.

Step 6 (Optional): Archive/Upload

If archiving is needed, use the upload-to-kb skill to store the Word document and the system package into the user's specified knowledge base.

---

Key Points & Tips

• Zero dependency is key: Uses only Python standard library + built-in vendor/qrcode. The user doesn't need to pip install anything. Word generation requires python-docx (only on the generation machine).
• Survey page uses pure HTML forms + minimal JS: Submissions go via POST /submit. The server validates required fields (missing fields will be highlighted in red, with previously filled data preserved).
• QR codes are generated server-side in SVG in real-time (/api/qr.svg?url=...). The admin page automatically generates the QR code based on the current access URL. If the network changes, a new QR code is generated without needing to repackage the system.
• Data is stored in data/responses.db (SQLite). To back up, copy the file; to clear data, delete the file.
• If the admin page is inaccessible on the local network, the cause is 90% likely the computer's firewall blocking Python. Instruct the user to allow Python through the firewall.
• To use a different port, run: PORT=8080 python3 server.py.

---

Directory Structure

survey-design-collector/
├── SKILL.md
├── scripts/
│   ├── build_survey.py    # One-click generator (reads spec -> Word + website + QR code)
│   ├── spec_to_word.py    # Generates Word document from questions.json
│   └── make_qr.py         # Generates QR code PNG from a URL
├── assets/app/            # Online survey system template (server.py / launchers / vendor/qrcode)
└── references/
    ├── spec-format.md     # questions.json format specification + method for converting recordings to surveys
    └── deploy-guide.md    # Deployment and user guide template