sam-docs/plans/notification-sound-react-request.md

알림설정 soundType 연동 — React 구현 요청

작성일: 2026-03-18 요청자: API 개발팀 대상: React 프론트엔드 상태: API 구현 완료, React 구현 대기

---

1. 개요

알림설정 페이지에서 사용자가 선택한 알림음(soundType)을 API에 저장하고, 미리듣기 기능을 실제 음원 재생으로 구현하는 작업이다.

1.1 현재 상태

항목	상태	설명
API soundType 저장	✅ 완료	PUT /api/v1/settings/notifications에서 soundType 저장
API soundType 반환	✅ 완료	GET /api/v1/settings/notifications에서 soundType 반환
React 타입 정의	✅ 이미 있음	types.ts에 SoundType, SOUND_OPTIONS 정의됨
React UI (드롭다운)	✅ 이미 있음	알림음 선택 Select + Play 버튼 렌더링 중
React 미리듣기	❌ Mock	토스트만 표시, 실제 재생 없음
음원 파일	❌ 빈 파일	public/sounds/default.wav (0 bytes)

---

2. API 변경사항 (이미 완료)

2.1 GET 응답 변경

기존 응답:

{
  "notice": {
    "enabled": true,
    "notice": { "enabled": true, "email": false },
    "event": { "enabled": true, "email": false }
  }
}

변경된 응답 (soundType 추가):

{
  "notice": {
    "enabled": true,
    "notice": { "enabled": true, "email": false, "soundType": "default" },
    "event": { "enabled": true, "email": false, "soundType": "sam_voice" }
  }
}

soundType 값: "default" | "sam_voice" | "mute" 미저장 항목의 기본값: "default"

2.2 PUT 요청

기존과 동일 구조에 soundType 필드 추가:

{
  "notice": {
    "enabled": true,
    "notice": { "enabled": true, "email": false, "soundType": "sam_voice" }
  }
}

soundType은 sometimes 규칙이므로 생략 가능 (생략 시 기존 값 유지)

---

3. React 구현 필요 항목

3.1 음원 파일 배치

public/sounds/ 폴더에 실제 음원 파일 배치 필요:

파일	용도	소스
public/sounds/default.wav	기본 알림음	mng/public/sounds/default.wav 복사 (788KB)
public/sounds/sam_voice.wav	SAM 보이스	별도 제작 필요 (임시로 default.wav 복사 가능)

# MNG에서 기본 알림음 복사
cp /home/aweso/sam/mng/public/sounds/default.wav /home/aweso/sam/react/public/sounds/default.wav

# SAM 보이스 임시 배치 (별도 음원 제작 전까지)
cp /home/aweso/sam/mng/public/sounds/default.wav /home/aweso/sam/react/public/sounds/sam_voice.wav

3.2 미리듣기 실제 재생 구현

파일: src/components/settings/NotificationSettings/index.tsx

현재 코드 (Mock):

function playPreviewSound(soundType: SoundType) {
  if (soundType === 'mute') {
    toast.info('무음으로 설정되어 있습니다.');
    return;
  }
  const soundName = soundType === 'default' ? '기본 알림음' : 'SAM 보이스';
  toast.info(`${soundName} 미리듣기`);
}

변경 코드 (실제 재생):

let previewAudio: HTMLAudioElement | null = null;

function playPreviewSound(soundType: SoundType) {
  if (soundType === 'mute') {
    toast.info('무음으로 설정되어 있습니다.');
    return;
  }

  // 이전 재생 중지
  if (previewAudio) {
    previewAudio.pause();
    previewAudio = null;
  }

  const soundFile = soundType === 'sam_voice' ? 'sam_voice.wav' : 'default.wav';
  previewAudio = new Audio(`/sounds/${soundFile}`);
  previewAudio.play().catch(() => {
    const soundName = soundType === 'default' ? '기본 알림음' : 'SAM 보이스';
    toast.info(`${soundName} 미리듣기`);
  });
}

3.3 types.ts 주석 업데이트

파일: src/components/settings/NotificationSettings/types.ts

상단 주석의 "백엔드 API 수정 필요 사항" 블록을 제거하거나 완료 표시로 변경:

/**
 * 알림 설정 타입 정의
 *
 * API 응답 구조: { enabled, email, soundType } per item
 * soundType: 'default' | 'sam_voice' | 'mute'
 *
 * [2026-03-18] soundType API 연동 완료
 */

---

4. 동작 확인 체크리스트

• GET /api/v1/settings/notifications 응답에 soundType 포함 확인
• 알림음 변경 후 저장 → 새로고침 시 선택값 유지 확인
• 기본 알림음 미리듣기(Play 버튼) → 실제 소리 재생
• SAM 보이스 미리듣기 → 실제 소리 재생
• 무음 미리듣기 → "무음으로 설정되어 있습니다" 토스트
• public/sounds/default.wav 파일 크기 확인 (0이 아닌 실제 파일)

---

5. 관련 파일

프로젝트	파일	변경 여부
API	app/Services/NotificationSettingService.php	✅ 완료
API	app/Http/Requests/NotificationSetting/UpdateGroupedSettingRequest.php	✅ 완료
React	public/sounds/default.wav	🔴 교체 필요 (0 → 788KB)
React	public/sounds/sam_voice.wav	🔴 신규 추가
React	src/components/settings/NotificationSettings/index.tsx	🔴 수정 필요
React	src/components/settings/NotificationSettings/types.ts	🟡 주석 정리
MNG	public/sounds/default.wav	참조용 (음원 소스)

---

최종 업데이트: 2026-03-18