클래스 관리/스케줄링 — 코드레벨 동작 흐름 P2코드레벨

마지막 업데이트 2026-07-22

작성일: 2026-06-14 대상: 개발자 — 수업/그룹/스케줄 관리 파악 핵심 파일: app/main/class-mgmt, api/class-mgmt/*, lib/class-group-utils.ts

개요 · 범위

치료사-아동 배정, 수업(class) 생성/관리, 그룹(시간대별 다중 세션) 편성, 예약 수업(scheduled-lessons) 조회를 다루는 관리자 영역. 대부분 Next API가 BFF로 외부 ppi-api를 프록시하고, 클라이언트는 시간대/그룹 구조로 변환해 표시한다.

페이지 · API 맵

영역	경로
클래스 관리	`/main/class-mgmt`
스케줄	`/main/schedule`
커리큘럼(학습플랜)	`/main/curriculum`
수업 CRUD	`api/class-mgmt/classes`, `classes/[childId]/[date]`(+status/videos), `batch-delete`, `counts`
그룹	`groups`, `groups/[groupId]/{assign,unassign,members,check-unassign}`, `auto-assign`
아동	`children/[childId]`(+class-type, auth/convert·expire), `children/search`
배정 현황	`assignment-matrix`, `assignment-drilldown`, `members/available`
예약 수업	`api/scheduled-lessons` (모니터 대시보드 #13가 소비)

시간대·그룹 변환 class-group-utils.ts: groupClassesByTimeslot L19

평면적인 class 목록을 시간대(timeslot) → 그룹/1:1 2단 구조로 변환해 UI에 표시한다.

TimeslotSection { timeslot, endTime(+20분), groups[], individualClasses[] }
각 class를 time으로 묶고, groupId 있으면 그룹 섹션·없으면 1:1로 분류.

그룹 정렬: custom 먼저, auto 나중, 그 다음 displayId(uuid 앞 8자) 순.
endTime = timeslot + 20분(수업 길이 20분 고정 가정).
isGroupClass(groupId 유무), formatGroupId(uuid[:8] 표시).

그룹 = 모니터 카드뷰 단위: 여기서 만든 groupId가 SFU room의 groupId(JOIN_ROOM #2), 모니터 그룹 모니터링(#20)과 연결된다.

그룹 운영 · class-type

배정: groups/[groupId]/assign|unassign(check-unassign으로 해제 가능 여부 사전 확인), auto-assign(자동 편성).
class-type: children/[childId]/class-type — 아동의 수업 유형(1:1/그룹 등) 설정, check로 변경 가능 여부 확인.
아동 인증 변환: children/[childId]/auth/convert·[orderNo]/expire(+preview) — 계정/주문 관련.
배정 현황: assignment-matrix(치료사×시간대 배정표), assignment-drilldown(상세).

함정 · 주의

대부분 BFF 프록시: 실제 데이터/로직은 외부 ppi-api. 인증(member)·에러 처리만 BFF가 담당. 비즈니스 로직 변경은 ppi-api 쪽일 수 있음.
groupId 일관성: class-mgmt의 groupId가 SFU room(#2)·모니터 그룹(#20)·카드뷰(#13)에 그대로 전파. 변경 시 cross-영역 영향.
20분 고정 가정: endTime 계산이 +20분 하드코딩. 수업 길이 변경 시 함께 수정 필요.
preview 패턴: auth convert/expire 등 파괴적 작업은 preview 엔드포인트로 영향 먼저 확인 후 실행.
scheduled-lessons는 모니터가 소비: 응답 구조 변경 시 모니터 대시보드(#13) 세션 분류·카드 병합에 영향(#614 회귀 주의).

파일 · 라인 레퍼런스