EduSync AI

AI 기반 퀴즈 생성 및 실시간 학습 분석 플랫폼

교사가 수업 자료를 입력하면 AI가 자동으로 퀴즈를 생성하고, 학생의 응답을 실시간으로 분석해 취약 개념을 파악할 수 있는 모바일·웹 교육 앱입니다.

---

라이브 데모 주소

: https://project-edu-sync-ai.vercel.app

주요 기능

교사

• AI 퀴즈 생성 — 수업 자료 텍스트 입력 → Gemini 2.5 Flash가 4지선다 5문제 자동 생성
• 입장 코드 — 수업별 6자리 코드를 학생에게 공유
• 실시간 대시보드 — 학생 응시 현황·정답률을 Supabase Realtime으로 즉시 반영
• 개념 분석 — 취약/강점 개념 태그 자동 집계

학생

• 퀴즈 탭 — 상단 입장 코드로 수업 참여 → 같은 화면 내 퀴즈에서 목록 선택·응시(별도 「수업 참여」 탭 없음)
• 오답 플로우 — 다음 문제로 바로 진행 가능, 필요 시 힌트 보기(Gemini 소크라테스식 힌트)
• 응시 완료 — 모든 문항 제출 완료 시 목록에서 취소선·비활성 표시, 동일 퀴즈 재응시 불가(리포트·통계 신뢰도)
• 학습 리포트 — 개념별 정답률 시각화 + 응시 이력

---

문서

문서	설명
docs/user-guide.md	사용자 가이드 (탭·플로우)
docs/demo-guide.md	웹(Vercel) 데모 시연 스크립트
docs/e2e-test-checklist.md	수동 E2E 체크리스트
docs/sample-quiz-materials.md	AI 퀴즈 생성 테스트용 붙여넣기 지문
NEXT_TO_DO.md	인프라·카카오·Secrets 점검

---

기술 스택

분류	기술
프레임워크	Expo SDK 54 + Expo Router v6
UI	React Native + NativeWind v4 (Tailwind CSS)
백엔드	Supabase (Auth · DB · Realtime · Edge Functions)
상태 관리	TanStack Query v5 + Context API
AI	Google Gemini 2.5 Flash API (EXPO_PUBLIC_GEMINI_MODEL로 변경 가능)
인증	카카오 OAuth (Supabase Edge Function 경유)
배포	EAS Build (모바일) · Vercel + GitHub Actions (웹)

---

시작하기

사전 준비

• Node.js 20+
• Expo CLI
• Supabase 프로젝트
• 카카오 개발자 콘솔 앱 등록
• Google AI Studio Gemini API 키

설치

git clone https://github.com/your-username/project--edu-sync-ai.git
cd project--edu-sync-ai
npm install

환경변수 설정

cp .env.example .env

.env 파일에 값을 입력합니다:

EXPO_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
EXPO_PUBLIC_SUPABASE_ANON_KEY=eyJ...
EXPO_PUBLIC_KAKAO_NATIVE_APP_KEY=카카오_앱_키
EXPO_PUBLIC_GEMINI_API_KEY=AIza...

Supabase 설정

1. DB 마이그레이션 실행 (Supabase Dashboard → SQL Editor)

# 순서대로 실행
supabase/migrations/001_initial_schema.sql
supabase/migrations/002_role_nullable.sql
# (선택) 002를 건너뛴 경우 역할 변경 시 400이 나면 아래도 실행
supabase/migrations/003_ensure_profiles_role_nullable.sql

2. Edge Function 배포

npm install -g supabase
supabase login
supabase functions deploy kakao-auth --project-ref {프로젝트_ref}

Edge Function Secrets 추가 (Dashboard → Edge Functions → kakao-auth → Secrets):

Key	Value
KAKAO_REST_API_KEY	카카오 REST API 키
SUPABASE_SERVICE_ROLE_KEY	Supabase service_role 키

3. 카카오 Redirect URI 등록 (카카오 개발자 콘솔 → 내 앱 → 카카오 로그인)

https://{supabase-project-ref}.supabase.co/functions/v1/kakao-auth

실행

# 개발 서버 시작
npm start

