Skip to content

Routine Architecture

wcorn edited this page Jun 20, 2026 · 2 revisions

시스템 아키텍처: Routine (반복 루틴 / 고정 일정)

범위: 통합 루틴(체크형 습관 + 시간 고정 일정)을 Google Calendar 반복 이벤트(RRULE)로 생성·편집·삭제하고, 습관 완료 체크만 orino 오버레이로 저장. Planner(Google 연동) 위에 올라간다.

상태: ✅ 구현 완료 — R0R5 (2026-06). 관련 PR: #589#597 (BE #589/#590/#591/#592/#593, FE #594/#595/#596/#597). 핵심 가치: 단일 사용자 / 유지보수 최소화 / 장기 운영 → "단순한 쪽"을 택하고, Planner의 BFF·라이브 프록시 자산을 최대한 재사용한다. 결정 근거는 결정 기록 참고.

1. 전체 구조 (Planner 확장)

┌──────────────┐    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 (습관 완료 오버레이). 이벤트/반복 미러는 만들지 않는다.

2. 백엔드 패키지 구조

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/...

3. 루틴 = 태그된 Google 반복 이벤트

루틴을 일반 일정과 구분하기 위해 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).

4. RRULE 작성: RecurrenceRuleFactory

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 예외 메커니즘 사용).

5. 시리즈 편집/삭제: 3가지 scope

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 조회로 확보한다.

6. 통합 피드 주석 (체크 상태 합류)

신규 캘린더 조회 엔드포인트를 만들지 않는다. 기존 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.

7. 습관 완료 오버레이: routine_check

항목 결정
저장 단위 (memberId, recurringEventId, instance_date) 1행 = 그날 완료
체크 행 upsert
해제 행 delete (존재 = 완료, 부재 = 미완료)
키 recurringEventId(시리즈 안정 키) + instance_date(사용자 로컬 날짜)
  • 시간 고정 일정은 이 테이블을 쓰지 않는다(체크 개념 없음).
  • 'following' 분할로 recurringEventId가 새로 생기면, 과거 체크는 옛 id, 분할 이후는 새 id로 자연 분리된다(데이터 손실 없음).
  • 상세 스키마는 데이터 모델.

8. 보안 / 실패 처리

Planner와 동일 인프라·정책을 상속한다.

상황 처리
미연동 루틴 쓰기 409 (PLN-ERR-003 재사용)
access 만료 refresh 1회 자동 재시도
invalid_grant revoked 마킹 → 재연동
Google 502/429 짧은 백오프 후 실패 토스트, FE 낙관적 갱신 롤백
following 분할 중단 멱등 재시도. ①UNTIL patch 성공 후 ②insert 실패 시 재시도로 보정(중복 방지 키 점검)

9. 명시적 비목표 (아키텍처)

  • 로컬 이벤트/반복 미러 테이블 (Planner와 동일 — 만들지 않음. 오버레이는 routine_check 하나뿐)
  • 자동 스케줄링 엔진 / 배치 서비스 (SP-V5-004, 여전히 백로그)
  • 루틴 알림/푸시, 스트릭/히트맵 집계
  • BYSETPOS·EXDATE 직접 작성 등 고급 RRULE
  • 루틴의 Google Tasks 생성 (Calendar 이벤트로 확정)

Clone this wiki locally