1SanTi/survey-design-collector

問卷設計與線上收集系統產生器

把「一份問卷需求」變成可直接使用的三件套：

1. Word 問卷（規範排版，可列印、可散發）
2. 線上答題網站（手機掃碼即答，零依賴，雙擊即用）
3. 後台資料彙總看板（各題自動統計圖表 + 明細 + 一鍵匯出 Excel + 答題二維碼）

全流程零第三方依賴（僅 Python 標準庫），產物可拷到任意電腦直接執行。

---

何時使用

• 用戶給出一段錄音/口述/文字，要求「設計一份問卷」「根據錄音設計問卷」。
• 用戶已有題目，想做成線上問卷 / 掃碼答題網站並自動彙總資料。
• 用戶要一個「調查問卷 + 後台統計」的完整方案。

---

執行流程（SOP）

第 1 步　獲取並理解需求

• 錄音：先用語音轉文字把錄音轉成文字（可用 speech-to-text 技能或直接 fetch 音訊檔案）， 提煉出：問卷主題、面向對象、有幾個板塊（維度）、每個維度下的具體題目、題型偏好（單選/多選/量表/填空）。
• 文字：直接讀用戶給的大綱。
• 不確定的地方（如是否加「基本資訊」板塊、面向哪個單位）要麼按慣例補齊並在交付時說明，要麼向用戶確認。

第 2 步　編寫問卷規格 questions.json

嚴格按 references/spec-format.md 的格式，把問卷寫成 JSON：

• 頂層：title（標題）、subtitle、intro（卷首語）、footer、scale_options（量表五個檔位）、sections。
• 每個 section 下 questions[]，每題含 id、type、title、required，選項題含 options。
• 題型：single 單選｜multi 多選｜scale 量表（選項取 scale_options）｜text 填空。
• allow_other: true 自動加「其他（請註明）」；exclusive: ['都沒用過'] 表示該選項與其他互斥。
• 建議：正式問卷一般先加一個精簡的「基本資訊」板塊（學段 / 學科 / 教齡），便於後續交叉分析。

設計要點：題幹用陳述式、避免誘導；選項窮盡且互斥；量表統一檔位；題目數量控制在 3—5 分鐘可完成。

第 3 步　一鍵生成三件套

python3 scripts/build_survey.py --spec questions.json --out <輸出目錄>
# 若已知最終答題網址，可加 --url http://xxx/ 直接生成二維碼

產物：

<輸出目錄>/
├── <問卷標題>.docx          規範排版的 Word 問卷
└── 線上任卷系統/
    ├── server.py            答題頁 + 後台 + 介面（零依賴）
    ├── questions.json       本問卷題目
    ├── 啟動_Windows.bat / 啟動_Mac_Linux.sh   一鍵啟動
    ├── make_qr.py           單獨生成二維碼
    ├── vendor/qrcode/       內建二維碼生成
    └── 使用說明.md

第 4 步　自檢（必做）

• 打開生成的 題庫/線上任卷系統/questions.json，確認題目、選項、必答標記無誤。
• 啟動一次系統做冒煙測試：

  cd 線上任卷系統 && PORT=8123 python3 server.py &
  curl -s http://127.0.0.1:8123/ | head            # 答題頁可打開
  curl -s -X POST http://127.0.0.1:8123/submit --data-urlencode "q1=..." # 提交入庫
  curl -s http://127.0.0.1:8123/api/stats | head   # 統計正常
  

• 確認 Word 裡每道題題幹與選項未被分頁切開（腳本已設定 keep-with-next）。

第 5 步　交付與部署說明

向用戶說明：

• 三件套各自怎麼用；二維碼在後台頁面自動顯示（http://電腦IP:8000/admin）。
• 老師怎麼訪問：同一 WiFi 下掃碼即答（校內最常用）；若要公網訪問，需放到有公網 IP 的伺服器上。
• 詳見 references/deploy-guide.md，可直接複用其中文案。
• 可用 provide_file 把 Word 問卷、以及打包後的「線上任卷系統」壓縮包交付給用戶下載。

第 6 步（可選）入庫歸檔

如需歸檔，用 upload-to-kb 技能把 Word 問卷與系統壓縮包存入用戶指定知識庫。

---

關鍵要點與經驗

• 零依賴是核心競爭力：只用 Python 標準庫 + 內建 vendor/qrcode，用戶無需 pip 安裝任何東西； Word 生成才需要 python-docx（生成端環境需有）。
• 答題頁用純 HTML 表單 + 少量 JS：提交走 POST /submit，伺服器端驗證必答項（缺項會帶著已填內容回顯並標紅）。
• 二維碼在伺服器端用 SVG 即時生成（/api/qr.svg?url=...），後台頁面按當前訪問網址自動出碼， 老師換網路/改網址後重新出碼即可，無需重打包。
• 資料落盤在 data/responses.db（SQLite），備份=複製該檔案，清空=刪該檔案。
• 區域網路訪問打不開，90% 是電腦防火牆未放行 Python，提示用戶允許即可。
• 埠被佔用可用 PORT=8080 python3 server.py 換埠。

---

目錄結構

survey-design-collector/
├── SKILL.md
├── scripts/
│   ├── build_survey.py    一鍵生成（讀 spec → Word + 網站 + 二維碼）
│   ├── spec_to_word.py    由 questions.json 生成 Word 問卷
│   └── make_qr.py         由網址生成二維碼 PNG
├── assets/app/            線上任卷系統模板（server.py / 啟動腳本 / vendor/qrcode）
└── references/
    ├── spec-format.md     questions.json 規格說明 + 錄音轉問卷方法
    └── deploy-guide.md    部署與對外說明模板