퀴즈 팩 제작 가이드
#

앱에서 설치 가능한 “퀴즈 팩(.zip)”을 만드는 방법을 단계별로 설명합니다.
핵심은 간단합니다: 폴더 구조 지키기 → JSON 스키마 맞추기 → zip으로 묶기.

이 가이드는 본 프로젝트의 합의된 스키마/동작을 기준으로 작성되었습니다.
외부 표준이나 정책 정보가 필요한 경우, 정보가 부족합니다. 프로젝트 문서 또는 운영 가이드라인을 확인해 주세요.

1) 개요
#

퀴즈 팩은 “zip 파일”입니다.
zip 루트에는 pack.json이 반드시 있어야 합니다.
실제 퀴즈 데이터는 quizzes/ 폴더 아래 JSON 파일로 넣습니다.
앱은 pack.json → quizzes[].file 경로를 따라 퀴즈를 읽습니다.

폴더 구조 예시

    my_quiz_pack/
      pack.json
      quizzes/
        vocab_basic.json
        vocab_intermediate.json

2) 준비물
#

텍스트 편집기(UTF-8 저장)
JSON 검증 도구(IDE 내장 혹은 온라인 Validator)
압축 유틸리티(zip)
(선택) Excel → JSON 변환용 파이썬 환경

3) pack.json 작성
#

pack.json은 “팩 메타 + 퀴즈 인덱스”를 담습니다. zip 루트(최상위)에 배치하세요.

예시

    {
      "packId": "vocab_bundle_ko",
      "title": "어휘 퀴즈 묶음(한국어)",
      "version": 1,
      "publisher": "YourNameOrTeam",
      "quizzes": [
        { "id": "vocab_basic", "title": "어휘 기초", "file": "quizzes/vocab_basic.json" },
        { "id": "vocab_intermediate", "title": "어휘 중급", "file": "quizzes/vocab_intermediate.json" }
      ],
      "hash": null,
      "signature": null
    }

필드 설명

packId: 팩 고유 식별자(영문/숫자/언더스코어 권장)
title: 팩 제목
version: 정수(새 버전은 +1)
publisher: 제작자/팀명(선택)
quizzes[]: 퀴즈 목록(각 항목은 id/title/file 필수)
file: zip 내부 상대 경로(예: quizzes/xxx.json)
hash/signature: 선택(무결성/서명. 운영 정책에 따라 사용)

실제 적용되면 설명(표시)

quizzes > title = Card title
quizzes > id = Card subtitle

주의

경로는 반드시 “상대 경로”만 사용(절대경로, .. 금지).
파일명은 정확히 pack.json이어야 합니다.

4) 퀴즈 JSON 스키마
#

앱이 이해하는 퀴즈 JSON(객관식 전용)입니다.

루트

    {
      "version": 1,
      "id": "vocab_basic",
      "title": "어휘 기초",
      "description": "영단어-뜻 매칭",
      "timeLimitSec": 300,
      "shuffleQuestions": true,
      "shuffleOptions": true,
      "questions": [ /* 문항 배열 */ ]
    }

문항(questions[])

    {
      "id": "q1",
      "type": "single",              // "single" | "multi"
      "text": "'abandon'의 뜻은?",
      "options": [
        { "id": "a", "text": "포기하다" },
        { "id": "b", "text": "증가하다" }
      ],
      "answers": ["a"],              // 정답 option id 배열(완전 일치)
      "explanation": "abandon = 포기하다",   // 선택
      "tags": ["vocab"],             // 선택
      "difficulty": 1                // 선택(정수)
    }

체크포인트

type은 “single” 또는 “multi”만 지원합니다.
answers의 id는 반드시 options[].id에 존재해야 합니다.
JSON은 UTF-8로 저장하세요.

5) Excel → JSON 변환(선택)
#

엑셀에서 아래 컬럼으로 작성 후 스크립트로 JSON을 만들 수 있습니다(프로젝트 제공 스키마 기준).

권장 컬럼

qid, type(single|multi), text, opt_a, opt_b, opt_c, opt_d, answers(a,b), explanation, tags, difficulty

샘플 행

    qid: q1
    type: single
    text: "'abandon'의 뜻은?"
    opt_a: "포기하다"
    opt_b: "증가하다"
    answers: "a"

워크플로

엑셀 작성 → 변환 스크립트로 JSON 생성
생성 JSON을 quizzes/ 에 배치
pack.json의 quizzes[].file에 경로 등록

6) ZIP 만들기
#

macOS / Linux

    cd my_quiz_pack
    zip -r ../vocab_bundle_ko.v1.zip .

Windows PowerShell

    Set-Location my_quiz_pack
    Compress-Archive -Path * -DestinationPath ..\vocab_bundle_ko.v1.zip -Force

권장 파일명

packId.v<version>.zip (예: vocab_bundle_ko.v1.zip)

