아동 활동 건너뛰기 (템플릿 허용 설정 → isSkippable) — PPI-1185 신규 기능코드레벨

개요 · 범위

회기 템플릿에서 활동 단위로 "아동 넘기기 허용"을 설정하면, 아동 화면에 건너뛰기 버튼이 뜨고 아동이 그 활동의 남은 스텝을 통째로 건너뛰어 다음 활동으로 이동할 수 있다. 허용되지 않은 활동은 기존과 동일하게 진행된다(기본값 OFF).

전체 데이터 흐름 — 설정이 버튼이 되기까지

값의 형태가 두 번 바뀐다. 템플릿에서는 "몇 번째 활동"(인덱스 배열), 실제 활동에서는 "이 활동이 되는지"(불리언 플래그)다.

주석 달린 코드 — 파일:줄 그대로 열어보기

아래 블록은 실제 소스와 동일하고, // ① 주석만 이 문서에서 덧붙인 설명이다. 소스에는 이 주석이 없다(PPI 컨벤션상 주석 최소화). 각 블록 위 파일:줄로 바로 열 수 있다.

# repo 루트에서
code -g apps/web/lib/activity-skip.ts:1
code -g apps/web/lib/lesson-utils.ts:105
code -g apps/web/entities/guest-page-session/model/use-guest-page-session.ts:2698
code -g apps/web/widgets/guest/guest-layout/ui/guest-layout.tsx:334
code -g apps/web/components/sections/lesson-template-form.tsx:234
code -g apps/web/lib/db-queries.ts:2042

① 순수 유틸 — 인덱스 정규화와 재매핑

export function normalizeSkippableActivityIndices(
  indices: unknown,          // ① unknown: API body로 들어온 값을 신뢰하지 않는다
  activityCount: number,     // ② "현재 활동 수" 기준으로 범위를 자른다
): number[] {
  if (!Array.isArray(indices) || activityCount <= 0) return [];
                                     // ③ 미설정(undefined)·빈 템플릿 → 빈 배열 (기본값 OFF)
  return Array.from(
    new Set(                         // ④ 중복 제거: 체크 토글 경합으로 같은 인덱스가 두 번 들어와도 안전
      indices.filter(
        (index): index is number =>
          Number.isInteger(index) && index >= 0 && index < activityCount,
                                     // ⑤ 비정수·음수·활동 수 초과 인덱스를 버린다
                                     //    (활동을 줄인 뒤 남은 옛 인덱스가 여기서 정리됨)
      ),
    ),
  ).sort((a, b) => a - b);           // ⑥ 정렬: 저장값 비교·diff를 안정화
}

export function remapSkippableActivityIndicesAfterRemove(
  indices: number[],
  removedIndex: number,
): number[] {
  return indices
    .filter((index) => index !== removedIndex)         // ⑦ 지워진 활동의 설정은 함께 삭제
    .map((index) => (index > removedIndex ? index - 1 : index));
                                                       // ⑧ 뒤쪽 활동들은 한 칸 앞으로 밀리므로 인덱스도 -1
}

export function remapSkippableActivityIndicesAfterReorder(
  indices: number[],
  newOrder: number[],   // ⑨ newOrder[새 위치] = 이전 위치. 드래그 결과의 순서 배열
): number[] {
  const skippableIndices = new Set(indices);

  return newOrder.flatMap((oldIndex, newIndex) =>
    skippableIndices.has(oldIndex) ? [newIndex] : [],
  );                        // ⑩ 설정이 "이전 위치"에 있었으면 그 활동의 "새 위치"로 옮긴다
}                           //    flatMap+빈배열 = filter+map을 한 번에 (해당 없으면 결과에서 빠짐)

export function isActivityIndexSkippable(
  indices: number[] | undefined,
  activityIndex: number,
): boolean {
  return indices?.includes(activityIndex) === true;
}                           // ⑪ === true: undefined를 false로 확정 (옵셔널 체이닝 결과가 undefined일 수 있음)

② 회기 생성 시 스냅샷 — 인덱스가 플래그로 굳는 지점

          createdAt: currentEpochTime,
          updatedAt: currentEpochTime,
          ...(activityTemplate.isSpare && { isSpare: true }),
          ...(isActivityIndexSkippable(
            lessonTemplate.skippableActivityIndices,  // ① 템플릿의 인덱스 배열
            i,                                       // ② 현재 만들고 있는 활동의 순번
          ) && { isSkippable: true }),                // ③ 참일 때만 필드를 넣는다(false는 저장 안 함)
          ...(activityJumpConfig && { jumpConfig: activityJumpConfig }),
        };

