PPI · CODE APPLICABILITY REVIEW · 2026-11-10

네트워크 불안정 대책
‘착수’ 항목 코드 적용성 검토

마지막 업데이트 2026-11-11

2026-11-10 미팅에서 착수로 표시된 1·3·5·8·10번을 현재 로컬 PPI checkout과 대조했다. 결론은 1·5·10은 코드상 구체적 착수 근거가 확인되고, 3은 중복 세션 방지·런타임 범위를 먼저 고정해야 하며, 8은 운영 가이드 작업으로 바로 시작할 수 있다는 것이다. 런타임 코드는 수정하지 않았다.

1 · 3 · 5 · 8 · 10
미팅에서 착수로 체크된 안건
1 · 5 · 10
코드에서 명확한 문제/작업 지점 확인
13a198b4
분석한 PPI checkout HEAD (develop)

판정: 착수 가능 — 단, 작은 단위로 분리 권고

안건 1의 초깃값 오탐과 안건 10의 성능 측정 함수 결함은 코드 근거가 뚜렷하다. 안건 5도 ACK를 누락할 수 있는 early-return 경로가 현재 checkout에서 보인다. AI 세션 자동 재시작은 실제 이득이 있지만 세션 세대·중복 생성·명시적 종료와의 경계가 필요하다. 운영 배포 및 실세션 영향은 이 checkout만으로 검증하지 않았다.

안건별 검토

1. 진입 직후 오탐 경고 제거 — 착수 가능, 우선순위 높음

코드 근거: apps/web/hooks/use-guest-network-alert.ts:161-178에서 video/audio stream이 live가 아니면 즉시 disconnected 시각을 기록하고, 7초 후 critical로 판단한다. AI audio만 null이면 판정 제외한다(170행). 호출부 apps/web/entities/guest-page-session/model/use-guest-page-session.ts:1926-1936는 미디어 준비/입장 완료 gate 없이 현재 stream 값을 훅에 전달한다.

적용 방향: 채널을 not-started / acquiring / live / disconnected / ended처럼 분리하고, 해당 채널이 수업에서 기대되는 상태가 된 뒤에만 끊김 타이머를 시작한다. socket ACK/입장 승인 전에는 네트워크 원인 판정을 보류하고, 실제 획득 실패는 별도 장치 권한/미디어 오류로 표시한다. null을 무기한 정상 취급하면 진짜 연결 실패를 감출 수 있으므로 기대 상태 기준이 필요하다.

수용 기준: 페이지 진입 후 스트림 획득 중에는 게스트 안내와 진행자 critical이 발생하지 않음; 스트림이 live가 된 뒤 실제 7초 단절은 경고됨; 마이크·카메라 미허용/미사용 시 false positive 없이 별도 상태로 보임.

3. 끊긴 AI 세션 자동 재시작 — 조건부 착수

코드 근거: apps/web/entities/guest-session/model/use-ai-session.ts:2284-2331에서 LiveKit disconnect/failure는 진단/입력 gate를 정리하고 callback으로 전달하며, recovery callback은 LiveKit interruption policy를 재적용한다. 여기서 새 세션 시작을 직접 호출하지 않는다. Realtime peer connection도 disconnect/fail/recovered callback 경로가 분리돼 있다(1900-1920행).

적용 방향: 먼저 대상 runtime을 LiveKit, Realtime 또는 양쪽으로 명시하고, SDK의 일시 재연결 시도 이후에도 실패 상태가 지속될 때만 제한된 재시작을 시작한다. session generation으로 이전 시도의 늦은 callback을 무시하고, old session cleanup 완료 후 1회성 재시작·backoff·최대 횟수를 둔다. force-kick, lesson 종료, 사용자의 stop, expired job은 자동 재시작하지 않는다. transcript/수업 step/듣기 상태를 어디까지 보존할지도 결정해야 한다.

수용 기준: transient disconnect→SDK recovery 성공 시 새 세션을 만들지 않음; 지속 실패는 중복 session/오디오 없이 1회 재시작; 명시적 종료/퇴장/expired job은 재시작 안 함; 재시작 실패와 최종 복구 시간을 로그에 남김. 독립된 pure state-machine 테스트를 먼저 두는 편이 안전하다.

5. 서버 응답 지연(ACK 무응답) 원인 확정 — 조사와 보완 착수 가능

