[STORY-102] Gmail 계정 연동

[jjjjjk12]

🔗 관련 작업

👤 User Story

• [STORY-102] Gmail 계정 연동 docs4capstone#2

📌 Task

• Closes [TASK-122] OAuth 인증 시작 및 콜백 처리 및 액세스 및 리프레시 토큰 암호화 저장 구현 #9
• Closes [TASK-123] 연동 직후 초기 메일 동기화 작업 및 동기화 상태 조회 API 구현 #12

💡 작업 내용

• Gmail OAuth 기반 MailAccount 연동 플로우를 구현하고, 실제 callback에서 토큰 교환 및 사용자 정보 조회 후 메일 계정을 저장하도록 구성했습니다.
• MailAccount 도메인을 확장해 alias, icon, color, OAuth 토큰 만료 시각 등을 저장하고, 연결된 메일 계정 목록 조회 API를 추가했습니다.

📝 추가 설명

1. Gmail OAuth 연동 구현

• GET /api/v1/mail-accounts/google/authorize와 GET /api/v1/mail-accounts/google/callback 흐름을 실제 Google OAuth 연동으로 연결했습니다.
• GoogleOAuthProperties, GoogleOAuthQueryService, GoogleOAuthTokenResult, GoogleUserInfoResult를 추가해 인가 URL 생성, 토큰 교환, 사용자 정보 조회를 분리했습니다.
• callback 성공 시 MailAccount 저장 후 /swagger-ui.html로 리다이렉트하도록 처리했습니다.

2. MailAccount 도메인 및 저장 정책 확장

• MailAccount 엔티티와 schema.sql에 access_token_expires_at, alias, icon, color 필드를 반영했습니다.
• refresh_token 누락 시 전용 예외를 통해 재연동을 유도하고, verified_email이 true가 아니면 연결을 차단하도록 검증을 추가했습니다.
• alias, icon, color는 authorize 단계에서 세션에 저장하고 callback 직전에 보정/검증하도록 변경했습니다.
  • alias 비어있음: emailAddress 사용
  • icon 비어있음: "good" 사용
  • color 비어있음: 랜덤 HEX 사용
  • color 값 존재 시 HEX 형식 검증

3. 메일 계정 조회 및 문서화

• 로그인한 사용자의 삭제되지 않은 메일 계정만 반환하는 목록 조회 API GET /api/v1/mail-accounts를 추가했습니다.
• 응답은 id, isActive, provider, emailAddress, alias, color, icon만 포함하는 List<MailAccountListResponse> 형태로 구성했습니다.
• Swagger 문서, 예외 코드, .claude 규칙 문서를 MailAccount OAuth/Validation/CQS 규칙에 맞게 보강했습니다.

⚡️ Test 결과

계정 등록 요청	CallBack	인박스 목록 조회
GET	GET	GET
/api/v1/mail-accounts/google/authorize	/api/v1/mail-accounts/google/callback	/api/v1/mail-accounts
	수동 확인 필요

Callback

• Callback은 클라이언트가 직접 호출하는게 아니라 브라우저에 의해 알아서 호출됩니다
• 그리고 조회가 잘 되니까 잘 등록된거고 Callback도 잘 된겁니다

[Copilot]

Pull request overview

Gmail OAuth 기반으로 MailAccount를 실제 연동(인가 URL 생성 → callback 토큰 교환/사용자 정보 조회 → 계정 저장)하고, 계정 표시용 메타데이터(alias/icon/color) 및 만료시각 저장과 “내 메일 계정 목록 조회” API를 추가하는 PR입니다.

Changes:

• Google OAuth 연동을 위한 Properties/QueryService/DTO를 추가하고 authorize/callback 플로우를 실제 Google API 호출로 연결
• MailAccount 도메인 확장(alias/icon/color) 및 삭제되지 않은 계정만 조회하도록 Repository/QueryService 수정
• 내 메일 계정 목록 조회 API 및 Swagger 문서/예외 코드 보강

sequenceDiagram
  participant C as Client/Browser
  participant API as Core API
  participant G as Google OAuth
  participant OQS as GoogleOAuthQueryService
  participant DB as DB(JPA)

  C->>API: GET /api/v1/mail-accounts/google/authorize (alias/icon/color)
  API->>API: session에 state,userId,appearance 저장
  API-->>C: authorizationUrl 반환
  C->>G: Google 동의 화면 이동
  G-->>C: redirect (code,state)
  C->>API: GET /api/v1/mail-accounts/google/callback?code&state
  API->>API: session state/userId 검증
  API->>OQS: code -> token 교환
  OQS->>G: POST token-uri
  OQS->>G: GET user-info-uri (Bearer access_token)
  OQS-->>API: GoogleMailAccountResult
  API->>DB: MailAccount 저장
  API-->>C: 302 Redirect (/)

Loading

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
docker-compose.yml	Google OAuth 환경변수 주입 추가
db/src/main/resources/schema.sql	mail_accounts에 alias/icon/color 컬럼 반영
db/src/main/java/com/mailsangja/db/port/MailAccountRepositoryPort.java	삭제되지 않은 계정 조회 메서드로 변경
db/src/main/java/com/mailsangja/db/module/mail/MailAccountJpaRepositoryModule.java	findAllByUserIdAndDeletedAtIsNull로 조회 정책 변경
db/src/main/java/com/mailsangja/db/entity/mail/MailAccount.java	alias/icon/color 필드 및 업데이트 메서드 추가
db/src/main/java/com/mailsangja/db/adapter/mail/MailAccountRepositoryAdapter.java	Port 변경사항 반영
core/src/main/resources/application.yaml	Google OAuth 설정(properties) 추가
core/src/main/java/com/mailsangja/core/service/mail/MailAccountQueryService.java	삭제되지 않은 계정만 조회하도록 변경
core/src/main/java/com/mailsangja/core/service/mail/MailAccountCommandService.java	Google MailAccount 생성 커맨드/검증 로직 추가
core/src/main/java/com/mailsangja/core/service/google/GoogleOAuthQueryService.java	토큰 교환/유저정보 조회/인가 URL 생성 로직 신규 추가
core/src/main/java/com/mailsangja/core/facade/MailAccountFacade.java	실제 OAuth 결과 기반 저장 + appearance 정규화/검증 + 목록 조회 추가
core/src/main/java/com/mailsangja/core/controller/MailAccountController.java	목록 조회 API 추가 및 callback 302 redirect로 변경
core/src/main/java/com/mailsangja/core/controller/docs/MailAccountControllerDocs.java	Swagger 문서에 목록 조회/redirect 응답 반영
core/src/main/java/com/mailsangja/core/dto/mail/*	authorize 요청, list 응답, OAuth DTO 및 response 필드 확장
core/src/main/java/com/mailsangja/core/config/properties/GoogleOAuthProperties.java	mailsangja.oauth.google 바인딩 클래스 추가
core/src/main/java/com/mailsangja/core/common/exception/mail/MailAccountErrorCode.java	OAuth/appearance 관련 에러 코드 추가
.claude/skills/spring-api-rules.md	OAuth/Validation 레이어 규칙 문서 업데이트

[rlagnlfo1004]

LGTM 😄 고생하셨습니다.