마지막 업데이트 2026-11-06
PR #1285 (PPI-1441). ppi-socket의 Host changed step(활동 전환·새로고침), Host cancelled AI response(말하기 멈춤) 같은 로그에 수업 식별값이 없어 KR2(양호 수업 비율)를 수업 단위로 셀 수 없었습니다. 10개 로그의 data에 roomId({아동ID}_{회기})를 넣고, 활동 전환 로그에는 direction(prev/next/jump/refresh)을 더해 새로고침과 전환을 나눠 셀 수 있게 했습니다. 바뀐 것은 로그 출력뿐이고 화면 동작은 그대로입니다. 리뷰 시 먼저 볼 곳은 direction 허용값 처리와 Peer left room의 roomId 선택입니다.
강제퇴장 로그에는 이미 roomId가 있었지만 다른 이벤트에는 없어서, 이벤트마다 수업별 집계 가능 여부가 달랐습니다. 이번 변경으로 KR2 대상 이벤트의 서버 로그를 같은 키로 묶어 셀 수 있습니다.
hasServerDerivedMonitorControlAccess)를 통과한 뒤에만 로그를 남깁니다. 아동 이벤트는 서버에 저장된 peer의 roomId를 씁니다.host-step-changed에 실어 보내고, 서버는 로그에만 기록합니다. 아동에게 전달하는 내용은 바뀌지 않았습니다.test/logger-privacy.test.ts)가 roomId를 가리지 않는 것을 허용합니다. 다만 개인정보 기준에 대한 정식 승인은 따로 확인해야 합니다.진행자 "활동 새로고침" 클릭 → handleRefreshCurrentStep
apps/web/hooks/client-host/use-step-selection.ts
direction: "refresh"로 emitStepChange 호출 (next/prev/jump도 같은 함수를 거침)
host-step-changed emit에 direction 포함
apps/web/features/session-control/api/emit-step-change.ts
서버 권한 검사 → 로그에 roomId·direction(허용값만) 기록 → 아동에게 기존 payload 전달
apps/socket/src/sfu-socket/handlers/session-relay-handlers.ts
클라이언트가 임의 문자열을 보내도 로그 필드가 오염되거나 카디널리티가 폭증하지 않습니다. 아동에게 전달하는 emitRoomEventWithoutMonitorSockets(... "host-step-changed", {...}) 내용에는 direction을 추가하지 않았습니다.
모니터 peer는 roomId가 null이고 관찰 중인 방은 joinedRoomId에 있습니다. 그래서 바로 위 decrementPeerCount와 같은 식을 씁니다.
| 레이어 | 파일 | 핵심 변경 |
|---|---|---|
| Web | features/session-control/api/emit-step-change.ts | host-step-changed에 direction 추가 |
| Socket | session-relay-handlers.ts | roomId 4종 + direction 허용값 처리 |
| Socket | avatar-handlers.ts | Host cancelled AI response에 roomId |
| Socket | session-alert-handlers.ts | Guest issue report accepted · Guest auto-finish에 roomId |
| Socket | connection-handlers.ts | Peer joined/left room · Continued live lesson session에 roomId |
| Test | socket 3개 + emit-step-change.test.ts(신규) | console.log 구조화 로그를 파싱해 roomId·direction 검증, 허용되지 않은 direction이 로그·아동 전달 양쪽에 없는지 확인 |
Peer joined room/Peer left room은 모니터 입장·퇴장도 같은 roomId로 남깁니다. 아동 입장만 셀 때는 role: "guest"로 걸러야 합니다.
roomId 형식은 createRoomId(userId, lessonIndex) = {아동ID}_{회기}입니다. 강제퇴장 로그는 roomId를 data가 아닌 msg 문자열(Guest force kicked from room ${roomId})에 넣고 있어, 집계 쿼리에서 다르게 다뤄야 합니다. 강제퇴장 로그는 이번 범위가 아닙니다.
듣기 ON/OFF 로그(voice_control_command)에는 여전히 roomId가 없습니다. 지금은 type·stage·outcome만 남습니다. 대상 표에 없어서 이번에는 고치지 않았습니다.
화면에 보이는 동작은 바뀌지 않았습니다. 로그 msg 이름도 그대로라서 기존 Grafana 검색은 계속 동작합니다. 웹과 소켓 중 어느 쪽을 먼저 배포해도 호환되지만, 둘 다 배포되기 전에는 direction 없는 로그가 남습니다.
새로 넣은 테스트는 모두 수정 전 실패, 수정 후 통과를 확인했습니다. socket 전체 테스트는 866개 통과, 25개 실패이고, 실패 25개는 수정 전 코드에서도 똑같이 실패합니다(time-end-request-state·router-manager-guest-state·runtime-secret-deployment-wiring). mutation 테스트는 이 기존 실패 때문에 사전 실행 단계에서 멈춰 결과가 없습니다. 실제 수업에서 Loki 로그는 아직 확인하지 않았습니다.
관련 문서: KR2 양호 수업 진행 비율 — 로그 기반 지표 검토 — 이 PR이 서버 로그 쪽 집계 공백(활동 새로고침·말하기 멈춤·도움 요청)을 메움
관련 문서: 진행자 "연결 불안정" 기록 527건 · 세션로그 대조와 아동 영향 — 수업 단위 이벤트 집계 분석 사례
관련 문서: 자동전환 미반영 — 게스트 socket.io 업링크 stall 원인 분석 및 로깅 추가 — host-step-changed 경로와 소켓 서버 로깅