DOCS/troubleshooting/250919_naverworks_slack_01_base_configuration.md

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

날짜: 2025-09-19

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

관련 서비스: rb8001, skill-email, auth-server

상태: 기본 구조 구현 필요

관련 문서

• 2/3 일일 브리핑
• 3/3 콜드메일 리스트업

---

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

-- 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 상태 코드로 문제 진단 용이