등호 수사대

초등 3~4학년 학생이 등호를 ‘답을 쓰는 표시’가 아니라 양쪽 값이 같다는 관계로 이해하도록 돕는 정적 학습 웹앱입니다. 서버·로그인·외부 API 없이 36문항 은행에서 뽑은 9문항을 풀고, 오답을 복기한 뒤 다시 도전할 수 있습니다.

공개 주소

• 웹앱: https://wbmaker2.github.io/equality-detective/
• GitHub 저장소: https://github.com/WBmaker2/equality-detective

main 브랜치가 갱신되면 GitHub Actions가 정적 파일만 모아 GitHub Pages에 자동 배포합니다.

학습 목표

• 식의 왼쪽과 오른쪽을 각각 계산합니다.
• 두 계산값이 같은지 비교합니다.
• 빈칸이나 잘못된 수를 양쪽 값이 같도록 고칩니다.
• 왼쪽 값 = 오른쪽 값 또는 왼쪽 값 ≠ 오른쪽 값인 이유를 확인합니다.

관련 성취기준은 [4수02-03] 등호를 사용하여 크기가 같은 두 양의 관계를 식으로 나타낼 수 있다.입니다.

문제 유형과 난이도

한 세션은 도움·기본·도전 단계에서 각각 3문항씩, 총 9문항으로 구성됩니다. 36문항 은행을 네 세션에 걸쳐 순환해 각 단계·유형 위치에서 같은 문항이 반복되지 않습니다. 각 단계에는 다음 활동이 한 번씩 등장합니다.

• 같을까요?: 식이 참인지 거짓인지 판단합니다.
• 빈칸을 채워요: 세 선택지 중 등식을 성립시키는 수를 고릅니다.
• 틀린 식을 고쳐요: 강조된 수를 알맞은 수로 바꿉니다.

도움 단계는 수 모형과 답 선택 위치를 자동으로 보여 줍니다. 작은 화면에서는 답 고르기로 이동을 눌러 선택지로 바로 이동할 수 있습니다. 기본·도전 단계는 학생이 요청할 때 각각 계산하기와 값 비교하기 힌트를 차례로 보여 주며, 단계가 바뀌는 4번째·7번째 문제에는 짧은 안내가 나타납니다. 두 번째 힌트도 정답 관계는 말하지 않습니다. 모든 답 제출 뒤에는 왼쪽 값, 오른쪽 값, 등호의 의미가 나타납니다.

결과 화면의 다시 볼 사건에는 틀린 식, 학생이 고른 답, 좌우 계산값과 올바른 관계가 나타납니다. 오답 목록 위와 아래에서 틀린 문제를 바로 다시 풀 수 있습니다. 문제를 푸는 중에는 수사 중단을 사용할 수 있으며, 선택하거나 제출한 기록이 있으면 확인 창에서 처음 화면으로 갈 때 탭의 학습 기록이 지워짐을 알려 줍니다.

헤더의 수업 모드를 켜면 프로젝터용으로 글자와 식이 커지고 새 수사는 고정된 문제 순서로 진행됩니다. 문제 화면의 문제 읽어 주기와 피드백의 해설 읽어 주기는 학생이 누를 때만 브라우저의 한국어 음성 합성을 실행합니다. 읽는 동안 버튼은 읽는 중 · 멈추기로 바뀌며 같은 버튼으로 음성을 멈출 수 있습니다. 음성의 종류와 품질은 운영체제와 브라우저에 따라 다를 수 있습니다.

로컬 실행

Node.js와 Python 3가 필요합니다.

npm install
npm start

브라우저에서 http://127.0.0.1:4173에 접속합니다. 4173 포트를 다른 앱이 사용 중이면 해당 서버를 종료하거나 다음처럼 임시 포트를 사용할 수 있습니다.

python3 -m http.server 4175 --bind 127.0.0.1

검증 명령

npm test
npm run test:e2e
npm run check:lines
npm run check

• npm test: 계산·문제 은행·학습 세션 단위 테스트
• npm run test:e2e: Chromium에서 키보드, 탭 복원, 수업 모드, 읽어 주기, 오답 복기, 안전한 중단, 반응형 흐름 검증
• npm run check:lines: HTML·CSS·JavaScript·테스트 파일이 모두 500줄 미만인지 검증
• npm run check: 위 세 품질 검사를 순서대로 실행

E2E는 다른 프로젝트의 4173 서버를 잘못 재사용하지 않도록 127.0.0.1:4174에 격리된 테스트 서버를 시작합니다.

개인정보와 저장 정책

• 이름, 학급, 장기 성적 등 개인정보와 학습 기록을 서버로 수집하지 않습니다.
• 현재 문제, 선택·제출 상태, 힌트 단계, 문항 순환 상태와 수업 모드 설정만 sessionStorage에 저장합니다.
• 같은 탭에서 새로고침하면 이어서 풀 수 있고, 일반적으로 탭을 닫으면 임시 기록이 삭제됩니다.
• localStorage, 쿠키, IndexedDB는 사용하지 않습니다.
• API·분석 도구·외부 CDN 요청을 보내지 않습니다.
• 저장 데이터가 손상되었거나 저장소 접근이 차단되면 기록을 사용하지 않고 정상적으로 시작합니다.

업데이트 내역 관리

화면 아래 푸터의 업데이트 내역 버튼에서 최초 개발일과 개선 내용을 확인할 수 있습니다. 앱을 수정할 때는 src/content/changelog.js 배열 맨 앞에 실제 KST 날짜, 제목, 한 줄 이상의 개선 내용을 추가합니다. 기존 기록은 고치거나 지우지 않습니다.

MVP 제외 범위

• 로그인, 교사 대시보드, 학급 코드, 클라우드 저장
• 자유 입력 수식, 문제 자동 생성, AI 해설
• 곱셈·나눗셈, 음수, 분수, 소수, 혼합 계산
• 타이머, 랭킹, 배지, 음성 녹음, 학습 분석
• HVC 관리자 등록, 정적 갤러리 동기화