③ 아동측 실행 — skipCurrentActivity

const skipCurrentActivity = useCallback(() => {
  if (terminatedRef.current) return false;
                                        // ① 수업 종료 후 종료 화면에서 눌려도 진행되지 않게
  const currentActivity = activities[currentActivityIndex];
  if (!currentActivity?.isSkippable) {   // ② 실행측 게이트 — UI를 우회해 호출돼도 여기서 막힌다
    logger.warn("Child activity skip ignored", {
      roomId,
      activityIndex: currentActivityIndex,
      reason: currentActivity ? "not-skippable" : "activity-not-found",
                                        // ③ 거부 사유를 남긴다 → 운영 로그로 원인 판별 가능
    });
    return false;                        // ④ 불리언 반환: 호출자(guest-layout)가 잠금을 되돌릴 수 있게
  }

  logger.info("Child activity skip requested", {
    roomId,
    activityIndex: currentActivityIndex,
    stepIndex: currentStepIndex,        // ⑤ 몇 번째 스텝에서 넘겼는지 = 얼마나 남기고 건너뜀
    activityId: currentActivity.id,
    activityTitle: currentActivity.title,
  });

  if (!goToNextStep(undefined, true)) {
                                        // ⑥ 2번째 인자 forceNextActivity=true
                                        //    → 전환 기준 스텝을 "마지막 스텝"으로 올려 남은 스텝을 통째로 건너뛴다
                                        //    (1번째 인자 triggerText는 undefined → conditional jump 키워드 매칭 없음)
    logger.warn("Child activity skip ignored", {
      roomId,
      activityIndex: currentActivityIndex,
      reason: "no-next-target",
                                        // ⑦ 마지막 활동 등 이동 대상이 없는 경우
    });
    return false;
  }

  aiSessionRef.current?.cancelResponse();
                                        // ⑧ 이동이 확정된 뒤에만 AI 발화를 끊는다
                                        //    (같은 동기 블록이라 전환 전 취소와 실효는 동일)
  return true;
}, [activities, currentActivityIndex, currentStepIndex, goToNextStep, roomId]);

④ 아동측 표시 조건과 연타 방지

const showSkipActivityButton =
  session.hasConfirmedReady &&              // ① 입장·준비 확인 전(대기 화면)에는 숨김
  session.isCurrentActivitySkippable &&     // ② 유일한 허용 소스 = 템플릿 설정 스냅샷
  !activeSelection;                         // ③ "선택 후 넘기기" 화면과 버튼이 겹치는 것을 방지

const handleSkipActivity = useCallback(() => {
  if (skipLockRef.current) return;      // ① ref로 즉시 차단 — setState는 비동기라 연타를 못 막는다

  skipLockRef.current = true;
  setIsSkippingActivity(true);           // ② state는 disabled 표시용(시각 피드백)
  const skipped = session.skipCurrentActivity();

  if (!skipped) {                          // ③ 훅이 거부하면 잠금 즉시 원복 (영구 비활성 방지)
    skipLockRef.current = false;
    setIsSkippingActivity(false);
    return;
  }

  trackEvent("ClientGuest:ActivitySkipped", {
    userId, roomId: props.roomId, lessonIndex: props.lessonIndex,
    activityIndex: session.currentActivityIndex,
    activityTitle: session.currentActivityTitle,
                                           // ④ 사후 분석용: 어느 활동을 아동이 실제로 건너뛰는지
  });

  skipUnlockTimerRef.current = setTimeout(() => {
    skipLockRef.current = false;
    setIsSkippingActivity(false);
    skipUnlockTimerRef.current = null;
  }, 1500);                              // ⑤ 유일한 잠금 해제 경로 — 전환 완료 여부와 무관하게 1.5초 유지
}, [...]);

④-1 조기 해제 사이드 이펙트 — 활동 인덱스 기반 해제 effect 제거 (a0ff593d)

초기 구현에는 "활동이 실제로 바뀌면 즉시 잠금을 풀어주는" effect가 이중 안전망으로 들어 있었다. 실제로는 안전망이 아니라 연타 방지를 무력화하는 유일한 경로였다.

