From 5f9eb7f44c6ac8dceb6662649842a04efe77d8e0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=EA=B9=80=EB=B3=B4=EA=B3=A4?= Date: Wed, 18 Mar 2026 12:41:28 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[changes]=20=EC=95=8C=EB=A6=BC=EC=84=A4?= =?UTF-8?q?=EC=A0=95=20soundType=20=EC=9E=91=EC=97=85=20=EB=B3=80=EA=B2=BD?= =?UTF-8?q?=20=EC=9D=B4=EB=A0=A5=20=EC=B6=94=EA=B0=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - API 변경 내용 (soundType 저장/반환, _soundUrls, 음원 서빙) - React 미구현 사항 정리 (프론트 개발자 전달 필요) - 커밋 이력 포함 --- INDEX.md | 1 + ...0260318_notification_settings_soundtype.md | 127 ++++++++++++++++++ 2 files changed, 128 insertions(+) create mode 100644 dev/changes/20260318_notification_settings_soundtype.md diff --git a/INDEX.md b/INDEX.md index 1492f30..99c8922 100644 --- 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 미구현 항목 포함) | --- diff --git a/dev/changes/20260318_notification_settings_soundtype.md b/dev/changes/20260318_notification_settings_soundtype.md new file mode 100644 index 0000000..fa76024 --- /dev/null +++ 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