Beginner Guide

교실 자리배치 앱을 처음 쓰는 선생님을 위한 자세한 설명서

이 설명서는 “앱을 열었는데 어디부터 눌러야 할지 모르겠다”는 상황을 기준으로 적었습니다. 자리배치와 청소분담을 한 번도 안 해봤어도 따라갈 수 있게 순서대로 설명합니다.

현재 기준 폴더는 /Users/hangbokee/Library/CloudStorage/GoogleDrive-ljs7555@gmail.com/다른 컴퓨터/서해고/School/900-개발/classroom-planner 입니다. 예전 경로 /Users/hangbokee/classroom-planner도 지금은 같은 폴더를 가리키도록 연결해 두었습니다.
앱으로 돌아가기 QR 실시간 준비 classpage 양식 다운로드 요약 README 보기

목차

1. 처음 시작할 때 2. 실제 사용 순서 3. classpage에서 가져오는 형식 4. QR 학생 선택 순번 준비 5. QR 실시간 운영 화면 사용법 6. 자리배치가 작동하는 방식 7. 청소분담이 작동하는 방식 8. 화면이 좁을 때 보는 방법 9. 자주 생기는 질문

1. 처음 시작할 때

1단계. 앱 열기 open-app.command를 더블클릭하거나 index.html을 브라우저로 엽니다.
2단계. 구조부터 보기 처음에는 완성 샘플 보기를 눌러서 전체 결과가 어떻게 나오는지 먼저 보는 것이 좋습니다.
3단계. 실제 데이터 넣기 교사용 설정 열기를 누른 뒤 CSV/MD 불러오기 또는 붙여넣기로 학생 데이터를 넣습니다.
처음부터 직접 데이터를 넣으면 구조가 잘 안 보일 수 있습니다. 먼저 샘플을 눌러 보고, 그 다음 실제 데이터를 넣는 순서를 추천합니다.

2. 실제 사용 순서

명단 준비

classpage에서 학생 이름과 별점을 준비합니다. 가능하면 CSV로 저장합니다.

불러오기

앱의 교사용 모드에서 CSV/MD 파일을 불러오거나, 엑셀 표를 그대로 붙여넣습니다.

부족한 정보 보완

성적, 부서, 학급도우미 여부를 표에서 직접 수정할 수 있습니다.

상위권 좌석 고정

앱이 계산한 상위 30% 학생 중 필요한 학생만 직접 자리를 고정합니다.

자동 자리배치

나머지는 별점, 성적, 랜덤 연출 강도를 섞어 자동 배치합니다.

청소분담

개인 9명 배정 또는 부서 조합 배정을 고른 뒤 생성하고, 확정하면 횟수가 누적됩니다.

3. classpage에서 가져오는 형식

제가 가장 다루기 편한 권장 형식은 아래 CSV입니다.

student_name,star_rating,grade,department_name,is_helper,exclude_from_seat,exclude_from_cleaning,absent_today,cleaning_count,selection_order
김민지,5,96,환경부,true,false,false,false,0,1
박준호,3,78,체육부,false,false,false,false,1,2
꼭 필요한 열은 student_name과 star_rating 두 개뿐입니다. 나머지는 비워도 됩니다.
  • student_name: 학생 이름
  • star_rating: 별점 1~5
  • grade: 성적 0~100
  • department_name: 부서 이름
  • is_helper: 학급도우미 여부
  • exclude_from_seat: 자리배치 제외
  • exclude_from_cleaning: 청소 제외
  • absent_today: 오늘 결석 등으로 제외
  • cleaning_count: 누적 청소 횟수
  • selection_order: QR 학생 직접 선택 순번
불리언 값은 true/false, yes/no, 예/아니오, 1/0를 모두 읽습니다.

4. QR 학생 선택 순번 준비

학생이 QR로 들어와 순서대로 자리를 고르게 하려면, 현재 앱에서는 먼저 순번 준비를 합니다.

1단계. 상위권 학생 계산 상위권 순번 자동 채우기를 누르면 현재 별점과 성적 기준으로 상위권 학생에게 순번이 자동으로 붙습니다.
2단계. 순번 수동 조정 선생님이 직접 선택 순번을 바꿔서 1번, 2번, 3번 순서를 원하는 대로 조정할 수 있습니다.
3단계. 순번/토큰 내보내기 순번/토큰 CSV 내보내기를 누르면 학생 이름, 순번, 토큰, 주소 템플릿이 담긴 파일을 만들 수 있습니다.
4단계. 실시간 앱으로 연결 실제 여러 학생이 동시에 QR로 접속해 차례대로 선택하게 하려면, 다음 단계에서 Supabase 같은 공유 DB를 붙여야 합니다.
지금은 다음 구현 단계까지 들어와 있습니다. 순번 준비가 끝나면 바로 QR 실시간 준비 화면으로 넘어가 실제 세션을 만들 수 있습니다.

5. QR 실시간 운영 화면 사용법

