DOCS/plans/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_tokens 테이블 수정

• 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.219.45)

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 연결 (희재)

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 객체 생성
• refresh_token 메서드 구현
  • 토큰 갱신 로직
  • DB 업데이트
• 에러 처리 추가
  • 토큰 없음 처리
  • DB 연결 실패 처리
  • 파싱 에러 처리

3.3 기존 코드 수정

• main.py 수정
  • FileCredentialsProvider import 제거
  • DBCredentialsProvider import 추가
  • Provider 초기화 코드 변경
• 환경변수 체크 로직 수정
• 테스트 코드 작성
• 로컬 테스트

3.4 배포 준비

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

---

4. rb8001 통합 (희재)

4.1 환경 설정

• .env 파일 생성/수정
  • DATABASE_URL 설정
  • SKILL_EMAIL_URL 설정
  • STATE_SERVICE_URL 설정
• 환경변수 로드 확인
• 연결 테스트 스크립트 작성

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 빌드
• 배포
• 로그 모니터링

---

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 연결
• 개발 서버 테스트
• 에러 케이스 테스트
  • 네트워크 에러
  • 인증 만료
  • 레벨 부족
  • 서버 에러

---

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

6.1 라우팅 규칙 추가

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

6.2 인증 미들웨어

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

---

7. 통합 테스트

7.1 E2E 시나리오

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

7.2 부하 테스트

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

7.3 보안 테스트

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

---

8. 문서화

8.1 API 문서

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

8.2 운영 가이드

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

8.3 사용자 가이드

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

---

완료 기준

• 모든 테스트 통과
• 프로덕션 배포 완료
• 문서 작성 완료
• 사용자 피드백 수집

---

총 작업 항목: 약 150개 예상 소요 시간: 각 항목 평균 30분 = 약 75시간

---

문서 끝