분수 연산 마스터

초등 분수·소수 연산 연습 웹앱 (37레벨). 배포 주소: https://mathpractice-five.vercel.app/ Google Apps Script(스프레드시트 + google.script.run)로 만들었던 「수학 연산 마스터」를 정적 웹앱 + Firebase Firestore 로 옮긴 것입니다.

• 빌드 도구 없음 — HTML/CSS/JS 파일을 그대로 Firebase Hosting에 올리면 끝
• 외부 CDN 의존 없음 — Tailwind와 Chart.js를 vendor/ 에 직접 담아 학교 네트워크에서도 안전
• Firebase 설정 전에는 로컬 모드(localStorage)로 그대로 돌아가므로 바로 열어볼 수 있음

---

1. 레벨 구성 (전 37레벨)

다음 레벨의 도전 연습을 열려면 이전 레벨 도전에서 오답 2개 이하(과정형 레벨은 1개 이하), 그리고 시간 감점 없이(제한시간의 80% 이내) 완주해야 합니다. (자유 연습은 언제나 열려 있습니다. 기준은 js/levels.js 의 allowedWrong 로 조절합니다.)

그룹	레벨	내용	방식	만점
🎨 개념	L1	분수 개념 — 그림 보고 맞히기 (대분수 포함)	4지선다	90
	L2	소수 개념 — 그림 보고 맞히기 (1보다 큰 소수 포함)	4지선다	95
🔁 변환	L3	가분수 → 대분수	4지선다	100
	L4	대분수 → 가분수	4지선다	105
	L5	분수 → 소수 (분모 10·100·1000 · 대분수 포함)	4지선다	110
	L6	소수 → 분수 (분모 10·100·1000 · 대분수 포함)	4지선다	115
🍕 동분모	L7	분모가 같은 분수의 덧셈 (약분 없음)	4지선다	120
	L8	분모가 같은 분수의 뺄셈 (약분 없음)	4지선다	125
🔗 통분	L9	최소공배수 구하기	4지선다	130
	L9-2	통분 과정 연습 — 최소공배수 → 학습지처럼 a/b = a×□/b×□ = □/□ 칸 채우기	과정	133
	L10	분수 통분하기	4지선다	135
➕➖ 이분모	L11	진분수 덧셈, 합이 1을 넘게	과정	140
	L12	〃	4지선다	145
	L13	진분수 뺄셈	과정	150
	L14	〃	4지선다	155
🎯 대분수	L15	대분수의 덧셈	과정	160
	L16	〃	4지선다	165
	L17	대분수의 뺄셈	과정	170
	L18	〃	4지선다	175
🔢 소수	L19	소수의 덧셈 (두 자리까지)	4지선다	180
	L20	소수의 뺄셈 (두 자리까지)	4지선다	185
	L21	소수의 덧셈 (자릿수 다름)	4지선다	190
	L22	소수의 뺄셈 (자릿수 다름)	4지선다	195
✖️ 분수의 곱셈	L23	진분수 × 자연수	과정	200
	L24	〃	4지선다	205
	L25	대분수 × 자연수 ① — 자연수 부분·분수 부분 따로 곱하기	과정	210
	L26	대분수 × 자연수 ② — 대분수를 가분수로 바꿔 곱하기	과정	215
	L27	대분수 × 자연수 계산하기	4지선다	220
✖️ 분수의 곱셈 ②	L28	자연수 × 진분수	과정	225
	L29	〃	4지선다	230
	L30	자연수 × 대분수 ① — 자연수 부분·분수 부분에 따로 곱하기	과정	235
	L31	자연수 × 대분수 ② — 대분수를 가분수로 바꿔 곱하기	과정	240
	L32	자연수 × 대분수 계산하기	4지선다	245
	L33	진분수 × 진분수	과정	250
	L34	〃	4지선다	255
	L35	대분수 × 대분수	과정	260
	L36	〃	4지선다	265

과정(단계 풀이)이 물어보는 것

L11 이분모 덧셈을 예로 들면: 분모가 같은가? → 최소공배수 → 통분 ① ② → 분자끼리 계산 → 약분 확인·실행 → 답이 1을 넘으므로 대분수로 나타내기. 답할 때마다 위쪽 풀이판이 한 줄씩 채워지고, 틀려도 정답을 보여준 뒤 진행합니다.

L9-2 통분 과정: ① 최소공배수 → ② 첫째 분수 a/b = a×□ / b×□ = □/□ 칸 채우기 → ③ 둘째 분수도 같게. 칸마다 맞으면 초록, 틀리면 빨강으로 표시하고 정답을 보여 줍니다. 풀이판의 '통분' 줄은 답할 때마다 채워집니다.

