From 2a35cf311fce0e9c0d0422059338cf73badba564 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 11:24:26 +0900 Subject: [PATCH] =?UTF-8?q?docs:=20[notification]=20=EC=95=8C=EB=A6=BC?= =?UTF-8?q?=EC=84=A4=EC=A0=95=20soundType=20React=20=EA=B5=AC=ED=98=84=20?= =?UTF-8?q?=EC=9A=94=EC=B2=AD=EC=84=9C=20=EC=9E=91=EC=84=B1?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - API soundType 연동 완료 내용 정리 - 음원 파일 배치 가이드 (MNG에서 복사) - 미리듣기 실제 재생 구현 코드 제공 - 동작 확인 체크리스트 포함 --- INDEX.md | 1 + plans/notification-sound-react-request.md | 175 ++++++++++++++++++++++ 2 files changed, 176 insertions(+) create mode 100644 plans/notification-sound-react-request.md diff --git a/INDEX.md b/INDEX.md index 2b79be2..9380f09 100644 --- a/INDEX.md +++ b/INDEX.md @@ -293,6 +293,7 @@ DB 도메인별: | [stock-detail-inventory-adjustment-request.md](plans/stock-detail-inventory-adjustment-request.md) | 재고 조정 위치 이동 요청 (입고관리 → 재고 상세 화면) | | [bom-tree-visualization-request.md](plans/bom-tree-visualization-request.md) | BOM Tree 시각화 React 구현 요청 (API 완료, 재귀 트리 UI) | | [ai-token-usage-service-migration.md](plans/ai-token-usage-service-migration.md) | AI 토큰사용량 서비스 이관 기획 (MNG→API+React, GCS→R2 저장소 차이) | +| [notification-sound-react-request.md](plans/notification-sound-react-request.md) | 알림설정 soundType React 구현 요청 (음원 배치, 미리듣기 실제 재생, API 연동 완료) | ### frontend/integration/ — 프론트엔드 개발 가이드 diff --git a/plans/notification-sound-react-request.md b/plans/notification-sound-react-request.md new file mode 100644 index 0000000..11556ff --- /dev/null +++ b/plans/notification-sound-react-request.md @@ -0,0 +1,175 @@ +# 알림설정 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