수업 중단 후 아동 재입장 — terminal status 서버 게이트 전환 설계 P1설계

한 줄 판정

핵심 해법은 PUT → forceKick 순서 조정이 아니다. DDB의 회기별 접근 게이트를 종료의 기준점으로 삼고, 모든 API·소켓·LiveKit 경로가 같은 accessEpoch를 검사하도록 만드는 것이다. Redis는 권위가 아니라 빠른 종료 통지와 캐시에만 쓴다.

본 문서는 서버 로그(Loki {service_name="ppi-web"}) 실측 대조로 확정한 사건 메커니즘과, 그에 대한 구조 전환 설계안을 담는다. 구현 전 설계 문서이며 아직 코드에 반영되지 않았다.

사건 타임라인 — 서버 로그 실측

아동 이리안(89ad88d1…) / 진행자 안나(99eb7085…, manager) / roomId 89ad88d1…_12

20:35:23.347  진행자 강제퇴장(reason="kick") → 아동 소켓 끊김
              모니터: guest_disconnected → peer_left → setGuestInfo(null)
    ↓ 8.2s   아동이 "수업으로 돌아가기" 클릭 → /guest 재진입
20:35:31.953  GET  /api/users/check-session
20:35:32.434  진행자 '중단' 클릭 (클라)
20:35:32.488  POST /api/validate-lesson  ← 아동
20:35:32.517  validate-lesson 완료 200 (30.9ms) — 통과   상태는 아직 PENDING
20:35:32.571  아동 /client-guest/session 마운트
20:35:32.620  PUT  /api/lessons/{uid}/12 시작  ← 진행자, 클릭 대비 186ms
20:35:32.626  PATCH ppiapi /class-mgmt/classes/{uid}/20260828/status
20:35:32.697  PUT 완료 200 (81.5ms) — STOPPED 확정
20:35:33.562  Ended pending lesson sessions  closedCount=1 (12#1787916869321)
20:35:34.445  LESSON_LOG_FINALIZE 아카이브 생성  totalEntries=938
20:35:34.600  아동 소켓 입장 요청
20:35:35.128  아동 소켓 룸 실제 참여  ← 서버가 인지하는 "입장". 이미 STOPPED
20:35:35.144  POST /api/lesson-progress → 35.176 갱신 성공
20:35:39.256  아동 준비 확인 클릭(confirmReady)
20:35:39.298  POST /api/lessons/{uid}/12/sessions → 39.376 200, 새 세션 생성
    ↓
20:50:14      엔딩영상까지 완주 → 20:50:37 강제퇴장으로 종료

500ms sleep이 실행되지 않았다

진행자 클릭 32.434 → PUT 시작 32.620 = 186ms. completeLesson의 고정 500ms sleep이 돌았다면 32.93 이후여야 한다. 즉 if (guestInfo) 가 false여서 forceKickGuest("complete")와 sleep이 통째로 스킵됐다. 클라이언트 세션로그 전체에 reason "complete" 강퇴가 0건이다.

apps/web/features/monitor/lesson-completion/model/use-lesson-completion.ts:363~415

왜 아동 연결이 끊기지 않았나

퇴장 로직 자체는 존재한다. completeLesson → forceKickGuest("complete") → 게스트 lesson-ended(재입장 버튼 없음). 동작하려면 세 조건이 동시에 성립해야 한다.

1. 모니터가 그 순간 아동을 인지 — monitorSession.guestInfo != null
2. 소켓 서버 로컬 peers Map에 guest 존재 (아니면 NoGuest)
3. 게스트 소켓 생존

이번 건은 1번에서 탈락했다. 원인은 "입장" 시점이 두 갈래로 갈리는 것이다.

아동이 말하는 "입장"        검증 통과 32.517 / 페이지 마운트 32.571
서버가 인지하는 "입장"      소켓 룸 참여 35.128 / GUEST_CONNECTED 39.256
진행자가 '중단'을 누른 시각  32.434  ← 이 순간 방에 게스트가 없었다
                            (직전 아동은 23.347에 강퇴돼 나갔고,
                             새 연결은 2.7초 뒤에 들어온다)

guestInfo 세팅 502~518(peerStreams 자동 탐지)·536(get-peers) / 해제 840(guest-disconnected)·905(peer-left) — apps/web/entities/monitor-session/model/use-monitor-session.ts

설계 전제 — completionStatus는 DynamoDB 값이 아니다

이 사실이 설계를 가른다. PUT /api/lessons/[userId]/[index]는 completionStatus·classDate를 payload에서 떼어낸 뒤 ppi-api에 PATCH한다. 코드 주석도 "PostgreSQL이 수업 상태의 원천"이라고 명시한다.

// Extract ppi-api-only fields before updating lesson (they are not DynamoDB fields)
const completionStatus: ClassStatusType | undefined = updates.completionStatus;
delete updates.completionStatus;
delete updates.classDate;
// PostgreSQL이 수업 상태의 원천이므로 ppi-api 실패를 DynamoDB 업데이트 성공으로 숨기지 않습니다.

apps/web/app/api/lessons/[userId]/[index]/route.ts:158, :176

설계안 — 업무 상태와 실행 접근의 분리

업무 상태 권위
ppi-api / PostgreSQL
PENDING · STOPPED · COMPLETED · CANCELLED
          │
          │ 서버 transition command
          ▼
실행 접근 권위
DDB Lesson.accessState + accessEpoch
          │
          ├─ Web API 공통 gate (assertLessonAccess)
          ├─ Socket 내부 access API
          └─ DDB outbox
                  │
                  ├─ Redis 종료 이벤트·캐시   (권위 아님)
                  ├─ Socket room 강제 종료
                  ├─ LiveKit room 종료
                  └─ ppi-api 상태 동기화 재시도

DDB Lesson 항목에 추가할 필드

accessState:       "ACTIVE" | "CLOSED";
accessEpoch:       number;
terminalStatus?:   100 | 200 | 300;
accessChangedAt:   number;
transitionId:      string;
transitionActor:   { type: "member" | "admin"; id: string };
businessSyncState: "PENDING" | "SYNCED" | "FAILED";

별도 테이블이 아니라 기존 Lesson 항목에 두는 이유:

• 실행 가능한 수업은 이미 (userId, index) Lesson 레코드가 필요하다 — 없으면 검증이 LESSON_NOT_PROVISIONED로 실패한다
• 진행률·세션 생성 시 같은 항목을 DDB 조건식/트랜잭션으로 검사할 수 있다
• 변경 범위가 작고, completionStatus와 의미가 분리돼 기존 PostgreSQL 업무 규칙이 보존된다

종료의 기준점

터미널 상태 변경은 일반 Lesson PUT이 아니라 전용 transition command로 분리한다.

1. DDB 트랜잭션으로 accessState=CLOSED, accessEpoch+1, outbox를 기록
2. 이 DDB 커밋이 "더 이상 입장·진행할 수 없는 시점"
3. outbox 처리기가 Redis 종료 이벤트를 발행하고 ppi-api 상태를 동기화
4. ppi-api 실패 시 접근 게이트는 닫힌 채 재시도. 자동으로 다시 열지 않는다
5. 클라이언트에 accessClosed:true, businessSyncState 반환

현재 completeLesson의 guestInfo 검사·클라이언트 강퇴·500ms sleep은 종료의 필수 조건에서 제거한다.

공통 접근 판정

assertLessonAccess({ principal, userId, lessonIndex, expectedAccessEpoch, capability });

// 판정 순서
1. 아동 세션 인증
2. 세션의 child.id === userId 확인
3. DDB consistent read
4. accessState === ACTIVE 확인
5. 요청의 accessEpoch === 현재 epoch 확인
6. 쓰기라면 DDB 조건식/트랜잭션에서도 다시 확인

409에 상태를 담는 이유는, 아동이 소켓 종료 이벤트를 놓쳐도 API 응답만으로 종료 화면으로 전환되게 하기 위함이다.

차단 지점과 우선순위

아래 경로는 전부 2026-08-28 사건에서 중단 확정 이후 통과한 것들이다.

이미 접속한 아동의 강제 종료 — 3층 구조

종료 정확성에서 클라이언트 guestInfo, 로컬 peers 조회, 클라이언트 ACK를 모두 제거해야 한다.

1. DDB gate가 CLOSED로 커밋된다
2. outbox가 {roomId, status, accessEpoch, transitionId}를 Redis 채널로 발행
3. 모든 Socket 인스턴스가 이벤트 수신
4. 게스트는 일반 room 외에 guest:${roomId} 전용 Socket.IO room에도 참여
5. 서버가 해당 guest room에 LESSON_TERMINATED 발송
6. 최대 1초 동안 화면 전환 ACK 대기
7. ACK 성공 여부와 무관하게 disconnectSockets(true)
8. 이벤트를 놓친 인스턴스는 최대 10초 주기의 DDB backstop 검사에서 CLOSED를 발견하고 종료
9. 그 뒤 재접속은 JOIN gate에서 거절

로컬 peers 조회와 1초 stale 타이머

현재 강퇴는 로컬 Map에서 게스트를 찾고, 고정 peerId(guest-${roomId})를 1초 뒤 다시 지운다. 같은 peerId로 1초 내 재입장하면 새 연결의 transport·producer가 닫힌다.

• cross-instance guest room을 직접 대상으로 삼아 로컬 Map 검색을 제거
• 1초 후 직접 리소스를 삭제하지 않고 해당 socket을 disconnect해 공통 cleanup 사용
• 불가피하게 지연 cleanup이 남는다면 {peerId, socketId, connectionGeneration}이 모두 일치할 때만 실행

apps/socket/src/sfu-socket/handlers/room-handlers.ts:332, :379~404 / signalingHandler.ts:151

오조작과 재개

STOPPED·COMPLETED·CANCELLED가 커밋된 뒤에는 모두 기존 아동 연결을 끊는다. 재개는 종료의 취소가 아니라 새 실행 세대를 여는 작업으로 취급한다.

• STOPPED → PENDING: 담당 manager/admin이 명시적 재개
• COMPLETED/CANCELLED → PENDING: admin 이상 또는 별도 승인
• ppi-api를 먼저 PENDING으로 변경 → 성공 후 DDB를 ACTIVE로 변경하며 accessEpoch+1
• 기존 socket·LiveKit 토큰은 이전 epoch이므로 계속 무효
• 아동은 반드시 /guest → validate-lesson → 새 세션으로 재입장. 자동 재접속 없음

오조작 방지는 커밋 전 확인 모달에서 처리한다.

아동 UX

현재 구조를 재사용할 수 있다. 수업 종료는 lesson-ended, 수동 강퇴는 force-kicked이고, lesson-ended에는 재입장 버튼이 없으며 종료 상태는 terminatedRef로 sticky하게 유지된다.

use-guest-page-session.ts:1882, :288 / widgets/guest/guest-layout/ui/guest-layout.tsx:286

함께 드러난 결함 3건과 통합 방식

단계별 PR 순서

회귀 테스트 — 이번 사건 타임라인 자동화

validate ACTIVE 성공
  → 진행자 terminal commit
  → 2초 뒤 기존 access token으로 socket JOIN
  → JOIN 거절
  → session / progress / livekit 모두 409
  → 종료 전 연결이 있었다면 cross-instance 강제 disconnect
  → reopen 후 새 epoch 토큰으로만 재입장 성공

기존 lesson-session.service.test.ts와 livekit-call-authorization.test.ts는 재사용 가능하지만, room·connection handler를 직접 검증하는 socket harness는 새로 필요하다.

확정과 추정의 경계

파일 · 라인 레퍼런스

관련 문서

• 수업 입장 제어 · 시간 검증(can-enter) — 코드레벨 동작 흐름 — 본 문서가 다루는 validate-lesson 게이트의 현재 동작
• 게스트 입장 플로우 · 디바이스/네트워크 — 코드레벨 동작 흐름
• 호스트 모니터링 claim / 그룹 모니터링 — 코드레벨 동작 흐름 — hasActiveMonitor가 focus 진행자를 뜻하지 않는 이유
• 클래스 관리 · 스케줄링 — 코드레벨 동작 흐름 — completionStatus 업무 상태 규칙