notification 모듈

책임: SMS/이메일/카카오 알림톡 발송, 알림 템플릿 관리, 다른 모듈에서 발생한 이벤트를 알림으로 변환.

의존 관계:

• 사용 주체: 거의 모든 모듈 (identity, learning, assessment, commerce) 이 이벤트 발생 시 이 모듈을 호출
• 외부 서비스: SMS 게이트웨이 (예: NHN Toast / Aligo / Coolsms), 이메일 (SES / SendGrid), 카카오 알림톡 (비즈메시지)

관련 DB 테이블:

• sms_content — SMS 템플릿 (제목/본문)
• sms_send — 발송 로그 (수신번호/시간/상태/응답)

특이사항: 이 모듈은 프론트에서 직접 호출하지 않음. 다른 모듈의 사이드이펙트로 호출됨. 따라서 UI 가 없어도 API 구현이 가능하고, 오히려 다른 모듈 구현과 함께 자연스럽게 등장함.

예상 API 엔드포인트

이벤트 기반 알림 (권장 방식)

POST /api/notification/events

도메인 이벤트를 받아서 적절한 알림 템플릿을 선택해 발송.

• Auth: 내부 서비스 토큰 (외부 노출 금지)
• Body:

  {
    eventType:
      | 'member.registered'
      | 'member.password_changed'
      | 'payment.completed'
      | 'payment.failed'
      | 'enrollment.activated'
      | 'exam.passed'
      | 'exam.all_completed'
      | 'certificate.issued'
      | 'certificate.shipped'
      | 'level_test.submitted'
      | 'consultation.requested';
    memberId?: number;
    payload: Record<string, unknown>;
  }
  

• 처리:
  1. eventType 에 매핑된 템플릿 조회 (sms_content 또는 상수)
  2. memberId 로 수신자 정보 조회 (hp, email)
  3. 사용자 알림 수신 동의 확인
  4. 실제 발송 (내부적으로 POST /api/notification/sms/send 등)
  5. sms_send 에 발송 이력 기록
• Response: { dispatched: Array<{ channel: 'sms'|'email'|'kakao'; to: string; ok: boolean }> }

이벤트 기반 방식의 장점:

• 호출하는 쪽은 "결제 완료됐어" 만 알려주면 됨
• 채널 선택 로직이 한 곳에 집중
• A/B 테스트, 채널 변경이 쉬움

직접 발송 API (내부 호출용)

POST /api/notification/sms/send

• Auth: 내부 서비스 토큰
• Body:

  {
    to: string;           // 전화번호
    templateCode?: string;  // sms_content.code
    body?: string;          // templateCode 없을 때 직접 본문
    variables?: Record<string, string>;  // 템플릿 치환 변수
  }
  

• Response: { messageId: string; status: 'queued' | 'sent' | 'failed' }
• 사이드이펙트: sms_send INSERT

POST /api/notification/email/send

• Body:

  {
    to: string;
    subject: string;
    bodyHtml?: string;
    bodyText?: string;
    templateCode?: string;
    variables?: Record<string, string>;
  }
  

POST /api/notification/kakao/send

카카오 알림톡 (비즈니스 메시지). 템플릿 사전 등록 필수.

• Body:

  {
    to: string;           // 전화번호
    templateCode: string; // 카카오에 사전 등록된 템플릿 ID
    variables: Record<string, string>;
  }
  

템플릿 관리 (관리자)

GET /api/notification/admin/templates

SMS/이메일 템플릿 목록.

• Auth: admin
• Response: sms_content 행 목록

POST /api/notification/admin/templates

템플릿 생성/수정.

POST /api/notification/admin/test-send

테스트 발송 (관리자가 자기 번호로 템플릿 미리보기).

발송 로그 조회

GET /api/notification/admin/logs

• Auth: admin
• Query: ?channel=sms&status=failed&from=...&to=...
• Response: sms_send 행 목록 + 실패 사유
• 용도: 결제 완료됐는데 SMS 실패한 케이스 등 수동 개입 모니터링

⚠️ 구현 시 주의사항

1. 직접 호출 vs 큐 기반

• MVP: 이벤트 수신 시 동기 발송 (단순하지만 장애 시 손실 위험)
• 정석: 이벤트를 큐 (Redis / DB queue) 에 쌓고 워커가 처리 → 재시도 가능
• 결제 완료 같이 놓치면 안 되는 이벤트 는 반드시 큐 기반 권장

2. 수신 동의 관리

• member 테이블에 sms_consent, email_consent, marketing_consent 플래그 필요 (현재 없음 — 나중에 추가)
• 법적 요구사항: 광고성 알림은 명시적 동의 필수, 거래성 알림 (결제/수강 확인 등) 은 동의 없이 가능

3. 발송량/비용

• SMS 는 건당 비용 (10~30원). 중복 발송 dedup 필수.
• 이메일은 무료에 가깝지만 bounce 관리 필요 (SES reputation)

4. 실패 재시도

• SMS 게이트웨이가 5xx 반환 시 exponential backoff 로 최대 3회 재시도
• 3회 실패 시 관리자 알림 큐에 넣기

5. 민감정보 로깅

• sms_send.content 에 OTP / 임시 비밀번호 등을 평문 저장 금지
• 최소 마스킹 or 해시 저장

이벤트 → 알림 매핑 예시 (참고)