Repository navigation
Planner Architecture
wcorn edited this page Jul 24, 2026
·
3 revisions
범위: Google Calendar 양방향 연동(일정), Google Tasks 연동(할 일), orino SM-2 복습 일정 읽기 전용 오버레이, 월/주/일 뷰. 핵심 가치: 단일 사용자 / 유지보수 최소화 / 장기 운영 → 모든 트레이드오프에서 "단순한 쪽"을 택한다. 결정 근거는 결정 기록 참고.
┌──────────────┐ JWT ┌───────────────────────────┐ OAuth/REST ┌──────────────┐
│ Frontend │──────────▶│ orino BE │─────────────▶│ Google │
│ (React) │◀──────────│ (Spring Boot, BFF 프록시) │◀─────────────│ Calendar/Tasks│
│ 월/주/일 뷰 │ │ │ └──────────────┘
└──────────────┘ │ ┌─────────────────────┐ │
│ │ GoogleTokenProvider │ │ refresh token ┌─────────┐
│ │ (access 캐시·refresh) │ │──────────────────▶│ MySQL │
│ └─────────────────────┘ │ google_account └─────────┘
│ ┌─────────────────────┐ │ access·state ┌─────────┐
│ │ ReviewQueryService │ │──────────────────▶│ Redis │
│ │ (복습 오버레이 재사용) │ │ └─────────┘
│ └─────────────────────┘ │
└───────────────────────────┘
- BE가 Google refresh token을 독점 보관하고 모든 Google API를 프록시한다. FE는 기존 JWT만 쓰며, 인증 모델은 바뀌지 않는다.
- 통합 피드 병합(일정+할일+복습)도 BE가 수행 → FE는 한 번의 호출로 화면을 그린다.
- 인증 모듈과 동일 인프라(MySQL, Redis, K8s)를 공유한다.
멀티모듈 구조는 BE 코드 아키텍처를 따른다.
orino-domain-rdb (ds.project.orino.domain.planner/):
planner/
├── material/ flashcard/ note/ review/ # 기존 (재사용)
└── google/ # google_account 엔티티 + 리포지토리 (신규)
orino-domain-redis (ds.project.orino.redis/):
planner/google/ # access token 캐시, oauth-state, (선택)캘린더 응답 캐시
orino-app-api (ds.project.orino.planner/):
planner/
├── review/ # 기존 (오버레이로 재사용)
└── google/ # 신규
├── config/ GoogleApiProperties, RestClient 빈
├── oauth/ GoogleOAuthService, GoogleOAuthController
├── token/ GoogleTokenProvider (access 캐시·자동 갱신)
├── client/ GoogleCalendarClient, GoogleTasksClient (RestClient 래퍼)
├── calendar/ PlannerCalendarController (통합 피드), GoogleEventController
└── task/ GoogleTaskController
| 후보 | 평가 |
|---|---|
google-api-java-client / google-api-services-calendar
|
기능 풍부하나 의존성 무거움(transitive 다수), Guava/Jackson 버전 충돌 위험, Java 25 / Spring Boot 4 호환 검증 부담 |
Spring RestClient 직접 호출 ✅ |
의존성 0 추가, Jackson 재사용. 사용 엔드포인트가 소수(events list/insert/patch/delete, tasks list/insert/patch/delete, OAuth token/revoke)라 충분 |
-
RestClient빈은planner.google.config에 두고 타임아웃 +defaultStatusHandler(4xx/5xx → CustomException 매핑) 를 명시한다. - OAuth도 라이브러리 없이 표준 HTTP로 처리(authorization code grant + refresh grant + revoke).
- 신규 의존성: 외부 HTTP 클라이언트가 처음 도입된다(기존엔 AWS SDK presign뿐). RestClient는 Spring Framework 기본 포함.
| 후보 | 평가 |
|---|---|
| 라이브 프록시 + 단기 캐시(Redis ~60초) ✅ | 단일 사용자/저트래픽에 최적. 미러 정합성·삭제 추적 코드 부채 없음. Google이 유일한 진실 |
| syncToken 증분 + 로컬 미러 테이블 | 두 진실(로컬·구글) 발생, 삭제·재동기화 코드 복잡. 과설계 |
- 월/주/일 요청마다
events.list?timeMin&timeMax&singleEvents=true&orderBy=startTime호출.-
singleEvents=true가 RRULE 반복 인스턴스를 기간 내로 펼쳐 반환 → orino는 RRULE을 직접 구현하지 않는다(요구사항 일치).
-
- Redis 단기 캐시(~60초)는 뷰 전환/리렌더의 중복 호출만 흡수. 쓰기 후엔 해당 기간 캐시 무효화.
- 비목표: 로컬 이벤트/태스크 미러 테이블, syncToken 저장소 — 만들지 않는다.
FE [Google 연결]
└─▶ GET /api/integrations/google/oauth/url (JWT 인증)
BE: state 생성(memberId 바인딩) → Redis 5분 저장
scope = calendar + tasks, access_type=offline, prompt=consent
◀── { authorizationUrl }
└─▶ 브라우저 리다이렉트 → Google 동의 화면
└─▶ GET /api/integrations/google/oauth/callback?code&state (permitAll: 브라우저 top-level redirect, JWT 헤더 없음)
BE: state 검증 → memberId 복원 → code→token 교환
refresh_token → google_account(DB) 저장
access_token → Redis 캐시(TTL=expires_in)
primary calendar id / 기본 task list id 조회 저장
◀── 302 redirect → FE(/integrations?google=connected)
-
access_type=offline+prompt=consent로 refresh token을 확실히 확보한다. -
콜백↔member 바인딩: 콜백 시점엔 JWT가 없으므로, url 발급 시
state에 memberId를 묶어 Redis에 저장하고 콜백에서 복원한다(멀티유저 확장 여지 유지). CSRF 방지 역할 겸용. - 콜백 경로는 SecurityConfig에서 permitAll 필요.
| 토큰 | 저장소 | 이유 |
|---|---|---|
| refresh token | DB google_account (암호화 권장) |
장기·영속(연결 해제까지 유지). Redis 휘발 시 재연동 불편 회피 |
| access token | Redis google:access:{memberId} (TTL=expires_in) |
단명(~1h). 만료 자동 정리 |
| OAuth state | Redis google:oauth-state:{state} (TTL 5분) |
콜백 1회성 검증 |
-
GoogleTokenProvider.getValidAccessToken(memberId): 캐시 hit→사용 / miss·401→refresh grant로 재발급 후 재캐시 /invalid_grant→google_account.revoked=true마킹 후 재연동 요구 예외. - refresh token은 평문 대신 env 주입 대칭키로 암호화 저장 권장(JWT_SECRET 패턴). 최소안은 DB 컬럼 저장 + 접근 통제로 시작 후 [#17 암호화] 적용.
단일 엔드포인트 GET /api/planner/calendar?from&to[&view] 가 세 소스를 모아 반환한다.
{ "from": "...", "to": "...",
"googleConnected": true, "partial": false, "errors": [],
"events": [...], "tasks": [...], "reviews": [...] }- BE가 사용자 시간대(
X-Timezone)로 정규화(종일/시간 이벤트 구분). - 복습은 기존
ReviewQueryService.findCalendar를 재사용하고readOnly:true로 표기. -
부분 실패 허용: 한 소스가 실패해도 200으로 나머지를 반환,
partial:true+errors[].
| 상황 | 처리 |
|---|---|
| 미연동 | 통합 피드 200(빈 events/tasks + googleConnected:false). 쓰기 API는 409 INVALID_STATE |
| access 만료 | refresh로 1회 자동 재시도 |
invalid_grant |
revoked 마킹 → FE 재연동 CTA |
| 429 / 5xx | 짧은 지수 백오프 1~2회 → 실패 시 해당 소스만 비우고 partial
|
| 연결 해제 | Google revoke 호출 + DB row 삭제 + Redis access 삭제 |
| OAuth CSRF |
state 난수 + Redis 단명 저장 후 콜백 검증 |
-
집 공인 IP 직결 환경: 콜백 redirect URI는
https://api.orino.dev/api/integrations/google/oauth/callback(+local). 모든 API는 JWT 인증 유지.
-
GoogleApiProperties(client-id/secret/redirect-uri/scopes)는application.yml의${ENV:default}패턴으로 주입. - prod: client-id/secret을 SealedSecret → 환경변수(BE deployment). local:
.env. - 신규 외부 의존(Google API)이라 관측성에
google.api.calls{result}카운터 추가 권장([#16]).
- 로컬 이벤트 미러 / syncToken 증분 동기화
- 자동 스케줄링 엔진 / 배치 서비스
- 복습 → Google 내보내기
- 여러 캘린더 동시 표시 / 캘린더별 색상
- 단, 공휴일은 예외적으로 별도 공공 데이터 소스(특일정보 API)로 동기화해 FE 오버레이 표시 — 멀티캘린더가 아님(결정 §4.4)
- 푸시 알림 / 웹훅 수신(Google push notifications)