# NAVER WORKS → Slack 연동 [1/3] 기본 구성

## 날짜: 2025-09-19
## 작성자: Claude (51123 서버 관리자)
## 관련 서비스: rb8001, skill-email, auth-server
## 상태: 기본 구조 구현 필요

## 관련 문서
- [2/3 일일 브리핑](./250919_naverworks_slack_02_daily_briefing.md)
- [3/3 콜드메일 리스트업](./250919_naverworks_slack_03_cold_mail_list.md)

---


## 1. 현재 구현 상태

### 구현 완료
- **auth-server**:
  - `naverworks.py`, `naverworks_passport.py` 파일 존재
  - NAVER WORKS OAuth 환경변수 설정 (CLIENT_ID, CLIENT_SECRET, REDIRECT_URI, TENANT_ID)
- **skill-email (포트 8501)**:
  - `services/naverworks_provider.py` NaverWorksProvider 클래스 구현
  - GET `/messages` 엔드포인트 (provider 파라미터 지원)
  - POST `/send` 엔드포인트
  - registry.register("naverworks", NaverWorksProvider()) 등록됨
- **NAVER WORKS Mail API**:
  - ✅ 올바른 엔드포인트 확인: `/mail/mailfolders/{folderId}/children`
  - ✅ mailAddress null 문제 해결 (API 사용에 영향 없음)
  - ✅ 9,192개 메일 정상 조회 확인

### 미구현 (기본 구성)
- rb8001이 provider=naverworks 미지정 → 기본 Gmail만 사용
- rb8001에서 "네이버웍스" 키워드 감지 로직 없음
- Slack ID → UUID 변환이 일부만 적용 (send만, list는 미적용)

---

## 2. 기본 구성 구현 사항

### 2.1 rb8001 수정 - 자동 Provider 감지
- `app/skills/email_integration.py`에 DB 기반 자동 분기 로직 추가
- 사용자의 메일 계정을 DB에서 조회하여 자동 선택
- 분기 로직:
  ```
  1. DB에서 user_id로 메일 계정 조회
  2. Gmail만 있음 → provider=gmail
  3. NaverWorks만 있음 → provider=naverworks
  4. 둘 다 있음 → 사용자에게 선택 요청
  5. 둘 다 없음 → 메일 계정 설정 안내
  ```
- 명시적 키워드("네이버웍스", "Gmail")는 오버라이드용

### 2.2 skill-email 수정 - 안전성 개선
- NaverWorksProvider.DEFAULT_USER_ID 제거
- account_id 누락 시 400/422 에러 반환
- 모든 요청에 UUID 검증 로직 추가

---

## 3. FastAPI 구조에 따른 파일 구성

### 3.1 skill-email 파일별 역할 (최소 변경 원칙)
| 파일 경로 | 역할 | 구현 내용 | 예상 코드 줄 수 |
|-----------|------|-----------|----------------|
| `main.py` | 앱 실행, 라우터 등록 | 기존 엔드포인트 유지, 새 라우터만 추가 | +5줄 추가 |
| `routers/naverworks_mail.py` (신규) | HTTP 요청 처리 | `/cold-mail-list`, `/daily-briefing` 엔드포인트 | 30-40줄 |
| `services/naverworks_mail_service.py` (신규) | 비즈니스 로직 | 콜드메일 필터링, 브리핑 생성 로직 | 100-150줄 |
| `services/naverworks_provider.py` | NAVER WORKS API 연동 | 기존 파일 활용, 메서드만 추가 | +50줄 추가 |
| `repositories/mail_cache_repository.py` (신규) | DB CRUD 작업 | 메일 캐시 저장/조회 SQL | 50-60줄 |
| `models/mail_cache.py` (신규) | DB 테이블 정의 | SQLAlchemy ORM 모델 (mail_cache 테이블) | 15-20줄 |
| `schemas/naverworks_schemas.py` (신규) | API 입출력 형식 | Pydantic 모델 (Request/Response) | 30-40줄 |
| `core/slack_formatter.py` (신규) | Slack 포맷터 | 메일→Slack 블록 변환 | 50-70줄 |

