🎭 멀티진진가 (진짜 진짜 가짜) · made by 문수네집

학생들이 진짜 사실 5가지를 적으면 그중 하나를 그럴듯한 가짜로 바꿔, 반 전체가 "어느 것이 가짜일까?"를 맞히는 실시간 교실 게임입니다. QR로 입장하고 api.moonsunezip.com의 PostgreSQL REST API와 방 단위 WebSocket으로 동기화합니다. 화면은 index.html, 데이터 연결은 postgres-adapter.v1.js입니다. 방·학생·문제·투표는 임시 데이터입니다.

made by 문수네집 — 🏠 문수네집 · 📷 인스타그램 · ✨ moonsune.zip

✅ 배포 완료 — 바로 사용 가능

👉 https://jinjinga.moonsunezip.com

• 데이터 원본: 홈서버 PostgreSQL (api.moonsunezip.com)
• 배포: GitHub main 푸시 후 홈서버 자동 배포. Firebase 데이터 저장은 사용하지 않습니다.

촬영용 가상 학생 시연

1. 선생님으로 실제 방을 만듭니다. 아직 학생이 없는 대기실에서 촬영용 가상 학생의 주제를 고릅니다.
2. 음식 취향 소개·운동 취향 소개·동물 취향 소개 중 하나를 선택하고 봇 1명 추가, 봇 5명 추가, 최대 50명 채우기를 누릅니다. 선생님은 학생 수에 포함되지 않습니다.
3. 봇들이 문제를 제출하면 발표 시작하기를 누릅니다. 봇은 자기 발표를 제외하고 실제 투표에 참여합니다.
4. 정답 공개·다음 문제·게임 종료는 기존 버튼으로 조작합니다. 촬영 중 봇 일시정지 / 계속 진행으로 투표를 멈추거나 이어갈 수 있습니다.

• 각 주제에 미리 만든 가상 취향 프로필 100개(진짜 5문장과 대응하는 가짜 문장)가 있습니다. 외부 AI 호출 없이 무작위로 고릅니다. 가상 학생의 설정이며 실제 사람이나 실제 사실에 대한 주장이 아닙니다.
• 50명 기준 문제별 정답률은 약 42→50→58→66→72→62→52→44→36→46% 순서로 변합니다. 맞히는 봇과 오답 선택지는 매번 무작위입니다. 인원이 적으면 표 수에 맞춰 반올림됩니다.
• 대기실에서 시연 봇 비우기로 봇의 참가·문제만 비울 수 있습니다. 실제 학생의 데이터는 비우지 않습니다. 주제를 바꾸려면 먼저 봇을 비웁니다.
• 교사 화면을 열어 둬야 봇이 자동으로 투표합니다. 새로고침 후에도 방 설정에 저장된 봇을 이어받습니다. 생성 중 다른 방으로 이동하면 나머지 생성은 멈춥니다.
• 데이터 등급: 기존 진진가와 같은 임시 데이터입니다. 기존 api.moonsunezip.com/v1/jinjinga/rooms/...의 학생·문제·투표별 행을 사용하며 별도 API·DB·서버·소켓을 만들지 않습니다. 100ms 이상 간격으로 생성하고 한 번에 1표씩 전송합니다. 기존 requestId 및 제한된 재시도를 유지합니다.
• 운영 서버 설정: 정적 화면 3001, 공용 PostgreSQL API 3100. 기존 API 주소·스키마·PM2·Cloudflare 설정 변경은 필요 없습니다.

검증: node --test demo-bots.test.mjs postgres-adapter.test.mjs. 50명 생성, 25명 투표, 50명 정답률 변화, 중복 클릭, 새로고침·방 이동, 학생별 제출 플래그 저장을 확인합니다. 브라우저 검증은 운영 API와 분리한 로컬 API 모형을 사용했습니다.

게임 흐름

