diff --git a/plans/250918_skill_email_naverworks_extension.md b/plans/250918_skill_email_naverworks_extension.md new file mode 100644 index 0000000..2ea4254 --- /dev/null +++ b/plans/250918_skill_email_naverworks_extension.md @@ -0,0 +1,203 @@ +# 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 신규 테이블 (선택적) +```sql +-- 사용자 기본 이메일 프로바이더 설정 +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 메일 발송 +```http +POST /v2/send-email +{ + "provider": "naverworks", + "user_id": "3550cef6-63e1-4ceb-8802-a25c9d1c6917", + "to": "recipient@example.com", + "subject": "회의 일정 안내", + "body": "내일 오후 2시 회의입니다." +} +``` + +### 7.2 메일 조회 +```http +GET /v2/list-emails?provider=naverworks&user_id={user_id}&limit=10 +``` + +### 7.3 메일 요약 (Slack용) +```http +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 # 토큰 갱신 전용 모듈 +``` + +**역할 분리**: +- auth-server: 모든 토큰 발급/갱신/저장 (포트 9000) +- rb8001/skill-email: API 호출만, 401 시 auth-server에 갱신 요청 +- 엔드포인트: `POST /auth/naverworks/refresh` + +### 8.3 동시성 제어 +- Redis Lock 또는 DB 트랜잭션으로 동시 갱신 방지 +- 첫 번째 갱신만 성공, 나머지는 대기 또는 실패 처리 + +--- + +## 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` + +--- + +**문서 끝** \ No newline at end of file