분수의 곱셈(L23·L25·L26)은 통분이 없어 단계가 짧습니다. L23 진분수 × 자연수: 분모는 그대로 두고 분자 × 자연수 → 약분 → (1을 넘으면) 대분수. L25 대분수 × 자연수 ①: 자연수 부분 × 자연수 → 분수 부분 × 자연수 → 약분 → 분수 부분을 대분수로 → 두 결과 더하기. L26 대분수 × 자연수 ②: 대분수를 가분수로 → 분자 × 자연수 → 약분 → 대분수. L28·L30·L31 자연수 × 분수: L23·L25·L26 과 같은 단계를 '자연수 × 분자' 순서로 묻습니다 (3 × 2/5 → 3 × 2 = 6 → 6/5 → 1 1/5). L33 진분수 × 진분수: 분자끼리 곱하기 → 분모끼리 곱하기 → 약분. 답이 늘 1보다 작아 대분수 단계가 없습니다. 절반쯤은 약분이 필요한 문제로 냅니다. L35 대분수 × 대분수: 두 대분수를 가분수로 → 분자끼리 → 분모끼리 → 약분 → 대분수. 정수 부분 13 · 분모 26, 약분 전 분자 200 이하로 수를 묶었습니다. 약분은 모두 곱한 뒤에 합니다 (곱하기 전에 약분하는 방법은 다루지 않음). 곱셈 결과가 정수로 딱 떨어지는 문제(2/3 × 3 = 2)는 내지 않습니다. 곱셈 4지선다(L24·L27)의 오답은 정답과 값이 가까운 것(분자 ±1, 정수 부분 ±1, 분모 ±1, 자연수 부분에만 곱한 값 등)으로 골라 찍기보다 계산을 끝까지 하도록 유도합니다. L34(진분수 × 진분수)는 분자·분모를 더해 버린 답, 분모를 그대로 둔 답, 엇갈려 곱한 답(나눗셈과 헷갈림), 약분 안 한 답을, L36(대분수 × 대분수)은 자연수끼리·분수끼리 따로 곱한 답(3 2/5 × 1 5/6 → 3 1/3)을 늘 보기로 넣습니다.

각 단계에는 간단한 시계가 붙습니다. 지금 단계에서 몇 초를 쓰고 있는지 칩으로 보이고, 답하면 그 단계의 수행 시간이 피드백에 함께 뜹니다. 문제를 끝내면 단계별 수행 시간 표 (가장 오래 걸린 단계는 색으로 표시)와 그 문제 전체 시간이, 도전을 끝내면 단계 이름별 평균 수행 시간이 오래 걸린 순으로 나옵니다. 시간은 화면에만 보여 주고 기록으로 저장하지는 않습니다.

4지선다의 오답 보기

각 유형의 '흔한 실수'가 오답으로 나옵니다 — 약분 안 한 답, 분모끼리 더한 답, 소수점 자리를 안 맞추고 더한 값, 몫·나머지를 뒤바꾼 대분수, 3/4 → 0.34 식 표기 등. 값은 맞지만 형태가 틀린 보기(예: 기약이 아닌 분수, 최소공배수가 아닌 통분)를 고르면 무엇이 아쉬운지 따로 알려 줍니다.

랭킹 (명예의 전당)

학생마다 레벨별 최고 점수를 모두 더한 합계 순으로 나열합니다. 같은 L22를 풀었더라도 먼저 푼 순서가 아니라 L1~L22 합계가 큰 학생이 위로 갑니다. 합계가 같으면 더 높은 레벨까지 간 학생, 그다음은 마지막 기록이 이른 학생이 앞섭니다. 표의 레벨은 그 학생이 도달한 최고 레벨입니다.

채점 규칙

• 분수 답은 기약분수만 정답, 1을 넘는 답은 대분수 형태만 정답입니다. 다만 L5~L8 에서는 약분을 다루지 않습니다. L5·L6(분수↔소수 변환)은 분모를 10·100·1000 으로 두어 소수 자릿수와 1:1로 맞추고, L7·L8(동분모 덧뺄셈)은 분모를 그대로 둔 답이 정답입니다(1/6 + 2/6 = 3/6). 네 레벨 모두 기약분수를 보기로 내지 않아 학생이 헷갈릴 일이 없습니다. 약분은 L9(최소공배수) 이후 이분모 계산에서 다룹니다.
• L1(그림 개념)만 예외 — 그림이 보여 주는 표기 그대로(3/6)가 정답입니다.
• L1·L2의 40%는 "꽉 채운 도형 몇 개 + 부분 도형"으로 대분수(1 1/2)나 1보다 큰 소수(1.69)를 묻습니다. 이때 가분수로 읽은 보기(3/2)를 고르면 대분수로 나타내라고 알려 줍니다.
• 도전 모드 4지선다에서 오답을 고르면 시간이 10초 깎입니다 (찍기 방지).
• 과정형의 정답·오답 피드백 대기는 짧게(0.6~1.8초) 잡고, 그만큼 제한시간을 넉넉히 두었습니다.