무결성 해시(선택)

    # macOS/Linux
    shasum -a 256 vocab_bundle_ko.v1.zip

    # Windows PowerShell
    Get-FileHash .\vocab_bundle_ko.v1.zip -Algorithm SHA256

해시값을 배포 페이지에 함께 표기하면 신뢰성이 높아집니다.

7) 앱에서 설치(사용자)
#

파일 탐색기/메신저/메일/클라우드에서 zip을 “파일로 열기” → 앱이 인식하여 설치합니다.
또는 앱의 “팩 관리” → “팩 가져오기(.zip)”에서 직접 선택합니다.
설치 후 홈 목록에 팩의 퀴즈가 나타납니다.

8) 버전/운영 원칙
#

같은 packId로 새 버전을 배포할 때는 version을 올리고 “새 파일명”으로 배포합니다.
(예: vocab_bundle_ko.v2.zip)
quizzes[].id는 앱 전체에서 유일한 이름을 권장합니다(예: jp_n1_0001 형태).
대용량 단어장도 앱이 “세션(10–25문항)”으로 자동 분할하여 부담을 줄입니다.

9) 자주 하는 실수(피하기)
#

pack.json을 루트가 아닌 하위 폴더에 둠 → 인식 실패
→ zip 루트에 pack.json 필수.
type에 임의 문자열 사용(예: “단일”, “복수”) → 파싱 에러
→ 반드시 “single” 또는 “multi”.
answers에 없는 option id 기재 → 채점/표시 오류
경로에 절대경로/.. 사용 → 보안상 차단
→ 항상 상대 경로 사용.
JSON 문법 오류(쉼표/따옴표) → Validator로 확인 권장

10) 체크리스트
#

zip 루트에 pack.json이 있는가?
quizzes/ 폴더에 모든 퀴즈 JSON이 있는가?
pack.json의 quizzes[].file 경로가 실제 파일과 일치하는가?
각 문항의 type은 single/multi만 사용했는가?
answers의 id가 options[].id에 존재하는가?
파일은 UTF-8로 저장했는가?
zip 파일명은 packId.vN.zip 규칙을 따르는가?
(선택) SHA-256 해시를 제공하는가?

11) 템플릿(복사해서 시작)
#

pack.json
#

    {
      "packId": "your_pack_id",
      "title": "팩 제목",
      "version": 1,
      "publisher": "YourName",
      "quizzes": [
        { "id": "your_quiz_id", "title": "퀴즈 제목", "file": "quizzes/your_quiz.json" }
      ],
      "hash": null,
      "signature": null
    }

quizzes/your_quiz.json
#

    {
      "version": 1,
      "id": "your_quiz_id",
      "title": "퀴즈 제목",
      "description": "설명(선택)",
      "timeLimitSec": 0,
      "shuffleQuestions": true,
      "shuffleOptions": true,
      "questions": [
        {
          "id": "q1",
          "type": "single",
          "text": "문제 내용",
          "options": [
            { "id": "a", "text": "보기 A" },
            { "id": "b", "text": "보기 B" }
          ],
          "answers": ["a"],
          "explanation": "해설(선택)"
        }
      ]
    }

12) FAQ
#

Q. 이미지/사운드 자원도 함께 넣을 수 있나요?
A. 현 버전 앱은 텍스트 중심입니다. assets/ 폴더에 자원 파일을 넣고 JSON에 경로를 추가해도 앱은 알 수 없는 필드를 무시하므로 스키마 호환성은 유지됩니다. 다만 표시 기능은 추후 앱 업데이트에 따라 달라집니다.
Q. 2,000+ 문항도 가능한가요?
A. 가능합니다. 앱이 세션(10–25문항)으로 자동 분할하고, 새/복습 비율과 사용자 속도에 맞춰 적응형으로 출제합니다.
Q. 기존 팩을 업데이트하려면?
A. 같은 packId로 version을 올린 새 zip을 배포하세요(파일명도 변경). 기존 파일은 보존합니다.(추천하지 않습니다)

자신만의 퀴즈 팩을 제작 행운을 빕니다! 🚀
궁금한 부분은 “문의하기” 메뉴를 통해 Github Issues 남겨 주세요.

가장 쉽게 하는 방법은 Excel 형식에 맞쳐서 Excel 만드시고, 퀴즈팩용 파일변환기 에서 zip 만들고 적용하시면 됩니다.

퀴즈 팩 제작 가이드#

1) 개요#

2) 준비물#

3) pack.json 작성#

4) 퀴즈 JSON 스키마#

5) Excel → JSON 변환(선택)#

6) ZIP 만들기#

7) 앱에서 설치(사용자)#

8) 버전/운영 원칙#

9) 자주 하는 실수(피하기)#

10) 체크리스트#

11) 템플릿(복사해서 시작)#

pack.json#

quizzes/your_quiz.json#

12) FAQ#