Repository navigation
Routine Architecture
범위: 통합 루틴(체크형 습관 + 시간 고정 일정)을 Google Calendar 반복 이벤트(RRULE)로 생성·편집·삭제하고, 습관 완료 체크만 orino 오버레이로 저장. Planner(Google 연동) 위에 올라간다.
상태: ✅ 구현 완료 — R0
R5 (2026-06). 관련 PR: #589#597 (BE #589/#590/#591/#592/#593, FE #594/#595/#596/#597). 핵심 가치: 단일 사용자 / 유지보수 최소화 / 장기 운영 → "단순한 쪽"을 택하고, Planner의 BFF·라이브 프록시 자산을 최대한 재사용한다. 결정 근거는 결정 기록 참고.
┌──────────────┐ JWT ┌────────────────────────────────┐ REST ┌──────────────┐
│ Frontend │──────────▶│ orino BE │───────▶│ Google │
│ 루틴 생성/관리 │◀──────────│ (Planner BFF 프록시 재사용) │◀───────│ Calendar │
│ 습관 체크 UI │ │ │ └──────────────┘
└──────────────┘ │ ┌──────────────────────────┐ │
│ │ RecurrenceRuleFactory │ │ 반복 이벤트(RRULE+extProps)
│ │ (규칙→RRULE 문자열) │ │
│ ├──────────────────────────┤ │ refresh ┌─────────┐
│ │ GoogleCalendarClient(확장)│ │───────────▶│ MySQL │
│ │ recurrence·instances │ │ google_account│ routine_check │
│ ├──────────────────────────┤ │ └─────────┘
│ │ RoutineCheckService │ │ access ┌─────────┐
│ │ (습관 완료 오버레이) │ │───────────▶│ Redis │
│ └──────────────────────────┘ │ └─────────┘
└────────────────────────────────┘
- 루틴 = Google Calendar 반복 이벤트. Google이 일정/반복의 source of truth. orino는 RRULE을 작성하고 시리즈 편집을 오케스트레이션한다.
- Planner의
GoogleTokenProvider,RestClient, OAuth, 캐시 무효화, 통합 피드를 그대로 재사용한다. 신규 외부 의존성·신규 인증 모델 없음. -
유일한 신규 영속 테이블은
routine_check(습관 완료 오버레이). 이벤트/반복 미러는 만들지 않는다.
BE 코드 아키텍처를 따른다. 대부분 Planner planner/google 하위에 추가한다.
orino-domain-rdb (ds.project.orino.domain.planner/):
planner/
├── google/ # 기존 (google_account)
└── routine/ # 신규
├── entity/RoutineCheck.java
└── repository/RoutineCheckRepository.java
orino-app-api (ds.project.orino.planner/):
planner/
└── google/
├── recurrence/ # 신규: RRULE 작성
│ ├── RecurrenceRule.java (VO: freq/interval/byDay/byMonthDay/until)
│ └── RecurrenceRuleFactory.java (VO → RRULE 문자열 / 역파싱)
├── client/GoogleCalendarClient # 확장: recurrence, instances, extendedProperties
└── routine/ # 신규
├── RoutineController.java (생성/목록/수정/삭제/체크)
├── RoutineService.java (시리즈 편집 오케스트레이션)
├── RoutineCheckService.java (습관 완료 오버레이)
└── dto/...
루틴을 일반 일정과 구분하기 위해 Google 이벤트의 extendedProperties.private에 태그를 박는다.
| 키 | 값 | 용도 |
|---|---|---|
orinoRoutine |
"1" |
루틴 식별 sentinel. events.list?privateExtendedProperty=orinoRoutine=1로 루틴만 필터 |
orinoRoutineType |
"habit" | "schedule"
|
체크형/일정형 구분 |
-
습관(habit): 종일 이벤트(
start.date/end.date) + 태그. → 통합 피드에서 체크 가능 항목으로 렌더. -
일정(schedule): 시간 이벤트(
start.dateTime/end.dateTime) + 태그. → 시간 블록으로 렌더, 체크 없음. - 통합 피드(
GET /planner/calendar)는 이미singleEvents=true로 인스턴스를 펼친다. BE는 펼쳐진 각 인스턴스에서 태그를 읽어routine메타를 주석으로 덧붙인다(아래 §6).
Planner는 RRULE을 읽기만(구글이 펼침) 했지만, Routine은 RRULE을 써야 한다. 의존성 없이 문자열로 직접 만든다.
| 패턴 | RecurrenceRule | RRULE |
|---|---|---|
| 매일 | freq=DAILY | RRULE:FREQ=DAILY |
| N일 간격 | freq=DAILY, interval=N | RRULE:FREQ=DAILY;INTERVAL=N |
| 주간 요일 | freq=WEEKLY, byDay=[MO,WE,FR] | RRULE:FREQ=WEEKLY;BYDAY=MO,WE,FR |
| 매월 특정일 | freq=MONTHLY, byMonthDay=[1,15] | RRULE:FREQ=MONTHLY;BYMONTHDAY=1,15 |
| 종료일 | + until=2026-12-31 | …;UNTIL=20261231T235959Z |
-
UNTIL은 UTC 로 직렬화한다(RFC 5545). 사용자 시간대(X-Timezone)의 종료일 23:59:59를 UTC로 변환. (UTC 저장 규칙 일관) -
DTSTART는 종일이면start.date(tz 없음), 시간이면start.dateTime+ tz. - 역파싱(
parse)은 시리즈 편집/목록 표시 때 Google RRULE → RecurrenceRule로 되돌려 폼에 채우는 용도. -
1차 미지원:
BYSETPOS(마지막 주 금요일 등), 복수 RRULE, EXDATE 직접 작성(인스턴스 삭제는 Google 예외 메커니즘 사용).
scope = all | following | instance (instance/following은 instanceDate 필요).
| scope | 수정 | 삭제 |
|---|---|---|
| all (전체) | 마스터 이벤트(eventId=recurringEventId) patch
|
마스터 delete
|
| instance (이 날짜만) | 해당 인스턴스 id({recurringEventId}_{UTC타임스탬프}) patch → 예외 생성 |
인스턴스 status=cancelled patch |
| following (이후 모두) | ① 마스터 RRULE UNTIL=분할 전날 → patch ② 분할일부터 새 반복 이벤트(변경값) insert(태그 복사) |
마스터 RRULE UNTIL=분할 전날 patch |
- following 수정은 2-스텝(Google 단일 콜 없음 — Google Calendar UI와 동일 전략). 멱등·실패 복구는 결정 기록 §편집에서 명시.
- 인스턴스 id 산출: 종일은
{id}_YYYYMMDD, 시간은{id}_YYYYMMDDTHHMMSSZ. BE가 instanceDate + 시리즈 시작시각으로 계산하거나,instances조회로 확보한다.
신규 캘린더 조회 엔드포인트를 만들지 않는다. 기존 GET /planner/calendar를 확장한다.
events.list(timeMin,timeMax,singleEvents=true)
└─ 각 인스턴스: extendedProperties.orinoRoutine == "1" ?
type = orinoRoutineType
habit이면 → routine_check 조회 결과로 done 세팅
- BE는
[from,to]기간의 habit 인스턴스에 대해routine_check를 한 번에 batch 로드(memberId + instance_date BETWEEN)하여Set<(recurringEventId, date)>로 만들고 done을 매긴다(N+1 회피). - 피드 event 항목에
routine: { type, recurringEventId, done }필드 추가. 루틴 아닌 일반 이벤트는routine: null.
| 항목 | 결정 |
|---|---|
| 저장 단위 | (memberId, recurringEventId, instance_date) 1행 = 그날 완료 |
| 체크 | 행 upsert |
| 해제 | 행 delete (존재 = 완료, 부재 = 미완료) |
| 키 |
recurringEventId(시리즈 안정 키) + instance_date(사용자 로컬 날짜) |
- 시간 고정 일정은 이 테이블을 쓰지 않는다(체크 개념 없음).
- 'following' 분할로 recurringEventId가 새로 생기면, 과거 체크는 옛 id, 분할 이후는 새 id로 자연 분리된다(데이터 손실 없음).
- 상세 스키마는 데이터 모델.
Planner와 동일 인프라·정책을 상속한다.
| 상황 | 처리 |
|---|---|
| 미연동 | 루틴 쓰기 409 (PLN-ERR-003 재사용) |
| access 만료 | refresh 1회 자동 재시도 |
invalid_grant |
revoked 마킹 → 재연동 |
| Google 502/429 | 짧은 백오프 후 실패 토스트, FE 낙관적 갱신 롤백 |
| following 분할 중단 | 멱등 재시도. ①UNTIL patch 성공 후 ②insert 실패 시 재시도로 보정(중복 방지 키 점검) |
- 로컬 이벤트/반복 미러 테이블 (Planner와 동일 — 만들지 않음. 오버레이는
routine_check하나뿐) - 자동 스케줄링 엔진 / 배치 서비스 (SP-V5-004, 여전히 백로그)
- 루틴 알림/푸시, 스트릭/히트맵 집계
- BYSETPOS·EXDATE 직접 작성 등 고급 RRULE
- 루틴의 Google Tasks 생성 (Calendar 이벤트로 확정)