// 제거된 코드 (a0ff593d)
// useEffect(() => {
//   skipLockRef.current = false;
//   setIsSkippingActivity(false);
//   clearTimeout(skipUnlockTimerRef.current);
// }, [session.currentActivityIndex]);

// 현재: 해제 경로는 두 갈래뿐
//   ① skipCurrentActivity()가 false → 즉시 해제 (먹통 버튼 방지)
//   ② 성공 → 1500ms 타이머만 해제 (다음 활동도 skippable이어도 1.5초 잠김)
//   언마운트 cleanup은 타이머만 정리한다

⑤ 템플릿 폼 — 재매핑을 붙인 두 지점

// 활동 삭제 핸들러 — jumpConfigs 재매핑과 같은 자리에 나란히 붙였다
setSelectedActivityTemplates(newTemplates);
setSkippableActivityIndices((prev) =>
  remapSkippableActivityIndicesAfterRemove(prev, index),
);

// 드래그 재정렬 핸들러 — newOrder는 jumpConfigs 재매핑이 이미 만들어둔 배열을 재사용
setJumpConfigs(remapped);
setSkippableActivityIndices((prev) =>
  remapSkippableActivityIndicesAfterReorder(prev, newOrder),
);
setDraggedIndex(null);

⑥ DynamoDB 업데이트 식 — 빠뜨리면 "저장이 안 되는" 증상

UpdateExpression:
  "set title = :title, activityTemplates = :activityTemplates, " +
  "skippableActivityIndices = :skippableActivityIndices, " // ① 여기에 없으면 체크해도 저장 안 됨
  "jumpConfigs = :jumpConfigs, sessionReport = :sessionReport, updatedAt = :updatedAt",
