diff --git a/plans/250819_gmail_item_detailed_tasks.md b/plans/250819_gmail_item_detailed_tasks.md new file mode 100644 index 0000000..d8ab869 --- /dev/null +++ b/plans/250819_gmail_item_detailed_tasks.md @@ -0,0 +1,359 @@ +# 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 시나리오 +- [ ] 로그인 → 인벤토리 조회 +- [ ] Gmail 아이템 장착 +- [ ] 이메일 발송 요청 +- [ ] 토큰 만료 → 재인증 +- [ ] 아이템 철회 + +### 7.2 부하 테스트 +- [ ] 동시 사용자 테스트 +- [ ] API 응답 시간 측정 +- [ ] 에러율 확인 + +### 7.3 보안 테스트 +- [ ] 토큰 노출 확인 +- [ ] SQL 인젝션 테스트 +- [ ] 권한 우회 시도 + +--- + +## 8. 문서화 + +### 8.1 API 문서 +- [ ] Swagger/OpenAPI 스펙 작성 +- [ ] 요청/응답 예시 추가 +- [ ] 에러 코드 정리 + +### 8.2 운영 가이드 +- [ ] 배포 절차 +- [ ] 모니터링 방법 +- [ ] 트러블슈팅 가이드 + +### 8.3 사용자 가이드 +- [ ] Gmail 아이템 사용법 +- [ ] 재인증 방법 +- [ ] FAQ + +--- + +## 완료 기준 + +- [ ] 모든 테스트 통과 +- [ ] 프로덕션 배포 완료 +- [ ] 문서 작성 완료 +- [ ] 사용자 피드백 수집 + +--- + +**총 작업 항목: 약 150개** +**예상 소요 시간: 각 항목 평균 30분 = 약 75시간** + +--- + +**문서 끝** \ No newline at end of file