네트워크 불안정 대책
착수 백로그
마지막 업데이트 2026-11-11
2026년 11월 10일 미팅에서 ‘착수’로 체크한 안건 1·3·5·8·10을 실행 가능한 백로그 타이틀과 요약으로 분해했다. 아래 항목은 회의 결정의 구현·운영 작업안이며, 별도 티켓 시스템에는 등록하지 않았다. 2026-11-10 현재 코드 재검토를 반영해 확인된 결함과 추가 조사, 기존 구현을 구분했다.
현재 코드 재검토 · 착수 범위 보정
검토 기준은 PPI 로컬 develop의 fd3f8721이다. 운영 배포 버전과 최근 세션 로그는 확인하지 않았다. 아래 판정은 현재 코드에 대한 결과이며, 과거 5주 분석의 발생률·복구율을 재검증한 결과가 아니다. 애플리케이션 코드는 변경하지 않았다.
| 미팅 안건 | 현재 판정 | 백로그에 반영할 범위 |
|---|---|---|
| 1 · 진입 직후 오탐 | 판정 결함 남아 있음 | 카메라·마이크 null도 7초 이상이면 critical이다. 고객 화면은 마이크 문제와 중복되는 경고를 일부 숨기지만 원본 판정과 모니터 전송은 유지된다. 준비 상태 분리와 실제 단절 감지를 함께 검증한다. |
| 2 · 재입장 안내 | 기존 문구의 현재 노출 전제 수정 | “나갔다 다시 들어와 주세요”는 미사용 NetworkToast 컴포넌트에 남아 있다. 현재 GuestLayout은 자가해결 가이드를 사용하므로 기존 토스트 수정 대신 실제 가이드와 진행자 안내의 대기 기준을 검토한다. 미팅 결정은 추가 조사로 유지한다. |
| 3 · AI 자동 재시작 | 개선 필요성 있음 | 확인한 끊김·실패 콜백은 상태 보고만 수행한다. LiveKit의 기존 재연결과 새 AI 세션 생성을 구분하고, 내장 복구 실패 후 재시작 조건과 수업 맥락 보존 범위를 먼저 정한다. |
| 4 · 소켓·수신 복구 | 부분적으로 맞음 | 소켓 자동 재시도 상한 5회는 남아 있다. 수신 transport가 서버에서 사라졌을 때 재생성하는 기능도 있으므로 “수신 복구 없음”으로 표현하지 않는다. 일반 연결 실패와 해당 복구 조건을 구분한다. 미팅 결정은 보류로 유지한다. |
| 5 · ACK 무응답 | 응답 누락 가능 경로 확인 | guest-step-update의 검증 거절과 처리 중 JOIN 무효화 등에 ACK 없이 반환하는 경로가 있다. 이것이 과거 129건의 원인인지는 미확정이다. 명시적 실패 ACK 계약과 운영 로그 대조를 나눠 진행한다. |
| 6 · 활동 전환 송신 재생성 | 원인 미확정 | 현재 micStream 변경 시 정리하는 것은 마이크 producer다. 전체 transport 정리는 별도 초기화 effect에 있다. 활동 전환 당시 어떤 의존값이 바뀌었는지 재현해야 한다. 미팅 결정은 추가 조사로 유지한다. |
| 7 · 품질 조절 | 일부 구현됨 | 카메라 송신량 300→150→80kbps와 해상도·프레임 조절이 구현돼 있으며 기본 모드는 on이다. 기존 적응 기능의 효과를 확인한 뒤 카메라 중지·음성 전용 모드의 필요성을 조사한다. |
| 8 · 운영 안내 | 운영 개선안으로 유효 | 보호자용 회선·앱 점검 가이드가 이미 있다. 기존 안내를 보완하고 강제 퇴장 전 대기 기준과 원인 미확인 태그를 정한다. 진행자 교육 적용 여부는 코드로 확인할 수 없다. |
| 9 · 측정 기준 | 정의·운영 확인 필요 | 경고·해제 로그만으로 고객 회선 원인을 확정하지 않는다. 과거 발생률은 당시 기간의 관찰치로 유지한다. 미팅 결정은 보류이며, 완료 기준에 필요한 측정 정의를 별도 합의한다. |
| 10 · iPhone 오디오 | 성능 측정 버그 확정, 지직거림 원인은 미확정 | measurePerformance()가 프레임 콜백 전에 계산해 0을 반환한다. 이 결함과 특정 아동의 오디오 지연 사이의 인과관계는 아직 입증되지 않았다. 성능 판정 수정과 실기기 오디오 조사를 분리한다. |
착수 안건 1·3·5·8·10과 아래 20개 작업은 유지한다. 회의상 담당은 철수이며, 개별 작업의 일정·티켓 ID는 미확정이다. 다른 안건의 착수 여부를 이 검토로 변경하지 않는다.
권장 진행 순서 (2026-11-11 재조정)
기존 제안(1 → 10 → 5 → 3 → 8)에서 안건 10을 맨 뒤로 내리고, 안건 8은 코드 작업과 별개로 즉시 병행하도록 바꿨다. 근거 코드는 PPI develop 54d265e7에서 다시 확인했으며, 1·5·10의 인용 지점은 fd3f8721 이후 변경이 없다.
- 안건 1 · 진입 직후 오탐 경고 제거 — 전체 회기의 20.3%에 아동 안내와 진행자 critical을 띄우고, 진행자 기록·CX의 “고객 측 92%”까지 왜곡한다. 이걸 먼저 고쳐야 나머지 개선의 효과를 같은 기준으로 잴 수 있다. 수정 지점은
use-guest-network-alert.ts:170부근으로 작다. - 안건 5 · 서버 ACK 무응답 — 129건 중 103건이 재진입으로 이어졌고 반복 아동은 223명으로 가장 많다. 원인은 미확정이지만, ACK 없이 반환하는 경로(
session-relay-handlers.ts:450,:551등)에 실패 ACK·상관 로그를 붙이는 일은 서버 한정·저위험이고, 그래야 Grafana 대조로 원인을 가릴 수 있다. - 안건 3 · AI 세션 자동 재시작 — 아동 직접 영향 119건 중 70건으로 효과는 가장 크지만 중복 세션·늦은 callback·맥락 보존·비용 위험도 가장 크다. 1·5를 진행하는 동안 runtime·발동 조건·종료 예외 설계를 먼저 확정하고, 구현은 그 뒤에 한다.
- 안건 10 · iPhone 오디오 지연 — 확인된 사례는 아동 A 1명이고, 아래 안건 10 절의 이유로
measurePerformance()수정은 오디오 대응이 아니다. 오디오 계측부터 시작하고, 성능 측정 수정은 영상 품질 판정 변경으로 따로 다룬다.
병행 · 안건 8 · 진행자·보호자 안내 — 코드가 필요 없어 지금 바로 시작한다. 서버 지연 129건의 재진입 상당수가 진행자 강제 퇴장이므로 “강제 퇴장 전 대기 기준”은 즉시 효과가 있다. 원인 태그는 안건 1이 끝나 앱 경고를 믿을 수 있게 된 뒤 확정한다.
안건 1 · 진입 직후 오탐 경고 제거
P1게스트 미디어 연결 상태를 준비·연결·단절 단계로 분리
아직 스트림을 획득하지 않은 상태와, 획득 후 끊긴 상태를 구분할 상태 모델을 정의한다. 카메라·마이크 미사용 또는 권한 미허용도 실제 네트워크 단절과 다르게 표현한다.
P1미디어 획득 전 critical 네트워크 경고 억제
해당 미디어 채널이 준비 상태에 들어가기 전에는 끊김 타이머를 시작하지 않도록 게스트 경고 hook과 진입 경로를 조정한다. 초기 상태를 영구 정상으로 간주하지 않도록 실제 획득 실패와 준비 timeout은 별도 판정한다.
P1초기 오탐·실제 단절 회귀 테스트 추가
스트림 획득 중 경고가 뜨지 않는 사례와, 스트림이 live가 된 뒤 임계 시간 이상 끊겨 경고가 뜨는 사례를 함께 보호한다. 진행자 monitor relay도 검증한다. 기존 network-alert.test.tsx의 15개 테스트는 통과하지만, 현재는 null 미디어를 critical로 기대하는 사례가 포함되어 있다. 준비 상태를 구분하는 새 요구사항과 기존 단절 보호를 명시적으로 분리한다.
안건 3 · 끊긴 AI 세션 자동 재시작
P1AI 세션 자동 재시작 대상 runtime과 발동 조건 정의
LiveKit과 Realtime runtime별 연결 상태·내장 재연결 동작을 확인하고, 어떤 실패가 자동 재시작 대상인지 정한다. 일시 disconnect 후 SDK가 복구 중인 경우에는 중복 시작하지 않는다.
P1중복 실행을 방지하는 AI 세션 재시작 상태 머신 구현
이전 시도의 종료, generation fencing, backoff 및 재시도 상한을 포함한 제어 흐름을 만든다. 지연 도착한 이전 세션 callback이 새 세션 상태를 덮지 못하게 한다.
P1사용자 종료·강제 퇴장·세션 만료 시 재시작 차단
명시적 stop, force kick, 수업 종료, job/session 만료를 자동 재시작 예외로 정의한다. 예외 상태가 바뀌는 동안 재시작 timer가 실행되지 않는지 테스트한다.
P2AI 세션 재시작 성공·실패·복구 시간 계측
시도 원인, runtime, 시도 번호, 성공 여부, 복구 소요 시간과 최종 실패를 민감정보 없이 기록해 재시작 효과와 반복 실패를 구분한다.
안건 5 · 서버 응답 지연(ACK 무응답) 원인 확정
P1참고 커밋 1ecfdac7의 포함 여부와 운영 배포 버전 확인
참고 커밋의 포함 여부와 운영 배포 버전은 이번 재검토에서 확정하지 않았다. 현재 코드의 로그 존재와 운영 배포 여부를 구분해 확인한다. roomId·direction 로그 변경이 실제 운영에 반영됐는지 확인하고, 조사 가능한 기간과 로그 보존 범위를 기록한다.
P1Socket 이벤트 ACK 누락 경로 전수 점검
session-relay-handlers.ts의 유효성 거절, 권한 거절, 비동기 commit 실패·결과 없음, monitor fanout 경로를 살펴 각각 ACK가 항상 완료되는지 계약을 정의한다. 현재 guest-step-update에는 검증 거절 및 JOIN 무효화 후 ACK 없이 반환하는 경로가 확인됐다. 단, 과거 지연 129건의 원인으로 단정하지 않는다.
P1성공·거절·실패를 구분하는 ACK 응답 계약 적용
의도된 거절에는 구체적인 실패 응답을, 처리 성공에는 성공 응답을, 내부 오류에는 실패 ACK와 상관 식별 로그를 남긴다. 재시도 가능한 이벤트는 중복 적용 방지 키를 검토한다.
P1ACK 무응답·서버 지연 회귀 테스트 추가
요청별 검증 실패, commit 결과 부재, 내부 오류, 정상 fanout 상황을 시험해 client timeout이 실제 서버 무응답과 명시적 거절을 구분하는지 확인한다.
P1Grafana roomId·direction 기준 ACK 지연 원인 대조
동일 수업의 요청·서버 처리·ACK 및 재진입 시점을 연결해 네트워크 단절과 서버 응답 지연을 분리한다. 로그가 없거나 식별되지 않는 사례는 원인 미확인으로 남긴다.
안건 8 · 진행자 가이드와 보호자 안내
P1연결 문제 유형별 진행자 대응 가이드 작성
실제 미디어 단절, 서버 응답 지연, AI 음성 정지, 오디오 출력 문제, 화면 탭 이탈을 구별하는 최소 확인 항목과 운영 조치를 정리한다.
P1강제 퇴장 전 대기 기준과 재진입 안내 문구 정리
짧은 자동 복구를 기다리는 시간, 새로고침/재진입이 필요한 조건과 수동 조치의 예외를 정한다. 복구 중인 아동에게 즉시 나갔다 들어오도록 안내하지 않는다.
P2원인 미확인 포함 연결 문제 기록 태그 정의
회선, 서버 지연, 앱/미디어, 기기 오디오, 화면 이탈, 원인 미확인 등 증거 기반 태그를 정의한다. 증상 문구만으로 고객 측 원인을 확정하지 않는다.
P2기존 보호자 회선·기기 점검 안내 보완
현재 NetworkGuidePanel의 와이파이 전환·다른 앱 닫기 안내를 바탕으로 대기, 기기 점검, 지원 요청 조건을 보완한다. 미사용 NetworkToast의 과거 문구가 현재 화면에 노출된다고 전제하지 않는다. 로그 근거가 없을 때 회선 탓으로 단정하지 않는 문구를 포함한다.
안건 10 · iPhone 오디오 처리 지연 대응
2026-11-11 재검토: isLowPerformanceDevice() 결과는 오디오 처리에 쓰이지 않는다. 영상·리소스 360p 선택과 아바타 영상 마운트에만 쓰인다(meet-video.tsx, meet-avatar.tsx, api/resources/urls/route.ts). 따라서 measurePerformance()를 고쳐도 아동 A의 지직거림은 달라지지 않는다. 또 이 측정값은 보고된 코어 수가 4 이하인 iOS 기기에서만 판정에 쓰이므로(utils.ts:160), 수정하면 지금 0점 때문에 저성능으로 분류되던 기기가 일반 성능으로 바뀌어 영상 부하가 커질 수 있다. iOS 기기가 실제로 보고하는 코어 수는 확인하지 않았다. 그래서 오디오 계측(P1)을 먼저 하고, 성능 측정 수정은 영향 기기 범위를 확인한 뒤 영상 품질 판정 변경으로 따로 배포한다.
P1iPhone 오디오 Context·clock drift·underrun 계측
실제 iPhone 세션에서 AudioContext 수·상태·sample rate와 오디오 렌더 지연 및 신고 시각을 상관 분석할 수 있게 한다. 아동 식별정보 없이 세션 단위로 수집한다.
P2iPhone 오디오 처리 완화 방안 실기기 검증
AudioContext 통합 또는 처리 단계 축소를 비교 실험하고 오디오 지연 감소와 음성 인식 품질을 함께 측정한다. 품질 저하가 허용 범위를 넘으면 적용하지 않는다.
P2프레임 성능 측정 함수의 동기 계산 오류 수정
measurePerformance()가 animation frame callback 결과를 받기 전에 점수를 계산하지 않도록 측정 완료 후 점수를 반환하게 수정한다. 측정 전·실패 상태는 저성능 판정과 구분한다. 오디오 대응이 아니라 영상 품질 판정 변경이므로, 저성능→일반으로 바뀌는 iOS 기기 범위를 먼저 확인하고 별도로 배포한다.
P2저성능 기기 판정 unknown 상태 및 단위 테스트 추가
유효 측정값, 낮은 점수, 지원 불가·측정 timeout의 경계를 테스트한다. 측정 실패를 점수 0으로 간주하지 않도록 한다. 현재 영향은 isOldIPad()의 iOS 판정 분기에 한정되며, 코어 수·해상도·OS 조건도 함께 작동하므로 모든 기기가 저성능으로 판정된다고 표현하지 않는다.
완료 판단 공통 기준
- 단기 끊김이 자동 복구되는 동안 불필요한 재진입 안내가 증가하지 않는다.
- 오탐·실제 네트워크 단절·서버 지연·오디오 문제를 별도 상태와 지표로 구분할 수 있다.
- 핵심 조건과 반례에 대한 관련 단위/통합 테스트가 있다.
- 배포 후에는 재진입률, 자동 복구율, 복구 시간, 오탐률을 동일한 분모·판정 기준으로 비교한다.
- 운영 데이터나 배포 버전을 확인하지 않은 효과 수치는 완료 보고에 기재하지 않는다.
검증 결과와 코드 근거
pnpm exec vitest run hooks/network-alert.test.tsx(apps/web): 1개 파일, 15개 테스트 통과. 현재 동작 확인이며 오탐이 해결됐다는 뜻은 아니다.- 실제 utils.ts의 measurePerformance 함수 본문을 읽어 프레임 콜백을 예약만 하는 격리 환경에서 실행: 반환값 0, 예약 콜백 1개. 콜백 전에 계산하는 순서 결함을 재현했다. 실기기 성능이나 지직거림을 재현한 검증은 아니다.
- 현재 UI 사용처, ACK 조기 반환, 소켓 재시도 설정, 수신 transport 복구 조건, 카메라 적응 설정을 정적으로 추적했다. 운영 로그·배포 버전·실기기 장애 재현은 수행하지 않았다.
아래 링크는 검토한 PPI 커밋의 소스다.
- 초기 미디어 판정 ·
apps/web/hooks/use-guest-network-alert.ts:163 - 현재 고객 안내 연결 ·
apps/web/widgets/guest/guest-layout/ui/guest-layout.tsx:248 - 중복 경고 억제 ·
apps/web/widgets/guest/self-help/status.ts:116 - AI 끊김·실패 콜백 ·
apps/web/entities/guest-page-session/model/use-guest-page-session.ts:646 - 소켓 재시도 설정 ·
apps/web/socketSfu.ts:365 - 조건부 수신 복구 ·
apps/web/hooks/mediasoup/use-mediasoup-consumer.ts:435 - ACK 누락 가능 경로 ·
apps/socket/src/sfu-socket/handlers/session-relay-handlers.ts:443 - 마이크 producer 정리 ·
apps/web/hooks/mediasoup/use-mediasoup-producer.ts:887 - 카메라 품질 조절 ·
apps/web/lib/camera-uplink-adaptation.ts:18 - 성능 측정 결함 ·
apps/web/lib/utils.ts:193
출처: 2026-11-10 「네트워크 연결 불안정 대책 미팅」에서 제공된 안건 및 PPI 로컬 코드 적용성 검토. 백로그 세부 항목과 완료 기준은 실행을 위한 제안이며 착수 안건의 회의상 담당은 철수이며, 개별 일정·티켓 ID는 별도 확정이 필요하다.