수학 학습 플랫폼

고등학교 교사가 운영하는 AI 학습 플랫폼. 학생은 학번으로 로그인해 내 교과 → 단원 → 활동(GeoGebra·자료·문제·사진·HTML 체험)을 수행하고, AI 소크라테스 문답과 사진/PDF 풀이 첨삭을 받습니다. 교사는 학생 계정 일괄 생성·활동 관리·진도 확인·기록 다운로드를, 관리자는 교사 계정까지 관리합니다.

누구나 — 로그인 없이 쓰는 조작 자료 만져보는 수학 · 학생 화면 체험 /demo 선생님 — 가입하면 내 학급(학생·교과·활동·기록)을 바로 꾸릴 수 있습니다 활동만 보기 — 공통수학2 인터랙티브 활동 30개: 활동 아카이브

주요 기능

대상	기능
학생	내 교과 → 단원 → 활동, 진도 저장, ‘내 생각 적기’ 서술, AI 문답·첨삭
교사	가입만 하면 내 학급 — 학생 일괄 생성, 교과·단원·활동 관리, 만져보는 수학을 활동 한 화면으로 추가, 진도 현황, 서술 읽기, 기록 CSV, 내 AI 키·모델·한도·프롬프트. 자료와 학생 기록은 내 것만 보입니다
학교 교사	관리자가 만든 교사 — 위 기능 + 학교 학생 명단에서 골라 담기(담임·교과 교사가 함께 담기 가능)
관리자	교사 계정만 관리 — 교사 가입 열고 닫기, 교사 계정 만들기·삭제, 내 학생·자료 넘기기, 만져보는 수학 자료 관리
누구나	만져보는 수학(/hands-on) — 로그인 없이, 링크만으로 열리는 조작 자료(기록 없음) · 체험판(/demo)

수학이 아닌 다른 교과로 바꾸는 법과 처음부터 만드는 법: docs/06_BUILD_FROM_SCRATCH.md

🚀 5분 만에 내 것으로 배포하기 (원클릭)

아래 버튼을 누르면 이 코드가 당신의 Vercel 계정으로 복사·배포됩니다. (배포 중 Supabase·AI 키를 입력하는 칸이 나옵니다 — 아래 절차 참고)

다른 분이 이 저장소를 자기 GitHub로 복사(fork)했다면, 버튼 주소의 sced9120 을 자기 아이디로 바꾸세요.

배포 순서 (버튼 누르기 전에 Supabase부터):

1. Supabase 프로젝트 생성 (supabase.com, Region: Seoul) → SQL Editor에 supabase/setup.sql 전체를 붙여넣고 Run (표·보안정책·함수가 한 번에 만들어짐)

2. Supabase → Project Settings → API 에서 URL / anon key / service_role key 복사

3. 위 Deploy 버튼 클릭 → 나오는 입력칸에:

   • NEXT_PUBLIC_SUPABASE_URL, NEXT_PUBLIC_SUPABASE_ANON_KEY, SUPABASE_SERVICE_ROLE_KEY → 2번 값
   • AI 키는 여기 넣지 않습니다 — 배포 후 각 교사가 AI 설정 화면에서 자기 키를 등록합니다

4. 배포된 주소로 접속 → 관리자 계정 만들기 화면이 자동으로 뜹니다. 아이디·이름·비밀번호를 정하면 끝. 이후 관리자 화면에서 교사·학생 계정을 만들면 됩니다.

   이 화면은 계정이 하나도 없을 때만 열리고, 첫 관리자가 만들어지면 스스로 닫힙니다. 터미널을 쓰고 싶다면 대신 npm run create-teacher -- admin 관리자 --admin 도 가능합니다.

각 단계를 화면과 함께 자세히: docs/06_BUILD_FROM_SCRATCH.md

기술 스택

Next.js (App Router, TypeScript) · Tailwind CSS · Supabase (Postgres + Auth + RLS) · Vercel 배포 · OpenAI/Anthropic

---

1. 처음 설정하기

1-1. Supabase 프로젝트 만들기

1. supabase.com → New project (Region: Northeast Asia — Seoul 권장)
2. Project Settings → API Keys 에서 세 값을 확인:
   • Project URL
   • anon(public) key
   • service_role(secret) key

1-2. 환경변수

cp .env.local.example .env.local

변수	용도	노출 범위
NEXT_PUBLIC_SUPABASE_URL	Supabase 프로젝트 URL	클라이언트 공개
NEXT_PUBLIC_SUPABASE_ANON_KEY	공개 키 (RLS로 보호됨)	클라이언트 공개
SUPABASE_SERVICE_ROLE_KEY	관리자 키 — RLS 우회	서버 전용. 절대 클라이언트/저장소에 노출 금지

