고등학교 영단어 학습/시험 웹 서비스 | Firebase Console

랭킹, 자율 학습, 모의 시험, 그리고 선생님이 진행하는 감독 시험(단어 테스트)에 응시할 수 있습니다.
선생님은 관리자 페이지에서 단어장과 시험을 직접 관리합니다.
고등학교 부분과 학교 로고 등은 자유롭게 자신의 학교 이름으로 바꿔 사용하면 됩니다.

주요 기능

• 랭킹: 오늘 응시한 단어 모의 시험 중 최고 점수 기준 실시간 순위
• 단어장 / 단어 외우기: 단어장 열람, 단어를 하나씩 넘기며 학습
• 단어 모의 시험: 학생이 원할 때마다 자율적으로 응시하는 연습 시험
• 단어 테스트: 선생님이 개설하는 감독 시험 — 실명 응시 CheckStar가 탭 전환/창 포커스 이탈/전체화면 이탈을 감지해 자동 실격 처리
• 관리자 페이지: 단어장 CRUD(일괄 가져오기 포함), 시험 생성 및 실시간 모니터링, 엑셀 결과 다운로드, 선생님 가입 승인, 다크 모드 지원

기술 스택

영역	사용 기술
프론트엔드	Vite, React, TypeScript, React Router, Zustand, Tailwind CSS
백엔드	Firebase (Auth, Firestore, Cloud Functions, Storage)

시작하기

1. 사전 준비

• Node.js 20 이상
• Firebase 프로젝트 (Auth: Google 로그인 활성화 / Firestore / Storage / Blaze 요금제)
• Firebase CLI (npm i -g firebase-tools)

2. 설치

npm install
cd functions && npm install && cd ..

3. 환경 변수 설정

.env.example을 .env로 복사 각 값을 본인의 Firebase 콘솔(프로젝트 설정 → 일반 → 내 앱)에서 발급받은 값으로 채워주세요.

cp .env.example .env

VITE_FIREBASE_API_KEY=          # Firebase 콘솔에서 발급받은 값 입력
VITE_FIREBASE_AUTH_DOMAIN=
VITE_FIREBASE_PROJECT_ID=
VITE_FIREBASE_STORAGE_BUCKET=
VITE_FIREBASE_MESSAGING_SENDER_ID=
VITE_FIREBASE_APP_ID=
VITE_GOOGLE_HD=                 # 선택: 특정 구글 워크스페이스 도메인으로 로그인 제한, 예: "your-school.hs.kr"

.firebaserc의 default 프로젝트 ID도 본인의 Firebase 프로젝트 ID로 변경해주세요.

4. 로컬 개발

npm run dev

5. 최초 관리자(슈퍼 관리자) 등록

Firebase 콘솔에서 서비스 계정 키(JSON)를 발급받아 로컬에 내려받고, 등록할 계정으로 사이트에 구글 로그인을 한 번 해둔 뒤:

GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json" npm run bootstrap-admin -- "admin@example.com" "관리자 이름"

6. 단어 데이터 시딩 (선택)

[{ "word": "...", "meaning": "..." }, ...] 형식의 JSON 파일을 준비한 뒤:

GOOGLE_APPLICATION_CREDENTIALS="/path/to/serviceAccountKey.json" npm run seed -- "./words.json"

7. 배포

# Firestore 규칙 / Cloud Functions
firebase deploy --only firestore:rules,functions

# 프론트엔드 (Cloudflare Workers)
npm run deploy

Cloudflare Workers로 배포하려면 wrangler.toml의 name/도메인을 본인 환경에 맞게 수정하고, npx wrangler login으로 먼저 로그인해주세요.

폴더 구조

src/                학생·교사 프론트엔드 (React)
functions/           Cloud Functions (채점, 랭킹 집계, 관리자 승인 등 서버 로직)
scripts/             관리자 부트스트랩 / 단어 시딩용 1회성 스크립트
firestore.rules      Firestore 접근 제어 규칙