ExpressionAttributeValues: {
  ":title": template.title,
  ":activityTemplates": template.activityTemplates,
  ":skippableActivityIndices": template.skippableActivityIndices || [],
                                  // ② || [] — 기존 템플릿 문서에는 이 속성이 아예 없다
                                  //    DDB는 undefined를 거부하므로 방어 필수
  ...

버튼 표시 조건 — 진리표와 이중 게이트

표시(UI)와 실행(훅) 두 단계가 같은 플래그로 각각 막는다. UI만 막으면 상태 경합으로 잘못된 호출이 통과할 수 있고, 훅만 막으면 아동에게 눌리지 않는 버튼이 보인다.

인덱스 재매핑 — 이 변경의 절반이 여기에 있다

설정이 "몇 번째 활동"으로 저장되므로, 템플릿에서 활동을 지우거나 순서를 바꾸면 설정이 다른 활동으로 옮겨간다. 아래는 재매핑이 무엇을 고치는지 눈으로 본 것.

케이스 1 — 활동 삭제 (AfterRemove)

변경 전 — 설정 [0, 2, 3] (인사·게임·마무리가 허용)

1번(대화) 삭제 → 재매핑 없으면 [0, 2, 3]이 그대로 남아 "게임"의 허용이 사라지고 범위 밖 3이 남는다

재매핑 적용 remapAfterRemove([0,2,3], 1) → [0,1,2] — 설정이 원래 활동을 따라간다

케이스 2 — 드래그 재정렬 (AfterReorder)

변경 전 — 설정 [0, 2]

"게임"을 맨 앞으로 → newOrder = [2, 0, 1] (새 위치 0에 이전 2번이 옴)

재매핑 결과 remapAfterReorder([0,2], [2,0,1]) → [0,1] — 게임·인사가 계속 허용

순번 어긋남 방어 3중 — 폼 재매핑만으로는 부족했다

인덱스 기반 저장의 위험은 "활동 목록을 편집하는 경로가 폼 하나가 아니다"라는 점이다. 폼 밖 경로는 폼의 재매핑을 타지 않는다. PR #981 리뷰에서 실제 도달 가능한 경로가 하나 발견됐고, 이후 서버 계약까지 함께 막았다.

활동 [A, B, C, D] 중 C만 허용 → skippableActivityIndices = [2]
  → 활동 표에서 B 삭제 (activityTemplates만 필터, 설정은 [2] 그대로 전송)
  → 서버 normalize([2], 3) = [2]        // 범위 내라 통과, 재매핑은 하지 않음
  → 순번 2 = D → 아동이 D를 건너뛸 수 있고 C는 불가

const survivingIndices = selectedTemplate.activityTemplates
  .map((id, index) => ({ id, index }))
  .filter(({ id }) => id !== activityTemplate.id)
  .map(({ index }) => index);

skippableActivityIndices: remapSkippableActivityIndicesAfterReorder(
  selectedTemplate.skippableActivityIndices || [],
  survivingIndices
)

진행자측 표시 — 왜 배지가 필요한가

아동이 스스로 활동을 넘기면, 진행자 화면에서는 이유 없이 활동이 전환된 것처럼 보인다. 오작동 오해와 불필요한 재현 조사를 막기 위해 "여기는 아동이 넘길 수 있는 활동"임을 미리 알린다.

함정 · 주의

• 스냅샷 시점 (가장 헷갈리는 지점): 템플릿 설정은 회기 생성 시점에만 활동으로 복사된다. 진행 중·이미 만들어진 회기는 템플릿을 체크해도 버튼이 안 뜨고, 반대로 체크를 해제해도 이미 만든 회기에서는 버튼이 계속 뜬다. 반영에는 회기 재생성 또는 일괄 덮어쓰기가 필요하다.
• 인덱스 기반 저장: 템플릿에서 활동을 API로 직접 수정해 활동 수를 줄이면, 서버 정규화(activityTemplates.length 기준)가 범위 밖 인덱스를 잘라낸다. 반면 순서만 바꾸는 경우는 잘라낼 근거가 없어 재매핑을 거치지 않으면 설정이 엉뚱한 활동에 남는다 → 지금은 서버가 400으로 거절한다. 위 "순번 어긋남 방어 3중" 절 참조.
• 마지막 활동의 건너뛰기 허용은 정책 미결: 설정 화면에서 막지 않으므로 마지막 활동에도 체크할 수 있다. 이동 대상이 없으면 reason: "no-next-target" WARN과 함께 실패 처리만 되고 아동 화면에서는 눌러도 아무 일도 일어나지 않는다(발화는 유지). 버튼을 숨길지, 수업 종료로 이을지는 미정.
• contentOverlay 조건 확장: 기존에는 isMobileLandscape일 때만 오버레이가 존재했는데 isMobileLandscape || showSkipActivityButton으로 넓어졌다. 데스크톱·세로 모드에서도 오버레이가 마운트되기 시작하므로(로고·워터마크는 내부 가드로 동일), 콘텐츠 영역 위 클릭·포인터 이벤트를 다룰 때 확인 필요. 버튼에는 pointer-events-auto가 붙어 있다.
• 1.5초 잠금은 안전망이지 정답이 아니다: 정상 경로에서는 currentActivityIndex 변경 effect가 먼저 잠금을 푼다. 타임아웃이 실제로 쓰이는 경우는 전환이 실패했거나 느린 상황이므로, 이 값이 자주 소진된다면 전환 실패를 의심할 신호다.
• 건너뛰기 전용 이동 경로가 없다: goToNextStep(undefined, true)로 기존 전환 로직을 그대로 타므로, jumpConfig(조건부 점프)·isSpare(예비 활동 스킵) 규칙이 함께 적용된다. 조건부 점프 활동에서 건너뛰면 triggerText가 undefined라 키워드 매칭 없이 기본 경로로 간다.
• 진행자에게는 중단 수단이 없다: 이번 변경은 아동측 버튼과 진행자측 표시만 추가했다. 수업 중 특정 활동의 허용을 끄는 진행자 UI는 없다.

로그로 판별하기

파일 · 라인 레퍼런스

관련 문서

• Activity 시스템 (템플릿·step·jumpConfig·auto-finish) — goToNextStep·jumpConfig·인덱스 기반 이동의 기반 문서. 건너뛰기는 이 전환 로직을 재사용한다
• 음성 입력 정책 공통화 (agent-input-policy) — 건너뛰기 시 cancelResponse()로 끊는 AI 발화 턴의 입력 게이트
• 예비활동 19분 스킵 오작동 · 누적시간 4분 누락 — 활동 스킵이 누적 시간 집계에 미치는 영향 사례
• 긴급종료 콘텐츠 흐름 추가 (PPI-1193) — 커밋 리뷰 — 같은 시기 develop에 들어온 변경. 건너뛰기와 같은 findNextStepSkippingSpare()를 공유하며, 긴급종료 묶음은 건너뛰기 이동 대상에서 자동 제외된다