Skip to content

Review Calendar Mirror

wcorn edited this page Jul 24, 2026 · 3 revisions

복습 → Google Calendar 단방향 미러링

상태: 구현 완료 (2026-06-27). RM0~RM4 머지 — 스키마·클라이언트 확장(#614) · reconcileDate+훅(#617) · 토글 API+백필(#618) · FE 토글 UI(#621) · 엣지 테스트(#624). Planner 모듈의 하위 기능. Planner 결정 기록 §4.2에서 "후속"으로 미뤘던 "복습 → Google 내보내기"를 활성화한다. 요약: orino 복습 일정을 보조 캘린더 "orino 복습" 에 종일 이벤트로 push해 휴대폰·워치 등 어디서나 보이고 Google 알림을 받는다. 순수 단방향(orino=진실, Google=투영). 하루치 복습을 dueDate당 1개 "복습 N개" 묶음 이벤트로 미러한다.

구현 노트 (설계 대비 차이): ① Liquibase는 026-add-google-account-review-mirror(컬럼 2개) + 027-create-review-calendar-mirror(테이블). ② 묶음 이벤트 설명(description)은 자료 제목별 개수("수학: 2개")만 담고, 링크는 데이터 모델에 URL 필드가 없어 제외(차기). ③ 미러 reconcile은 복습 생성/완료 트랜잭션 커밋 후(afterCommit + REQUIRES_NEW)에 실행해 Google 장애가 복습 자체를 롤백하지 않는다. 토글 enable은 활성화 커밋을 백필보다 먼저 끝내 reconcile이 enabled 상태를 보게 한다.

1. 배경 / 동기

현재 일정(events)·할 일(tasks)은 Google이 source of truth라 휴대폰 구글앱에 보이지만, 복습만 orino DB(review_schedule)에 갇혀 통합 피드 읽기 전용 오버레이로만 표시된다. 복습도 "시간이 박힌 공부 약속"이므로 events·tasks처럼 Google에 띄워 모델을 일치시키고, 공짜 Google 알림을 얻는다.

2. 사전 검증 (코드 기준)

항목 확인
OAuth 스코프 application.yml = auth/calendar(풀) + auth/tasks. 보조 캘린더 생성(calendars.insert) 가능, 재동의 불필요
최소권한 calendar.app.created로 좁히면 오히려 재동의 필요 → 현 풀 권한 유지가 재동의 회피에 유리
복습 생애주기 완료 시 다음 일정이 새 레코드로 생성. AGAIN=+10분 당일 churn(RELEARN_MINUTES), 그 외=로컬 +interval일 04:00 롤오버(ROLLOVER_HOUR)
GoogleCalendarClient 현재 /calendars/primary/events 하드코딩 — calendarId 파라미터화 + calendars.insert + 종일(date)·reminders 확장 필요
배치 인프라 orino-app-batch+ShedLock은 SP-V5-009로 보류 → 미러는 이벤트 기반으로(배치 0)

3. 핵심 설계 결정 (사용자 합의)

# 결정 이유
캘린더 보조 "orino 복습" 캘린더 (기본 캘린더 안 씀) 기본 캘린더 안 더럽힘, 토글=캘린더/이벤트 정리, 색 그룹 공짜
묶음 dueDate당 종일 이벤트 1개 "복습 N개" 카드별이면 도배(하루 20장=20개). 묶음=깔끔·1회 쓰기·쿼터 절약. 매핑 = dueDate↔eventId
형태 종일(all-day) 복습은 "그날 할 일"이지 04:00 약속이 아님. 종일 알림(아침)으로 푸시
트리거 이벤트 기반 reconcileDate(즉시) 배치 인프라 보류 회피. 복습 생성/완료 시 영향 날짜만 재계산
AGAIN 미러 제외 +10분 재학습은 약속 아님·도배. 04:00 롤오버 건만 미러
완료 남은 개수 반영 → 0이면 이벤트·행 삭제 캘린더=앞으로 할 일. 완료 이력은 orino가 진실
방향 순수 단방향(orino→Google) 양방향 충돌 로직 불필요. reconcile가 self-heal
토글 설정 on/off 제공 ON=캘린더 생성+백필, OFF=이벤트·행 정리
알림 v1 useDefault(구글 기본 상속) 단순. 커스텀 시각은 차기

4. 아키텍처

flashcard 생성 / 복습 완료
        │  (다음 일정 = 새 review_schedule row)
        ▼
ReviewMirrorService.reconcileDate(memberId, dueDate, zone)   ← 이벤트 기반, 멱등
        │  ① 그날 PENDING 복습 수 N 집계(04:00 롤오버 건만, AGAIN 제외)
        │  ② N>0 → 보조 캘린더에 종일 "복습 N개" 이벤트 upsert + review_calendar_mirror upsert
        │  ② N=0 → Google 이벤트 delete + mirror row delete
        ▼
[보조 캘린더 "orino 복습"] ──(Google)──▶ 휴대폰/워치/구글앱 + 알림
  • orino=진실, Google=투영. orino 내부 화면은 기존 복습 오버레이를 그대로 쓴다(미러와 무관).
  • 이중 표시 없음: orino 통합 피드는 calendars/primary/events만 읽으므로, 보조 캘린더의 미러 이벤트는 orino 안에서 다시 안 보인다. 미러는 외부(폰/워치) 전용.
  • 신규 외부 의존성 0, 신규 인증/스코프 0. planner/google 패키지에 미러 서비스만 추가.

4.1 reconcileDate 로직 (멱등·self-heal)

  1. N = review_schedule 중 member_id & status=PENDING & scheduledAt의 로컬 날짜 == dueDate & 04:00 롤오버 건(AGAIN +10분 제외).
  2. N > 0:
    • mirror row 있으면 해당 google_event_id patch(제목 "복습 N개", 종일 dueDate), 없으면 보조 캘린더에 insert 후 row 생성.
    • Google이 404(사용자가 지움)면 재생성 → 단방향 self-heal.
    • row의 pending_count=N, synced_at 갱신.
  3. N == 0: row 있으면 Google delete + row delete.
  • 트리거 지점:
    • flashcard 생성(첫 복습) → reconcileDate(firstReviewDate)
    • 복습 완료 → 완료된 건의 날짜 + 새로 생성된 다음 복습의 날짜, 두 날짜 reconcile
    • 백필(토글 ON) → PENDING 있는 모든 날짜 reconcile
  • 멱등: 항상 DB 진실에서 재계산 → 중복 호출·부분 실패에 안전.
  • AGAIN 판별: 코드상 AGAIN은 now+10분(분 단위), 정상 건은 04:00. → "scheduledAt 로컬 시각 == 04:00"으로 깔끔히 구분(매직넘버 ROLLOVER_HOUR 일관).
  • 오버듀: 지난 PENDING은 원래 dueDate 묶음에 그대로 둔다(캘린더엔 놓친 날 표시). orino "오늘 복습"은 기존대로 동적 합류 — 미러와 독립.

5. 데이터 모델

상세 컬럼·Liquibase 관례는 Planner 데이터 모델에 합류 기재.

5.1 review_calendar_mirror (신규 테이블)

dueDate 묶음 ↔ Google 이벤트 매핑. 행 존재 = 그날 미러 중.

컬럼 타입 제약 설명
id BIGINT PK AI
member_id BIGINT NOT NULL, FK→member(id)
due_date DATE NOT NULL 복습 묶음 로컬 날짜
google_event_id VARCHAR(255) NOT NULL 보조 캘린더 이벤트 id
pending_count INT NOT NULL 마지막 동기화 시 남은 PENDING 수
synced_at DATETIME(6) NOT NULL 마지막 동기화
created_at/updated_at DATETIME(6) NOT NULL JPA Auditing
  • UNIQUE (member_id, due_date) — 하루 1행(upsert 키).
  • 0 도달 시 행 delete. member 삭제 cascade.

5.2 google_account 컬럼 추가

컬럼 타입 설명
review_calendar_id VARCHAR(255) NULL 보조 "orino 복습" 캘린더 id(최초 ON 시 생성·저장)
review_mirror_enabled BIT(1) NOT NULL DEFAULT 0 미러 토글 상태 (BOOLEAN은 BIT(1)로 — Hibernate validate 호환)
  • OFF 시 이벤트·mirror row는 정리하되 빈 보조 캘린더는 보존(재ON 즉시).

Liquibase

  • 0NN-create-review-calendar-mirror.yaml + 0NN-add-google-account-review-mirror.yaml(컬럼 2개) — Planner 최신 changelog 다음 번호. tableExists/columnExists 가드, member(id) FK, DATETIME(6).

6. API

Base /api. 인증·에러·시간대(X-Timezone) 규약은 Planner API 상속.

Method Path 설명
PUT /api/planner/reviews/mirror 미러 토글 { "enabled": true|false }
GET /api/integrations/google/status (확장) reviewMirrorEnabled 필드 추가
  • PUT enable=true: review_calendar_id 없으면 calendars.insert로 "orino 복습" 생성·저장 → 미연동 시 409 → PENDING 전 날짜 백필 reconcile → review_mirror_enabled=1.
  • PUT enable=false: 모든 mirror 이벤트 delete + row delete + review_mirror_enabled=0(캘린더는 보존).
  • 미러 동기화 자체는 별도 엔드포인트 없음 — 복습 생성/완료 서비스 내부에서 reconcileDate 호출.

Response 200 (toggle): { "code": "SUCCESS", "data": { "enabled": true, "reviewCalendarId": "..." } }. 미연동 시 409 PLN-ERR-003.

7. 화면

Planner UI 설정 화면(/integrations) 또는 Google 연결 카드에 토글 추가.

┌─ Google 연동 ──────────────────────────┐
│  연결됨 · me@gmail.com      [연결 해제]  │
│  ───────────────────────────────────── │
│  복습을 Google 캘린더에 표시      [ ●ON ]│
│  보조 캘린더 "orino 복습"에 단방향으로    │
│  띄웁니다. 폰·워치에서도 보이고 알림을    │
│  받습니다. (orino가 원본)                │
└──────────────────────────────────────────┘
  • 토글 ON → 백필 진행 스피너 → "켜짐". 미연동이면 [Google 연결] 선행.
  • 단방향임을 안내(구글에서 수정해도 orino 기준으로 갱신됨).

8. 비목표

  • 양방향 동기화 / Google 측 편집 반영 (순수 단방향 확정)
  • 카드별 개별 이벤트(도배), 완료 이력을 캘린더에 영구 보존
  • 사용자 지정 알림 시각·커스텀 reminder (v1 useDefault)
  • AGAIN 당일 재학습 미러
  • 배치 동기화 서비스(SP-V5-009 보류) — 이벤트 기반으로 충분
  • 미러 이벤트를 orino 통합 피드에 재표시(보조 캘린더는 외부 전용)

Clone this wiki locally