Merge pull request #257 from depromeet/feature/talk-calendar-reminder

[Feat] 톡캘린더 일정에 시작 5분 전 알림 추가

Author: lydbsdud

docs/superpowers/specs/2026-08-18-kakao-talk-calendar-design.md

@@ -337,6 +337,7 @@ JWT 서명 키를 재사용하지 않는 이유는 수명주기가 묶이기 때
 | 종료 | `startedAt` + 30분 |
 | 타임존 | `Asia/Seoul`. 카카오에 넘기는 시각은 UTC RFC5545 형식 |
 | 설명 | `초대 링크: {URL}` 한 줄. URL 은 `PartyInviteService.findLatestUsableInviteToken` 의 토큰과 `app.web-base-url` 을 조합. 사용 가능한 초대가 없으면 빈 문자열 |
+| 미리 알림 | 시작 5분 전 하나. 카카오는 `0(시작 시각) < 값 ≤ 43200` 만 받으므로 시작 시각 알림은 지정할 수 없다 |
 
 파티 엔티티의 `endedAt()`은 롤링페이퍼 열람 기한인 7일 뒤라 캘린더 일정 종료 시각으로 쓰지 않는다.
 

src/main/kotlin/com/team2/server/calendar/domain/policy/PartyCalendarEventPolicy.kt

@@ -10,6 +10,14 @@ object PartyCalendarEventPolicy {
     /** 카카오 톡캘린더 일정 제목 제한. */
     const val MAX_TITLE_LENGTH = 50
 
+    /**
+     * 미리 알림 시점(분).
+     *
+     * 카카오는 `0 < 값 ≤ 43200` 만 받으므로 시작 시각 알림(0)은 지정할 수 없다.
+     * 파티가 [DURATION_MINUTES] 분짜리라 한 번이면 충분하다.
+     */
+    const val REMINDER_MINUTES_BEFORE = 5
+
     fun compose(
         kind: CelebrationKind,
         celebrantName: String?,
@@ -21,6 +29,7 @@ object PartyCalendarEventPolicy {
             startAt = startedAt,
             endAt = startedAt.plusMinutes(DURATION_MINUTES),
             description = inviteUrl?.let { "초대 링크: $it" } ?: "",
+            reminderMinutes = listOf(REMINDER_MINUTES_BEFORE),
         )
 
     private fun composeTitle(

src/main/kotlin/com/team2/server/calendar/domain/vo/CalendarEvent.kt

@@ -2,9 +2,32 @@ package com.team2.server.calendar.domain.vo
 
 import java.time.LocalDateTime
 
+private const val REMINDER_MIN_MINUTES = 5
+private const val REMINDER_MAX_MINUTES = 43_200
+private const val REMINDER_INTERVAL_MINUTES = 5
+private const val REMINDER_MAX_COUNT = 2
+
 data class CalendarEvent(
     val title: String,
     val startAt: LocalDateTime,
     val endAt: LocalDateTime,
     val description: String,
-)
+    /** 미리 알림 시점(분). 카카오는 5분 간격으로 최대 2개까지 받는다. */
+    val reminderMinutes: List<Int>,
+) {
+    /**
+     * 카카오 제약을 여기서 막는다. 통과시키면 일정 생성 요청이 400 으로 거부되는데,
+     * 어댑터가 그것을 `KAKAO_CALENDAR_UNAVAILABLE` 로 바꿔 카카오 장애처럼 보이게 된다.
+     */
+    init {
+        require(reminderMinutes.size <= REMINDER_MAX_COUNT) {
+            "미리 알림은 최대 ${REMINDER_MAX_COUNT}개다 (현재 ${reminderMinutes.size}개)"
+        }
+        require(reminderMinutes.all { it in REMINDER_MIN_MINUTES..REMINDER_MAX_MINUTES }) {
+            "미리 알림은 $REMINDER_MIN_MINUTES~$REMINDER_MAX_MINUTES 분이어야 한다 (현재 $reminderMinutes)"
+        }
+        require(reminderMinutes.all { it % REMINDER_INTERVAL_MINUTES == 0 }) {
+            "미리 알림은 ${REMINDER_INTERVAL_MINUTES}분 간격이어야 한다 (현재 $reminderMinutes)"
+        }
+    }
+}

src/main/kotlin/com/team2/server/calendar/infrastructure/kakao/KakaoTalkCalendarAdapter.kt

@@ -118,6 +118,7 @@ class KakaoTalkCalendarAdapter(
                         "all_day" to false,
                     ),
                 "description" to event.description,
+                "reminders" to event.reminderMinutes,
             ),
         )
 

