info-class-portal

장평중학교 1학년 정보과 수업 포털 · 2026학년도 2학기

하나의 대문에 들어오면 오늘 자기 반 수업으로 바로 이어지는 웹앱. 설계 근거는 PRD.md에 있다.

• 수업 진입점 — 코드 2자리 + 학번 5자리로 오늘 수업에 진입
• 감정 체크 — 무드미터 4사분면, 익명 집계는 교실 앞 화면에 공유
• 한 줄 성찰 — 차시별 질문, 입력 중 자동 임시저장, 학기 누적 기록
• 출석 확인 — 인증 완료 시각(접속 로그)으로 확정
• 교사 대시보드 — 접속자 명단, 감정·성찰 열람, 명렬표·차시·시간표 관리

기술 스택: Next.js 16 (App Router) · React 19 · Tailwind CSS 4 · Firebase Firestore · Vercel

---

1. 왜 이런 구조인가

학생 브라우저는 Firestore에 직접 접근하지 않는다. 학생 화면의 모든 읽기·쓰기는 Next.js Route Handler(서버)를 거치고, 서버만 Firebase Admin SDK를 쓴다. 그래서 firestore.rules를 전면 차단으로 둘 수 있고, 명렬표 112명이 클라이언트로 통째로 내려가는 경로가 아예 존재하지 않는다.

코드를 학번보다 먼저 받는다. 학번이 규칙적(10209)이라 학번을 먼저 받으면 아무 숫자나 넣어 이름을 조회할 수 있다. 코드가 앞에 있으면 그 교실에 있는 학생만 이름 확인 화면에 도달한다. 수업 코드는 (날짜, 교시, 반)에 묶이므로 다른 반 코드를 알아내도 통과하지 못한다.

세션에 스냅샷을 복사한다. 교사는 1반 수업을 해보고 부족한 부분을 다음 반 수업 전에 고친다. 차시 계획만 수정하면 이미 끝난 1반 기록이 소급 변경되어 "1반은 어떤 질문에 답한 것인가"를 알 수 없게 된다. 그래서 세션 생성 시점에 슬라이드 URL·성찰 질문을 세션으로 복사하고, 수정은 아직 시작하지 않은 세션에만 반영한다.

공유 화면과 개별 열람 화면은 API부터 분리했다. 교실 앞에 띄우는 /teacher/board가 쓰는 /api/teacher/board 응답에는 학번·이름·이유가 아예 들어 있지 않다. 화면 코드가 실수해도 개인 응답이 뜰 수 없다.

---

2. 설정

2.1 Firebase

Firebase 콘솔에서 프로젝트를 연다 (없으면 생성).

1. Firestore 생성 — 빌드 > Firestore Database > 데이터베이스 만들기
   • 위치는 반드시 asia-northeast3 (서울). 생성 후 변경할 수 없다.
   • 모드는 프로덕션 모드(전면 차단)로 시작한다.
2. 보안 규칙 적용 — firestore.rules 내용을 규칙 탭에 붙여넣고 게시. 서버는 Admin SDK로 접근하므로 이 규칙의 영향을 받지 않는다.
3. 웹 앱 등록 — 프로젝트 설정 > 내 앱 > 웹(</>) 추가 → firebaseConfig 값을 복사
4. Google 로그인 켜기 — 빌드 > Authentication > 로그인 방법 > Google 사용 설정
5. 승인된 도메인 추가 — Authentication > 설정 > 승인된 도메인에 배포 도메인 (*.vercel.app 또는 사용할 도메인) 추가. localhost는 기본 포함.
6. 서비스 계정 키 발급 — 프로젝트 설정 > 서비스 계정 > 새 비공개 키 생성 (JSON 다운로드)
7. 예산 알림 설정 — Google Cloud Console > 결제 > 예산 및 알림 (이상 징후 조기 감지)

2.2 환경변수

cp .env.example .env.local

.env.local을 열어 값을 채운다.

변수	어디서 얻는가
NEXT_PUBLIC_FIREBASE_API_KEY 등	2.1-3의 firebaseConfig
FIREBASE_PROJECT_ID / CLIENT_EMAIL / PRIVATE_KEY	2.1-6의 서비스 계정 JSON
SESSION_SECRET	node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
TEACHER_EMAILS	교사 Google 계정 이메일 (쉼표로 구분)

TEACHER_EMAILS가 비어 있으면 아무도 교사 화면에 들어올 수 없다. 열어두는 쪽이 더 위험하므로 의도한 기본값이다.

2.3 실행

npm install
npm run dev     # http://localhost:3000

2.4 Vercel 배포

npx vercel        # 프리뷰
npx vercel --prod # 운영

.env.local의 모든 변수를 Vercel 프로젝트 환경변수에도 등록한다. FIREBASE_PRIVATE_KEY는 줄바꿈이 포함된 값이라 \n 이스케이프 그대로 붙여넣어도 된다 (서버에서 복원한다).

