# 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` (생성 필요)
- 포트: 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`

---

**문서 끝**