docs: NAVER WORKS 토큰 갱신 구현 위치 결정 - auth-server 중앙 관리, Refresh Token Rotation 정책 문서화
This commit is contained in:
parent
c5e4bde275
commit
19ede8ad53
203
plans/250918_skill_email_naverworks_extension.md
Normal file
203
plans/250918_skill_email_naverworks_extension.md
Normal file
@ -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`
|
||||
|
||||
---
|
||||
|
||||
**문서 끝**
|
||||
Loading…
x
Reference in New Issue
Block a user