아동 알림 프리셋 — 생성·관리 도입 및 개별 ON/OFF 토글 변경

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

1.1 배경 — 하드코딩 {{환경소음}}의 한계

이전 develop 구현은 환경소음 알림이 코드에 박혀 있었다.

• 안내 문구("주변이 시끄러워서 친구가 잘 못 들을 수 있어요")가 컴포넌트 상수로 고정.
• 표시 이미지가 단일 기본 이미지(/icon_bgnoise.png)로 고정.
• 트리거가 일반 채팅 프리셋 메시지에 {{환경소음}} 토큰을 끼워 넣는 방식이라, 안내 문안/이미지를 바꾸려면 코드 수정·배포가 필요했다.

이 PR은 이를 데이터로 빼내어 운영자가 직접 프리셋을 만들고 관리하도록 했다.

1.2 전체 구조 — 데이터 흐름

1. 등록 — 운영자가 관리 화면(/main/message)에서 프리셋 생성: 제목·표시 텍스트·발송 문구·이미지 N장.
2. 선택 — 진행자가 세션 중 카드뷰 드롭다운 또는 포커스뷰 패널에서 활성 프리셋 클릭.
3. 전파 — pickAndBroadcastAmbientTemplate가 이미지 N장 중 1장을 랜덤 선택, 그 단일 ID만 소켓(HOST_SET_AMBIENT_NOISE_TEMPLATE)으로 게스트에 전파.
4. 표시 — 게스트는 이미지 ID를 presigned URL로 resolve해 중앙 이미지 + 하단 배너를 표시. 진행자 미러뷰/모니터도 store 구독으로 동일 이미지 표시.
5. 동기화 — 활성 프리셋 스냅샷을 Redis(settings-store)에 저장, 새로 입장하는 게스트와 다른 인스턴스에 cross-instance 전파.

1.3 데이터 모델 · DynamoDB 쿼리

프리셋을 테이블 ppi-ambient-noise-template-{stage}에 저장한다. 각 템플릿 필드:

• title — 관리용 제목
• text — 게스트 화면 표시 텍스트(배너 문구)
• sendText — 트리거용 발송 문구(AI에게 전달되는 메시지)
• imageResourceIds — 표시 이미지 리소스 ID 목록(복수)
• isActive — 활성화 상태

lib/db-queries.ts의 CRUD 함수: getAmbientNoiseTemplates, createAmbientNoiseTemplate, updateAmbientNoiseTemplate, deleteAmbientNoiseTemplate, 활성화 토글. 타입은 types/db/ambient-noise-template.types.ts.

1.4 REST API 엔드포인트

이미지 등록은 /api/resources/upload-url로 발급한 업로드 URL을 사용하며, 리소스 탭의 기존 이미지를 골라 붙이는 방식이다.

1.5 프리셋 관리 화면

components/sections/ambient-noise-templates-section.tsx(신규)는 chat-preset.tsx(/main/message)에 통합된 관리 UI다.

• 폼 — 제목, 표시 텍스트, 발송 문구(선택), 이미지 검색·추가(복수).
• 이미지 — 리소스 탭 기존 이미지를 드롭다운으로 선택해 추가.
• 활성화 — 프리셋별 독립 ON/OFF 스위치 + 전역 ON/OFF 토글.
• 상태 훅: entities/ambient-noise-template/model/use-ambient-noise-templates.ts(목록·CRUD·낙관적 업데이트).

1.6 진행자 세션 트리거

진행자가 프리셋을 선택하면 pickAndBroadcastAmbientTemplate(entities/ambient-noise-template/model/broadcast-ambient-template.ts)가 실행된다.

1. 이미지 목록에서 1장 랜덤 선택.
2. 선택 ID 1개만 HOST_SET_AMBIENT_NOISE_TEMPLATE로 게스트에 전파 → 모든 아동이 동일 이미지.
3. 발송 문구를 채팅 메시지로 전송(스냅샷이 먼저 도착하도록 200ms 지연).
4. 진행자 미러뷰 store(useAmbientNoiseAlertStore.current)에 반영.