이제는 순번 준비만 하는 것이 아니라, 실제로 학생들이 각자 휴대폰으로 들어와 자기 차례일 때만 자리를 누를 수 있는 화면도 함께 들어 있습니다.

1단계. 세션 JSON 만들기 메인 앱에서 세션 JSON 내보내기를 눌러 실시간 세션용 파일을 만듭니다.
2단계. QR 실시간 준비 열기 qr-setup.html 또는 첫 화면의 QR 실시간 준비 버튼을 엽니다.
3단계. Supabase 세션 만들기 세션 JSON을 붙여 넣고 실시간 세션 만들기를 누르면 교사용 링크와 학생 링크가 생성됩니다.
4단계. 선생님이 진행 화면 열기 teacher-live.html에서 시작, 일시정지, 건너뛰기, 종료를 제어합니다.
5단계. 학생이 순서대로 선택 student-select.html은 자기 차례일 때만 좌석 선택 버튼이 나타납니다.
이 기능은 반드시 공개 주소와 Supabase 설정이 필요합니다. 로컬 파일로만 열어 두면 학생 휴대폰에서 접속할 수 없습니다.
처음 세팅은 [`realtime-qr-setup.md`](/Users/hangbokee/classroom-planner/docs/realtime-qr-setup.md)를 차근차근 따라가는 것이 가장 쉽습니다.

6. 자리배치가 작동하는 방식

이 앱은 완전 랜덤보다는 “선생님이 방향을 정하고, 랜덤처럼 보이게 만드는 방식”에 가깝습니다.

  1. 별점과 성적을 기준으로 학생 우선순위를 계산합니다.
  2. 상위 30% 학생을 직접 지정 대상자로 뽑습니다.
  3. 그 학생들 중 필요한 학생만 선생님이 직접 좌석을 고정합니다.
  4. 나머지는 자동으로 배치합니다.
학생 공개 모드에서는 수동 고정, 가중치, 랜덤 연출 강도 같은 설정이 보이지 않습니다. 다만 강한 보안 기능은 아니므로, 같은 기기에서 완전 비밀이라고 생각하면 안 됩니다.
  • 별점 가중치가 높으면 별점이 높은 학생이 좋은 자리로 더 먼저 갑니다.
  • 성적 가중치가 높으면 성적이 높은 학생이 더 반영됩니다.
  • 랜덤 연출 강도가 높으면 순서가 조금 더 섞입니다.
  • 좌석 우선순위 숫자가 작을수록 먼저 배정되는 자리입니다.

7. 청소분담이 작동하는 방식

개인 9명 배정

현재 후보 학생 중에서 9명을 뽑아 역할 9개에 배정합니다. 청소 횟수가 적은 학생이 우선됩니다.

부서 조합 배정

부서별 인원을 보고 9명에 가장 가까운 조합을 찾은 뒤, 그 안에서 역할 9개를 나눕니다.

면제 옵션

학급도우미 면제, 별점 높은 학생 면제를 켜고 끌 수 있습니다.

아직 정책이 완전히 정해지지 않았다면, 같은 명단으로 개인 배정과 부서 배정을 번갈아 눌러 보고 더 자연스러운 쪽을 선택하면 됩니다.

8. 화면이 좁을 때 보는 방법

  • 자리판과 청소 카드는 작은 노트북에서 좌우 스크롤이 됩니다.
  • 학생 표는 헤더가 위에 고정되고 표 안쪽만 스크롤됩니다.
  • 데이터가 이미 들어간 뒤 학생 공개 모드로 바꾸면 첫 안내 패널은 자동으로 숨겨집니다.
작은 노트북에서는 교사용 설정을 할 때 브라우저를 최대화해서 쓰는 것이 좋습니다. 학생에게 보여줄 때는 공개 모드로 바꾸면 화면이 훨씬 단순해집니다.

9. 자주 생기는 질문

엑셀 xlsx 파일을 바로 읽을 수 있나요?

아직은 아닙니다. 대신 엑셀에서 CSV로 저장하거나, 표를 복사해서 붙여넣으면 됩니다.

성적이 없는 학생도 사용할 수 있나요?

가능합니다. 성적이 비어 있으면 기본값 0으로 처리합니다.

샘플로 먼저 테스트하고 싶은데 가장 빠른 방법은 무엇인가요?

첫 화면에서 완성 샘플 보기를 누르면 됩니다.

학생에게 보여줄 때 어디까지 숨겨지나요?

교사용 설정 패널과 일부 관리 버튼은 숨겨집니다. 다만 기술적으로 완전 잠금은 아니므로 같은 기기를 계속 학생이 만지는 상황이라면 PIN 설정을 권합니다.

학생이 QR로 직접 들어와 선택하는 것도 지금 가능한가요?

가능합니다. 다만 공개 주소와 Supabase 설정이 끝나야 합니다. 설정 방법은 realtime-qr-setup.md 문서를 보면 됩니다.