---

2. 실행

로컬에서 바로 보기 (Firebase 없이)

npm install
npm start          # http://127.0.0.1:8080

js/firebase-config.js 가 예시값 그대로면 로컬 모드로 동작합니다. 예시 학생 3명이 자동으로 만들어지고 기록은 그 브라우저에만 저장됩니다.

파일 하나로 묶어 나눠 주기 (서버·인터넷 없이)

node tools/build-single-file.js     # → dist/분수연산마스터.html

CSS와 JS를 전부 집어넣은 HTML 한 개가 나옵니다. 더블클릭하면 바로 열리므로 USB로 나눠 주거나 인터넷이 안 되는 교실에서 쓰기 좋습니다. (이 파일은 항상 로컬 모드라 기록이 그 컴퓨터에만 남습니다.)

Firebase에 올리기 (진짜 '사이트'를 만드는 단계)

배포하면 https://<프로젝트이름>.web.app 주소가 생깁니다. 그 전까지는 사이트 주소가 없습니다.

1. Firebase 콘솔에서 프로젝트를 만들고 Firestore Database를 (프로덕션 모드로) 켭니다.
2. 프로젝트 설정 → 내 앱 → 웹 앱 추가 → 설정값을 복사해 js/firebase-config.js 에 붙여넣습니다.
3. .firebaserc.example 를 .firebaserc 로 복사하고 프로젝트 ID를 채웁니다.
4. 배포:

npm install -g firebase-tools
firebase login
firebase deploy --only firestore:rules,hosting

---

3. Firestore 데이터 구조

컬렉션	내용
teachers/{uid}	교사 프로필 (Firebase 인증 계정과 1:1)
classes/{반코드}	반 — teacherUid, name, archived, offDays(등교 안 하는 날, YYYY-MM-DD 배열)
classes/{반코드}/students/{번호}	학생 — number, name, pinHash
classes/{반코드}/results	연습·도전 기록
classes/{반코드}/best/{번호}	학생별 레벨 최고점 요약 — 랭킹용 (학생 기기가 자동으로 채움)
classes/{반코드}/logs	접속 로그

읽기 한도 (무료 요금제 하루 5만 건)

Firestore 무료 요금제(Spark)는 하루 읽기 5만 건까지이고, 한국 시간 오후 4~5시(미국 태평양 자정)에 다시 채워집니다. 한도를 넘기면 그때부터 모든 읽기가 실패합니다. 예전 버전은 레벨 화면을 열 때마다 반 전체 기록(최대 3,000건)을 읽었고, 읽기에 실패하면 빈 기록으로 보여 줘서 다 푼 학생도 '초기화'된 것처럼 보였습니다. 지금은 이렇게 읽습니다.

• 학생 화면: 자기 기록만 읽음. 저장한 기록은 캐시에 바로 덧붙여 다시 읽지 않음
• 랭킹(학생 화면): best 요약만 읽음 (학생 수만큼, 5분 캐시)
• 반 전체 기록: 교사 화면의 랭킹 탭에서만 읽음. 이때 모든 학생의 best 요약도 다시 채움
• 읽기가 실패하면 점수를 지우지 않고, 그 기기에 남은 마지막 기록과 함께 🔄 다시 불러오기 안내를 띄움

best 컬렉션은 보안 규칙을 새로 배포해야 쓸 수 있습니다(firebase deploy --only firestore:rules, 또는 Firebase 콘솔 → Firestore → 규칙에 firestore.rules 내용을 붙여넣고 게시). 배포 뒤 교사 화면 랭킹 탭을 한 번 열면 모든 학생의 요약이 채워집니다.

학생 명단 넣기

Firestore 콘솔에서 students 컬렉션에 문서를 하나씩 추가합니다. 문서 ID는 학번으로 두는 것이 편합니다.

students/1   { number: "1", name: "김철수", pinHash: "" }
students/2   { number: "2", name: "이영희", pinHash: "9f2c..." }

• pinHash 가 비어 있으면 그 학생은 비밀번호 없이 바로 들어갑니다.
• 해시값은 tools/pin-hash.html 을 브라우저로 열어 만드세요.

교사 PIN

기본값은 js/firebase-config.js 의 DEFAULT_TEACHER_PIN (490800) 입니다. 바꾸려면 config/app 문서에 teacherPinHash 를 넣으세요 (역시 tools/pin-hash.html 사용).

학생 비교의 '이전 등교일' 자동 설정

