DOCS/journey/plans/archive/250819_gmail_item_detailed_tasks.md

Gmail 아이템 구현 세부 작업 목록

작성일: 2025-08-19

작성자: Claude (with 종태)

상태: 세부 작업 분해

---

1. 데이터베이스 작업 (서버 관리자)

1.1 robeing_stats 테이블 생성

• 테이블 생성 SQL 작성
• user_id 외래키 제약 추가
• robeing_id 유니크 제약 추가
• 인덱스 생성 (robeing_id, user_id)
• 기본 데이터 삽입 (rb8001, level=5)
• 생성 확인 쿼리 실행

1.2 gmail_token 테이블 수정

• is_equipped 컬럼 추가
• equipped_to 컬럼 추가
• 기존 데이터 is_equipped=false로 초기화
• 인덱스 재구성
• 수정 확인 쿼리 실행

1.3 gmail_audit_logs 테이블 생성

• 테이블 생성 SQL 작성
• created_at 인덱스 추가
• user_id 인덱스 추가
• action 인덱스 추가
• 생성 확인 쿼리 실행

---

2. robeing-monitor 서비스 구축 (로컬 개발자)

2.1 프로젝트 초기 설정

• robeing-state-service 클론
• 포트 9024로 변경
• requirements.txt 확인
• .env 파일 생성
• PostgreSQL 연결 설정 (192.168.0.100)

2.2 아이템 매니저 구현

• app/monitor 디렉토리 생성
• gmail_item_manager.py 생성
• 데이터베이스 연결 클래스 작성
• 아이템 조회 메서드 구현
  • get_all_items(user_id)
  • get_equipped_item(user_id)
  • get_available_items(user_id)
• 아이템 장착 메서드 구현
  • check_level_requirement(robeing_id)
  • check_ownership(user_id, item_id)
  • equip_item(user_id, robeing_id, item_id)
  • unequip_item(user_id, item_id)
• 감사 로그 메서드 구현
  • log_action(user_id, robeing_id, action, details)

2.3 API 엔드포인트 구현

• app/api/item_routes.py 생성
• GET /api/items/gmail 엔드포인트
  • 요청 파라미터 검증
  • 아이템 목록 조회
  • capabilities 계산
  • 응답 포맷팅
• POST /api/items/gmail/:userId/equip 엔드포인트
  • 요청 바디 검증
  • 레벨 체크
  • 소유권 확인
  • 장착 처리
  • 감사 로그 기록
  • 응답 반환
• POST /api/items/gmail/:userId/reauth 엔드포인트
  • auth-server와 통신 설정
  • OAuth URL 생성 요청
  • state 관리
  • 응답 반환
• DELETE /api/items/gmail/:userId 엔드포인트
  • 철회 권한 확인
  • 토큰 삭제 처리
  • 감사 로그 기록
  • 응답 반환

2.4 서비스 배포

• Dockerfile 수정
• docker-compose.yml 작성
• 빌드 테스트
• 컨테이너 실행
• 헬스체크 엔드포인트 확인
• 로그 확인

---

3. skill-email DB 연결 (희재) ✅ 완료 (2025-08-20)

3.1 DB 연결 설정

• psycopg2 의존성 추가
• .env 파일 수정
  • TOKEN_PROVIDER=database
  • POSTGRES_CONNECTION_STRING 설정
• 데이터베이스 연결 테스트 스크립트 작성
• 연결 확인

3.2 DBCredentialsProvider 구현

• services/db_credentials_provider.py 생성
• init 메서드 구현
  • DB 연결 초기화
  • 연결 풀 설정
• get_credentials 메서드 구현
  • SQL 쿼리 작성
  • 토큰 조회 로직
  • JSON 파싱
  • Credentials 객체 생성
  • oauth_config에서 client_id/secret 가져오기
• save_credentials 메서드 구현 (토큰 업데이트용)
  • 토큰 갱신 로직
  • DB 업데이트
• 에러 처리 추가
  • 토큰 없음 처리
  • DB 연결 실패 처리
  • 파싱 에러 처리

3.3 기존 코드 수정

• main.py 수정
  • FileCredentialsProvider 유지 (조건부 사용)
  • DBCredentialsProvider import 추가
  • Provider 초기화 코드 변경 (TOKEN_PROVIDER 환경변수 기반)
• 환경변수 체크 로직 수정
• 테스트 코드 작성
• 로컬 테스트

3.4 배포 준비

• requirements.txt 업데이트
• Dockerfile 확인
• 빌드 테스트
• 커밋 및 푸시

---

4. rb8001 통합 (희재)

4.1 환경 설정