---

3. 수업 전 준비 순서

1. /teacher 접속 → Google 로그인
2. 명렬표 — 학번,이름 CSV 업로드 (예: 10101,김철수)
3. 차시 — 차시 번호·제목·슬라이드 URL·성찰 질문 등록
4. 시간표 — 반별 요일·교시를 넣고 학기 전체 세션 일괄 생성 (첫날처럼 한 차시만 급히 열 때는 차시 화면 아래 "수업 하나만 바로 열기" 사용)
5. 대시보드 — 오늘 수업을 고르면 수업 코드 2자리가 크게 보인다. 칠판에 적는다.
6. 학생에게 포털 주소를 알린다 (QR은 학생 태블릿에서 인식되지 않으므로 링크 직접 배포)

수업 중에는 대시보드에 접속자가 5초마다 갱신된다. 수업이 끝나면 수업 종료를 눌러 코드를 만료시키고, 감정 응답을 확인한 뒤 수업 후 메모를 남긴다. 다음 반 수업 전에 그 메모를 보는 것이 개선 루프의 출발점이다.

---

3.1 테스트용 학생

교사가 학생 화면을 직접 걸어보기 위해 각 반 30번을 테스트 계정으로 두었다.

학번	이름	반
10130	가길동	1반
10230	나길동	2반
10330	다길동	3반
10430	라길동	4반

30번을 쓰는 이유: 실제 학생은 128번까지라 겹치지 않고, 임시 번호(9099번)와 달리 정규 학생과 똑같은 경로로 진입하므로 학생이 실제로 겪는 화면을 그대로 볼 수 있다.

주의 — 출석 집계에 포함된다. 이 학생들도 명렬표에 있으므로 대시보드의 정원 수에 잡히고, 접속하지 않으면 "아직 안 들어온 학생"에 뜬다. 예를 들어 1반은 정원이 28명(실제 27 + 테스트 1)으로 표시된다. 수업 중 숫자가 헷갈리면 /teacher/students 에서 해당 학번을 삭제하면 된다.

4. 운영 습관

• 주 1회 CSV 내보내기 — 무료 티어에는 자동 백업이 없다. /teacher/data에서 내려받는다.
• 매 수업 후 감정 확인 — 받아두고 보지 않는 상태가 가장 위험하다. 대시보드가 미확인 건수를 항상 보여준다.
• 월 단위로 감정 이유 삭제 — /teacher/data에서 "감정 — 이유 한 줄"만 지운다. 아이콘·색은 남는다.
• 학기말 일괄 삭제 — 내보내기를 먼저 하고 명렬표·기록을 지운다.

---

5. 데이터 구조

students          학번(문서ID) · 이름 · 반 · 번호 · 임시여부
lessonPlans       차시번호 · 제목 · 슬라이드URL · 성찰질문 · 감정체크여부  ← 반과 무관, 4반 공용
classSessions     문서ID = 날짜__교시__반 · 수업코드 · 스냅샷 · 교사메모
codeReservations  문서ID = 날짜__코드                        ← 코드 중복 발급 방지
attendance        학번 · sessionId · 접속시각                 ← 출석
moodEntries       학번 · sessionId · 감정 · valence/arousal · 이유 · 확인여부
reflections       학번 · sessionId · 내용 · draft
meta/purgeLog     마지막 일괄 삭제 일자

활동 기록에는 학번만 저장한다. 이름은 students에만 있고 화면에 보여줄 때만 조인하므로, 기록 데이터가 유출되어도 숫자만 남는다.

문서 ID로 중복을 막는다. 세션 ID가 날짜__교시__반, 코드 예약 ID가 날짜__코드라서, 두 요청이 동시에 들어와도 Firestore가 뒤엣것을 거부한다. 조회 후 배정하는 방식이면 같은 날 두 반에 같은 코드가 나갈 수 있고, 그러면 한쪽 반 학생 전원이 반 불일치로 막힌다.

학번 범위: 정상 01~30번(정원 28명 + 전입 여유), 임시 90~99번. 그 사이(31~89)는 오타로 보고 거부한다.

---

6. 아직 없는 것

PRD의 로드맵 중 이번 범위에 넣지 않은 것들:

• 산출물 담벼락 (P2, 9월 이후 — 이미지 업로드는 Blaze 전환이 필요하다)
• Gemini API 연동 (성찰 요약·경향 정리). 붙일 때는 PRD 6.5의 전제 조건을 먼저 확인할 것: 유료 티어 키, 비식별 전송, 배치 전송, 개별 학생 진단 금지, 교사 원문 확인.
• 감정 시각화 형태 전환 (나침반형·분포형). 지금은 무드미터 격자 하나.
• 지난 수업 다시 보기 (학생용 아카이브)