교사 화면 학생 비교 탭은 열 때마다 비교 대상일 = 오늘, 비교 기준일 = 오늘의 이전 등교일로 자동 채워집니다. 월요일에 열면 지난 금요일, 연휴 다음 날에 열면 연휴 전 마지막 등교일과 비교합니다. 기준일을 직접 고르면 자동이 멈추고, ↺ 이전 등교일로 자동 버튼으로 다시 켤 수 있습니다.

등교일 판단(js/schoolday.js)은 다음을 뺀 월~금입니다.

• 날짜가 고정된 공휴일 — 신정 · 3·1절 · 어린이날 · 현충일 · 광복절 · 개천절 · 한글날 · 성탄절. 3·1절 · 어린이날 · 광복절 · 개천절 · 한글날 · 성탄절이 토·일과 겹치면 대체공휴일(다음 평일)도 자동으로 뺍니다.
• 반에서 정한 등교 안 하는 날 — 설·추석·부처님오신날처럼 해마다 바뀌는 날, 선거일, 재량휴업일, 방학. 학생 비교 탭의 📅 등교 안 하는 날 설정에 한 줄에 하나씩(2026-09-24) 적고 저장하면 반 문서의 offDays 필드에 들어갑니다. # 뒤는 메모로 무시됩니다.

offDays 는 반 코드만 알면 읽을 수 있으므로, 칠판 공지판 같은 다른 프로그램에서 같은 등교일 기준을 쓸 수 있습니다.

개인 링크

https://<프로젝트>.web.app/?student=3 처럼 열면 그 학생으로 바로 들어갑니다. ?view=teacher 로 열면 교사 로그인 화면으로 바로 갑니다.

---

4. ⚠️ 보안에 대해 (꼭 읽어 주세요)

이 앱은 요청하신 대로 Firebase 인증 없이 동작합니다. 그래서 다음이 사실입니다.

• 앱 URL을 아는 사람은 누구나 학생 명단과 모든 점수 기록을 읽을 수 있습니다.
• 점수는 브라우저에서 계산해 저장하므로, 마음먹으면 점수를 위조할 수 있습니다.
• 학생 PIN·교사 PIN은 해시로 저장해도 자릿수가 짧아 알아낼 수 있습니다. PIN은 "다른 친구 이름으로 잘못 들어가는 것"을 막는 정도로만 생각하세요.
• 교사 대시보드 PIN도 마찬가지로 화면을 가려 줄 뿐, 데이터를 지켜 주지는 못합니다.

firestore.rules 는 인증 없이 할 수 있는 만큼은 막아 두었습니다.

• 기록은 추가만 가능 — 이미 저장된 점수를 고치거나 지울 수 없음
• 학생 명단과 설정은 읽기 전용 — 콘솔에서만 수정
• 기록 문서의 필드 종류·개수·값 범위를 검사해 아무 데이터나 못 넣게 함

나중에 이 부분이 신경 쓰이면 익명 인증(Anonymous Auth) 을 켜고 규칙을 request.auth != null 로 좁히는 것이 가장 적은 노력으로 크게 나아지는 방법입니다. 점수 위조까지 막으려면 Cloud Functions에서 점수를 계산해야 하고, 이때는 Blaze 요금제가 필요합니다.

---

5. 파일 구조

index.html              모든 화면의 마크업
css/app.css             분수 표기 · 풀이판 · 세로셈 격자 스타일
vendor/tailwind.css     Tailwind 빌드 결과 (CDN 대신 직접 호스팅)
vendor/chart.umd.js     Chart.js (성장 그래프)
js/firebase-config.js   Firebase 설정 (직접 채우는 파일)
js/fraction.js          분수 코어 (약분 · 사칙연산 · 대분수 변환 · 한국어 조사)
js/decimal.js           소수 코어 (정수 스케일 연산 · 분수↔소수 변환)
js/pictures.js          L1·L2 그림 문제용 SVG 생성기
js/levels.js            레벨 정의 · 잠금 규칙 · 점수 계산
js/schoolday.js         등교일 판단 (주말 · 공휴일 · 대체공휴일 · 반별 등교 안 하는 날)
js/generator.js         레벨별 문제 생성 + 4지선다 오답 보기
js/db.js                Firestore / localStorage 데이터 계층
js/session.js           연습 세션 공통 (타이머 · 결과 화면 · 저장)
js/step-frac.js         분수 단계 풀이 엔진
js/quiz.js              4지선다 엔진 (오답 시간 페널티 포함)
js/app.js               화면 전환 · 레벨 목록 · 교사 대시보드
tools/pin-hash.html     PIN 해시 생성기
tools/build-single-file.js  파일 하나로 묶는 스크립트
firestore.rules         Firestore 보안 규칙