게스트 입장 플로우 (디바이스·네트워크·can-enter) — 코드레벨 동작 흐름 P2코드레벨

마지막 업데이트 2026-07-29

동작 흐름 요약

입력: 개요 · 범위
주요 처리 단계: 전체 흐름
결과: 파일 · 라인 레퍼런스

작성일: 2026-06-14 대상: 개발자 — 아동 입장 게이트/디바이스 파악 핵심 파일: components/pages/guest-entry.tsx, hooks/use-device-manager.ts, use-guest-entry-socket.ts

💬 대화로 먼저 이해하기 — "공항 탑승 수속 비유" (비개발자·처음 읽는 사람용)

Q아동이 수업 링크를 누르면 바로 수업방에 들어가나요?

A아니요, 공항 탑승 수속처럼 게이트를 차례로 통과해요. 장비 검사(마이크·카메라 선택 + getUserMedia 권한 확인), 기상 확인(네트워크 품질 표시), 티켓 검사(can-enter 스케줄/상태 검증) 순서죠. 카카오 인앱 브라우저는 제약이 많아 먼저 외부 브라우저로 안내합니다.

Q검사를 다 통과하면 탑승인가요?

A게이트 앞 대기(WaitingRoom)가 남았어요. 승무원(호스트)이 탑승 허가(onApproved)를 줘야 들어가요. 호스트가 요청을 잠시 놓치면 카운트다운 후 자동 재요청으로 복구됩니다.

Q허가가 나면 바로 입장?

A마지막으로 수업에 쓸 짐(활동 영상 등 리소스)을 기내에 실어요 — 완료까지 기다리는 blocking 캐싱(진척 표시)이고, 다 실린 뒤에야 entered 상태가 됩니다. 거부(denied)·강제퇴장(forceKicked) 분기도 따로 있어요.

QV1/V2 두 가지가 있다던데요?

A노선이 두 개예요. 신형 노선(V2 flow)을 먼저 시도하고, 처리되면 구형(V1 requestEntry)으로 넘어가지 않아요 — 순서를 바꾸면 중복 탑승 요청이 됩니다. 하단 "함정 · 주의"를 보세요.

개요 · 범위

아동이 수업 링크로 들어와 디바이스를 고르고 네트워크 품질을 확인한 뒤, 로그인·입장 검증을 거쳐 호스트 승인을 받고 리소스를 캐싱하기까지의 게스트측 진입 플로우. 호스트측 승인·세션 라이프사이클은 #15.

전체 흐름

[입장 페이지] 카카오 인앱 브라우저 가드(리다이렉트) → 디바이스 선택(useDeviceManager) + 네트워크 품질 표시(useNetworkQuality) → 로그인/저장된 유저 → 권한 검증(getUserMedia) → V2 flow 시도(tryV2Flow) ─ 처리되면 끝 └ 아니면 V1: requestEntry(socket) → 승인 대기(WaitingRoom, 카운트다운 auto-retry) → onApproved → 리소스 캐싱(blocking, #22) → entered (거부 denied / 강제퇴장 forceKicked 분기)

디바이스 관리 use-device-manager.ts

enumerateDevices로 audioinput/audiooutput/videoinput 분류, devicechange 이벤트로 재열거.
문제 카메라 필터: PROBLEMATIC_CAMERAS(가상 카메라 등) 라벨 포함 기기 제외.
권한: getUserMedia로 audio/video 권한 요청·검증(즉시 stop). 권한 실패 시 입장 진행 중단(PermissionValidationFailed).
비디오 디바이스 유효성: use-video-device-validator.

네트워크 품질 · 브라우저 가드

네트워크 품질: useNetworkQuality(latency 기반 quality) → NetworkQualityIndicator로 표시. 약한 망 사전 경고. (관련: httpbin 네트워크 품질 체크 분석)
카카오 인앱 브라우저: use-kakao-browser-redirect로 인앱 브라우저 감지 시 외부 브라우저 유도(WebRTC/권한 제약 회피).

입장 · 승인 use-guest-entry-socket.ts

① 권한 검증 통과 후 V2 flow 우선 시도(tryV2Flow(roomId)) — 처리되면 V1 requestEntry로 안 넘어감(중복 입장 방지).
② V2 미처리면 V1: requestEntry → 소켓으로 호스트에 입장 요청 → waitingApproval.
③ onApproved(resourceFileNames 동봉): 저사양 판정(initLowPerformanceDevice) 후 cacheResources로 blocking 캐싱(진척 표시) → entered.
④ denied(거부) / forceKicked(강제퇴장) 분기 처리.

WaitingRoom 자동 재시도: 승인 대기 중 카운트다운(handleWaitingRoomComplete) 후 자동 재요청 → 호스트가 잠시 못 본 경우 복구.

can-enter 게이트: 입장 가능 여부(스케줄/상태)는 /api/lessons/:userId/:index/can-enter·/api/validate-lesson으로 검증(#15). 통과해야 입장 요청 진행.

함정 · 주의

V2 우선·중복 방지: tryV2Flow가 처리하면 isSubmitting(V1 requestEntry)을 건드리지 않는다. 순서를 바꾸면 V1/V2 동시 입장 요청.
권한 검증 선행: getUserMedia 권한 없이 입장하면 세션에서 마이크/카메라 실패. 입장 전 검증 필수.
문제 카메라 필터: 가상 카메라가 기본 선택되면 영상이 안 나옴 → PROBLEMATIC_CAMERAS 필터 유지.
리소스 캐싱 blocking: onApproved에서 캐싱 완료까지 대기. 실패해도 입장은 진행하지만, 활동 영상이 안 뜰 수 있음(#22 입장 차단 게이트와 별개 — 여기선 경고 후 진행).
카카오 인앱: 리다이렉트 안 하면 권한/WebRTC 제약으로 입장 실패. 인앱 가드 유지.

파일 · 라인 레퍼런스

파일	역할
components/pages/guest-entry.tsx	입장 페이지·플로우 오케스트레이션(952L)
hooks/use-device-manager.ts	디바이스 열거·필터·권한
hooks/use-guest-entry-socket.ts	requestEntry·승인·캐싱
hooks/use-kakao-browser-redirect.ts, use-video-device-validator.ts	브라우저/디바이스 가드
shared/lib/use-network-quality.ts	네트워크 품질
api/lessons/[userId]/[index]/can-enter, api/validate-lesson	입장 검증(#15)