• .env 파일 생성/수정
  • DATABASE_URL 설정
  • SKILL_EMAIL_URL=http://192.168.219.52:8501
  • MONITOR_SERVICE_URL=http://192.168.219.52:9024
• 환경변수 로드 확인
• 연결 테스트 스크립트 작성

4.2 아이템 관리 로직

• app/items 디렉토리 생성
• gmail_item_handler.py 생성
• 아이템 상태 체크 함수
  • check_gmail_equipped(user_id)
  • get_gmail_capabilities(user_id)
• robeing-monitor와 통신
  • 아이템 조회 API 호출
  • 응답 파싱
  • 에러 처리

4.3 이메일 스킬 연동

• app/skills/email_integration.py 생성
• 이메일 요청 감지
  • 메시지 파싱
  • 이메일 의도 분류
• 아이템 장착 확인
  • robeing-monitor API 호출
  • 장착 상태 검증
• skill-email 호출
  • 요청 포맷 구성
  • API 호출
  • 응답 처리
• 사용자 피드백
  • 성공 메시지 생성
  • 에러 메시지 생성
  • 재인증 안내

4.4 router 수정

• app/router.py 수정
• 이메일 관련 라우팅 추가
• 아이템 체크 미들웨어 추가
• 에러 핸들링 추가

4.5 테스트 및 배포

• 단위 테스트 작성
• 통합 테스트
• Docker 빌드
• 배포
• 로그 모니터링

---

4-1. rb10508_micro 통합 (종태)

4-1.1 환경 설정

• .env 파일 수정
  • MONITOR_SERVICE_URL=http://192.168.219.52:9024
  • SKILL_EMAIL_URL=http://192.168.219.52:8501
  • AUTH_SERVER_URL=http://192.168.0.100:9000 (이미 설정됨)
• 환경변수 로드 확인

4-1.2 Gmail 의도 분류 수정

• Mistral API 의도 분석 수정 완료 (250819 트러블슈팅)
  • intent_mapper 응답 경로 수정
  • email/news/general 분류 정상 작동
• Gmail 세부 의도 추가 (250819 완료)
  • send_email (발송) - Gemini API 통합
  • list_emails (조회) - 기본 구현
  • search_email (검색) - 기본 구현

4-1.3 아이템 확인 미들웨어

• Gmail 아이템 상태 체크 로직 추가
  • robeing-monitor API 연동
  • 캐싱 메커니즘 (5분)
• 미장착 시 응답 메시지
  • "Gmail 패스포트를 먼저 장착해주세요"
  • 레벨 부족 시 안내

4-1.4 skill-email 통합

• external_bridge.py 엔드포인트 수정 완료
  • /api/process → /process 경로 수정
• Gmail 특화 처리 추가 (250819-20 완료)
  • 사용자 이메일 주소 조회 (slack_user_mapping 활용)
  • 대화형 이메일 처리 (누락 정보 추가 요청)
• 에러 처리 (250819 완료)
  • Gemini API 폴백 구현
  • 네트워크 에러 → 로깅 및 사용자 안내

4-1.5 사용자 매핑 활용

• slack_user_mapping API 연동 완료 (250812)
  • Auth 서버 API 호출
  • 5분 캐싱 구현
• Gmail용 이메일 매핑 추가
  • workspace_member 테이블에서 email 조회
  • "종태님" → goeun2dc@gmail.com 변환

4-1.6 테스트 시나리오

• "종태님한테 회의 일정 메일 보내줘"
  • 사용자 이름 → 이메일 변환
  • Gmail 미장착 → 장착 안내
  • Gmail 장착 → 이메일 발송 성공
• "최근 메일 확인해줘"
  • 받은 메일함 조회
  • 요약 표시
• 토큰 만료 시나리오
  • 재인증 안내 메시지

4-1.7 배포

• 코드 커밋 및 푸시
• Gitea Actions 배포 확인
• 로그 모니터링 (/mnt/hdd/logs/rb10508_micro/)
• 실제 테스트

---

5. 프론트엔드 구현 (종태) ✅ 완료

5.1 API 클라이언트 확장

• src/api/robeing-api.ts 수정
• 타입 정의
  • GmailCredentialItem 인터페이스
  • GmailItemsResponse 인터페이스
  • EquipResponse 인터페이스
  • ReauthResponse 인터페이스
• API 함수 구현
  • getGmailItems()
    • 헤더 설정 (JWT 토큰)
    • 에러 처리
    • 응답 타입 변환
  • equipGmailItem()
    • 요청 바디 구성
    • 에러 처리
    • 성공 콜백
  • startGmailReauth()
    • OAuth 리다이렉트 처리
    • state 저장
  • revokeGmailItem()
    • 확인 다이얼로그
    • 삭제 요청
    • 상태 업데이트