1. 선생님: 접속 → 문제 방 만들기 → 주제 입력 + 가짜 방식 선택(AI / 직접 작성) → 방 생성
2. QR코드·방 코드가 표시됨. 학생은 QR을 찍거나 코드 입력 → 이름 입력 → 입장
3. 학생: 진짜 사실 5개 작성 → 그중 1개를 골라 비슷한 가짜로 직접 변경(예시·팁 자동 안내) → 제출
4. 선생님 화면: 누가 제출했는지 실시간 표시 (○/○ 완료)
5. 선생님: 발표 시작하기 → 학생 한 명씩 문제 슬라이드 표시
6. 학생: 각자 폰에서 가짜라고 생각하는 보기에 투표 (실시간 집계)
7. 선생님: 정답 공개 → 가짜 강조 + 진짜값 + 정답률 → 다음 → 반복
8. 마지막에 문제별 정답률 요약

가짜 만드는 방식

학생이 진짜 5개 중 하나를 골라 직접 비슷한 가짜로 바꿉니다. 작성 화면에 예시·팁이 자동으로 표시돼요:

• 🔢 숫자·개수: "강아지를 3마리 → 2마리 키운다"
• 📍 장소: "제주도 → 부산에서 태어났다"
• 📅 연도·이름: "2015년 → 2016년에 이사했다"

AI·외부 API를 전혀 쓰지 않습니다. API 키·요금·네트워크 호출이 필요 없어 100% 무료로 동작합니다.

데이터 구조 (Realtime Database)

rooms/JJG_<코드>
  ├─ topic, state(writing|presenting|done)
  ├─ players/<pid>   : name, submitted
  ├─ problems/<pid>  : items[5], fakeIndex, realValue, submittedAt
  ├─ present         : order[], idx, revealed
  └─ votes/<주인pid>/<투표자pid> : 선택한 보기 index

기존 qr-bingo 보안 규칙(rooms/$room 읽기·쓰기 허용)을 그대로 사용하므로 규칙 수정이 필요 없습니다.

파일

• index.html — 앱 전체 (HTML/CSS/JS + Firebase + QR, 빌드 불필요)
• firebase.json, .firebaserc — 배포 설정 (hosting target: jinjinga → 사이트 jinjinga-class)

🏠 홈서버 배포 정보 (moonsunezip 노트북 서버)

다른 세션·다른 AI 에서 이 앱을 고치기 전에 이 섹션을 먼저 읽으세요. 서버 관리자가 관리하는 섹션입니다(마지막 갱신 2026-09-27). 앱 설명은 위쪽 본문을 보세요.

멀티진진가 — 운영 정보

항목	값
주소	https://jinjinga.moonsunezip.com
서버 포트	3001 (PM2 이름 jinjinga)
배포 브랜치	main
배포 방식	빌드 없음 — 저장소 루트의 index.html 등을 그대로 정적 서버가 제공
서버 위치	C:\homeserver\apps\multijinjinga

이 앱만의 주의점

• 빌드 과정이 없어서 저장소 루트의 파일이 그대로 공개됩니다. 비밀값이나 내부 메모 파일을 루트에 두지 마세요.
• 데이터는 postgres-adapter.v1.js → https://api.moonsunezip.com/v1/jinjinga/…, 실시간은 wss://api.moonsunezip.com/v1/realtime?room=방코드 입니다(쿼리 이름은 room, code 아님). 실시간은 서버→화면 단방향이고, 보내는 것은 HTTP 로 합니다.
• 진진가 데이터(jjg_* 테이블)는 임시 데이터입니다. PostgreSQL UNLOGGED 테이블이라 빠르지만, 24시간이 지나면 자동 삭제되고 서버가 비정상 종료되면 비워집니다. 선생님이 오래 남길 기능(문제 저장 등)은 /v1/documents 같은 영구 저장소를 쓰세요.
• firebase.json, pb-adapter.js 는 예전 흔적입니다. 새 코드에서 쓰지 마세요.
• 실측 수용량: 권장 5,000명(200개 반), 동시 WebSocket 10,400개까지 끊김 없음 확인.