1.7 게스트 화면 표시

components/ui/ambient-noise-alert.tsx가 중앙 이미지 + 하단 배너를 렌더한다.

• 이미지 모션 — noiseIconBounce 0.8s ease-in-out infinite 바운스(scale+rotate). 레거시 {{환경소음}} 구현의 모션을 신규 구조에 복원(커밋 id-010).
• 배너 모션 — slideUp 0.35s + bannerFloat 2.4s infinite.
• 깜빡임 방지 — 커스텀 이미지 resolve 대기 중(hasCustomImage)이면 기본 이미지를 띄우지 않음(2부 6절 참고).
• 게스트 수신·resolve 로직: entities/guest-page-session/model/use-guest-page-session.ts, 상태: stores/use-ambient-noise-alert-store.ts.

1.8 모니터 대시보드 미러뷰

• 포커스뷰(/monitor-dashboard/[group]/[roomId]) — ChildAlertPresetsPanel 활성 프리셋 버튼 그리드.
• 카드뷰(/monitor-dashboard/[group]) — 세션 카드 드롭다운으로 선택.
• 미러뷰 — shared/ui/monitor-media-display.tsx가 store 구독으로 아동 화면과 동일한 이미지+배너 표시.

1.9 소켓 · Redis cross-instance 동기화

• 신규 이벤트 HOST_SET_AMBIENT_NOISE_TEMPLATE(roomId 없음 → 전체 게스트 broadcast).
• Redis settings-store(apps/socket/src/redis/settings-store.ts)에 활성 프리셋 스냅샷 저장 → 새로 입장하는 게스트가 최신 상태 수신.
• 소켓 핸들러(room-handlers.ts, session-handlers.ts)가 Redis 업데이트를 구독해 모든 연결 인스턴스에 전파.

1.10 1부 주요 변경 파일

2.1 배경 — 왜 바꿨나

기존 구조는 DB에 isActive: true인 프리셋이 항상 정확히 1개가 되도록 강제했다. 첫 등록 시 자동 활성화하고, 활성 프리셋을 삭제하면 남은 첫 프리셋을 자동 활성화하며, 다른 것을 켜면 나머지를 모두 껐다.

• 진행자가 상황별로 여러 안내 프리셋(예: "환경소음2", "환경소음3"…)을 준비해 둬도 동시에 하나만 쓸 수 있었다.
• 전역 OFF 상태에서도 진행자 화면에 프리셋 버튼/드롭다운이 그대로 노출돼 혼란을 줬다.
• 알림 이미지가 여러 장이면 표시할 때마다 랜덤 1장을 골라 presigned URL로 resolve하는데, 그 사이 기본 이미지(icon_bgnoise.png)가 먼저 깜빡이고 곧 실제 이미지로 교체됐다.

2.2 Before / After — 핵심 동작 변화

2.3 데이터 레이어 — 단일활성 강제 로직 제거

lib/db-queries.ts에서 "항상 1개 활성" 불변식을 만들던 코드를 걷어내고, 토글 함수로 교체했다.

• 신규 생성 — createAmbientNoiseTemplate: 첫 등록 자동 활성화를 제거하고 항상 isActive: false로 생성.
• 삭제 — deleteAmbientNoiseTemplate: 활성 프리셋 삭제 시 남은 프리셋을 자동 활성화하던 블록 제거.
• 활성화 — setActiveAmbientNoiseTemplate(전체 끄고 하나만 켜기) → toggleAmbientNoiseTemplate(지정 프리셋의 isActive만 반전)으로 교체.

// AS-IS: 지정한 것만 활성, 나머지는 모두 비활성 (정확히 1개)
for (const t of templates) {
  const shouldBeActive = t.id === id;
  if (t.isActive !== shouldBeActive) { /* UpdateCommand ... */ }
}

// TO-BE: 지정한 프리셋의 isActive만 토글
const target = templates.find((t) => t.id === id);
const nextActive = !target.isActive;
// UpdateCommand SET isActive = nextActive

