마지막 업데이트 2026-07-22
코드레벨 문서화 로드맵(28/28 완료)은 실시간 세션·미디어·STT 코어를 다룬다. 이 백로그는 그 범위 밖에서 ppi-docs에 아직 문서가 없는 영역 — 운영/관리 백오피스(CRUD), 알림·프롬프트, 인증·권한·시간, TTS, 관측성, 인프라/배포, 그리고 ppi 리포에만 있는 내부 문서 — 을 추적한다. ppi 모노레포(apps/web·apps/socket·apps/stt·packages/shared) 전수 조사(2026-06-25)로 도출.
n / 27)도 같이 갱신. ✅ P0 전체 완료 (7/7, 2026-06-25): #1 입장 제어 · #2 PPI-API 보강 · #3 누적 경과시간 · #4 TTS · #5 알림톡 · #6 프롬프트 변수 · #7 관측성. 다음은 P1 11건.
bugs/에 증상별 분석은 많지만 시스템 설계 흐름이 부재 → 신규/디버깅 시 비용이 가장 큼. 흩어진 bugs/ 분석을 증상 축으로 한 번에 훑는 진입점은 증상별 트러블슈팅 매트릭스를 참고(증상→즉시 확인→코드 위치).
미작성 문서 없음 진행중 작성 중 완료 코드레벨 문서 존재 부분 관련/개념 문서는 있으나 코드레벨 흐름 보강 필요
실시간 코어 28개 기능은 코드레벨 문서화 로드맵에서 모두 완료(28/28). 세션매니저·SFU·녹음·STT·릴레이·오디오체인·mediasoup·activity·모니터대시보드·세션로그·Redis 등은 이 백로그에서 제외한다. 화면 지도 → 기능 흐름별에서 해당 문서로 바로 이동 가능.
| # | 기능 | 주요 파일 | 상태 |
|---|---|---|---|
| 1 | 수업 시간 검증 & 입장 제어 app첫입장 −15분~+30분·재입장 20분·하드컷 60분·8시간 간격·임시개방 상태머신. 입장 성공/실패의 근원 | lib/lesson-time-utils.ts, lib/lesson-gap-validation.ts, api/validate-lesson, api/lessons/.../can-enter | 완료 |
| 2 | PPI-API 연동 / 수업 데이터 보강 appDynamoDB Lessons ↔ ppi-api classes 병합·상태 우선순위·plannedStartTime 계산. 세 경로(단일/관리자/모니터)·resolvePlannedClass | lib/lesson-ppi-api-utils.ts, lib/planned-class-resolver.ts, api/monitor-dashboard/planned-lessons | 완료 |
| 3 | 누적 경과시간 추적 시스템 appanchor/live/finalize clamp·이중 가산 방지·3600초 캡. 회귀 버그 다수의 설계 원본 | hooks/use-cumulative-elapsed.ts, lib/api/services/lesson-session.service.ts, api/lessons/[userId]/[index]/sessions | 완료 |
| 4 | TTS 모드 & TTS API app / audioRealtime 음성 vs 외부 TTS(Typecast/OpenAI) 합성·자막 일치·in-flight 한도·재시도·buffered·WAV 검증. 원본 docs/realtime-tts.md 통합 | app/api/tts/{synthesize,stream}, lib/tts/{authz,limits,openai,typecast,buffered-audio}.ts | 완료 |
| 5 | 알림톡 (NCP SENS) app / server미접속/안내 카카오 비즈메시지. HmacSHA256 서명·템플릿 5분 캐싱·전화번호 정규화·진행자 확인식 발송. 모니터 미접속 토스트와 연결 | api/alimtalk/send, api/alimtalk-templates/*, lib/db-queries.ts | 완료 |
| 6 | 프롬프트 변수 시스템 app@{아동명}·${}·#{}·{{}} 파싱/치환 + 한국어 조사 자동(받침). replaceAllVariables 3단 펼침·중첩 금지 | lib/instruction-variables.ts, lib/instruction-highlight.ts, lib/openai-create-call.ts, api/prompt-variables | 완료 |
| 7 | 관측성 스택 (Prometheus·Loki·Grafana) web / socket메트릭 카탈로그(SFU/Redis/reaper)·15초 gauge 수집·instance_id 라벨·route 정규화·Loki JSON Lines | apps/socket/src/metrics.ts, apps/web/metrics.js, apps/web/logger.js | 완료 |
| # | 기능 | 주요 파일 | 상태 |
|---|---|---|---|
| 8 | 그룹 배정 / 재편성 app1:1↔그룹 전환·정원(2)·진행자 충돌 해결·점진적 재편성(simKey→realId) | lib/bulk-group-convert.ts, api/class-mgmt/groups/* | 미작성 |
| 9 | 커리큘럼 시스템 app학습 플랜 마스터·카테고리·아동 할당(User.curriculumId)·다음 회차 생성 연계 | api/curriculums, api/curriculum-categories, components/pages/curriculum-page.tsx | 미작성 |
| 10 | 자동 회차 생성 (Auto-Session) appprepareNextSession·커리큘럼 순서·템플릿→활동 확장·완료/미보유 케이스 | lib/auto-session-utils.ts, lib/lesson-utils.ts | 미작성 |
| 11 | 이슈 알림 / 이슈 로그 app7종 issue type·webhook 포워딩·카테고리 taxonomy·클립보드 포맷·세션로그 변환 | api/issue-notification, api/issue-texts, lib/issue-alert.ts, lib/issue-formatting.ts | 미작성 |
| 12 | 발화 알림 규칙 (Speech Alert Rules) appSTT 키워드 트리거·child/ai 소스별·활성화 토글·세션 런타임 통합 | api/speech-alert-rules/*, entities/speech-alert-rule | 미작성 |
| 13 | 첫 발화 한국어 유도 — 런타임 app설정 스토어 + 감지→멘트 삽입 연쇄. 개념 가이드는 있으나 런타임 통합이 미문서 | stores/use-first-turn-korean-guide-store.ts, api/first-turn-korean-guide-settings | 부분 개념 가이드만 |
| 14 | 회원 / 역할 / 권한 모델 (RBAC) app / serveradmin/developer/manager 3단계·민감정보 접근 제어·미들웨어 경로 보호 | lib/admin-sensitive-access.ts, lib/auth.middleware.ts, proxy.ts, api/members | 부분 로그인 흐름만 문서화 |
| 15 | SFU REST API socket/rooms·/workers/stats·/health·/router-capabilities·/debug/redis-state·/peers. socket.io 시그널링과 별개의 HTTP 표면 | apps/socket/src/sfu-api/*, apps/socket/src/server.ts | 미작성 |
| 16 | STT 저장소 / 설정 (Go) sttS3 key 규칙·session prefix 인덱스·cross-instance resolution·배치 파라미터 튜닝 | apps/stt/internal/storage/s3.go, apps/stt/config/config.go | 미작성 |
| 17 | CI/CD 파이프라인 infradev(브랜치 배포)·web-prod·socket-prod·stt dev/prod·loadtest. 배포/소멸 시퀀스·환경변수 전달 | .github/workflows/{dev,deploy-web-prod,deploy-socket-prod,deploy-stt-*}.yml | 미작성 |
| 18 | Terraform 인프라 infrabranch-deploy·EC2(ARM64)/ALB/Route53/IAM·S3 state backend·userdata 부트스트랩 | terraform/branch-deploy/{main,variables}.tf, userdata*.sh | 미작성 |
| # | 기능 | 주요 파일 | 상태 |
|---|---|---|---|
| 19 | 녹음 다운로드 & 캡션 서빙 appS3 presigned URL·캡션 JSON 스키마·inline audio. 녹음 생산 파이프라인과 별개 | api/recording-download, api/recording-captions, lib/s3.ts | 미작성 |
| 20 | 오디오 분석 에이전트 관리/CRUD app에이전트 CRUD·active 설정·로그 업/다운로드 presigned URL. 런타임 분석 흐름과 별개 | api/audio-analysis-agents/*, api/audio-analysis-logs/* | 미작성 |
| 21 | 게스트 버전 맵 app/guest·/guest2/[roomId](레거시)·/client-guest/session(V2). 버전 전환·redirect 로직 | app/guest, app/guest2/[roomId], app/client-guest/session | 부분 V1_V2 가이드 이관 필요 |
| 22 | 설문 프록시 (Surveys) appppi-api 설문 시스템 프록시·경로 라우팅·인증 토큰 전달 | api/surveys/[...path], lib/ppi-api-client.ts | 미작성 |
| 23 | 클라이언트↔SFU 소켓 와이어링 websocketSfu lazy proxy·targetInstance 다중 인스턴스 라우팅·WS-only·reconnect 조건 | socketSfu.ts, socket-config.js, hooks/mediasoup/* | 부분 이벤트만 일부 문서화 |
| 24 | 앱 전역 상태 아키텍처 webContext API(activities/members/templates) + Zustand(monitor/lesson) 혼용·SoT 책임 범위 | contexts/*, stores/* | 미작성 |
| 25 | 호스트 개입 로깅 + 세션 제어 app텍스트/음소거/스텝변경/응답취소 개입 기록·emit-step-change 소켓 전송 | features/host-intervention, features/session-control | 부분 로깅 함수만 |
| 26 | Docker / 컨테이너화 + PWA/SW infra / web멀티스테이지 빌드·socket ffmpeg 의존·standalone·SW 캐싱/정리 전략 | Dockerfile.dev*, apps/*/Containerfile, next.config.mjs, public/ | 부분 코드 헤더만 |
| 27 | EventBridge + Lambda 자동 정리 infra3일 stale dev 배포 자동 정리(EC2/ALB/Route53). CLAUDE.md 기술, IaC 위치 확인 필요 | ppi-dev-cleanup-function (IaC 위치 미확정 — 별도 repo 가능성) | 미작성 |
ppi 리포 docs/에만 존재하고 ppi-docs 사이트에는 없는 문서. 기존 ppi-docs는 "어떻게 동작하나"를 다루지만, 아래 인수인계 문서의 왜 이렇게 했나 · 함정 · 미해결 부채 · 장애 대응은 ppi-docs에 전혀 없다.
| 문서 | 내용 | 상태 |
|---|---|---|
| V1_V2_SYSTEM_GUIDE | V1(P2P)↔V2(SFU) 토폴로지·페이지·namespace 비교. V2 온보딩 필수. docs/architecture/V1_V2_SYSTEM_GUIDE.md | 미이관 |
| realtime-tts | P0 #4의 원본. docs/realtime-tts.md | 미이관 |
| Jacob 인수인계 (9편) | architecture · decision-log · landmines · known-gaps · runbooks · card-view · monitor-dashboard · focus-view · redis-infra. card-view/monitor/focus/redis는 ppi-docs와 일부 중복이나 설계 의도·결정·함정이 빠짐. decision-log/landmines/known-gaps/runbooks는 완전 부재. docs/handover/jacob/* | 부분 의도/부채/런북 부재 |
/blocked·/main/debug/*·prompt-test — 코드 embedded, 운영 가치 낮음 (단, ROOM_META_SOURCE·ROOM_INSTANCE_PIN·MONITOR_CLAIM_SOURCE env 토글은 운영 가이드에 한 줄 명시 권장)class-sort.ts·class-mgmt-bypass-policy.ts·class-group-utils.ts 등 정렬·정책 유틸ecosystem.config.js(PM2)·scripts/·소켓 utils/ 일부features/오디오-분석-에이전트-코드레벨-동작흐름.html 구조 (증상/개요 → 진입점 → 코드 흐름 → 파일·라인 표 → 함정/주의).features/, 인프라/아키텍처는 architecture/, 운영 가이드/이관 문서는 reference/.copy-for-claude.js + share-link.js 포함, index.html 카테고리 등록 + count 갱신, build-graph.js로 graph 재생성, log.md 기록.flow-map.data.js에 feature 1개를 추가하면 화면 지도 → 기능 흐름별에 자동 노출.n / 27) 갱신.