# 알림설정 soundType API 연동 및 음원 파일 서빙

**날짜:** 2026-03-18
**작업자:** Claude Code

## 변경 개요

서비스 알림설정 페이지에서 사용자가 선택한 알림음(soundType)을 API에서 저장/반환하도록 구현하고, 미리듣기용 음원 파일을 API 서버에서 서빙하도록 구성했다.

---

## 배경

- React UI에 알림음 선택 드롭다운(`default`/`sam_voice`/`mute`)과 Play 버튼이 이미 구현되어 있었음
- 그러나 API에서 `soundType` 값을 저장/반환하지 않아 선택값이 유지되지 않았음
- 미리듣기는 Mock(토스트만 표시), 음원 파일은 0바이트 placeholder 상태였음

---

## 수정된 파일

### API (`sam/api`)

| 파일 | 변경 내용 |
|------|----------|
| `app/Services/NotificationSettingService.php` | `getGroupedSettings()` — 각 항목에 `soundType` 반환 (`settings.sound_type`에서 읽기, 기본값 `'default'`) |
| | `getGroupedSettings()` — 응답에 `_soundUrls` 맵 추가 (음원 파일 절대 URL) |
| | `updateGroupedSettings()` — `soundType`을 `notification_settings.settings` JSON의 `sound_type` 키로 저장 |
| `app/Http/Requests/NotificationSetting/UpdateGroupedSettingRequest.php` | 모든 알림 항목에 `soundType` 검증 규칙 추가 (`in:default,sam_voice,mute`) |
| `public/sounds/default.wav` | 기본 알림음 파일 배치 (788KB, MNG에서 복사) |
| `public/sounds/sam_voice.wav` | SAM 보이스 파일 배치 (788KB, 임시로 기본음 동일) |
| `.gitignore` | `!public/sounds/*.wav` 예외 추가 (*.wav 글로벌 무시에서 제외) |

### docs (`sam/docs`)

| 파일 | 변경 내용 |
|------|----------|
| `features/notification-settings/README.md` | 신규 — 서비스 알림설정 설계 문서 (테이블 5개, API 엔드포인트, 알림음 시스템, 연동 현황) |
| `plans/notification-sound-react-request.md` | 신규 — React 프론트엔드 구현 요청서 (미리듣기 구현 코드, `_soundUrls` 활용법, 체크리스트) |
| `INDEX.md` | 위 2개 문서 등록 |

---

## 상세 변경 사항

### 1. soundType 저장/반환

`notification_settings` 테이블의 `settings` JSON 컬럼에 `sound_type` 키로 저장한다.

```
저장: PUT → { "notice": { "notice": { "soundType": "sam_voice" } } }
     → notification_settings.settings = { "sound_type": "sam_voice" }

조회: GET → notification_settings.settings['sound_type'] 읽기
     → 미저장 시 기본값 'default'
     → 응답: { "enabled": true, "email": false, "soundType": "sam_voice" }
```

### 2. _soundUrls 응답

GET 응답 최상위에 음원 URL 맵을 포함하여 프론트에서 환경별 URL을 하드코딩할 필요 없도록 했다.

```json
{
  "notice": { ... },
  "approval": { ... },
  "_soundUrls": {
    "default": "https://api.dev.codebridge-x.com/sounds/default.wav",
    "sam_voice": "https://api.dev.codebridge-x.com/sounds/sam_voice.wav"
  }
}
```

### 3. 음원 파일 서빙

API 서버의 `public/sounds/` 디렉토리에 wav 파일을 배치하여 Nginx가 정적 파일로 서빙한다.
React에 음원 파일을 둘 필요 없다.

| 환경 | URL |
|------|-----|
| 개발 서버 | `https://api.dev.codebridge-x.com/sounds/default.wav` |
| 운영 서버 | `https://api.codebridge-x.com/sounds/default.wav` |
| 로컬 | `http://api.sam.kr/sounds/default.wav` |

---

## React 미구현 사항 (프론트 개발자 전달)

React 코드는 이번에 수정하지 않았다. 프론트 개발자에게 요청 문서(`docs/plans/notification-sound-react-request.md`)를 전달하여 다음 항목을 구현해야 한다:

| 항목 | 현재 | 변경 필요 |
|------|------|----------|
| `playPreviewSound()` | Mock (토스트만 표시) | `_soundUrls` URL로 `new Audio().play()` |
| `actions.ts` | `_soundUrls` 무시 | API 응답에서 `_soundUrls` 추출하여 전달 |
| `types.ts` 주석 | "백엔드 수정 필요" | 완료 표시로 변경 |

---

## 커밋 이력

### API (`sam/api` develop)

| 커밋 | 내용 |
|------|------|
| `540255e` | `feat: [notification] 알림설정 soundType API 연동` |
| `72bb33e` | `feat: [notification] 알림음 파일 서빙 + 응답에 soundUrls 추가` |
| `13f8446` | `chore: [notification] 알림음 wav 파일 gitignore 예외 + 파일 추가` |

### docs (`sam/docs` main)

| 커밋 | 내용 |
|------|------|
| `c169fd2` | `docs: [notification-settings] 서비스 알림설정 설계 문서 작성` |
| `2a35cf3` | `docs: [notification] 알림설정 soundType React 구현 요청서 작성` |
| `ac1eecb` | `docs: [notification-settings] API soundType 완료 상태 반영` |
| `950626f` | `docs: [notification] API 음원 서빙 방식으로 문서 전면 수정` |

---

## 관련 문서

- [서비스 알림설정 설계 문서](../../features/notification-settings/README.md)
- [soundType React 구현 요청서](../../plans/notification-sound-react-request.md)

---

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