선생님 것으로 설치하세요.

질문나무, 칭찬도장판, 진도 트래커. 학생 데이터는 우리 학교 Supabase 에만 남습니다.

시작하기구조 보기

처음 한 번 40~60분 · 설치할 프로그램 없음 · 무료

0준비물과 구조

필요한 것은 계정 두 개뿐입니다. 나머지는 전부 브라우저에서 합니다.

🗄️

Supabase 계정

supabase.com · 무료. 학생·질문·도장이 저장되는 데이터베이스. GitHub 계정으로 가입하면 가장 빠릅니다.

🐙

GitHub 계정

github.com · 무료. 웹페이지를 공짜로 올려 주는 GitHub Pages 에 꾸러미를 올립니다.

⚙️

고치는 파일은 하나

config.js. 학교 이름과 Supabase 키만 넣으면 세 앱이 모두 우리 학교 것이 됩니다.

꾸러미 폴더

class-kit/
├─ index.html            꾸러미 홈 · 설치 상태 자동 점검
├─ config.js             ⚙️ 고치는 파일은 이것 하나
├─ question-tree/        🌳 질문 과수원 (index.html 학생 · teacher.html 교사)
├─ stamp-board/          🏅 칭찬도장판
├─ progress/             📊 진도 트래커
└─ setup/
   ├─ guide.html         📘 이 문서
   ├─ 01_설치.sql        🗄️ Supabase 에 한 번 실행
   └─ 02_관리_레시피.sql 🧹 초기화·백업·비밀번호 등 필요할 때 조각 실행
세 앱은 같은 Supabase 프로젝트, 같은 교사 계정, 같은 학생 계정을 씁니다. 학생은 한 번 가입하면 질문나무와 칭찬도장판에 같은 아이디로 들어갑니다.

1Supabase 프로젝트 만들기

10분. 프로젝트 하나를 만들고, 설정 하나를 끄고, 값 두 개를 복사합니다.

  1. supabase.com → Start your project → GitHub 로 로그인

  2. New project → Name class-kit(자유) · Database Password 는 아무 거나 길게 적고 메모 · Region Northeast Asia → Create. 2분쯤 기다립니다.

  3. Authentication → Sign In / Providers → Email → Confirm email 을 끕니다(OFF) → Save.학생은 진짜 이메일 없이 «학년·반·번호»로 만든 가짜 이메일로 가입합니다. 이걸 켜 두면 학생이 가입해도 로그인이 되지 않습니다.

  4. Project Settings(⚙️) → API 에서 두 값을 메모장에 복사해 둡니다.Project URL — https://xxxxxxxx.supabase.co · Project API keys → publishable(또는 anon public) — sb_publishable_… 또는 eyJ…

⚠️ service_role / secret 키는 절대 복사하지 마세요. 그 키는 모든 보안을 우회합니다. 꾸러미 홈의 설치 점검이 그 키를 발견하면 경고를 띄웁니다.

2설치 SQL 한 번 실행

5분. 파일 하나가 표 22개, 함수 30여 개, 보안규칙을 만듭니다. 서버 함수나 CLI 설치는 없습니다.

  1. setup/01_설치.sql 을 메모장으로 엽니다.

  2. 맨 위 PART 0 의 '우리학교-교사-2026' 을 우리 학교만의 교사 초대코드로 바꿉니다.동료 선생님이 교사 등록할 때 입력하는 암호입니다. 나중에 대시보드 ⚙️ 관리에서 바꿀 수 있습니다.

  3. Supabase 왼쪽 SQL Editor → New query → 파일 전체를 붙여넣고 Run (Ctrl+Enter).

  4. 아래 결과표가 전부 ✅ 인지 확인합니다.❌ 가 있으면 파일 전체를 한 번 더 Run 하세요. 여러 번 실행해도 안전합니다.

3GitHub Pages 에 올리기

10분. 저장소를 복제하고 Pages 를 켜면 주소가 생깁니다.

  1. 꾸러미 저장소 github.com/scienceisjo/class-kit 에서 초록 Use this template → Create a new repository. Repository name class-kit(자유) · Public → Create.

  2. 새 저장소에서 Settings → Pages → Build and deployment Deploy from a branch → Branch main / /(root) → Save.

  3. 1~2분 뒤 같은 화면 위에 주소가 뜹니다. https://아이디.github.io/class-kit/ 가 꾸러미 홈, …/class-kit/question-tree/ 가 학생 앱입니다.

