수업 입장 제어 — 시간 검증 · can-enter 코드레벨 동작 흐름

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

한눈에 보는 입장 판정

등장 인물 (모듈 맵)

진입점 — 어디서 호출되나

경로 A — /api/validate-lesson 시간 윈도우 판정

app/api/validate-lesson/route.ts의 POST → findAvailableLesson 순서:

★ validateLessonTime — 입장 허용 상태머신

경로 A의 심장. lib/lesson-time-utils.ts:21-98. 입력 scheduledTime(= 회차의 plannedStartTime), now, 옵션 {isReentry, lastExitedAt}. 판정 순서:

plannedStartTime 계산 + 입장 모드

모든 시간 판정의 기준 시각. resolvePlannedClass planned-class-resolver.ts:33가 ppi-api 정규 수업(date+time)과 회차의 scheduledTime(예외 개방)을 합쳐 결정한다.

// planned-class-resolver.ts — KST(+09:00) 기준 ISO 변환
const classDateTime = parseClassDateTimeToIso(cls.date, cls.time);  // 정규 시각
// 그룹 수업이면 scheduledTime 무시(정규 시각 사용), 1:1이면 예외 개방 시각 사용
const scheduledTime = cls.groupId ? undefined : lesson?.scheduledTime;
return {
  plannedStartTime: scheduledTime ?? classDateTime,   // ← 입장 기준 시각
  isTempOpen: !!scheduledTime,                          // 1:1 임시 개방 여부
};

이 값으로 입장 모드(bypass mode)가 갈린다 — class-mgmt-bypass-policy.ts:10:

보강 본체 — enrichUserLessonsWithPpiApiData

lib/lesson-ppi-api-utils.ts:248-422. ① accessToken 없으면 그대로 반환(보강 skip). ② child면 getChildScheduledClasses, member면 getScheduledClasses 후 childId 필터. ③ statusMap/groupIdMap 구성 → 모든 회차에 completionStatus·classDate/Time·groupId 부착. ④ plannedStartTime은 enrichedLessons에서 먼저 찾고, 없으면 getLesson DynamoDB 폴백. ⑤ 폴백도 실패하면 missingTodayClasses에 push + warn 로깅(7단계 LESSON_NOT_PROVISIONED의 근거).

경로 B — canEnterLesson 회차 게이트

lib/db-queries.ts:2450-2490. getLesson(userId, index) 후 순서대로 차단:

경로 C — validateLessonGap 예외 시간 8시간 간격

관리자가 회차에 scheduledTime(예외 개방 시각)을 저장할 때, 같은 아동의 다른 모든 회차와 8시간 이상 떨어져 있어야 한다. lib/lesson-gap-validation.ts:19. 위반 시 POST /api/lessons:78 / PUT …/[index]:115가 409 LESSON_TIME_CONFLICT를 돌려준다. (수정 시 currentLessonIndex를 넘겨 자기 자신은 비교 제외.)

코드 맵 — 파일별 역할

읽을 때 주의할 함정

관련 문서