docs: [changes] 알림설정 soundType 작업 변경 이력 추가

- API 변경 내용 (soundType 저장/반환, _soundUrls, 음원 서빙) - React 미구현 사항 정리 (프론트 개발자 전달 필요) - 커밋 이력 포함
2026-03-18 12:41:28 +09:00
parent 950626f06d
commit 5f9eb7f44c
2 changed files with 128 additions and 0 deletions
--- a/INDEX.md
+++ b/INDEX.md
@@ -252,6 +252,7 @@ DB 도메인별:
 | [20260316_stock_production_order.md](dev/changes/20260316_stock_production_order.md) | 재고생산관리 기능 추가 (STOCK 타입, 절곡 공정 자동, 생산지시 연동) |
 | [20260317_account_code_migration_mapping.md](changes/20260317_account_code_migration_mapping.md) | 계정과목 코드 변경 매핑 (더존 3자리 → KIS 5자리) |
 | [20260317_account_code_change_notice.md](changes/20260317_account_code_change_notice.md) | 계정과목 코드 변경 안내 (경리 전달용) |
+| [20260318_notification_settings_soundtype.md](dev/changes/20260318_notification_settings_soundtype.md) | 알림설정 soundType API 연동 + 음원 파일 서빙 (React 미구현 항목 포함) |

 ---

--- a/dev/changes/20260318_notification_settings_soundtype.md
+++ b/dev/changes/20260318_notification_settings_soundtype.md
@@ -0,0 +1,127 @@
+# 알림설정 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