개발일지 (2026-07-16)

개요

학원 알림 템플릿 관리 시스템 구축, 카카오 알림톡 연동, 수강권 상태 복원 버그 수정, 예약 오픈일수 적용 등을 진행했다.

---

수정/생성 파일 목록

백엔드 (piano-backend)

• migration-20260715d-notification-templates.sql (신규) — 학원 알림 템플릿 테이블 + 기본 시드 7종
• NotificationTemplate.java (신규) — 알림 템플릿 엔티티
• NotificationTemplateMapper.java/xml (신규) — 학원 커스텀 우선 COALESCE 조회 + UPSERT
• NotificationTemplateController.java (신규) — 목록/자동발송토글/저장 API
• AcademyNotificationSender.java (신규) — 자동 알림 발송기 (SMS + 카카오 알림톡 + SMS 폴백)
• StudentBookingService.java (수정) — 예약 확정 시 LESSON_CONFIRM 자동 알림 발송, 오픈일수 API
• StudentBookingController.java (수정) — /open-days 엔드포인트 추가
• StudentTicketService.java (수정) — DEPLETED 상태에서 취소 시 복원 허용
• PpurioService.java (수정) — [*N*] 형식 변수 치환 추가
• NotificationTemplateMapper.xml (수정) — kakao_template_code 컬럼 SELECT/UPSERT 추가

프론트 — 학원 앱 (academy)

• api/notificationTemplates.ts (신규) — 알림 템플릿 API 클라이언트
• pages/NotificationTemplates.tsx (신규) — 알림 관리 페이지 (규칙 테이블 + 템플릿 편집기 + 미리보기)
• App.tsx (수정) — /notification-templates 라우트 추가

프론트 — 학생 앱 (student)

• api/booking.ts (수정) — getOpenDays API 추가
• pages/LessonBookingPage.tsx (수정) — 오픈일수 maxDate 적용, ticketExpiresAt 선언 순서 버그 수정
• pages/DashboardPage.tsx (수정) — "피아노" 하드코딩 제거
• pages/MyPage.tsx (수정) — "피아노" 하드코딩 제거
• pages/LoginPage.tsx (수정) — 슬로건 "음악과 함께 성장하는 특별한 시간"으로 변경

---

파일별 상세

1. 학원 알림 템플릿 관리

학원별 자동 알림을 관리하는 시스템을 구축했다.

DB 구조:

• academy_notification_templates 테이블: academy_id=0은 기본값, 학원별 UPSERT로 커스텀
• 7개 알림 유형: 레슨 확정, 리마인더, 수강권 만료, 결제 완료, 환불 완료, 상담 예약, 체험 레슨
• kakao_template_code 컬럼으로 뿌리오 카카오 알림톡 키 저장

발송기 (AcademyNotificationSender):

• 이벤트 발생 → 템플릿 조회(학원 커스텀 우선) → auto_send 확인 → 변수 치환 → 발송
• 카카오 키가 있으면 알림톡 발송, 실패 시 SMS 폴백
• 발송 성패와 무관하게 도메인 트랜잭션은 정상 커밋 (예외 흡수)

2. 카카오 알림톡 연동

뿌리오 카카오 알림톡 API와 연동했다. 변수 형식은 카카오 심사 규격에 맞춰 [*N*] / [*이름*] 형태를 사용한다.

3. 수강권 DEPLETED 복원 버그 수정

예약 3회 → 2회 취소 시 횟수는 복원되지만 status가 DEPLETED로 남는 버그.

• 원인: restore()에서 ACTIVE만 복원 허용 → DEPLETED는 차단됨
• 수정: DEPLETED도 복원 허용. incrementSession SQL이 자동으로 DEPLETED→ACTIVE 전환.

4. 예약 오픈일수 학생 앱 적용

학원 설정의 bookingOpenDays를 학생 앱 달력에 반영. 수강권 만료일과 오픈일수 중 빠른 날짜를 maxDate로 적용.

---

트러블슈팅 메모

• ticketExpiresAt 선언 전 참조: maxDateStr 계산에서 ticketExpiresAt를 사용하는데, 선언이 아래에 있어서 런타임 에러 → 선언 뒤로 이동
• 카카오 알림톡 반려: {1} 형식 → #{변수내용} 형식으로 바꿔야 함. 수신자 액션("신청하신", "예약하신") 명시 필요
• 알림 관리 페이지 배포 누락: tar가 제대로 안 올라가서 이전 번들이 서빙됨 → 번들 해시 확인 필수

---

결론 / 배운 점

• 알림 발송은 도메인과 분리해야 한다. 알림 실패로 예약/결제가 롤백되면 안 된다. 예외를 흡수하고 이력만 남기는 패턴이 안전하다.
• 카카오 알림톡 심사는 까다롭다. 변수 형식([*N*]), 수신자 액션 명시, 광고성 문구 제한 등 규격을 미리 파악해야 한다.
• DEPLETED 상태 전환은 양방향이어야 한다. 차감 시 ACTIVE→DEPLETED는 되는데 복원 시 역방향이 안 되면 데이터 불일치가 생긴다.