2.4 API · 상태 훅

• app/api/ambient-noise-templates/[id]/activate — 핸들러가 toggleAmbientNoiseTemplate를 호출하도록 변경(URL 경로는 /activate 유지).
• entities/ambient-noise-template/.../use-ambient-noise-templates.ts — activateTemplate → toggleTemplate. 낙관적 업데이트도 "전부 끄고 하나만 켜기"에서 해당 id만 반전으로 변경.

// AS-IS
return prev.map((t) => ({ ...t, isActive: t.id === id }));
// TO-BE
return prev.map((t) => (t.id === id ? { ...t, isActive: !t.isActive } : t));

2.5 진행자 화면 — 노출 조건 & 비활성 클릭 차단

포커스뷰 패널 (widgets/monitor/ui/child-alert-presets-panel.tsx)

• 전역 enabled가 OFF이거나 등록 프리셋이 없으면 섹션 전체를 렌더하지 않음(return null).
• 비활성 프리셋 버튼은 disabled(회색 + 클릭 불가), title에 · 비활성 표기.
• 진입 시 미리 전파(prebroadcast)는 활성 프리셋이 있을 때만 수행.

카드뷰 (features/session/ui/session-controls.tsx)

• 같은 알림 프리셋을 띄우는 <select> 드롭다운도 전역 OFF면 숨김.
• 비활성 프리셋은 <option disabled> + (비활성) 표기. triggerAmbientPreset에 !t.isActive 방어 가드 추가.

2.6 알림 이미지 깜빡임 제거

원인은 트리거 시점에 imageUrl: undefined로 먼저 상태를 세팅하고 동시에 알림을 표시(visible)했기 때문이다. 알림 컴포넌트는 imageUrl이 없으면 기본 이미지로 폴백하므로, presigned URL이 resolve되기 전 짧은 순간 기본 이미지가 떴다가 선택 이미지로 교체됐다.

해결: hasCustomImage 플래그를 도입해 선택 이미지가 없을 때만 기본 이미지를 표시한다.

// components/ui/ambient-noise-alert.tsx
// 선택 이미지가 있으면(hasCustomImage) resolve 전까진 미표시, 없을 때만 기본 이미지
const resolvedImage = imageUrl || (hasCustomImage ? undefined : DEFAULT_IMAGE);
// resolvedImage가 없으면 중앙 <img> 자체를 렌더하지 않음

진행자 미러뷰에도 동일 적용

아동 화면뿐 아니라 진행자/모니터 미러뷰(monitor-media-display.tsx, host-video.tsx)도 같은 깜빡임이 있었다. 이쪽은 Zustand store(useAmbientNoiseAlertStore의 current)를 거치므로, CurrentAmbientNoiseAlert 타입과 pickAndBroadcastAmbientTemplate, 3개 렌더 사이트 모두에 hasCustomImage를 전달해 일관되게 제거했다.

연속 트리거 race 가드

알림을 빠르게 연달아 띄울 때, 이전 템플릿의 늦은 URL resolve가 최신 템플릿의 표시 상태를 덮어쓰는 race가 있었다. 게스트 훅(ambientApplySeqRef)과 broadcast 함수(broadcastSeq) 양쪽에 시퀀스 토큰을 두어, .then/.catch가 최신 시퀀스일 때만 상태를 반영하도록 했다.

2.7 2부 주요 변경 파일

2.8 알려진 한계 — 후속 논의 필요

다중활성으로 바뀌었지만 소켓/Redis 전파 모델은 여전히 단일 스냅샷(슬롯 1개)이다. 진행자가 클릭하는 시점에 그 프리셋을 게스트에 직접 전파(HOST_SET_AMBIENT_NOISE_TEMPLATE)하므로 클릭 기반 동작은 정상이지만, 다음은 의도적으로 손대지 않았다.

다중활성을 게스트까지 일관되게 반영하려면 소켓 페이로드/Redis를 활성 스냅샷 배열로 확장하는 후속 작업이 필요하다.

관련 문서