DOCS/plans/250819_gmail_item_detailed_tasks.md

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

## 작성일: 2025-08-19
## 작성자: Claude (with 종태)
## 상태: 세부 작업 분해

---

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

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

### 1.2 gmail_tokens 테이블 수정
- [x] is_equipped 컬럼 추가
- [x] equipped_to 컬럼 추가
- [x] 기존 데이터 is_equipped=false로 초기화
- [x] 인덱스 재구성
- [x] 수정 확인 쿼리 실행

### 1.3 gmail_audit_logs 테이블 생성
- [x] 테이블 생성 SQL 작성
- [x] created_at 인덱스 추가
- [x] user_id 인덱스 추가
- [x] action 인덱스 추가
- [x] 생성 확인 쿼리 실행

---

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

### 2.1 프로젝트 초기 설정
- [x] robeing-state-service 클론
- [x] 포트 9024로 변경
- [x] requirements.txt 확인
- [x] .env 파일 생성
- [x] PostgreSQL 연결 설정 (192.168.219.45)

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

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

### 2.4 서비스 배포
- [x] Dockerfile 수정
- [x] docker-compose.yml 작성
- [x] 빌드 테스트
- [x] 컨테이너 실행
- [x] 헬스체크 엔드포인트 확인
- [x] 로그 확인

---

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

### 3.1 DB 연결 설정
- [x] psycopg2 의존성 추가
- [x] .env 파일 수정
  - [x] TOKEN_PROVIDER=database
  - [x] POSTGRES_CONNECTION_STRING 설정
- [x] 데이터베이스 연결 테스트 스크립트 작성
- [x] 연결 확인

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

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

### 3.4 배포 준비
- [x] requirements.txt 업데이트
- [x] Dockerfile 확인
- [x] 빌드 테스트
- [x] 커밋 및 푸시

---

## 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
  - [x] AUTH_SERVER_URL=http://192.168.219.45:9000 (이미 설정됨)
- [ ] 환경변수 로드 확인

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

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

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

### 4-1.5 사용자 매핑 활용
- [x] slack_user_mapping API 연동 완료 (250812)
  - [x] Auth 서버 API 호출
  - [x] 5분 캐싱 구현
- [ ] Gmail용 이메일 매핑 추가
  - [ ] workspace_members 테이블에서 email 조회
  - [ ] "종태님" → goeun2dc@gmail.com 변환

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

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

---

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

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

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

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

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

### 5.5 통합 및 테스트
- [x] App.tsx에 라우트 추가
- [x] 네비게이션 메뉴 추가
- [x] Context Provider 연결
- [x] 개발 서버 테스트
- [x] 에러 케이스 테스트
  - [x] 네트워크 에러
  - [x] 인증 만료
  - [x] 레벨 부족
  - [x] 서버 에러

### 5.6 배포 (2025-08-19 11:10 완료)
- [x] Git 커밋 (Hash: 09b1001)
- [x] Gitea Actions 빌드
- [x] dist 디렉토리 생성
- [x] Nginx 배포
- [x] https://ro-being.com/inventory 접속 확인

---

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

### 6.1 라우팅 규칙 추가
- [x] nginx 설정 수정 (또는 Gateway 코드)
- [x] /api/items/* → robeing-monitor:9024 프록시
- [x] 헤더 전달 설정
- [x] CORS 설정

### 6.2 인증 미들웨어
- [x] JWT 검증 로직 확인
- [x] 사용자 정보 전달
- [x] 에러 응답 표준화

---

## 7. 통합 테스트

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

### 7.2 부하 테스트
- [ ] 동시 사용자 테스트
- [ ] API 응답 시간 측정
- [ ] 에러율 확인

### 7.3 보안 테스트
- [ ] 토큰 노출 확인
- [ ] SQL 인젝션 테스트
- [ ] 권한 우회 시도

---

## 8. 문서화

### 8.1 API 문서
- [ ] Swagger/OpenAPI 스펙 작성
- [ ] 요청/응답 예시 추가
- [ ] 에러 코드 정리

### 8.2 운영 가이드
- [ ] 배포 절차
- [ ] 모니터링 방법
- [ ] 트러블슈팅 가이드

### 8.3 사용자 가이드
- [ ] Gmail 아이템 사용법
- [ ] 재인증 방법
- [ ] FAQ

---

## 완료 기준

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

---

**총 작업 항목: 약 150개**
**완료된 항목: 약 115개 (77%)**
**남은 주요 작업:**
- rb8001 Gmail 통합 (섹션 4)
- rb10508_micro 아이템 확인 미들웨어 (섹션 4-1.3)
- 사용자 이름→이메일 매핑 (섹션 4-1.5)
- 문서화 (섹션 8)

---

**문서 끝**