### 3.2 데이터 계층 구분
| 계층 | 파일 종류 | 역할 | 비유 |
|------|-----------|------|------|
| **Model** | `models/*.py` | DB 테이블 구조 정의 (SQLAlchemy ORM) | 창고 선반 설계도 (내부용) |
| **Schema** | `schemas/*.py` | API 요청/응답 형식 (Pydantic) | 손님 주문서 양식 (외부용) |
| **Repository** | `repositories/*.py` | DB 접근 로직 (CRUD) | 창고 관리 직원 |
| **Database** | `db/session.py` | DB 연결 관리 | 창고 출입문 열쇠 |

#### 데이터 흐름 예시
```
1. API 요청 → Schema (검증)
2. Service → Repository (DB 작업 요청)
3. Repository → Model (ORM으로 DB 테이블 접근)
4. Model → Database (실제 SQL 실행)
5. 결과 → Schema (응답 포맷) → API 응답
```

### 3.3 rb8001 파일별 역할
| 파일 경로 | 역할 | 구현 내용 |
|-----------|------|-----------|
| `app/main.py` | 메시지 라우팅 | Slack 메시지 수신 및 처리 |
| `app/skills/email_integration.py` | 이메일 스킬 통합 | NaverWorks 지원 추가 |
| `app/services/scheduler.py` | 스케줄러 | 일일 브리핑 자동 실행 |
| `app/schemas/skill_schemas.py` | 스킬 요청/응답 형식 | SkillRequest, SkillResponse |

### 3.4 auth-server 파일별 역할
| 파일 경로 | 역할 | 현재 상태 |
|-----------|------|-----------|
| `app/providers/naverworks.py` | OAuth 로그인 | ✅ 구현됨 |
| `app/providers/naverworks_passport.py` | Passport 시스템 | ✅ 구현됨 |

---

## 4. 기본 연동 테스트 시나리오

### 4.1 자동 Provider 감지 테스트
- Slack: "@로빙 메일 확인"
- rb8001이 DB 조회:
  - Gmail만: 자동으로 Gmail 메일 표시
  - NaverWorks만: 자동으로 NaverWorks 메일 표시
  - 둘 다: "Gmail과 네이버웍스 중 어떤 메일을 확인할까요?"

### 4.2 명시적 Provider 지정
- Slack: "@로빙 네이버웍스 메일 확인"
- DB 조회 없이 바로 provider=naverworks 사용
- 오버라이드로 특정 provider 강제 지정

### 4.3 DB 조회 SQL
```sql
-- Gmail 계정 확인
SELECT * FROM gmail_token
WHERE user_id = ? AND is_equipped = true

-- NaverWorks 계정 확인
SELECT * FROM naverworks_token
WHERE user_id = ?
```

---

## 5. 기본 구성 구현 체크리스트

### 5.1 rb8001 수정
- [ ] `app/skills/email_integration.py` 수정
  - [ ] `detect_email_provider()` 함수 추가 - DB 기반 자동 감지
  - [ ] get_messages()에 자동 provider 선택 로직
  - [ ] send_email()에 자동 provider 선택 로직
  - [ ] 둘 다 있을 때 선택 UI 구현
- [ ] DB 조회 로직 구현
  - [ ] gmail_token 테이블 조회
  - [ ] naverworks_token 테이블 조회
  - [ ] 결과 기반 provider 자동 결정
- [ ] Slack ID → UUID 변환 일관성 확보
  - [ ] get_uuid_from_slack() 활용 확대
  - [ ] 모든 skill-email 호출에 UUID 사용

### 5.2 skill-email 수정
- [ ] `services/naverworks_provider.py` 수정
  - [ ] DEFAULT_USER_ID 하드코딩 제거
  - [ ] account_id 없을 시 명확한 에러 처리
- [ ] 에러 응답 표준화
  - [ ] 400: 잘못된 요청
  - [ ] 422: 필수 정보 누락

---

## 6. 환경 설정 및 주의사항

### 6.1 환경 설정 확인
- skill-email .env 파일에 NAVER WORKS 관련 설정 확인
- rb8001에서 skill-email 호출 시 포트 8501 사용
- auth-server의 NAVER WORKS OAuth 설정 확인

### 6.2 보안 주의사항
- **계정 오매핑 방지**: DEFAULT_USER_ID 제거로 잘못된 계정 접근 차단
- **UUID 검증**: 모든 사용자 식별자를 UUID로 표준화
- **에러 처리**: 명확한 HTTP 상태 코드로 문제 진단 용이