코드 근거: apps/socket/src/sfu-socket/handlers/session-relay-handlers.ts:423-455에서 guest peer/payload가 유효하지 않으면 ACK 없이 return할 수 있다. structural commit 경로에서도 current가 비어 있으면 532행에서 ACK 없이 반환한다. 성공 ACK는 monitor fanout이 끝난 뒤 580-581행에서 보낸다. 따라서 의도적으로 거절한 요청과 서버 내부 무응답을 구별할 명시 ACK 계약이 필요하다.

주의/선행 확인: 미팅 메모의 참고 커밋 1ecfdac7은 이 로컬 저장소에서 git show로 확인되지 않았다. 현재 HEAD는 13a198b4이고, 이 checkout만으로 해당 커밋의 코드 포함 여부나 운영 배포 여부를 확인할 수 없다. 저장소 최신 동기화/커밋 존재 여부 및 배포 버전을 별도로 확인해야 한다.

적용 방향: 모든 유효 요청은 success ACK, 거절은 typed failure ACK, commit/fanout 실패는 실패 ACK와 상관 식별자를 남긴다. ACK timeout만으로 재진입을 권하지 말고, 클라이언트가 재시도할 수 있는 이벤트는 revision/idempotency key를 사용한다. 서버 원인 확정은 roomId·direction 로그와 Grafana 운영 대조가 완료된 뒤 한다.

8. 진행자 가이드와 보호자 안내 — 바로 착수 가능(운영 산출물)

이 항목은 네트워크 자동복구 코드보다 현장 절차와 커뮤니케이션에 해당한다. 강제 퇴장 전 잠시 대기할 기준, 재진입을 권할 조건, 앱 경고·서버 지연·미디어 무음·화면 탭 이탈을 구분하는 원인 태그, 보호자 회선 점검 안내를 짧은 체크리스트로 만들 수 있다.

주의: 안내 문구는 원인을 단정하지 않도록 한다. 앱의 warning/critical은 원인 확정 진단이 아니며, 서버 ACK 지연과 오디오 출력 문제도 네트워크처럼 보일 수 있다. 근거가 없을 때는 “원인 미확인”으로 기록하도록 해야 CX의 고객 측 비율을 다시 왜곡하지 않는다.

10. iPhone 오디오 처리 지연 대응 — 첫 수정은 명확, 후속 튜닝은 계측 후

코드 근거: apps/web/lib/utils.ts:193-209의 measurePerformance()는 requestAnimationFrame을 예약한 직후 동기적으로 frameCount를 계산한다. 예약된 callback이 실행되기 전에 계산하므로 일반 브라우저 실행에서는 0을 반환할 수 있고, 점수 60 미만을 저성능으로 보는 호출부(apps/web/lib/utils.ts:142-143)가 사실상 모든 기기를 낮은 성능으로 분류할 위험이 있다.

적용 방향: benchmark를 실제 측정 종료 뒤 결과를 반환하는 async 방식으로 수정하고, 측정값이 준비되지 않았을 때의 unknown 상태를 둔다. 그 다음 iPhone/iOS Chrome의 AudioContext 개수·state·sample rate, 오디오 처리 구간별 clock drift/underrun, 입력 음성 품질을 계측한다. AudioContext 통합이나 처리 단계 축소는 측정 재현 후 단계적으로 적용한다. 저성능 판정 하나만으로 필터/처리를 끄면 인식 품질 저하와 무관한 기기까지의 오분류가 생길 수 있다.

권장 실행 순서

  1. 안건 1과 10의 작은 결함 수정을 분리해 각각 테스트: 초기 미디어 상태 분류, 성능 benchmark 결과 계산.
  2. 안건 5 ACK 계약과 운영 로그 대조: 1ecfdac7 및 실제 배포 여부부터 확인하고, 거절/실패/성공 ACK의 구분 테스트 추가.
  3. 안건 3 재시작 state machine 설계·테스트: runtime, restart 조건, 재시도 상한, stop/expired 예외를 정한 뒤 구현.
  4. 안건 8 진행자·보호자 가이드 배포: 기술 원인 단정 금지와 대기/재진입 절차를 포함.
  5. 모든 변경 후 실제 자동 복구율, child re-entry, 오탐률, AI audio 복구시간을 같은 정의로 재측정한다. 운영 수치가 확보되기 전에는 효과 수치를 가정하지 않는다.

검토 범위와 한계

참고 분석

분석자: DevClaw · 분석은 미팅 원문(회의록)과 해당 로컬 checkout의 코드에 한정. 네트워크 원인과 운영 효과는 코드만으로 확정하지 않음.