Repository navigation
Review Calendar Mirror
상태: 구현 완료 (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 상태를 보게 한다.
현재 일정(events)·할 일(tasks)은 Google이 source of truth라 휴대폰 구글앱에 보이지만, 복습만 orino DB(review_schedule)에 갇혀 통합 피드 읽기 전용 오버레이로만 표시된다. 복습도 "시간이 박힌 공부 약속"이므로 events·tasks처럼 Google에 띄워 모델을 일치시키고, 공짜 Google 알림을 얻는다.
| 항목 | 확인 |
|---|---|
| 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) |
| # | 결정 | 이유 |
|---|---|---|
| 캘린더 | 보조 "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(구글 기본 상속) |
단순. 커스텀 시각은 차기 |
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패키지에 미러 서비스만 추가.
-
N=review_schedule중member_id&status=PENDING&scheduledAt의 로컬 날짜 ==dueDate& 04:00 롤오버 건(AGAIN +10분 제외). -
N > 0:- mirror row 있으면 해당
google_event_idpatch(제목 "복습 N개", 종일 dueDate), 없으면 보조 캘린더에 insert 후 row 생성. - Google이 404(사용자가 지움)면 재생성 → 단방향 self-heal.
- row의
pending_count=N,synced_at갱신.
- mirror row 있으면 해당
-
N == 0: row 있으면 Google delete + row delete.
-
트리거 지점:
- flashcard 생성(첫 복습) →
reconcileDate(firstReviewDate) - 복습 완료 → 완료된 건의 날짜 + 새로 생성된 다음 복습의 날짜, 두 날짜 reconcile
- 백필(토글 ON) → PENDING 있는 모든 날짜 reconcile
- flashcard 생성(첫 복습) →
- 멱등: 항상 DB 진실에서 재계산 → 중복 호출·부분 실패에 안전.
-
AGAIN 판별: 코드상 AGAIN은
now+10분(분 단위), 정상 건은04:00. → "scheduledAt 로컬 시각 == 04:00"으로 깔끔히 구분(매직넘버ROLLOVER_HOUR일관). - 오버듀: 지난 PENDING은 원래 dueDate 묶음에 그대로 둔다(캘린더엔 놓친 날 표시). orino "오늘 복습"은 기존대로 동적 합류 — 미러와 독립.
상세 컬럼·Liquibase 관례는 Planner 데이터 모델에 합류 기재.
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.
| 컬럼 | 타입 | 설명 |
|---|---|---|
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 즉시).
-
0NN-create-review-calendar-mirror.yaml+0NN-add-google-account-review-mirror.yaml(컬럼 2개) — Planner 최신 changelog 다음 번호.tableExists/columnExists가드,member(id)FK,DATETIME(6).
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.
Planner UI 설정 화면(/integrations) 또는 Google 연결 카드에 토글 추가.
┌─ Google 연동 ──────────────────────────┐
│ 연결됨 · me@gmail.com [연결 해제] │
│ ───────────────────────────────────── │
│ 복습을 Google 캘린더에 표시 [ ●ON ]│
│ 보조 캘린더 "orino 복습"에 단방향으로 │
│ 띄웁니다. 폰·워치에서도 보이고 알림을 │
│ 받습니다. (orino가 원본) │
└──────────────────────────────────────────┘
- 토글 ON → 백필 진행 스피너 → "켜짐". 미연동이면 [Google 연결] 선행.
- 단방향임을 안내(구글에서 수정해도 orino 기준으로 갱신됨).
- 양방향 동기화 / Google 측 편집 반영 (순수 단방향 확정)
- 카드별 개별 이벤트(도배), 완료 이력을 캘린더에 영구 보존
- 사용자 지정 알림 시각·커스텀 reminder (v1
useDefault) - AGAIN 당일 재학습 미러
- 배치 동기화 서비스(SP-V5-009 보류) — 이벤트 기반으로 충분
- 미러 이벤트를 orino 통합 피드에 재표시(보조 캘린더는 외부 전용)