주소를 열었는데 «아직 설정이 없어요»가 뜨면 정상입니다. 다음 단계에서 config.js 를 넣으면 사라집니다.

4config.js 만들기

5분. 아래 칸을 채우고 단추를 누르면 파일 내용이 만들어집니다. GitHub 의 config.js 에 통째로 붙여넣으면 끝입니다.

GitHub 에 넣는 법

  1. 내 저장소에서 config.js 파일을 클릭 → 오른쪽 위 연필(Edit)

  2. 기존 내용을 전부 지우고 복사한 내용을 붙여넣기 → Commit changes… → Commit

  3. 1~2분 뒤 꾸러미 홈을 새로고침(Ctrl+F5). «설치 상태»가 전부 ✅ 이면 완료.

생성기는 이 저장소의 config.js 를 바탕으로 필수 칸만 바꿔 줍니다. 역량 이름·보상·과목 목록 같은 나머지는 7단계에서 파일을 직접 고칩니다.

5교사 등록, 학생 가입

교사는 초대코드로 한 번, 학생은 학년·반·번호로 스스로.

🧑‍🏫

교사

…/question-tree/teacher.html → 회원가입 탭 → 성함 · 담당 과목 · 학년 · 진짜 이메일 · 비밀번호 · 교사 초대코드 → 가입. 이 계정 하나로 교사 대시보드·칭찬도장판·진도 트래커에 모두 로그인합니다.

🎒

학생

칠판에 학생 앱 주소(…/question-tree/) 또는 QR 을 띄웁니다. 학생은 가입 → 학년 · 반 · 번호 · 이름 · 비밀번호(4자 이상) → 완료. 이메일은 필요 없습니다. 같은 학년·반·번호로는 한 번만 가입됩니다.

🔑

비밀번호를 잊으면

교사 대시보드 학생 목록의 🔑 로 초기화합니다. 학생 아이디는 내부적으로 s2_3_15@student.school 같은 가짜 이메일이며, 도메인은 config.js 의 studentEmailDomain 입니다. 학생이 가입한 뒤에는 바꾸지 마세요.

6수업에서 쓰기

짧게. 교사가 하는 일과 학생이 하는 일.

앱교사학생
🌳 질문 과수원수업 시작에 대시보드에서 📑 지금 차시 켜기 → 질문에 되묻기(🌿) · ⭐ 대표 질문 · 🏷️ 라벨 · 주간 리포트질문 심기 → 다듬기 → 스스로 해결하기 → 열매
🏅 칭찬도장판차시당 3명만 목표로 «관찰된 행동» 한 문장과 함께 도장. 골든벨 · 쿠폰 승인캐릭터 고르기·키우기, 잔액으로 보상 교환
📊 진도 트래커수업 끝나고 칸 하나 클릭. 메모(✎)로 «이 반은 실험 못 함» 남기기교사용

질문 과수원 ⭐ 를 누르면 칭찬도장판에 도장이 함께 찍힙니다. 도장판의 «차시 이름»과 과수원의 «지금 차시»를 같은 이름으로 쓰면 두 기록이 한 이름으로 모입니다.

7커스터마이징

전부 config.js 한 파일입니다. 값을 비우면 기본값, 넣으면 그 값. 파일 안에 주석으로 설명이 있습니다.

