클래스뱅크 (ClassBank)
학원용 포인트 뱅킹 웹앱. React + Vite + Supabase.
pointbank/
├─ supabase/schema.sql ← DB 스키마 (SQL Editor에서 실행)
├─ app/ ← React 앱
│ ├─ .env.local ← Supabase URL / anon key (git 커밋 금지)
│ └─ src/
│ ├─ lib/ supabase 클라이언트, API 함수, 타입
│ ├─ context/ 인증 상태, 토스트
│ ├─ components/ 통장 카드
│ └─ pages/ 인증 · 온보딩 · 반별통장 · 순위 · 설정 · 학생화면
└─ point-bank-prototype.html ← 원본 프로토타입 (참고용, 이제 미사용)
처음 한 번만: DB 스키마 적용
아직 적용되지 않았습니다. 이 단계를 먼저 하셔야 앱이 동작합니다.
- https://supabase.com/dashboard 접속 → 해당 프로젝트 선택
- 왼쪽 메뉴에서 SQL Editor → New query
supabase/schema.sql 파일 내용을 전부 복사해서 붙여넣기- Run 클릭
여러 번 실행해도 안전하게 작성되어 있으니, 나중에 스키마를 고칠 때도 같은 방식으로 다시 실행하면 됩니다.
추가 마이그레이션
이미 schema.sql을 한 번 실행한 뒤 기능이 추가되면, supabase/ 폴더의 번호 붙은 파일만 따로 실행하면 됩니다.
| 파일 | 내용 |
|---|
002_daily_board.sql | 일일 마감(settlements) + 결과 보기 집계 함수(ranking_summary) |
003_student_scope.sql | 순위 조회 함수를 선생님/원장 전용으로 제한 |
004_academy_logo.sql | 학원 로고 업로드 (academies.logo_url + logos 스토리지 버킷) |
005_attendance.sql | 출석부 (attendance 테이블 — 등원/하원 체크 + 월별 기록) |
006_disable_student_login.sql | 보안 — 학생 로그인 잠금 (베타 기간 동안 원장·선생님만) |
007_platform_admin.sql | 플랫폼 관리자 ([email protected] 전용 — 가입 학원 목록/삭제) |
008_ladder_order_games.sql | 사다리타기 · 랜덤 공 뽑기 게임 + 게임 배경음악 업로드 |
009_fix_logo_storage.sql | 학원 로고 업로드 RLS 수정 (upsert 시 SELECT 정책 누락 문제) |
010_homework_tracking.sql | 프리셋·거래 내역에 "숙제 관련" 표시(is_homework) 추가 |
011_game_images.sql | 명칭이 있는 다이어그램 · 이미지 퀴즈용 사진 업로드 (game-images 스토리지 버킷) |
새 프로젝트를 처음부터 세팅할 때는 schema.sql 하나만 실행하면 됩니다 (마이그레이션 내용이 이미 포함돼 있음).
테스트를 빠르게 하려면 (선택)
Supabase는 기본적으로 회원가입 시 이메일 인증을 요구합니다. 개발 중에는 꺼두는 게 편합니다.
- Dashboard → Authentication → Sign In / Providers → Email → Confirm email 끄기
실제 서비스 오픈 전에는 다시 켜세요.
실행
npm run dev --prefix app
http://localhost:5173
처음 사용해보는 순서
- 회원가입 (원장님 계정)
- 온보딩에서 "학원을 새로 만들기" 선택 → 학원 이름 / 포인트 단위(별, 달러 등) / 내 이름 입력
- 학원, 첫 번째 반("1반"), 기본 사유 프리셋 5개가 자동 생성됩니다
- 반별 통장 화면에서
+ 학생 추가
- 학생 카드의 사유 버튼을 눌러 포인트 지급/차감 (도장 애니메이션)
- 수업이 끝나면 우측 상단
오늘 마감 → 학생별 오늘 적립분을 확인하고 통장에 적립하기
- 결과 보기에서 기간별(오늘/이번 주/이번 달/전체) 누적 결과 확인
- 설정에서 반 추가, 사유 프리셋 편집, 학생 코드 / 선생님 초대 코드 확인
반별 통장 화면이 "오늘"만 보여주는 이유
누적 총액을 항상 띄워두면 격차가 고정된 사실처럼 보여서, 뒤처진 학생은 따라잡을 수 없다고 느낍니다.
그래서 수업 중에 보는 화면은 오늘 적립분만 크게 표시하고, 매일 0에서 다시 시작합니다.
- 누적 보기 토글 — 선생님이 필요할 때만 켜서 확인합니다. 학생들 앞에서는 꺼두세요.
- 오늘 마감 — 그날 내역을 확정하고 카드를 잠급니다. 실수했으면
취소로 되돌릴 수 있습니다.
- 누적 결과는
결과 보기 화면에서 봅니다.
포인트는 버튼을 누르는 즉시 DB에 저장됩니다. 마감은 저장이 아니라 "확정 + 잠금"이라, 수업 중에
브라우저가 닫히거나 새로고침돼도 기록이 날아가지 않습니다.
날짜는 선생님 브라우저의 로컬 시간 기준입니다 (transactions.created_at은 UTC로 저장되지만,
조회할 때 로컬 자정을 UTC로 변환해 넘깁니다).
다른 선생님 합류시키기
설정 화면의 선생님 초대 코드(6자리)를 전달 → 그 선생님이 회원가입 후 "선생님으로 합류하기"에서 입력.
학생 로그인 (현재 베타 기간 동안 비활성화됨)
위 "베타 기간: 학생 로그인 잠금" 참고. 코드는 남아 있고(StudentPage.tsx 등) DB 실행 권한만
회수한 상태라, 다시 열 때 새로 개발할 필요는 없습니다.
데이터 구조 요약
| 테이블 | 역할 |
|---|
academies | 학원 (테넌트 최상위). 포인트 단위, 선생님 초대 코드 보유 |
classes | 반 |
students | 학생 계좌. claim_code로 학생 계정과 연결 |
profiles | 로그인 사용자 (owner / teacher / student / admin) |
transactions | 거래 원장. 잔액은 저장하지 않고 이 합으로 계산 |
presets | 지급/차감 사유 버튼 |
redemptions | 포인트 상품 교환 내역 (추후 기능용, 테이블만 준비) |
game_templates | 미니게임 템플릿 (추후 기능용, 테이블만 준비) |
잔액을 따로 저장하지 않는 이유: "누가 언제 왜 줬는지"를 항상 추적·정정할 수 있어야 하기 때문입니다. 잔액은 student_balances 뷰가 합산해줍니다.
베타 기간: 학생 로그인 잠금 (중요)
지금은 원장·선생님만 로그인할 수 있습니다. 학생 온보딩 옵션과 claim_student() 함수 실행
권한을 껐습니다.
이유: academies.invite_code(선생님 초대 코드)와 students.claim_code(학생 통장 연결 코드)는
같은 학원 소속이면 누구나 조회할 수 있는 구조입니다. 학생 계정이 존재하면, 학생이 이 값을 읽어
① 선생님 초대 코드로 재가입해 선생님 권한을 얻거나 ② 다른 학생의 claim_code로 그 학생 계정을
가로챌 수 있었습니다. 이메일 인증까지 꺼둔 상태(현재 베타 세팅)라 실제로 가능한 공격 경로였습니다.
학생 로그인을 다시 열려면:
supabase/006_disable_student_login.sql 맨 아래 주석 처리된 grant execute 실행app/src/pages/OnboardingPage.tsx, AuthPage.tsx, SettingsPage.tsx에서 이 마이그레이션 때
지워진 학생 관련 UI 복구 (git log에서 "학생 로그인 잠금" 커밋 참고)- 그 전에 반드시 이메일 인증(Confirm email)을 켜고 외부 SMTP를 연결할 것 — 안 그러면 같은
구멍이 다시 열립니다.
보안 (중요)
.env.local의 anon key는 공개되어도 되는 값입니다. 프론트엔드 번들에 어차피 포함됩니다.- 실제 데이터 보호는 전적으로 RLS(Row Level Security) 정책이 담당합니다.
schema.sql의 4번 섹션.
- 읽기: 같은 학원 소속만
- 쓰기: 원장/선생님만
- 학생: 자기 거래 내역만. 순위는 이름+합계만 돌려주는 함수로 별도 제공
- service_role key는 절대 프론트엔드에 넣지 마세요. RLS를 전부 무시합니다.
- 프로필 생성은
create_academy / join_academy_as_teacher / claim_student / claim_admin 네 함수로만 가능합니다. 아무나 임의 학원에 owner로 끼어드는 걸 막기 위해서입니다.
플랫폼 관리자
supabase/007_platform_admin.sql 실행 후, [email protected]으로 정상 회원가입만 하면 됩니다
(비밀번호는 Supabase 최소 자리수인 6자 이상이어야 합니다). 이 이메일로 로그인하면 온보딩 화면에
"관리자로 시작하기" 버튼이 뜨고, 누르면 학원 소속 없이 /admin으로 들어갑니다.
- 가입한 학원 목록(선생님/학생 수 포함), 학원 삭제(이름을 정확히 입력해야 삭제됨), 관리자 비밀번호
변경을 제공합니다.
- 권한 부여는
claim_admin() RPC가 서버에서 auth.users.email을 다시 확인하는 방식이라, 클라이언트가
임의로 admin을 자칭할 수 없습니다. admin_list_academies()/claim_admin() 둘 다 anon 롤의 실행
권한을 명시적으로 회수해뒀습니다 (Supabase는 함수 생성 시 anon에게도 기본 EXECUTE 권한을 자동
부여하므로, authenticated/public만 revoke하면 구멍이 남습니다 — 006_disable_student_login.sql
작업 때 발견한 것과 같은 함정).
- 사용량 통계(학원별/계정별)는 아직 없습니다 — 무료 테스트 기간이라 필요해지면 나중에 추가합니다.
미니게임 — 돌림판 / 사다리타기 / 랜덤 공 뽑기 / 시한폭탄 / 타이머 맞추기
다섯 게임 모두 game_templates 테이블 하나를 공유합니다 (game_type 컬럼으로 구분, CHECK 제약이
없어 새 게임 종류를 추가해도 스키마 변경이 필요 없습니다). 반 전용/학원 공용 여부, 만들기·이름변경·
삭제 흐름은 다섯 게임이 동일해서 app/src/lib/useGameTemplates.ts 훅 하나로 공통 처리합니다.
- 사다리타기: 참가자(위) ↔ 결과(아래) 목록을 각각 등록. "사다리 타기 시작"을 누르면 무작위
사다리를 만들어 전원이 동시에 내려가는 애니메이션을 보여줍니다. 사다리 생성 로직은
app/src/lib/ladder.ts — 같은 행에서 인접한 가로줄이 겹치지 않게만 배치하면 항상 1:1 대응이
된다는 성질을 이용했고, 2~10명 기준 2만 회 시뮬레이션으로 검증했습니다.
- 랜덤 공 뽑기: 이름을 등록해 두고 뽑으면 "뽑기 기계" 연출로 순서가 공개됩니다 — 상자 안에서
공이 요란하게 튕겨 다니다가 하나씩 튀어나와 자리에 안착합니다(
LotteryMachine.tsx).
순위 이름표("1등"/"1번" 등)는 선생님이 직접 눌러서 수정할 수 있고, 참가자 수와 항상 맞춰
자동으로 늘어나거나 줄어듭니다.
- 시한폭탄: 참가자를 등록하고 폭발 시간 범위(초, 예: 15~60초)를 정해두면, "시작" 시 그 사이
무작위 시각에 터지는 숨겨진 타이머가 걸립니다. "다음 사람에게 넘기기"를 누르며 폭탄을 돌리다가,
터지는 순간 폭탄을 들고 있던 사람이 걸립니다(
app/src/components/TimeBomb.tsx). 정확히 언제
터질지는 아무도(선생님도) 알 수 없습니다 — setTimeout으로 한 번만 무작위 지연을 걸어두는
방식이라 서버 폴링 없이 클라이언트에서 그대로 동작합니다.
- 타이머 맞추기: 목표 시간(초)을 정해두고 "시작"→"멈춤"으로 최대한 가깝게 맞히는 게임
(
app/src/components/TimerMatch.tsx). 숫자를 보이게/숨기게 고를 수 있고(숨기면 감으로만 맞혀야
하는 원래 방식), "공용 도전판"(참가자 구분 없이 반복 도전)과 "참가자별 순위"(한 명씩 도전하고
끝나면 오차 순 순위표) 중에서도 고를 수 있습니다. 시간 측정은 performance.now() 기준이라
브라우저 프레임 속도와 무관하게 정확합니다.
- 참가자를 학생 명단에서 추가: 다섯 게임 모두 "학생 명단에서 추가" 패널에서 이 반/학원 전체
학생을 클릭하거나 "전체 추가"로 한 번에 넣을 수 있습니다. 매번 이름을 직접 입력할 필요가
없습니다 (
app/src/components/StudentRosterPicker.tsx, app/src/lib/useGameTemplates.ts).
- 게임 배경음악 / 결과 사운드:
game_templates.config (jsonb)에 각각 따로 저장합니다.
배경음악은 진행 중 반복 재생, 결과 사운드는 결과가 확정되는 순간 한 번 재생됩니다(둘 다 한 번도
안 건드린 게임은 결과 사운드가 "짜잔"으로 기본 재생됨 — resolveResultSound()).
- 기본 제공 효과음(두구두구/심장박동/시계 초침/박수 갈채/펑!/짜잔/카운트다운/딩동)은 실제 음원
파일 없이 Web Audio API로 그 자리에서 합성합니다(
app/src/lib/gameMusic.ts) — 어느 학원에서
써도 저작권 문제가 없도록.
- 선생님이 직접 mp3 등을 올릴 수도 있습니다 —
game-audio 공개 스토리지 버킷에
<academy_id>/<uuid>.<확장자>로 저장(008_ladder_order_games.sql). 업로드하는 음원의
저작권 책임은 업로드한 학원에 있습니다 (서비스가 기본 제공하는 음원이 아님).
Vercel 배포
Vite 결과물은 정적 파일이라 그대로 올라갑니다. 백엔드는 Supabase에 있으니 서버는 필요 없습니다.
- GitHub에 푸시 (아직 git 저장소가 아니면
git init 부터)
- Vercel에서 Import Project → 해당 저장소 선택
- Root Directory 를
app 으로 지정 ← 저장소 루트가 아니라 app/ 폴더가 프로젝트입니다
- Framework Preset은 Vite로 자동 인식됩니다
- Environment Variables 두 개 등록 (
.env.local은 git에 안 올라가므로 여기서 따로 넣어야 함)
VITE_SUPABASE_URLVITE_SUPABASE_ANON_KEY
- Deploy
배포 후 Supabase에서 꼭 해줘야 하는 설정
Dashboard → Authentication → URL Configuration
- Site URL:
https://내프로젝트.vercel.app
- Redirect URLs: 위 주소 추가
안 하면 이메일 인증 링크나 비밀번호 재설정 링크가 localhost:3000으로 가버립니다.
이미 처리해둔 것
app/vercel.json — SPA rewrite 설정.
react-router를 쓰기 때문에, 이게 없으면 /board 같은 주소에서 새로고침 시 404가 납니다.
(Vercel이 실제 파일을 찾다가 없으니 404를 내는데, 모든 경로를 index.html로 넘겨야 라우터가 처리합니다)
게임 (미니게임 카테고리)
네비게이션의 게임 메뉴를 누르면 게임 목록(/games)이 뜨고, 카드를 눌러 개별 게임으로 들어갑니다.
앞으로 추가되는 미니게임(사다리, 빙고 …)은 전부 이 목록 안에 카드로 들어갑니다 —
네비게이션에 메뉴가 하나씩 늘어나지 않습니다.
돌림판
game_templates 테이블을 그대로 씁니다(스키마 변경 없음).
- 범위 선택: 만들 때 "이 반에서만" / "학원 전체 공용" 중 선택. 공용으로 만들면 모든 반에서 보입니다.
- 항목 편집: 선생님·원장만 가능. 바꾸는 즉시 저장됩니다(같은 학원 누구나 바로 최신 목록을 봄).
- 학생도 접근 가능: 자기 반의 돌림판을 보고 돌릴 수 있지만 항목은 수정할 수 없습니다(RLS로 강제).
- 당첨된 항목 제거하며 진행: 켜면 그 판(브라우저 세션)에서만 당첨 항목이 빠집니다. 저장된 템플릿은
그대로라 새로고침하면 원래 목록으로 돌아옵니다. 발표 순서 뽑기처럼 중복 없이 뽑을 때 씁니다.
학원 로고
설정 → 학원 로고에서 이미지를 올리면 헤더 좌측 브랜드 마크(기본은 🐷)가 학원 로고로 바뀝니다.
- 업로드 전 브라우저에서 자동으로 256×256 PNG로 축소해서 올립니다 (원본 그대로 올리지 않음 — 용량/로딩 속도 때문).
- 저장 경로는
logos/<academy_id>/logo.png 로 학원마다 고정. RLS로 자기 학원 폴더에만 쓸 수 있고, 읽기는 공개 버킷이라 누구나 가능합니다 (로그인 화면 등에서도 문제없이 표시하려면 공개가 맞습니다).
- "기본 이미지로" 버튼으로 다시 🐷로 되돌릴 수 있습니다.
출석부
- 반별 통장 카드마다 "등원"/"하원" 버튼이 있습니다. 누르면 그 즉시 시각이 기록되고,
버튼은 시각이 찍힌 채로 비활성화됩니다 (등원 전엔 하원 버튼이 막혀 있음).
- 상단 출석부 메뉴(또는 반별 통장의 "출석부" 버튼)에서 반별 · 월별로 학생 × 날짜 표를 봅니다.
빈 칸을 누르면 그날 출석 처리, 이미 표시된 칸을 누르면 등원/하원 시각을 보여주는 팝업이
뜹니다 — 실수로 바로 삭제되지 않도록 확인 단계를 거치고, 등원만/하원만 따로 지우거나 그날
기록 전체를 지울 수 있습니다. 칸에 마우스를 올려도 시각이 툴팁으로 보입니다.
맨 오른쪽에 그 달 출석일수가 나옵니다.
- 학부모 자동 알림(카톡/문자)은 아직 없습니다. 별도 논의 중 — README 상단 "다음 작업" 참고.
홈 화면에 추가 (PWA)
스마트폰에서 앱처럼 아이콘으로 실행할 수 있습니다.
- 매니페스트 + 아이콘(
app/public/manifest.webmanifest, icon-192/512.png, apple-touch-icon.png)을
붙여서 Android Chrome은 자체 설치 배너를 띄우고, iOS Safari는 홈 화면 추가 시 아이콘/이름이 제대로 잡힙니다.
InstallBanner 컴포넌트가 기기를 감지해서 안내합니다:
- iOS(사파리) → "공유 아이콘 → 홈 화면에 추가"
- Android → "⋮ 메뉴 → 홈 화면에 추가"
- 카카오톡 인앱 브라우저 → 카카오톡은 홈 화면 설치 자체를 지원하지 않아서, "‥ 메뉴 → 다른
브라우저로 열기"를 안내합니다 (그 메뉴를 코드로 대신 눌러줄 방법은 없어서 위치만 알려주는 방식).
- 이미 홈 화면에서 실행 중이면(standalone) 아무것도 안 뜹니다.
- 한 번 닫으면
localStorage에 기억해서 다시 안 뜹니다.
다음 작업
- 미니게임 추가 (사다리 → 빙고).
game_templates.game_type 값만 늘리면 되는 구조.
- 포인트 상품 교환 기능 (
redemptions 활용)
- 선생님별 담당 반 제한 (지금은 학원 내 모든 반 접근 가능)