1-3. 데이터베이스 설정

Supabase 대시보드 SQL Editor에 supabase/setup.sql 전체를 한 번에 붙여넣고 Run 하세요 (테이블·RLS 정책·함수가 모두 만들어집니다). (setup.sql 은 0001~0018 을 모두 합친 파일입니다 — 새로 설치할 때는 이것 하나면 됩니다.)

supabase CLI 로 하고 싶다면 supabase init 과 supabase link --project-ref <ref> 를 먼저 해야 supabase db push 가 동작합니다. 이 저장소에는 config.toml 이 없어 기본은 SQL Editor 방식입니다.

이미 운영 중인 분은 setup.sql 을 다시 돌리지 말고, 아직 실행하지 않은 마이그레이션만 supabase/migrations/ 에서 번호 순으로 SQL Editor 에 붙여넣어 실행하세요. (이 저장소는 supabase CLI 를 쓰지 않습니다 — config.toml 이 없어 supabase db push 는 동작하지 않습니다.)

파일	하는 일
0010_subjects.sql	교과(subjects) 계층 추가 — 교과 → 단원 → 활동
0011_student_owner.sql	학생에 담당 교사 지정 — 교사는 자기 학생만 보고 관리
0012_screen_responses.sql	활동 화면별 기록칸 + 사진 첨부 — 화면마다 다른 질문을 두고 답도 화면 단위로 저장. 비공개 버킷 student-uploads 도 이 SQL 이 만듭니다
0013_activity_screens.sql	활동을 화면 단위로 (activity_screens) + 기록을 질문 단위로 확장. 학생용 조회 함수 student_screens() 가 정답을 걷어내고 내려줍니다
0014_ai_authoring.sql	교사용 조작 활동 만들기 챗봇을 AI 기능에 추가 (일일 한도 기본 40회)
0015_ai_usage_authoring.sql	위와 한 쌍 — ai_usage 쪽 제약도 넓힙니다. 0014 만 실행하면 제작 챗봇이 500 으로 실패합니다
0016_teacher_students.sql	담당을 여러 교사가 나눠 가질 수 있게 (teacher_students). 교사가 서버 전체 명단에서 골라 자기 목록에 담습니다. 관리자가 만든 학생이 교사에게 안 보이던 문제를 없앱니다
0017_open_platform.sql	누구나 교사 가입 + 교사별 공간 + 교사별 AI + 만져보는 수학. 교과·단원·소단원·활동에 주인(owner_id) — 교사는 자기 것만, 학생은 자기를 담은 교사 것만. 학생 기록은 담은 교사만. 가입 교사(self_signup)에게는 학교 명단이 안 보이고 학생은 학급 코드(class_code)로 로그인. AI 키·모델·한도·프롬프트를 교사별로(owner_id), 관리자 → 교사 넘기기(transfer_teaching), 사이트 설정(site_settings), 공개 조작 자료(manipulatives). 이 SQL 을 먼저 실행한 뒤 새 코드를 배포하세요
0018_hands_on_levels.sql	만져보는 수학을 학교급(초등학교·중학교·고등학교) 메뉴로 나눕니다 (manipulatives.school_level, 기존 예시는 고등학교). 중학교 작도에 자유 작도(눈금 없는 자와 컴퍼스) 를 넣습니다. 이 SQL 을 먼저 실행한 뒤 새 코드를 배포하세요

0011 을 실행하면 기존 학생은 가장 먼저 만들어진 교사/관리자에게 자동 배정됩니다 (아무에게도 안 보이게 되는 것을 막기 위함). 이후 관리자 화면에서 확인할 수 있습니다.

0013 은 screen_responses 의 기본키를 질문 단위로 바꿉니다. 기존 행은 question_key = '' 로 남아 그대로 읽히므로 예전에 낸 답이 사라지지 않습니다.

0016 은 지금의 profiles.teacher_id 담당 관계를 teacher_students 로 그대로 옮깁니다 — 실행 직후 각 교사의 목록은 전과 같습니다. teacher_id 는 남지만 뜻이 "이 계정을 만든 사람" 으로 바뀌어, 이제 계정 삭제 권한을 가리는 데만 쓰입니다.

0017 을 실행하면 기존 교과·단원·활동과 AI 키·모델·한도·프롬프트는 전부 가장 먼저 만들어진 관리자의 것이 됩니다. 관리자를 담당으로 둔 학생에게는 지금과 똑같이 보입니다. 그다음 관리자 화면 교사 관리 → 내 학생·자료 넘기기로 수업용 교사 계정에 옮기세요(학생은 계속 학번만으로 로그인).

무엇까지 적용됐는지 확인하려면 SQL Editor 에서:

以上为 README 的开头部分。其余内容请阅读原文。 查看完整 README ↗