ivada-infra/DOCS
3
0
Fork 0
Code Issues 1 Pull Requests 5 Actions Packages Projects Releases Wiki Activity
DOCS/plans/250918_skill_email_naverworks_extension.md

5.4 KiB
Raw Blame History

skill-email 서비스 NAVER WORKS 확장 계획

날짜: 2025-09-18

작성자: Claude (51123 서버 관리자)

상태: 계획 수립

서비스: skill-email (51124 서버, 포트 8501)

1. 목표

기존 Gmail 전용 skill-email 서비스를 멀티 프로바이더 이메일 서비스로 확장하여 NAVER WORKS Mail API를 지원

주요 목표

  • ✅ 기존 Gmail 기능 유지
  • 🎯 NAVER WORKS 메일 조회/발송 추가
  • 🎯 Provider 파라미터로 서비스 구분
  • 🎯 Slack 통합 지원

2. 현재 구조 분석

2.1 skill-email 현황

위치: 51124 서버
포트: 8501
기능: Gmail 메일 발송/조회
인증: gmail_token 테이블

2.2 NAVER WORKS 준비 현황

  • ✅ OAuth 인증 구현 완료 (auth-server)
  • ✅ naverworks_token 테이블 구조 완료
  • ✅ Mail API 엔드포인트 확인 완료
  • ✅ 토큰 저장 및 갱신 로직 완료

3. 확장 설계

3.1 Provider 추상화

  • EmailProvider 추상 클래스로 공통 인터페이스 정의
  • GmailProvider: 기존 Gmail 로직 (변경 없음)
  • NaverWorksProvider: NAVER WORKS Mail API 신규 구현

3.2 API 엔드포인트 수정

  • /send-email: 기존 엔드포인트 유지 (Gmail 기본값)
  • /v2/send-email: 새 엔드포인트 (provider 파라미터 지원)
  • /v2/list-emails: 메일 목록 조회
  • /v2/mail-summary: Slack용 메일 요약

3.3 토큰 관리 통합

  • gmail_token 테이블: Gmail 토큰
  • naverworks_token 테이블: NAVER WORKS 토큰
  • provider 파라미터로 테이블 선택

4. 구현 단계

Phase 1: 기반 구조 (Day 1)

  • Provider 인터페이스 정의
  • 기존 Gmail 코드를 GmailProvider로 리팩토링
  • 테스트 코드 작성

Phase 2: NAVER WORKS 구현 (Day 2)

  • NaverWorksProvider 클래스 생성
  • Mail API 클라이언트 구현
    • 메일 목록 조회 (/mailfolders/{folderId}/children)
    • 메일 발송 (POST /mail)
    • 폴더 목록 조회 (/mailfolders)
  • 토큰 갱신 로직

Phase 3: Slack 통합 (Day 3)

  • rb8001 라우팅 수정
  • Slack 사용자 → NAVER WORKS 매핑
  • 응답 포맷팅

Phase 4: 테스트 및 배포 (Day 4)

  • 통합 테스트
  • Docker 이미지 빌드
  • 51124 서버 배포
  • 모니터링 설정

5. 주요 기능

5.1 메일 요약 (Slack 전용)

  • 최근 메일 5-10개 조회
  • Gemini API로 요약 생성
  • Slack 블록 포맷으로 응답

5.2 프로바이더 상태 확인

  • Gmail 토큰 상태
  • NAVER WORKS 토큰 상태
  • 사용자 기본 프로바이더 설정

6. 데이터베이스 스키마

6.1 기존 테이블 (변경 없음)

  • gmail_token: Gmail OAuth 토큰
  • naverworks_token: NAVER WORKS OAuth 토큰

6.2 신규 테이블 (선택적)

-- 사용자 기본 이메일 프로바이더 설정
CREATE TABLE email_provider_preference (
    user_id UUID PRIMARY KEY,
    default_provider VARCHAR(20) DEFAULT 'gmail',
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
    updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

-- Slack → NAVER WORKS 사용자 매핑
CREATE TABLE slack_naverworks_mapping (
    slack_user_id VARCHAR PRIMARY KEY,
    naverworks_user_id UUID,
    email VARCHAR,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
);

7. API 명세

7.1 메일 발송

POST /v2/send-email
{
    "provider": "naverworks",
    "user_id": "3550cef6-63e1-4ceb-8802-a25c9d1c6917",
    "to": "recipient@example.com",
    "subject": "회의 일정 안내",
    "body": "내일 오후 2시 회의입니다."
}

7.2 메일 조회

GET /v2/list-emails?provider=naverworks&user_id={user_id}&limit=10

7.3 메일 요약 (Slack용)

POST /v2/mail-summary
{
    "provider": "naverworks",
    "user_id": "3550cef6-63e1-4ceb-8802-a25c9d1c6917",
    "slack_channel": "C1234567890"
}

8. 토큰 갱신 구현 위치 및 정책

8.1 NAVER WORKS Refresh Token Rotation 정책 (확인 완료)

  • 핵심: refresh_token 사용 시 새로운 access_token + 새로운 refresh_token 발급
  • 기존 refresh_token 즉시 무효화 (재사용 절대 불가)
  • 수명: Access Token 1시간, Refresh Token 90일
  • 위험: DB 저장 실패 시 영구 토큰 손실, 재인증 필요

8.2 구현 위치 (결정 완료)

auth-server에서 중앙 관리

  • 위치: /home/admin/auth-server/app/providers/naverworks_refresh.py (생성 필요)
  • 포트: 9000
  • 엔드포인트: 결정 필요 - /auth/naverworks/refresh 또는 /api/auth/naverworks/refresh

8.3 현재 인프라 상태 (확인 완료)

  • Redis 컨테이너: 실행 중 (6f083213a8b1)
  • auth-server 컨테이너: 실행 중 (dba7eb03216a)
  • 현재 토큰 상태: Access Token 만료 (4시간 경과), Refresh Token 보유
  • DB 필드: token_data (JSONB), expires_at, expiry 존재 (확인 필요: 어느 필드 사용?)

8.4 동시성 제어

  • 확인 필요: Redis Lock 구현 여부
  • 결정 필요: DB 트랜잭션 vs Redis Lock

9. 성공 지표

  • Gmail 기존 기능 100% 유지
  • NAVER WORKS 메일 조회 성공률 > 95%
  • 응답 시간 < 2초
  • Slack 통합 정상 작동

10. 참고 문서

  • /home/admin/DOCS/troubleshooting/250918_naverworks_mail_api_mailaddress_null_issue.md
  • /home/admin/DOCS/troubleshooting/250917_네이버웍스_passport_작업.md
  • /home/admin/DOCS/300_architecture/sequences/email_sequences.md

문서 끝