# 알림설정 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 응답 변경

기존 응답:
```json
{
  "notice": {
    "enabled": true,
    "notice": { "enabled": true, "email": false },
    "event": { "enabled": true, "email": false }
  }
}
```

변경된 응답 (**soundType 추가**):
```json
{
  "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` 필드 추가:
```json
{
  "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 복사 가능) |

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

**변경 코드** (실제 재생):
```typescript
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 수정 필요 사항" 블록을 제거하거나 완료 표시로 변경:
```typescript
/**
 * 알림 설정 타입 정의
 *
 * 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