Skip to content

Planner Architecture

wcorn edited this page Jul 24, 2026 · 3 revisions

시스템 아키텍처: Planner (Google Calendar 연동)

범위: Google Calendar 양방향 연동(일정), Google Tasks 연동(할 일), orino SM-2 복습 일정 읽기 전용 오버레이, 월/주/일 뷰. 핵심 가치: 단일 사용자 / 유지보수 최소화 / 장기 운영 → 모든 트레이드오프에서 "단순한 쪽"을 택한다. 결정 근거는 결정 기록 참고.

1. 전체 구조 (BFF 프록시)

┌──────────────┐    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)를 공유한다.

2. 백엔드 패키지 구조

멀티모듈 구조는 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

3. Google API 호출 방식: Spring RestClient 직접 호출

후보 평가
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 기본 포함.

4. 동기화 전략: 라이브 프록시 + 단기 캐시

후보 평가
라이브 프록시 + 단기 캐시(Redis ~60초) ✅ 단일 사용자/저트래픽에 최적. 미러 정합성·삭제 추적 코드 부채 없음. Google이 유일한 진실
syncToken 증분 + 로컬 미러 테이블 두 진실(로컬·구글) 발생, 삭제·재동기화 코드 복잡. 과설계
  • 월/주/일 요청마다 events.list?timeMin&timeMax&singleEvents=true&orderBy=startTime 호출.
    • singleEvents=true 가 RRULE 반복 인스턴스를 기간 내로 펼쳐 반환 → orino는 RRULE을 직접 구현하지 않는다(요구사항 일치).
  • Redis 단기 캐시(~60초)는 뷰 전환/리렌더의 중복 호출만 흡수. 쓰기 후엔 해당 기간 캐시 무효화.
  • 비목표: 로컬 이벤트/태스크 미러 테이블, syncToken 저장소 — 만들지 않는다.

5. OAuth 2.0 흐름 (단일 사용자, offline)

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 필요.

6. 토큰 저장

토큰 저장소 이유
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 암호화] 적용.

7. 통합 캘린더 피드

단일 엔드포인트 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[].

8. 보안 / 실패 처리

상황 처리
미연동 통합 피드 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 인증 유지.

9. 인프라 / 시크릿

  • 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]).

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

  • 로컬 이벤트 미러 / syncToken 증분 동기화
  • 자동 스케줄링 엔진 / 배치 서비스
  • 복습 → Google 내보내기
  • 여러 캘린더 동시 표시 / 캘린더별 색상
    • 단, 공휴일은 예외적으로 별도 공공 데이터 소스(특일정보 API)로 동기화해 FE 오버레이 표시 — 멀티캘린더가 아님(결정 §4.4)
  • 푸시 알림 / 웹훅 수신(Google push notifications)

Clone this wiki locally