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` 맵이 추가되었다.

```json
{
  "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` 필드 추가:
```json
{
  "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):
```typescript
function playPreviewSound(soundType: SoundType) {
  if (soundType === 'mute') {
    toast.info('무음으로 설정되어 있습니다.');
    return;
  }
  const soundName = soundType === 'default' ? '기본 알림음' : 'SAM 보이스';
  toast.info(`${soundName} 미리듣기`);
}
```

**변경 코드** (실제 재생 — `_soundUrls` 활용):
```typescript
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`를 별도로 추출하여 반환한다.

```typescript
// 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 수정 필요 사항" 블록을 완료 표시로 변경:
```typescript
/**
 * 알림 설정 타입 정의
 *
 * 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