src/test/kotlin/com/team2/server/calendar/domain/policy/PartyCalendarEventPolicyTest.kt

@@ -1,9 +1,11 @@
 package com.team2.server.calendar.domain.policy
 
+import com.team2.server.calendar.domain.vo.CalendarEvent
 import com.team2.server.calendar.domain.vo.CelebrationKind
 import org.junit.jupiter.api.Test
 import java.time.LocalDateTime
 import kotlin.test.assertEquals
+import kotlin.test.assertFailsWith
 import kotlin.test.assertFalse
 import kotlin.test.assertTrue
 
@@ -118,4 +120,35 @@ class PartyCalendarEventPolicyTest {
 
         assertEquals("", event.description)
     }
+
+    @Test
+    fun `미리 알림은 시작 5분 전 하나다`() {
+        // 카카오는 0(시작 시각) 을 허용하지 않으므로 시작 시각 알림은 지정할 수 없다.
+        val event =
+            PartyCalendarEventPolicy.compose(
+                kind = CelebrationKind.BIRTHDAY,
+                celebrantName = "지민",
+                startedAt = LocalDateTime.of(2026, 8, 20, 19, 0),
+                inviteUrl = null,
+            )
+
+        assertEquals(listOf(5), event.reminderMinutes)
+    }
+
+    @Test
+    fun `카카오 제약을 벗어난 미리 알림은 일정을 만들 수 없다`() {
+        val rejected = listOf(listOf(0), listOf(3), listOf(43205), listOf(-5), listOf(5, 10, 15))
+
+        for (reminders in rejected) {
+            assertFailsWith<IllegalArgumentException>(message = "$reminders") {
+                CalendarEvent(
+                    title = "제목",
+                    startAt = startedAt,
+                    endAt = startedAt.plusMinutes(30),
+                    description = "",
+                    reminderMinutes = reminders,
+                )
+            }
+        }
+    }
 }

src/test/kotlin/com/team2/server/calendar/infrastructure/kakao/KakaoTalkCalendarAdapterTest.kt

@@ -42,6 +42,7 @@ class KakaoTalkCalendarAdapterTest {
             startAt = LocalDateTime.of(2026, 8, 20, 19, 0),
             endAt = LocalDateTime.of(2026, 8, 20, 19, 30),
             description = "초대 링크: https://example.com/invite/abc",
+            reminderMinutes = listOf(5),
         )
 
     @Test
@@ -54,6 +55,7 @@ class KakaoTalkCalendarAdapterTest {
             .andExpect(content().string(org.hamcrest.Matchers.containsString("calendar_id=primary")))
             .andExpect(content().string(org.hamcrest.Matchers.containsString("2026-08-20T10%3A00%3A00Z")))
             .andExpect(content().string(org.hamcrest.Matchers.containsString("2026-08-20T10%3A30%3A00Z")))
+            .andExpect(content().string(org.hamcrest.Matchers.containsString("%22reminders%22%3A%5B5%5D")))
             .andRespond(withSuccess("""{"event_id":"event-1"}""", MediaType.APPLICATION_JSON))
 
         val eventId = adapter.createEvent("kakao-token", event)