Google 캘린더 연동

Sudapapa Diary는 Google OAuth 2.0과 Google Calendar API v3를 사용해 사용자의 Google 캘린더를 안전하게 연동합니다. 한 번 로그인하면 RefreshToken이 안전하게 저장되어 매번 다시 로그인할 필요가 없으며, 5분 주기로 자동 동기화되어 외부에서 만든 일정도 곧바로 위젯에 반영됩니다.

요약

• 양방향 동기화(Pull + Push) - 외부 변경은 5분 안에 가져오고, 로컬 변경은 즉시 push 합니다.
• OAuth 2.0 + 외부 브라우저 로그인 - 앱 안에 비밀번호를 입력하지 않습니다.
• 다중 캘린더 - 색상별로 구분된 모든 캘린더를 동시에 표시하며, 캘린더별로 동기화 ON/OFF를 토글할 수 있습니다.
• 무료 플랜에서는 외부 계정 연결이 잠금 처리되며 유료 플랜으로 업그레이드 시 활성화됩니다.

권한 범위 (Scopes)

로그인 시 다음 OAuth 스코프를 요청합니다(src/main/google/googleAuth.js).

Scope	용도
calendar.readonly	캘린더 목록 및 일정 읽기
calendar.events	일정 생성·수정·삭제
userinfo.email	로그인된 계정의 이메일 표시
userinfo.profile	이름, 프로필 사진 표시

Tip

캘린더 자체의 메타데이터(색상, 시간대 등)를 변경하지는 않으므로 calendar 전체 쓰기 스코프는 요청하지 않습니다. 권한이 부담스럽다면 Google 계정의 보안 페이지에서 언제든지 접근을 철회할 수 있습니다.

연결 절차

1. 캘린더 관리 페이지 열기 - 사이드바의 “캘린더 관리”(또는 설정 → 계정) 메뉴로 이동합니다.
2. Google 카드의 추가 버튼 클릭 - 외부 계정 영역에서 Google 타일을 클릭합니다.
3. 외부 브라우저로 OAuth 동의 화면 이동 - 앱이 시스템 기본 브라우저로 Google 로그인 페이지를 엽니다(shell.openExternal).
4. Google 계정 선택 후 동의 - 위 스코프를 승인합니다.
5. 로컬 콜백 처리 - 앱이 http://localhost:8888/callback에서 인증 코드를 받습니다.
6. 자동 토큰 교환·캘린더 목록 로드 - 액세스/리프레시 토큰이 저장되고 캘린더 목록이 자동으로 가져와집니다.
7. 동기화 시작 - 5분 주기 자동 동기화가 시작되고, 위젯이 즉시 새 일정으로 갱신됩니다.

캘린더 관리 페이지 — Google 추가 후 캘린더가 이곳에 노출됩니다

콜백 서버

인증 콜백을 받는 로컬 HTTP 서버는 8888 포트(/callback 경로)를 잠깐 사용합니다. 인증이 끝나면 자동으로 종료되며, 다른 OAuth 제공자(Microsoft, Naver)와 포트를 공유합니다. 8888 포트가 사용 중이라면 인증이 실패하므로 충돌하는 프로세스를 종료한 뒤 다시 시도하세요.

양방향 동기화 동작

SyncEngine은 캘린더별로 다음을 수행합니다.

1. Push - 로컬 변경(syncStatus가 pending_create/pending_update/pending_delete인 이벤트)을 먼저 Google에 반영하여 충돌 가능성을 최소화합니다.
2. Pull - Google에서 최근 1년 이전부터 현재까지의 이벤트를 가져와 로컬에 저장합니다(최대 2,500건/요청, singleEvents=true로 반복 일정 펼침).
3. 메타데이터 갱신 - 캘린더 색상, 이름 등을 googleCalendarStore와 connectionStore에 갱신합니다.
4. 재시도/오류 격리 - 한 캘린더가 실패해도 다른 캘린더는 계속 동기화합니다.

자동 동기화 주기

GoogleCalendarCache는 앱 시작 후 5분 간격으로 모든 활성화된 캘린더를 다시 가져옵니다(startAutoSync(5 * 60 * 1000)). 즉시 동기화가 필요하면 캘린더 관리 페이지에서 새로고침 버튼을 눌러 수동으로 트리거할 수 있습니다.

충돌 처리

• 같은 일정을 양쪽에서 동시에 수정한 경우, 마지막에 push된 쪽이 살아남습니다(Last-Write-Wins).
• pending 상태의 로컬 일정은 push가 끝날 때까지 다시 push되지 않습니다.
• 삭제 일정은 pending_delete 상태로 표시 후 push 성공 시 로컬에서도 제거됩니다.

캘린더 선택 및 색상

연결이 끝나면 모든 Google 캘린더가 자동으로 활성화됩니다. 캘린더 관리 페이지에서 다음 작업이 가능합니다.

작업	설명
동기화 ON/OFF	캘린더별 토글 - OFF 상태에서는 위젯에 표시되지 않고 push도 발생하지 않습니다
색상 확인	Google에서 설정한 캘린더 색상이 그대로 표시됩니다
기본 캘린더 지정	QuickAdd에서 기본으로 선택될 캘린더
새로고침	즉시 모든 캘린더 다시 동기화

토큰 갱신

액세스 토큰은 일반적으로 1시간 후 만료됩니다. 만료가 임박하면 RefreshToken을 사용해 자동으로 갱신하므로 사용자는 별도 작업이 필요 없습니다(refreshAccessToken). RefreshToken 자체가 무효화된 경우(비밀번호 변경, 권한 철회, 6개월 미사용 등)에만 다시 로그인이 필요합니다.

다시 로그인이 필요한 경우

다음 상황에서는 토큰이 만료되어 재로그인 안내가 표시됩니다.

