설문지 설계 및 온라인 수집 시스템 생성기
「하나의 설문 요구사항」을 바로 사용 가능한 세 가지 산출물로 변환합니다:
- Word 설문지 (규격화된 포맷으로 인쇄 및 배포 가능)
- 온라인 응답 웹사이트 (휴대폰 QR 코드 스캔으로 즉시 응답, 별도 종속성 없음, 더블클릭으로 실행)
- 백엔드 데이터 집계 대시보드 (각 문항별 자동 통계 차트 + 세부 내역 + 원클릭 Excel 내보내기 + 응답 QR 코드)
전체 프로세스에 타사 종속성이 전혀 없으며(Python 표준 라이브러리만 사용), 산출물을 복사하여 모든 컴퓨터에서 바로 실행할 수 있습니다.
사용 시기
- 사용자가 녹음/구두 설명/텍스트 형식으로 '설문지를 설계해 주세요', '녹음을 바탕으로 설문지를 만들어 주세요'라고 요청할 때
- 사용자가 이미 질문 목록을 가지고 있으며, 이를 온라인 설문/QR 코드 응답 웹사이트로 만들고 데이터를 자동 집계하려 할 때
- 사용자가 '설문조사 + 백엔드 통계'가 포함된 완전한 솔루션을 원할 때
실행 프로세스 (SOP)
1단계: 요구사항 수집 및 이해
- 녹음: 먼저 음성을 텍스트로 변환합니다(
speech-to-text스킬 또는fetch로 오디오 파일 직접 변환). 주제, 대상, 섹션(차원) 수, 각 차원의 구체적인 질문, 선호하는 질문 유형(단일 선택/다중 선택/척도/텍스트)을 추출합니다. - 텍스트: 사용자가 제공한 개요를 직접 읽습니다.
- 불확실한 사항(예: '기본 정보' 섹션 추가 여부, 대상 기관)은 관례에 따라 채우고 전달 시 명시적으로 언급하거나, 사용자에게 확인합니다.
2단계: 설문 사양 questions.json 작성
references/spec-format.md의 형식을 엄격히 준수하여 설문을 JSON으로 작성합니다:
- 최상위 레벨:
title(제목),subtitle(부제목),intro(서문),footer(바닥글),scale_options(척도 5단계),sections. - 각 섹션 아래
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을 알고 있다면 --url http://xxx/ 를 추가하여 QR 코드를 직접 생성합니다.
산출물:
<출력 디렉터리>/
├── <설문 제목>.docx 규격화된 포맷의 Word 설문지
└── 온라인_설문_시스템/
├── server.py 응답 페이지 + 백엔드 + API (종속성 없음)
├── questions.json 본 설문 질문
├── 실행_Windows.bat / 실행_Mac_Linux.sh 원클릭 실행
├── make_qr.py QR 코드 개별 생성
├── vendor/qrcode/ 내장 QR 코드 생성 라이브러리
└── 사용_설명서.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단계: 전달 및 배포 설명
사용자에게 설명:
- 세 가지 산출물 각각의 사용법; QR 코드는 백엔드 페이지(
http://컴퓨터IP:8000/admin)에 자동으로 표시됩니다. - 교사가 접속하는 방법: 동일한 WiFi 환경에서 QR 코드를 스캔하여 즉시 응답(학교 내에서 가장 일반적); 공개 인터넷 접속을 원할 경우 공인 IP가 있는 서버에 배포해야 합니다.
- 자세한 내용은
references/deploy-guide.md를 참조하며, 해당 문서의 문구를 재사용할 수 있습니다. provide_file을 사용하여 Word 설문지와 압축된 '온라인 설문 시스템' 패키지를 사용자에게 다운로드용으로 제공할 수 있습니다.
6단계 (선택 사항): 저장 및 아카이브
아카이브가 필요한 경우 upload-to-kb 스킬을 사용하여 Word 설문지와 시스템 패키지를 사용자 지정 지식 베이스에 저장합니다.
핵심 사항 및 경험
- 종속성 제로가 핵심 경쟁력: Python 표준 라이브러리 + 내장
vendor/qrcode만 사용하므로 사용자는 pip로 아무것도 설치할 필요가 없습니다. Word 생성을 위해서는python-docx가 필요합니다(생성 환경에 설치되어 있어야 함). - 응답 페이지는 순수 HTML 폼 + 약간의 JS: 제출은
POST /submit을 통해 이루어지며 서버 측에서 필수 항목을 검증합니다(누락된 항목이 있으면 이미 입력된 내용을 유지한 채 빨간색으로 강조 표시하여 반환). - QR 코드는 서버 측에서 SVG로 실시간 생성(
/api/qr.svg?url=...), 백엔드 페이지는 현재 접속 URL을 기반으로 자동으로 QR 코드를 생성하므로 교사가 네트워크를 변경하거나 URL을 변경해도 다시 패키징할 필요 없이 QR 코드가 다시 생성됩니다. - 데이터는
data/responses.db(SQLite)에 저장됨; 백업 = 해당 파일 복사, 초기화 = 해당 파일 삭제. - 로컬 네트워크에서 접속이 안 되는 경우, 90%는 컴퓨터 방화벽이 Python을 차단하기 때문이므로 사용자에게 허용하도록 안내합니다.
- 포트가 사용 중이면
PORT=8080 python3 server.py로 변경할 수 있습니다.
디렉터리 구조
survey-design-collector/
├── SKILL.md
├── scripts/
│ ├── build_survey.py 일괄 생성 (spec → Word + 웹사이트 + QR 코드)
│ ├── spec_to_word.py questions.json으로 Word 설문지 생성
│ └── make_qr.py URL로 QR 코드 PNG 생성
├── assets/app/ 온라인 설문 시스템 템플릿 (server.py / 실행 스크립트 / vendor/qrcode)
└── references/
├── spec-format.md questions.json 사양 설명 + 녹음을 설문으로 변환하는 방법
└── deploy-guide.md 배포 및 외부 안내 템플릿