# 웹 브라우저
npm run web

# iOS (Xcode 필요)
npx expo run:ios

# Android (Android Studio 필요)
npx expo run:android

---

프로젝트 구조

├── app/                        # Expo Router 페이지
│   ├── (auth)/                 # 인증 플로우
│   │   └── role-select.tsx     # 역할 선택 화면
│   ├── (teacher)/              # 교사 전용
│   │   ├── quiz-create.tsx     # AI 퀴즈 생성
│   │   ├── quiz-library.tsx    # 퀴즈 목록
│   │   └── dashboard.tsx       # 실시간 대시보드
│   ├── (student)/              # 학생 전용
│   │   ├── quiz-list.tsx       # 입장 코드 + 퀴즈 목록
│   │   ├── join.tsx            # → quiz-list 리다이렉트(구 URL 호환)
│   │   ├── quiz.tsx            # 퀴즈 응시
│   │   └── report.tsx          # 학습 리포트
│   └── index.tsx               # 진입점 (역할별 라우팅)
│
├── src/
│   ├── api/
│   │   ├── ai.ts               # Gemini API (퀴즈 생성·힌트)
│   │   ├── quiz.ts             # 퀴즈 CRUD
│   │   ├── logs.ts             # 대시보드·리포트 집계
│   │   ├── auth.ts             # 카카오 로그인
│   │   └── supabase.ts         # Supabase 클라이언트
│   ├── hooks/
│   │   ├── useQuizGeneration.ts
│   │   ├── useQuiz.ts
│   │   ├── useRealtimeLogs.ts
│   │   └── useReport.ts
│   ├── store/
│   │   └── AuthContext.tsx      # 전역 인증 상태
│   ├── components/common/
│   │   ├── Button.tsx
│   │   └── LoadingSpinner.tsx
│   ├── components/layout/
│   │   └── ScreenContent.tsx   # max-width + 좌우 패딩으로 콘텐츠 폭 제한
│   └── types/index.ts
│
├── supabase/
│   ├── migrations/             # DB 스키마
│   └── functions/kakao-auth/   # 카카오 인증 Edge Function
│
├── docs/
│   ├── user-guide.md           # 사용자 가이드
│   ├── demo-guide.md           # 웹 데모 시연 가이드
│   ├── e2e-test-checklist.md   # 수동 E2E 테스트 체크리스트
│   └── sample-quiz-materials.md # 퀴즈 생성 테스트용 샘플 지문
│
├── eas.json                    # EAS Build 설정
└── vercel.json                 # Vercel 웹 배포 설정

---

배포

모바일 (EAS Build)

npm install -g eas-cli
eas login
eas build:configure

# 테스트 빌드 (APK + IPA)
npm run build:preview

# 스토어 제출용 빌드
npm run build:prod

웹 (Vercel)

main 브랜치에 push하면 GitHub Actions가 자동으로 Vercel에 배포합니다.

필요한 GitHub Secrets:

VERCEL_TOKEN, VERCEL_ORG_ID, VERCEL_PROJECT_ID
EXPO_PUBLIC_SUPABASE_URL, EXPO_PUBLIC_SUPABASE_ANON_KEY
EXPO_PUBLIC_KAKAO_NATIVE_APP_KEY, EXPO_PUBLIC_GEMINI_API_KEY

수동 배포:

npm run build:web   # dist/ 폴더 생성
vercel --prod

---

데이터베이스 스키마

profiles          — 사용자 (kakao_id, role, display_name)
classrooms        — 수업 (teacher_id, name, entry_code)
classroom_members — 수업-학생 참여 (N:M)
quiz_sets         — 퀴즈 세트 (classroom_id, title, questions JSONB)
student_logs      — 응답 기록 (student_id, question_id, is_correct, ai_feedback)

학생의 응시 완료 판정은 student_logs에 해당 퀴즈의 모든 question_id가 쌓였는지로 계산합니다. 완료된 퀴즈는 앱에서 재응시 UI가 비활성화됩니다.

RLS(Row Level Security) 정책으로 교사는 본인 수업만, 학생은 참여한 수업의 데이터만 접근합니다.

---

라이선스

MIT