• Google 계정 비밀번호 변경
• Google 보안 설정에서 앱 액세스 철회
• 6개월 이상 앱 미사용
• 디바이스 간 충돌(여러 PC에서 동시에 같은 계정 사용 시 일부 토큰 무효화)

일정 작업이 외부에 반영되는 시점

생성

QuickAdd에서 Google 캘린더를 선택해 저장하면 즉시 로컬에 pending_create 상태로 기록되고, 다음 동기화 사이클(또는 즉시 push)에서 Google에 생성됩니다.

수정

편집 모드로 저장하면 pending_update로 표시되며 push 시 Google에 반영됩니다. Google에서 가져온 ID(googleId)는 보존되어 같은 일정을 가리킵니다.

삭제

삭제는 pending_delete로 표시 후 push 성공 시 양쪽에서 제거됩니다. push 실패 시 로컬 사본은 남고 다음 시도에서 재시도합니다.

캐시와 오프라인 동작

GoogleCalendarCache는 메모리 기반 캐시입니다. 앱 시작 시 한 번 로드되며, 네트워크 연결이 끊겨도 마지막으로 가져온 일정 데이터를 위젯에 표시합니다. 단, 메모리 캐시이므로 앱을 재시작하면 다시 동기화가 일어나야 표시됩니다(SQLite의 googleCalendarStore에 영속 사본이 저장되어 시작 시 즉시 표시).

연결 해제

캘린더 관리 페이지의 Google 카드에서 로그아웃 또는 연결 해제를 누르면 다음이 수행됩니다.

1. 자동 동기화 타이머 중지
2. 메모리 캐시 비우기
3. SQLite의 토큰·사용자 정보·캘린더 메타데이터 삭제(clearGoogle)
4. Google에서 가져온 일정 사본을 로컬에서 제거
5. 위젯/페이지 즉시 새로고침

로컬 사본도 삭제됩니다

연결 해제 시 Google에서 가져왔던 일정의 로컬 사본은 함께 삭제됩니다. Google 서버의 원본 일정에는 영향이 없으며, 다시 로그인하면 모두 복구됩니다. 일정을 다른 캘린더로 옮기고 싶다면 연결 해제 전에 내보내기/가져오기를 활용하세요.

트러블슈팅

증상	원인	해결
인증 페이지가 열리지 않음	시스템 기본 브라우저 미설정	기본 브라우저 설정 후 다시 시도
This site can't be reached(localhost:8888)	8888 포트 충돌	포트를 사용 중인 프로세스 종료 후 재시도
Calendar API is not enabled	Google Cloud 프로젝트의 Calendar API 비활성	개발자 전용 정식 빌드에서는 발생하지 않으며, 자체 빌드 시 Google Cloud Console에서 활성화
일정이 중복으로 보임	같은 일정이 여러 Google 캘린더에 동시에 존재	각 캘린더에서 어떤 곳을 활성화할지 토글로 정리
시간이 1시간 어긋남	시스템 시간대 또는 일광절약시간 문제	Windows 시간대를 자동 설정으로 변경 후 재시작
5분 넘게 새 일정이 보이지 않음	자동 동기화 주기 대기 중	캘린더 관리에서 새로고침을 눌러 즉시 동기화
pending_* 상태로 멈춤	일시적 네트워크 오류 또는 권한 부족	잠시 후 자동 재시도, 계속 실패하면 로그아웃 후 재로그인

보안과 개인정보

• 액세스/리프레시 토큰은 시스템 키체인이 아닌 SQLite의 암호화된 컬럼에 저장됩니다(AES-256-GCM, 디바이스 키 기반).
• 토큰은 메인 프로세스에서만 사용되며 렌더러로 노출되지 않습니다(IPC 핸들러 경계).
• 백업 파일에 토큰이 포함되지 않도록, 토큰 컬럼은 내보내기/가져오기에서 자동 제외됩니다.
• Sudapapa Diary는 사용자의 일정 데이터를 자체 서버로 전송하지 않습니다. 모든 통신은 사용자 PC와 Google 사이에서만 이루어집니다.

데이터 흐름 요약

로그인 1회

외부 브라우저 → Google → localhost:8888/callback → 토큰 저장 → 캘린더 목록 로드

자동 동기화

5분 주기 → push(pending) → pull(최근 1년~) → 메모리 캐시 갱신 → 위젯 갱신

QuickAdd 저장

로컬 SQLite 즉시 기록 → pending 상태 표시 → 다음 push에서 Google에 반영

로그아웃

타이머 중지 → 캐시/토큰/캘린더 메타데이터 삭제 → 위젯 갱신

자주 묻는 질문

Q. 여러 Google 계정을 동시에 연결할 수 있나요?

현재는 제공자당 한 계정 사용을 권장합니다. 두 번째 계정으로 다시 로그인하면 첫 번째 계정의 토큰이 교체될 수 있으니, 다중 계정이 필요하다면 별도의 Windows 사용자 프로필을 활용하세요.

Q. 일정 변경이 즉시 Google에 반영되나요?

QuickAdd 저장 직후 push가 시작되므로 보통 몇 초 안에 Google에 반영됩니다. 네트워크가 끊겨 있어도 pending_* 상태로 안전하게 보관되어 다음 동기화 시도 시 자동 재시도됩니다.

Q. 캘린더를 OFF로 두면 일정도 사라지나요?

위젯에 표시만 안 될 뿐 로컬 사본은 그대로 유지됩니다. 다시 ON으로 켜면 즉시 다시 표시되며, 그동안 외부에서 발생한 변경은 다음 동기화에서 반영됩니다.

Note

다른 OAuth 기반 캘린더(Microsoft, Naver, Kakao) 연결은 다중 계정 연동 문서를 참고하세요.