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

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

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

---

1. 개요

알림설정 페이지에서 사용자가 선택한 알림음(soundType)을 API에 저장/반환하도록 구현 완료했다. React에서는 미리듣기 기능을 실제 음원 재생으로 변경하면 된다.

1.1 현재 상태

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

---

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

2.1 GET 응답 변경

각 알림 항목에 soundType 필드가 추가되고, 최상위에 _soundUrls 맵이 추가되었다.

{
  "notice": {
    "enabled": true,
    "notice": { "enabled": true, "email": false, "soundType": "default" },
    "event": { "enabled": true, "email": false, "soundType": "sam_voice" }
  },
  "approval": {
    "enabled": true,
    "approvalRequest": { "enabled": true, "email": true, "soundType": "default" },
    "draftApproved": { "enabled": true, "email": false, "soundType": "sam_voice" },
    "draftRejected": { "enabled": true, "email": false, "soundType": "default" },
    "draftCompleted": { "enabled": true, "email": false, "soundType": "mute" }
  },
  "_soundUrls": {
    "default": "https://api.dev.codebridge-x.com/sounds/default.wav",
    "sam_voice": "https://api.dev.codebridge-x.com/sounds/sam_voice.wav"
  }
}

soundType 값: "default" | "sam_voice" | "mute" 미저장 항목의 기본값: "default" _soundUrls는 미리듣기 재생에 사용할 음원 파일의 절대 URL

2.2 PUT 요청

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

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

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

---

3. React 구현 필요 항목

3.1 미리듣기 실제 재생 구현

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

API 응답의 _soundUrls를 사용하여 미리듣기를 실제 음원 재생으로 변경한다. React public/sounds/에 파일을 둘 필요 없이, API가 서빙하는 URL을 직접 사용한다.

현재 코드 (Mock):

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

변경 코드 (실제 재생 — _soundUrls 활용):

let previewAudio: HTMLAudioElement | null = null;

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

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

  const url = soundUrls?.[soundType];
  if (!url) {
    const soundName = soundType === 'default' ? '기본 알림음' : 'SAM 보이스';
    toast.info(`${soundName} 미리듣기`);
    return;
  }

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

호출 시:

• API 응답에서 _soundUrls를 state로 보관
• Play 버튼 클릭 시 playPreviewSound(item.soundType, soundUrls) 호출

3.2 _soundUrls 수신 처리

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

transformApiToFrontend() 함수에서 _soundUrls를 별도로 추출하여 반환한다.

// API 응답에서 _soundUrls 추출
export async function getNotificationSettings(): Promise<{
  success: boolean;
  data: NotificationSettings;
  soundUrls?: Record<string, string>;
  error?: string;
}> {
  const result = await executeServerAction({
    url: `${API_URL}/api/v1/settings/notifications`,
    transform: (data: Record<string, unknown>) => {
      const soundUrls = data._soundUrls as Record<string, string> | undefined;
      // _soundUrls는 그룹 데이터가 아니므로 제거 후 변환
      const { _soundUrls, ...groupData } = data;
      return { settings: transformApiToFrontend(groupData), soundUrls };
    },
    errorMessage: '알림 설정 조회에 실패했습니다.',
  });

  // ... 기존 에러 처리
}

3.3 types.ts 주석 업데이트

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

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

/**
 * 알림 설정 타입 정의
 *
 * API 응답 구조: { enabled, email, soundType } per item
 * soundType: 'default' | 'sam_voice' | 'mute'
 * _soundUrls: { default: URL, sam_voice: URL } — 미리듣기용 음원 URL
 *
 * [2026-03-18] soundType API 연동 완료
 */

---

4. 음원 파일 접근 URL

API 서버에서 정적 파일로 서빙한다. React에 파일을 둘 필요 없다.

환경	기본 알림음	SAM 보이스
개발 서버	https://api.dev.codebridge-x.com/sounds/default.wav	https://api.dev.codebridge-x.com/sounds/sam_voice.wav
운영 서버	https://api.codebridge-x.com/sounds/default.wav	https://api.codebridge-x.com/sounds/sam_voice.wav
로컬	http://api.sam.kr/sounds/default.wav	http://api.sam.kr/sounds/sam_voice.wav

sam_voice.wav는 현재 default.wav와 동일한 파일이다. 별도 음원이 준비되면 API에서 교체한다.

---

5. 동작 확인 체크리스트

• GET /api/v1/settings/notifications 응답에 soundType 포함 확인
• GET /api/v1/settings/notifications 응답에 _soundUrls 포함 확인
• _soundUrls.default URL 브라우저에서 직접 열어 소리 재생 확인
• 알림음 변경 후 저장 → 새로고침 시 선택값 유지 확인
• 기본 알림음 미리듣기(Play 버튼) → 실제 소리 재생
• SAM 보이스 미리듣기 → 실제 소리 재생
• 무음 미리듣기 → "무음으로 설정되어 있습니다" 토스트

---

6. 관련 파일

프로젝트	파일	변경 여부
API	app/Services/NotificationSettingService.php	✅ 완료
API	app/Http/Requests/NotificationSetting/UpdateGroupedSettingRequest.php	✅ 완료
API	public/sounds/default.wav (788KB)	✅ 배포 완료
API	public/sounds/sam_voice.wav (788KB)	✅ 배포 완료
React	src/components/settings/NotificationSettings/index.tsx	🔴 수정 필요
React	src/components/settings/NotificationSettings/actions.ts	🔴 수정 필요 (_soundUrls 추출)
React	src/components/settings/NotificationSettings/types.ts	🟡 주석 정리

---

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