시사 문해력 기르기 학습지

이번 주 주요 뉴스로 학생들의 어휘력·문해력을 기르는 웹앱입니다. 매주 월요일 새벽 서버가 Brave 뉴스 검색으로 지난 7일 한국·세계 주요 뉴스를 모아 AI(Claude)가 주제 2개를 고르고(정치·일일 날씨 제외), 학년군(초34 / 초56 / 중학생)마다 수준에 맞춘 기사·어휘 퀴즈·생각 나누기 질문을 미리 만들어 둡니다. 교사는 이번 주 기사 불러오기로 반 학년군 기사를 가져오거나 나만의 학습지 제작하기로 원하는 신문 기사를 학습지로 만들고, 검토·수정 후 배포하면 학생은 기사 읽기 → 어휘 퀴즈 → 스스로 요약(AI 피드백) → 생각 나누기 순서로 학습합니다.

지금까지 바뀐 내용은 작업 기록(CHANGELOG.md)에서 볼 수 있습니다.

주요 기능

구분	기능
교사	17개 시·도 교육청 메일로만 가입: 메일로 받은 인증 코드 확인 후 계정 생성, 로그인, 반 만들기(초34 / 초56 / 중학생), 반 코드 발급, 학생 PIN 초기화
교사	베타 테스트 체험: 가입 없이 공용 체험 계정으로 모든 기능 사용(예시 기사, AI 비용 없음)
교사	기사·어휘·퀴즈·채점 기준·생각 나누기 질문 편집, 기사별 다시 만들기, 배포/배포 취소
교사	이번 주 기사 불러오기: 서버가 매주 학년군별로 미리 만들어 둔 기사를 AI 호출 없이 복사해 초안으로 만들기. 아직 준비되지 않았으면(Cron 실패 등) 누를 때 그 반 학년군 기사를 바로 만듦 (카드에서 이번 주 기사 제목 미리 보기, 이미 불러왔으면 표시)
교사	나만의 학습지 제작하기: 신문 기사 주소(또는 본문)를 붙여넣으면 AI가 분석(Claude Haiku 4.5)해 반 학년군 수준으로 기사·어휘·퀴즈·생각 나누기 질문 작성
교사	결과 분석표: 기간(학생 제출일 기준)을 골라 학생별 어휘 퀴즈(유형별 정답률·틀린 낱말)와 요약(평균·영역별·점수 변화)을 한 표에서 정렬·비교, 최근 3주 퀴즈 정답률이나 요약 평균이 30% 미만이면 '도움 필요' 표시, 반 전체 AI 의견(학생용 문장·교사용 메모)을 Claude Haiku 4.5 Batch API로 만들고 고치기
교사	학생별 완독·퀴즈·요약 점수·생각 표, 요약문과 AI 피드백·의견 상세 보기, 부적절한 의견 숨기기, CSV 내려받기
학생	교사가 만든 반의 반 코드 + 번호·이름 + PIN 4자리로 입장 (PIN 5회 오류 시 5분 잠금). 학생은 교사 계정을 만들 수 없음
학생	기사 읽기: 스크롤 끝 + 최소 읽기 시간을 채워야 다음 단계, 핵심 어휘를 누르면 뜻 보기
학생	어휘 퀴즈 7문항: 문맥 속 빈칸 채우기 2·비슷한 말 2·내용 이해 3(사실·까닭과 영향·중심 생각), 문항마다 정답·해설 (첫 답만 점수에 반영)
학생	요약: 100점 만점(핵심 내용 50 / 텍스트 재구성 30 / 문장 완성도 20) + 잘한 점·빠진 내용·조언, 최대 3회 제출
학생	생각 나누기: 입장 선택 + 까닭 쓰기(필수) → 제출 후 반 친구들의 입장 비율과 의견을 이름 없이 보기
학생	관심 분야 학습(상시): 우주·과학 / 지구·환경 / 경제 / 역사·문화 상자에서 키워드를 골라 언제든 기사 읽기 → 어휘 퀴즈 → 요약. 기사마다 별 최대 3개(끝까지 읽고 퀴즈 풀기 ★, 퀴즈 70% 이상 ★, 요약 70점 이상 ★)를 모으고 학생 홈 위쪽에 모은 별을 표시. 분야마다 기사가 한 줄로 이어져 첫 기사만 열려 있고, 별 3개를 모으면 자물쇠가 열리는 애니메이션과 함께 다음 기사가 열림(잠긴 기사는 # ??? 로 가림). 관심 분야 학습에서는 퀴즈를 다시 풀 수 있고 가장 잘한 기록으로 별을 셈. 우리나라 교육과정에서 그 내용을 배우는 학년군 학생에게만 보임
교사	반 화면 성취도 탭에서 학생별로 관심 분야 학습에서 모은 별(★)과 상점에서 쓰고 남은 별 보기
교사	별 상점: 반마다 상품(이모지·이름·설명·가격·수량·1인당 최대 개수)을 등록·수정·삭제하고, 교환 기록과 학생별 모은 별·쓴 별·남은 별 보기
학생	별 상점: 모은 별로 선생님이 올린 상품을 교환. 누르는 즉시 별이 빠지고 기록이 남음(모은 별·열린 기사는 그대로). 품절·1인당 한도·별 부족이면 버튼이 막힘
학생	내 학습 분석: 지금까지 푼 어휘 퀴즈(유형별 정답률·다시 볼 낱말)와 요약(평균·영역별·점수 변화), AI가 쓴 응원 한마디 보기
안전	AI 사용 고지(입장·기사·피드백 화면), 학생 글의 개인정보·욕설 차단(AI 전송 전), 운영 정책 페이지

바로 실행해 보기 (데모 모드)

API 키가 없어도 실행됩니다. 이때는 예시 기사로 학습지가 만들어지고, 요약은 간단한 규칙으로 채점하며, 데이터는 .data/db.json 파일에 저장됩니다.

npm install
npm run dev

http://localhost:3000 에 접속 → 선생님으로 시작하기에서 가입 → 반 만들기 → 이번 주 기사 불러오기(데모 모드에서는 누르는 즉시 예시 기사로 준비) → 배포 → 다른 브라우저(또는 시크릿 창)에서 학생으로 시작하기.

실제 뉴스로 운영하기

.env.example을 .env.local로 복사하고 값을 채웁니다.

1. Brave Search API — Brave API 대시보드에서 가입 → 크레딧 충전(선불, 1,000회당 약 $5) → API Keys에서 키 발급 → BRAVE_API_KEY. 학습지 1회 생성에 약 15회(약 $0.08)를 씁니다.
2. Anthropic API — Claude Console에서 결제 수단 등록 후 API Keys에서 키 발급 → ANTHROPIC_API_KEY (모델은 CLAUDE_MODEL로 바꿀 수 있고 기본값은 claude-sonnet-5-5. 요약 채점·기사 분석·결과 분석표 의견은 claude-haiku-4-5).
3. Supabase — 프로젝트 생성 → SQL Editor에서 supabase/schema.sql 실행(이미 만든 DB에 다시 실행해도 새 열만 추가됨) → Project Settings > API의 URL과 secret(service_role) key → SUPABASE_URL, SUPABASE_SECRET_KEY
   • Vercel에서 Supabase 연동(Marketplace)을 쓰면 자동으로 들어가는 NEXT_PUBLIC_SUPABASE_URL, SUPABASE_SERVICE_ROLE_KEY도 그대로 인식합니다.
4. SESSION_SECRET, CRON_SECRET — 각각 32자 이상 무작위 문자열 (예: openssl rand -base64 32)
5. SMTP (교사 가입 인증 메일) — Gmail이면 앱 비밀번호를 만들고 SMTP_HOST=smtp.gmail.com, SMTP_PORT=465, SMTP_USER=내 Gmail, SMTP_PASS=앱 비밀번호. 없으면 개발 환경에서만 인증 코드가 화면·콘솔에 표시되고, 배포 환경에서는 가입이 막힙니다.
6. (선택) TEACHER_EMAIL_DOMAINS — 17개 시·도 교육청 메일(src/lib/teacher-email.ts에 고정) 외에 더 허용할 도메인(예: example.go.kr). 쉼표로 여러 개.
7. (선택) TEACHER_SIGNUP_CODE — 넣으면 메일 인증에 더해 이 코드도 입력해야 가입할 수 있습니다.

Vercel 배포

1. GitHub 저장소를 Vercel에서 Import
2. Settings > Environment Variables에 위 값을 모두 입력 (배포 환경에서는 Supabase, SESSION_SECRET, CRON_SECRET, SMTP_*가 필수)
3. Deploy — vercel.json의 Cron 두 개가 자동으로 등록됩니다.
   • 0 19 * * 0 = 매주 월요일 04:00 KST: 이번 주 기사 준비
   • 0 21 * * * = 매일 06:00 KST: 빠지거나 실패한 기사 채우기 (모두 준비돼 있으면 AI를 부르지 않고 바로 끝남), 도착한 결과 분석표 AI 의견 가져오기, 관심 분야 학습 기사 자동 추가(아래)

이번 주 기사 준비(뉴스 수집 + 학년군 3개 × 기사 2개)는 몇 분 걸려 Cron 함수 최대 실행 시간을 300초로 설정해 두었습니다(maxDuration, Hobby 요금제 최대값). 시간 안에 다 끝나지 않아도 고른 주제와 완성된 기사는 저장되고, 다음 실행이 남은 기사부터 이어서 만듭니다.

이번 주 기사를 지금 바로 만들려면 (처음 배포했을 때 등): Vercel 프로젝트 Settings > Cron Jobs에서 /api/cron/weekly의 Run을 누르거나, curl -H "Authorization: Bearer <CRON_SECRET>" https://<배포 주소>/api/cron/weekly를 실행합니다. 로컬 개발 서버에서도 같은 주소(http://localhost:3000/api/cron/weekly)로 실행할 수 있습니다.

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