항목바꿀 수 있는 것
school · supabase학교 이름·짧은 이름·선생님·교과 / Supabase 주소·키 (필수)
brand앱 이름 세 개, 부제, 로고 파일 경로 (예: assets/logo.png 를 저장소에 올리고 경로 지정)
theme앱별 색. CSS 변수 이름으로 적습니다. 예: '--pr':'#0b5fa5'. 자주 쓰는 변수는 파일 주석에, 전체 목록은 각 HTML 맨 위 :root
stamp.pack · stamp.packs세계관 팩 14종 — 공룡알·동물마을·텃밭·세계 여행 여권·수족관·우주 탐사·빵집·오케스트라·명화 퍼즐·로봇(교과 무관) / 탐구생물·과학자·연구소·결정 키우기(과학). 팩마다 6갈래 × 7단계 그림 27장. 선생님이 하나로 잠그거나(pack:'dino'), 비워서 학생이 고르게. 미리보기: packs-preview.html
stamp.competencies역량 6종의 이름(칩·교사용·학생용)·아이콘·색·행동 칩 문장. 과학이 아닌 교과는 여기만 고치면 됩니다. 코드(inquiry …)는 그림과 묶여 있어 바꾸지 않습니다.
stamp.rewards / honors / howToEarn소비형 보상(잔액 차감) · 명예형 보상(누적 15·20개 자동) · «이럴 때 도장» 안내
stamp.themes캐릭터 테마 4종의 이름과 7단계 이름
question.subjects학생이 «과목 추가»할 때 고르는 목록. integrated 는 기본 과목이라 지우지 않습니다.
question.pickMax / learnerText / aiTeacherText차시당 대표 질문 수 · AI 프롬프트에서 학생·교사를 부르는 말 («고등학교 1학년» 등)
progress.boards / lessonBank처음 만들어 둘 진도표(반·수업 횟수·차시) · «+ 차시 고르기» 목록
credits원작 표기 (바꾸지 않아도 됩니다)
⚠️ config.js 는 자바스크립트라서 따옴표 짝·쉼표 하나가 틀리면 파일이 읽히지 않고 «아직 설정이 없어요»가 뜹니다. 고친 뒤에는 꾸러미 홈의 설치 상태를 확인하세요.
서버(SQL)에서 바꾸는 것

하루 질문 상한(하루 8개·차시당 3개)은 교사 대시보드 ⚙️ 관리 또는 02_관리_레시피.sql ③ 에서 바꿉니다. 캐릭터 진화 단계 도장 수(0/1/3/6/10/15/20)는 서버 함수와 묶여 있어 바꾸지 않는 것을 권합니다.

8관리와 문제 해결

대시보드 ⚙️ 관리와 02_관리_레시피.sql 로 대부분 해결됩니다.

초대코드 · 하루 상한

대시보드 ⚙️ 관리 에서 보고 바꿉니다.

학생 비밀번호

학생 목록 🔑, 또는 레시피 ④.

학년 말 정리 · 백업

setup/02_관리_레시피.sql 의 조각 ⑥ ⑦ ⑧. 통째로 실행하지 마세요.

방학 뒤 첫 수업 전

무료 Supabase 는 1주일 동안 아무도 안 쓰면 일시정지(Paused)됩니다. supabase.com 에서 Restore.

자주 겪는 문제

증상원인 → 해결
«아직 설정이 없어요»가 계속 뜸config.js 가 없거나 문법 오류. 생성기로 다시 만들어 붙여넣고 Ctrl+F5
Invalid API key키를 잘못 복사. Project Settings → API 의 publishable(anon) 키를 다시
학생이 가입했는데 로그인이 안 됨 / Email not confirmed1단계 ③ Confirm email 이 켜져 있음 → 끄고, 이미 가입한 학생은 레시피 ⑤로 지운 뒤 재가입
could not find the function … / PGRST202설치 SQL 미실행 또는 일부 실패 → 01_설치.sql 전체를 다시 Run
교사 등록 시 «초대코드가 올바르지 않습니다»01_설치.sql PART 0 의 코드와 다름 → 레시피 ②로 확인
페이지가 404Settings → Pages 가 main / root 인지, 주소 끝에 저장소 이름(/class-kit/)이 맞는지
이미지·소리가 안 나옴question-tree/assets, stamp-board/audio, stamp-board/images 폴더가 그대로 올라갔는지
갑자기 아무것도 안 됨 (방학 뒤)Supabase 프로젝트 일시정지 → supabase.com 에서 Restore

9라이선스

조승재(과학이조선생)가 만들었고 CC BY-NC-SA 4.0 으로 나눕니다. 마음껏 가져다 쓰세요.

이름은 선생님 것으로

푸터 표기는 config.js 의 credits 에서 자유롭게 바꿀 수 있습니다. 원작 표기를 남겨 주시면 고맙지만, 선생님 이름을 넣어 쓰셔도 괜찮습니다.

비영리

수업·연수·학교 안에서는 자유롭게. 판매하거나 유료 서비스에 넣을 수 없습니다.

동일조건변경허락

고쳐서 나눌 때도 같은 라이선스로.