class-rpg

우리반 성장 RPG

초등 학급 운영용 웹앱. 학생들이 퀘스트를 수행하고 경험치·골드·레벨·스탯을 쌓으며 캐릭터·농장·전투 등으로 성장하는 “학급 성장 RPG”다.

기술적으로는 정적 HTML + 바닐라 JavaScript + Firebase Realtime Database 기반이다. 빌드 도구·번들러·프레임워크·package.json이 없다. 브라우저가 HTML을 열고, HTML이 외부 JS/CSS와 Firebase SDK(CDN)를 직접 불러오는 단순 구조다.

⚠️ 이 저장소는 RPG 프로젝트 단독이다. (사내 다른 “가지(branch)” 프로젝트와는 완전 별개이며, RPG에는 AI 기능이 없다.)

프로젝트 개요

화면 구성

세 개의 독립 HTML이 각각 다른 사용자/용도를 담당한다. 셋 다 같은 Firebase 트리를 공유한다.

화면 파일 용도
학생 student.html 학생 본인 화면. 캐릭터·퀘스트·보상 수령·농장·전투·작품 등
관리(교사) admin.html 교사용 관리 화면. 학생 관리, 퀘스트/보상 승인, 설정, 백업/복원/초기화
키오스크 kiosk.html 교실 공용 “할 일 체크판”. 학생이 퀘스트 신청/취소(부분 저장 위주)

파일 구조

루트에 앱 파일이 평면(flat)으로 놓여 있다.

gamedata.js        공유 데이터 + DB 레이어 (게임 상수, Utils, Firebase 연결/정규화/저장 helper)
student.html  / student.js  / student.css     학생 화면
admin.html    / admin.js    / admin.css       관리(교사) 화면
kiosk.html    / kiosk.js    / kiosk.css        키오스크(할 일 체크판) 화면
assets/monsters/                               몬스터 이미지 100장 (iconImg()가 이모지 폴백과 함께 표시)
scripts/verify-safety.mjs                      저장 안전 정적 검증 스크립트 (Node 기본 모듈만)
scripts/smoke-test.mjs                         로컬 HTTP/정적 구조 smoke-test
docs/                                          리팩토링 안전 규칙 / 인수인계 / 에셋 명세 문서
CNAME                                          GitHub Pages 커스텀 도메인 (funclassrpg.kr)

각 파일 역할

로드 구조 (중요)

세 HTML 모두 클래식 스크립트로 로드한다 — type="module"/async/defer를 쓰지 않는다.

(Firebase compat SDK, Chart.js)  →  ./gamedata.js  →  ./<화면>.js

실행 방법

빌드 단계가 없다. 정적 파일을 그대로 브라우저가 열면 된다.

로컬 확인은 간단한 정적 서버 사용을 권장한다(상대경로/브라우저 보안정책 안정):

python3 -m http.server 8800
# → http://localhost:8800/student.html (admin.html / kiosk.html)

file:// 직접 열기 주의점

운영/배포

curl -s "https://funclassrpg.kr/student.js?v=20260602&cb=$(date +%s)"

Firebase 데이터 구조 요약

루트 키 classRPG_v3 아래에 학급 전체 상태가 모여 있다(주요 노드):

노드 내용
students 학생별 객체(경험치·골드·레벨·스탯·인벤토리·집/농장·작품 등). pendingRewards는 학생 객체 내부의 배열
questLogs 퀘스트 수행 로그
boardQuests 게시판(공용) 퀘스트
promotionRequests / pwResetRequests 승급 요청 / 비밀번호 재설정 요청
artworks 학생 작품
emotionLogs 감정 기록
settings 학급 설정(반 이름, 보스, 보상 기준 등)
customMonsters / customQuestTemplates / hiddenQuestTemplates 교사 커스텀/숨김 항목
backups 관리 화면에서 만든 백업 스냅샷

안전 검증

저장 footgun과 구조 회귀를 막기 위한 정적 검증 스크립트가 있다(외부 의존성 0, Node 기본 모듈만):

node scripts/verify-safety.mjs

검증 시 점검하는 주요 항목: 필수 파일 존재, node --check 문법, DB.save(/this.save( 0건, kiosk pendingRewards 부분 저장, HTML 로드 순서/클래식 로드, 날짜 helper Utils 통일, kiosk 정규화 통일, HTML 인라인 <script>/<style> 잔여 등.

작업 원칙

리팩토링/안정화 작업은 다음 규칙을 따른다(상세는 docs/rpg_refactor_safety_rules.md).

고위험 주의 영역

아래는 건드리기 전에 별도 승인 + 조사가 필요한 영역이다(현재 보류).

참고 문서

현재 안정화 상태