적용 범위: PPI-1376 작업 브랜치

2026-11-11 코드 대조 · 로컬 ppi develop b0e1e91c

본문은 PPI-1376 브랜치 caf485c3 기준이다. 현재 develop b0e1e91c의 동작이나 운영 배포 완료를 보증하지 않는다. 11월 11일 추가 요구는 아동 미접속 녹화 저장·재입장·재전송 설계에서 별도로 관리한다.

코드와 커밋을 대조한 문서 업데이트이며 운영 환경·실기기 검증은 포함하지 않는다.

Feature · PPI-1376 · 2026-11-09

PPI-1376 모니터 앱 수업 녹화 — 브랜치 전체 정리

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

모니터 앱(Electron)에서 그룹 카드뷰·1:1 포커스뷰 수업을 화면 영상 1개 + 아동별 음성으로 녹화해 S3에 올리고, 수업 로그의 녹화 보기에서 다시 재생하는 기능. develop 대비 브랜치 고유 커밋 41개(머지 제외)를 기준으로 구조·흐름·변천을 정리합니다.

브랜치 PPI-1376최신 caf485c3웹 쪽 변경만 · 모니터 앱 저장소(ppi-monitor-app)는 별도

01코드 경로

영역경로책임
녹화(쓰기)apps/web/features/monitor-recording/앱 브리지, 아동 음성 녹음·조각 저장, 시작·종료 자동화, 업로드, 상태 표시
녹화 보기(읽기)apps/web/features/recording-viewer/녹화 목록·상세 조회, 영상·음성 동기 재생, 이어보기 타임라인
서버apps/web/lib/monitor-recording/, app/api/monitor-recordings/presigned URL, manifest 검증·complete, 목록·상세·삭제, 권한
화면 연결app/monitor-dashboard/[group]/page.tsx, [group]/[roomId]/page.tsx, app/main/log/recording/page.tsx그룹 녹화 / 1:1 녹화 / 녹화 보기 진입
공통shared/lib/ (room-media-state, recording-retention, recording-lesson-snapshot, one-on-one-recording-key)영상 스텝 상태, 보관 기한, 수업 정보 스냅샷, 1:1 녹화 키

02목적 요약

진행자가 따로 조작하지 않아도 수업이 예정 시각에 자동으로 녹화되고, 끝나면 자동으로 올라가며, 수업 로그에서 아동별로 그날 수업 화면과 아동·AI 대화를 다시 볼 수 있게 한다.
항목값
영상모니터 앱이 메인 창 화면 + 페이지 재생음을 MP4로 녹화해 직접 업로드
음성웹 페이지가 이미 받고 있는 SFU 스트림으로 room별 아동 mic + AI 음성 혼합 1파일
녹화 가능 위치모니터 앱 안에서만 (일반 브라우저는 차단·안내)
최대 길이예정 시각 기준 40분
보관90일 (S3 lifecycle), 기한이 지나면 파일이 남아 있어도 재생 URL 미발급
S3 키{stage}/monitor-recordings/{groupId}/{recordingId}/final/…, manifest.json
녹화 목록ppi-session-log-{stage}에 room마다 type="monitor_recording" 행

03입출력 흐름

그룹 페이지 /monitor-dashboard/{group}   또는   1:1 포커스뷰 /monitor-dashboard/{group}/{roomId}
 ├ 예정 시각 도달 → 자동 시작 (테스트 모드는 수동 시작·종료 버튼)
 │    web → window.ppiMonitorApp.recording.start({ groupId, recordingId })
 │    app: 메인 창 MP4 녹화 시작, 시작 시각 V0 응답
 │    web: room별 아동 mic + AI 음성 녹음 → 5초 조각을 IndexedDB에 저장
 ├ 녹화 중
 │    청취 ON/OFF·영상 스텝 재생 상태(roomMedia)를 manifest 이벤트로 기록
 │    새로고침 → 조각 보존 + 새 세그먼트로 재개(gap 기록), 앱 영상은 계속
 ├ 종료: 모든 아동 완료·중단·취소 │ 예정+40분 │ 다른 경로로 이탈
 │    web: 음성 업로드(presigned PUT) → manifest → POST /complete
 │         서버: manifest 검증 → room별 세션로그 행 기록
 │    app: 화면 영상 업로드 (kind "video")
 │    web: 15초마다 상세 API videoPending 확인 → '영상 전송 대기' / 30분 초과 시 '확인 필요'
 └ 녹화 보기 /main/log/recording
      GET /api/monitor-recordings?userId=&lessonIndex= → 회기의 녹화들
      GET /api/monitor-recordings/{id} → manifest + 재생 URL
      영상 + 아동 음성 + 영상 스텝 소리를 V0 기준으로 맞춰 재생

04모듈별 세부

녹화 시작·종료

음성 녹음·저장

업로드·서버

녹화 보기

05설계 변천 (커밋 순서)

단계커밋내용
1. PoCc2abbc2b~5d16e451카드 영역 크롭 녹화, 로컬 폴더 저장, 녹화 뷰어와 영상 스텝 소리 재구성
2. S36c515d77~144381caS3 업로드·서버 기반 목록, 탭 화면 전체 녹화로 전환, 자동 시작, 화질 개선
3. 역할 분리30488342~fc0c325d별도 녹화 창 제거 → 영상은 모니터 앱, 음성은 그룹 페이지. 앱 밖 녹화 차단, 자동 시작·종료, 최대 40분
4. 뷰어191f2e36~d7e5a108수업 정보 헤더, 재생 단축키, 레터박스, 녹화 당시 일시·진행자 저장
5. 1:1 확장69f4db70~da01f817포커스뷰 자동 녹화, 단독뷰 펼치기는 외부 브라우저, 이탈 시 즉시 마감
6. 안정화d0326e06~659ced2f이어보기, 만료·403·실패 안내, 업로드 중복 방지, 영상 수신 확인 후 완료 표시, 2.5·3배속, 1:1 영상 스텝 소리
이전 단계 설계 문서는 PPI-1376 그룹 녹화 자동 시작·종료와 음성 저장 구현(커밋 1da7134e 기준)과 모니터 탭 화면·오디오 녹화 구현 계획을 참고합니다. 저장소 안 상세 설계는 docs/superpowers/specs/2026-10-19~27-*입니다.

06주의사항

  • 모니터 앱 안에서만 녹화됩니다. 1:1 링크는 앱 안에서 같은 창으로 이동합니다. 새 창에는 녹화 브리지가 없습니다.
  • 영상 업로드는 앱 담당입니다. 웹 음성 전송이 끝나도 영상이 없으면 '영상 전송 대기/확인 필요'로 남습니다. 뷰어는 '화면 영상 업로드 대기'를 보여 줍니다.
  • 툴바 "다시 시작"으로 생긴 두 번째 이후 앱 영상은 재생하지 않습니다(첫 파일만 재생).
  • 1:1 영상 스텝 소리 수정(659ced2f)은 새로 녹화하는 수업부터 적용됩니다. 이전 1:1 녹화에는 소리를 재구성할 정보가 없습니다.
  • multipart 업로드는 범위 밖이라 파일당 단일 PUT입니다(영상 2GB·오디오 300MB 상한).