이 서버는 어떤 곳인가

• 집 노트북 1대(Lenovo IdeaPad L340 · i5-9300H 4코어 8스레드 · RAM 8GB · Windows 11)가 moonsunezip.com 의 앱 전부를 서비스합니다.
• 모든 앱은 127.0.0.1 에만 열리고, 외부 접속은 Cloudflare Tunnel 이 전담합니다(집 IP·포트 비노출, HTTPS 자동).
• 프로세스는 PM2 가 관리하고, 5분마다 감시(watchdog) 가 죽은 앱을 되살립니다.
• 데이터 저장은 PostgreSQL 17 + 공용 API(https://api.moonsunezip.com) 입니다. Firebase·PocketBase 는 새로 쓰지 않습니다.
• 여유 자원: RAM 여유 약 0.8GB(넉넉하지 않음), 집 인터넷 업로드 약 170Mbps(Wi-Fi).

배포 흐름 — 반드시 이해하고 수정하세요

1. 배포 브랜치에 push 하면 서버가 3분 안에 감지합니다.
2. 서버는 git reset --hard origin/<브랜치> 로 코드를 통째로 덮어쓰고 → npm ci → npm run build → PM2 재시작 순서로 배포합니다.
3. 빌드나 헬스체크가 실패하면 이전 버전으로 자동 롤백되고 사이트는 이전 상태로 유지됩니다.

따라서:

• 서버 폴더를 직접 고치지 마세요. 다음 배포 때 사라지거나, "커밋 안 된 수정"으로 판단돼 배포가 멈춥니다.
• package-lock.json 을 반드시 커밋하세요(npm ci 는 lock 파일이 없으면 실패합니다).
• 게임 서버가 있는 앱은 배포 = 서버 재시작 = 진행 중인 방이 전부 사라짐 입니다. push 하기 전에 서버 관리자에게 물어보세요(.md 문서만 바꾼 push는 재시작 없음).

실시간·게임 코드를 짤 때 지킬 것 (실제로 겪은 문제들)

규칙	이유
서버는 HOST, PORT 환경변수를 읽고 기본값을 127.0.0.1 로	주소를 0.0.0.0 으로 코드에 고정하면 서버 설정으로 바꿀 수 없음
IP 당 제한을 걸지 마세요	학교는 전교생이 공인 IP 하나로 나갑니다. 윷놀이의 "IP당 방 6개" 제한이 학교 전체를 막았습니다
방 상태 전송 시각·타이머는 방마다 따로	전역 변수 하나로 두면 한 반의 활동이 다른 반 갱신을 밀어냅니다(줄다리기에서 최장 4초 멈춤)
큰 상태를 자주 보내면 WebSocket 압축(perMessageDeflate)	줄다리기 20개 반 기준 161Mbps → 3Mbps
끊긴 학생이 60초 안에 같은 자리로 재접속할 수 있게	교실 와이파이는 자주 끊깁니다. 빈 방도 60초는 유지하세요
요청 처리 중 동기 파일 I/O·느린 OS 호출 금지	Windows 에서 os.networkInterfaces() 1회 25ms → 30명 방에서 서버가 멈췄습니다
요청마다 목록 전체를 훑는 코드 금지	사용자가 늘수록 느려집니다(backend 처리량이 4분의 1이던 원인)
비밀값(키·비밀번호)은 저장소에 넣지 않기	서버의 비밀값은 C:\homeserver\secrets 에 따로 있습니다

부하 목표: 한 학교 20개 반 동시 사용(약 600명). 전국 배포라 한글날처럼 특정 날에 몰립니다.

공용 서버 주소

용도	주소
데이터 API (PostgreSQL)	https://api.moonsunezip.com — /v1/documents/doc·/query·/commit, /health
데이터 실시간 알림 (서버→화면 단방향)	wss://api.moonsunezip.com/v1/realtime?room=방코드 · /v1/documents/realtime?scope=범위
공용 게임 서버 (메모리, 양방향)	wss://game.moonsunezip.com/v1/game?room=방코드&game=게임이름&name=이름

새 주소(서브도메인)나 새 포트가 필요하면 서버 쪽에서 Cloudflare 설정과 PM2 등록을 해야 합니다. 코드만 올려서는 열리지 않습니다.

📏 코드 규칙 (coderule)

이 저장소를 고치기 전에 moonsugugu/coderule 을 먼저 읽으세요. 사람과 AI 모두 지킵니다.

핵심 여섯 가지

1. 30명 반 하나의 전송량은 1Mbps 이하. 메시지 크기(바이트) × 초당 횟수 × 받는 사람 수 × 8 ÷ 1,000,000 으로 완료 전에 잰다. 2026-10-02 고조선이 30명 방 하나에 22Mbps를 써서, 20개 반이 몰리자 집 업로드(약 170Mbps)가 막혀 모든 앱이 끊겼다.
2. 바뀐 것만 보내고, WebSocket 압축(perMessageDeflate)을 켜고, 위치처럼 계속 바뀌는 값은 초당 57회 + 화면 보간. 입력마다 즉시 방송하지 말고 50150ms 모아서 보낸다.
3. 인원 제한에 선생님을 세지 않는다. IP당 제한을 걸지 않는다(학교는 전교생이 공인 IP 하나).
4. 방마다 타이머 따로, 끊긴 학생은 60초 이상 같은 자리 유지, 서버는 HOST·PORT 환경변수(기본 127.0.0.1), 요청 경로에 동기 I/O 금지.
5. 배포·앱 재시작·터널 재시작은 서버 관리자에게 물어보고 한다. 배포 = 서버 재시작 = 진행 중인 방이 전부 사라진다. (README 같은 .md 문서만 바꾼 push는 재시작 없이 반영된다)
6. 서버가 바쁘면 끊지 말고 느리게(과부하 보호, 규칙 19). 이 앱의 데이터·실시간은 backend(api.moonsunezip.com)가 맡는다. backend 가 쓰기를 적응형 대기열로 나눠 처리하고, 바쁜 동안 실시간 연결을 끊지 않는다. 화면은 쓰기 503 을 받으면 1~5초 간격으로 늘려 가며 다시 시도하고, 같은 요청을 곧바로 반복하지 않는다.

이 저장소 점검(2026-10-02): 이미 규칙을 지키고 있습니다(api.moonsunezip.com 방 단위 실시간, 바뀐 행만 전달, 재접속 백오프 최대 15초).

재접속·QR·부하 점검 (2026-10-02)

• 선생님/방장 화면에서 참가 QR을 클릭하면 팝업이 열립니다. 180~720px 슬라이더와 확대·축소 버튼, Esc·바깥 클릭 닫기를 지원하며 작은 화면에는 QR 전체가 보이도록 맞춥니다.
• 같은 기기·브라우저의 새로고침/다시 입장에서 기존 참가 정보와 방별 자리를 복원합니다. 실제 계정 로그인 기능이 없는 게임은 참가 자리 복귀를 뜻합니다.
• 같은 방의 병렬 읽기는 한 HTTP 요청으로 합칩니다. 겹치는 구독의 중복 호출과 과거 소켓의 종료 경합을 방지하고 화면 갱신을 80ms 묶습니다.
• 쓰기 요청은 requestId를 헤더와 본문에 포함합니다. 409/429/503·오프라인·타임아웃은 같은 ID로 최대 세 번 재시도합니다. 개별 학생/문제/투표 행을 분리합니다.
• node --test postgres-adapter.test.mjs로 25명 동시 저장, ID 재사용, 방 격리, 재접속과 제한된 재시도를 검증했습니다. 테스트 API의 중복 제거를 검증했으며 운영 API 자체의 requestId 중복 제거는 서버 코드 확인이 별도로 필요합니다.