5.2 Context 상태 관리

• src/contexts/ItemContext.tsx 생성
• State 인터페이스 정의
  • equippedItem: GmailCredentialItem | null
  • availableItems: GmailCredentialItem[]
  • loading: boolean
  • error: string | null
• Actions 정의
  • FETCH_ITEMS_START
  • FETCH_ITEMS_SUCCESS
  • FETCH_ITEMS_ERROR
  • EQUIP_ITEM_SUCCESS
  • UNEQUIP_ITEM_SUCCESS
• Reducer 구현
• Context Provider 구현
• Custom hooks
  • useGmailItems()
  • useEquipItem()

5.3 인벤토리 UI 컴포넌트

• src/components/Inventory 디렉토리 생성
• GmailPassportCard.tsx
  • 카드 레이아웃
  • Gmail 로고 아이콘
  • 이메일 주소 표시
  • 권한 뱃지 (send/read/modify)
  • 장착 상태 표시
  • 장착/해제 버튼
  • 재인증 버튼 (필요시)
• InventoryGrid.tsx
  • 카드 그리드 레이아웃
  • 장착된 아이템 섹션
  • 사용 가능 아이템 섹션
  • 빈 상태 메시지
• EquipModal.tsx
  • 장착 확인 다이얼로그
  • 레벨 요구사항 표시
  • 애니메이션 효과
• LevelRequirement.tsx
  • 레벨 부족 시 표시
  • "레벨 5가 되면 사용 가능해요!" 메시지
  • 현재 레벨 표시

5.4 스타일링

• src/styles/inventory.css 생성
• 카드 스타일
  • 호버 효과
  • 장착 상태 하이라이트
  • 비활성 상태 (레벨 부족)
• 버튼 스타일
  • 장착 버튼 (Primary)
  • 해제 버튼 (Secondary)
  • 재인증 버튼 (Warning)
• 애니메이션
  • 페이드인/아웃
  • 장착 시 반짝임
  • 로딩 스피너

5.5 통합 및 테스트

• App.tsx에 라우트 추가
• 네비게이션 메뉴 추가
• Context Provider 연결
• 개발 서버 테스트
• 에러 케이스 테스트
  • 네트워크 에러
  • 인증 만료
  • 레벨 부족
  • 서버 에러

5.6 배포 (2025-08-19 11:10 완료)

• Git 커밋 (Hash: 09b1001)
• Gitea Actions 빌드
• dist 디렉토리 생성
• Nginx 배포
• https://ro-being.com/inventory 접속 확인

---

6. Gateway 설정 (서버 관리자)

6.1 라우팅 규칙 추가

• nginx 설정 수정 (또는 Gateway 코드)
• /api/items/* → robeing-monitor:9024 프록시
• 헤더 전달 설정
• CORS 설정

6.2 인증 미들웨어

• JWT 검증 로직 확인
• 사용자 정보 전달
• 에러 응답 표준화

---

7. 통합 테스트

7.1 E2E 시나리오

• 로그인 → 인벤토리 조회 (Gateway 통해 테스트 완료)
• Gmail 아이템 장착 (250820 테스트 완료)
• 이메일 발송 요청 (250819-20 테스트 완료)
• 토큰 만료 → 재인증
• 아이템 철회

7.2 부하 테스트

• 동시 사용자 테스트
• API 응답 시간 측정
• 에러율 확인

7.3 보안 테스트

• 토큰 노출 확인
• SQL 인젝션 테스트
• 권한 우회 시도

---

8. 문서화

8.1 API 문서

• Swagger/OpenAPI 스펙 작성
• 요청/응답 예시 추가
• 에러 코드 정리

8.2 운영 가이드

• 배포 절차
• 모니터링 방법
• 트러블슈팅 가이드

8.3 사용자 가이드

• Gmail 아이템 사용법
• 재인증 방법
• FAQ

---

완료 기준

• 핵심 기능 테스트 통과 (Gmail 발송, 아이템 관리)
• 프로덕션 배포 완료 (skill-email DB 연동 완료)
• 문서 작성 완료
• 사용자 피드백 수집

---

총 작업 항목: 약 150개 완료된 항목: 약 115개 (77%) 남은 주요 작업:

• rb8001 Gmail 통합 (섹션 4)
• rb10508_micro 아이템 확인 미들웨어 (섹션 4-1.3)
• 사용자 이름→이메일 매핑 (섹션 4-1.5)
• 문서화 (섹션 8)

---

문서 끝