카카오 알림 개발 명세 (FRD)¶
요지¶
카카오 알림톡 연동을 어떻게 구현하는지 정리한다. 발송은 NHN Cloud 알림톡 API로 하고, 자동·수동 두 갈래의 발송과 템플릿 7종, 발송 이력 로그를 다룬다. 이 기능은 시스템 알림(알림) 위에 외부 채널을 얹은 것이다.
상위 PRD (링크 · 변경 시 알림)¶
기획(역할별 설정·발송 플로우·수익화)은 prd이며, 바탕이 되는 시스템 알림은 알림에 있다.
기술 접근 · 아키텍처¶
알림 채널·유형¶
채널은 시스템 내 웹 알림과 카카오 알림톡 두 가지를 함께 쓴다. 자동 발송은 기존 알림 이벤트가 일어날 때 웹과 함께(선생님이 켜 뒀다면) 카카오를 동시에 내보내며, 시스템이 정한 문구라 고칠 수 없다. 수동 발송은 선생님이 스터디룸에서 직접 쓰는 커스텀 메시지로, 자유 입력에 템플릿·치환 변수를 더해 학생·보호자에게 개별·일괄로 보낸다.
발송 플로우¶
발송은 한 번에 나가지 않고 몇 단계의 확인을 거친다. 이벤트가 발생하면 수신자가 있는지, 그 사람이 해당 채널·유형 알림을 켜 뒀는지, 카카오로 받을 수 있는지를 차례로 확인하고, 모두 통과해야 발송한다. 실패하면 사유를 로그로 남긴다.
NHN Cloud 알림톡 연동¶
발송은 NHN Cloud Alimtalk API(POST /alimtalk/v2.3/appkeys/{appKey}/messages)로 호출. 코드는 templateCode + templateParameter(변수값)만 전달하고, 템플릿 본문은 NHN Cloud 콘솔에 등록·심사되어야 발송된다.
구현 구성 (신규 14 / 수정 3):
- 핵심 클래스: NhnKakaoAlimtalkClient(WebClient), KakaoAlimtalkService(중복방지·상태관리), KakaoAlimtalkNotificationEventHandler(이벤트 핸들러), KakaoWebhookController(Webhook 수신).
- 도메인 이벤트: HomeworkEvents(Created/Submitted) 등 — HomeworkService.createHomework/submitHomework에 이벤트 발행 추가.
- 발송 이력: KakaoNotificationLog(도메인) + KakaoNotificationLogEntity(JPA) + Adapter/Repository, Flyway V21__create_kakao_notification_log.sql.
- SecurityConfig에 /webhook/** 인증 제외.
API · 데이터 모델¶
템플릿 (7개)¶
알림톡은 우리가 본문을 보내는 게 아니라, NHN 콘솔에 등록·심사된 템플릿을 templateCode로 지정하고 변수값만 채워 보내는 방식이다. 그래서 트리거 7종마다 템플릿을 하나씩 만들어 뒀다.
| templateCode | 수신 | 변수 |
|---|---|---|
TEACHING_NOTE_CREATED |
학생 | teacherName |
QNA_QUESTION_CREATED |
선생님 | studentName |
QNA_ANSWER_ADDED |
학생 | teacherName |
HOMEWORK_CREATED |
학생 | teacherName, title |
HOMEWORK_SUBMITTED |
선생님 | studentName |
INQUIRY_CREATED |
선생님 | inquirerName |
INQUIRY_ANSWERED |
학생/보호자 | teacherName |
코드 변수명(Map.of(...))과 콘솔 본문 #{변수명}·변수 개수가 정확히 일치해야 한다. 불일치 시 NHN resultCode != 0 → FAILED 기록. 재발송(resend)은 SMS 폴백 지원.
notification_log 핵심 컬럼¶
request_id(NHN requestId), recipient_no(마스킹 저장 고려), template_code, event_type, reference_id, status(PENDING/SENT/DELIVERED/FAILED), fail_reason, retry_count.
의존성 · 영향 범위¶
자격증명(nhn.kakao.*의 앱 키·시크릿·발신 키)은 환경변수로 주입하고 값은 시크릿 저장소에만 둔다(로컬 기본값은 not-configured). 알림톡 버튼을 누르면 이벤트 유형별로 정한 주소로 이동하는데, 비로그인이면 from 쿼리로 원래 목적지를 보존한 채 로그인을 거친다 — 케이스 목록은 알림과 같은 패턴이다.
작업 초기에는 NCP SENS 알림톡도 검토했지만 최종 구현은 NHN Cloud로 정했다. 관리자용 발송 현황·선생님별 사용량·실패 로그·비용 추적은 추후 확장으로 남겨 뒀다.
테스트 계획¶
가장 잘 깨지는 지점이 템플릿 변수 불일치라, 변수가 콘솔 템플릿과 정확히 맞아 resultCode=0이 나오는지를 먼저 본다. 그 밖에 자동 발송이 트리거 이벤트와 잘 연동되는지, 수동 발송의 대상·치환이 정확한지, 실패 시 FAILED·사유가 기록되고 SMS로 폴백되는지, Webhook으로 전달 상태(DELIVERED)를 받는지, 중복 발송이 막히는지를 확인한다.
작업 분해 (이슈 링크)¶
크게 NHN 클라이언트·서비스·이벤트 핸들러·Webhook 컨트롤러, 각 기능의 도메인 이벤트 발행, 발송 이력(notification_log) 도메인·JPA·마이그레이션, Webhook 인증 예외, 그리고 수동 발송 API·미리보기 연동으로 나뉜다. 학생별 학습 리포트를 자동 생성해 보호자에게 카카오로 보내기, AI 메시지 초안 추천, 예약·반복(주간/월간) 발송은 후속 확장 후보다.