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

개요 · 범위

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

전체 흐름

디바이스 관리 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

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

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 제약으로 입장 실패. 인앱 가드 유지.

파일 · 라인 레퍼런스

관련 문서

• 수업 입장 제어 — 시간 검증·can-enter (이 디바이스 단계 직전의 시간/회차 판정)
• 코드레벨 문서화 로드맵 (#25 본 문서)
• Meet/호스트 라이프사이클 (#15, 승인 측)
• 리소스 캐싱/프리캐시 (#22)
• 저사양 기기 분류 기준
• httpbin 네트워크 품질 체크 분석