알림 개발 명세 (FRD)¶
요지¶
SSE 기반 시스템 내 알림을 어떻게 구현하는지 정리한다. 트리거 7종, 조회·읽음·삭제 API, SSE 연결, 분류별 설정, 그리고 알림을 눌렀을 때 어디로 보낼지를 정하는 targetMetadata 라우팅을 다룬다.
상위 PRD (링크 · 변경 시 알림)¶
기획(트리거·채널·설정·보관 정책)은 prd이며, 외부 채널 발송은 카카오알림이 맡는다.
기술 접근 · 아키텍처¶
흐름은 단순하다. 사용자 이벤트가 일어나면 알림 서비스가 DB에 저장하고 SSE로 클라이언트에 밀어 준다. 2차로 외부 채널을 붙이면, 같은 알림 서비스가 외부 메시지 게이트웨이를 거쳐 SMS·카카오톡으로 내보내고 결과를 로그로 남긴다.
알림 트리거 (7종)¶
학습 흐름의 주요 길목마다 알림을 건다. 누가 받고 어디로 이동하는지까지 정해 뒀다.
| 이벤트 | 수신 대상 | 예시 메시지 | 이동 |
|---|---|---|---|
| 수업노트 작성 | 스터디룸 학생 | [OO선생님]이 새 수업노트를 작성했습니다. |
수업노트 상세 |
| 질문 등록 | 선생님 | [학생OO]이 질문을 남겼습니다. |
질문 상세 |
| 답변 등록 | 질문 작성 학생 | [OO선생님]이 답변을 달았습니다. |
답변 상세 |
| 과제 등록 | 대상 학생 | [OO선생님]이 새 과제를 등록했습니다. |
과제 상세 |
| 과제 제출 | 선생님 | [학생OO]이 과제를 제출했습니다. |
과제 상세 |
| 과제 마감 임박(24h) | 학생 | [OO과제] 마감이 내일로 다가왔습니다. |
과제 상세 |
| 스터디룸 초대 | 선생님·초대 학생 | {스터디룸명}에 초대되었습니다. |
— |
API · 데이터 모델¶
알림 API¶
알림은 조회·읽음·삭제와 실시간 연결(SSE)로 이뤄진다.
| Method | Endpoint | 설명 |
|---|---|---|
| GET | /api/notification/unread |
미조회 알림 리스트 (미접속 중 발생분) |
| GET | /api/notification/all |
모든 알림 리스트 (스키마 동일) |
| PATCH | /api/notification/read |
읽음 처리 — body notificationIds: List |
| DELETE | /api/notification |
삭제 — body notificationIds |
| GET | /api/notification/sse |
SSE 연결 (개발 완료) |
응답 스키마 (조회)¶
| 필드 | 타입 | 설명 |
|---|---|---|
| id | Long | 알림 ID |
| message | String | 표시 텍스트 |
| category | String | SYSTEM / HOMEWORK / TEACHING_NOTE / STUDY_ROOM / QNA |
| targetMetadata | String(json) | 관련 리소스 식별자 |
| isRead | Boolean | 읽음 여부 |
| regDate | DateTime | 생성 시간 |
targetMetadata 구조: QNA → {qnaId, studyRoomId} / 스터디룸 → {studyRoomId} / 강의노트 → {teachingNoteId} / 공지 → {noticeId}(예정). 클라이언트는 이 값으로 대상 화면 라우팅을 구성한다.
알림 설정¶
설정은 마스터 스위치(ALL) 아래 분류별 토글을 두는 구조다. 분류 중 일부(수업노트·질문·과제·문의)는 카카오까지 보내고, 일부(칼럼·스터디룸)는 시스템 내 알림(SSE)에만 쓴다.
ALL이 핵심이다. 이걸 끄면 나머지가 모두 강제로 꺼지므로, ALL이 켜져 있어야만 알림이 살아 있다. 변경은 PUT /api/me/notification-settings/{category}로 하고, 기본값은 기존 회원 OFF·신규 가입 ON이다.
의존성 · 영향 범위¶
- 외부 채널 발송 버튼 링크(딥링크): 카카오 알림톡 버튼 클릭 시 이동 주소를 케이스별로 정의. 비로그인 진입은
login?from=...패턴으로 리다이렉트를 보존한다:
| 트리거 | 수신자 | 이동(요지) |
|---|---|---|
| 문의 등록/답변 | 선생님/학생 | /inquiry/{id} |
| 수업노트 등록 | 스터디룸 학생 | login?from=/study-rooms/{rid}/note/{nid} |
| 질문 생성/답변 | 선생님/학생 | login?from=/study-rooms/{rid}/qna/{qid} |
| 과제 생성/제출 | 학생/선생님 | login?from=/study-rooms/{rid}/homework/{hid} |
발신키·템플릿코드 등 자격증명은 카카오알림 frd에서 구조만 다룬다(값은 환경변수·시크릿 저장소).
- 컬럼 게시판 좋아요: 같은 구현 정리 문서에 포함 — OptionalJwtAuthFilter로 /public/**에 선택적 유저 컨텍스트를 주입(좋아요 상세는 별도 도메인).
테스트 계획¶
트리거 7종이 각각 올바른 수신자에게 알림을 만드는지, SSE로 실시간 푸시가 가는지, 읽음·삭제가 멱등하게 동작하는지, 분류별 설정 ON/OFF가 반영되고 ALL을 끄면 하위가 연쇄로 꺼지는지, 그리고 90일 보관 경계를 확인한다.
작업 분해 (이슈 링크)¶
크게 알림 도메인·서비스·SSE 엔드포인트, 조회·읽음·삭제 API, 설정 API, 그리고 각 기능(수업노트·질문·답변·과제·초대)에서의 트리거 이벤트 발행으로 나뉜다. 화면 쪽으로는 알림센터(최신순·미확인 표시)와 "모두 읽음 처리"·설정 변경을 붙이고 90일까지 노출한다. 관리자용 로그·통계, AI 요약형 인사이트, 행동 기반 추천 알림은 후속 확장 후보다. 외부 채널 발송은 카카오알림이 맡는다.