DOCS/journey/troubleshooting/250819_happybell80_GmailItem구현및GitActions설정.md

Gmail 아이템 구현 및 Gitea Actions 설정 트러블슈팅

날짜: 2025-08-19
작업자: happybell80 & Claude
관련 서비스: robeing-monitor, robeing-gateway, 51123/51124 서버

오전 7시 30분

Gmail 아이템 구현 계획 수립

상황: Gmail OAuth 토큰을 "아이템"으로 관리하는 시스템 구현 필요

구현 계획:

1. robeing-monitor(9024) - 아이템 상태 관리
2. robeing-gateway - API 프록시
3. 프론트엔드 - 인벤토리 UI
4. skill-email - DB 기반 토큰 조회

아키텍처 결정:

프론트 → Gateway(8100) → robeing-monitor(9024)
                           ↓
                    PostgreSQL(gmail_token)

오전 8시 00분

테이블 생성 및 Gateway 수정

51123 서버 작업:

-- 생성된 테이블들
- robeing_stats (레벨 관리)
- gmail_token (is_equipped, equipped_to 컬럼 추가)
- gmail_audit_logs (감사 로그)

Gateway 수정:

# robeing-gateway/app/main.py에 추가
@app.api_route("/api/items/{path:path}", methods=["GET", "POST", "DELETE"])
async def items_proxy(...):
    monitor_url = os.getenv("MONITOR_URL", "http://192.168.219.52:9024")
    # 프록시 로직

오전 8시 30분

robeing-monitor 구현

구현 내용:

• FastAPI 기반 서비스 (포트 9024)
• Gmail 아이템 CRUD API
• PostgreSQL 연결 (asyncpg 사용)
• 레벨 체크 및 장착/해제 로직

주요 API:

• GET /api/items/gmail - 아이템 목록
• POST /api/items/gmail/{user_id}/equip - 장착
• POST /api/items/gmail/{user_id}/unequip - 해제
• POST /api/items/gmail/{user_id}/reauth - 재인증
• DELETE /api/items/gmail/{user_id} - 철회

오전 9시 00분

Gitea Actions 설정 오류 연쇄

1차 오류 - YAML 문법 오류 (line 87):

# ❌ 잘못된 heredoc
cat > .env << 'ENV_FILE'
SERVICE_NAME=robeing-monitor  # 들여쓰기 없음
ENV_FILE

# ✅ 수정된 heredoc
cat > .env << 'ENVFILE'
            SERVICE_NAME=robeing-monitor  # 들여쓰기 추가
            ENVFILE

원인:

• heredoc 구분자에 하이픈 사용 (ENV_FILE)
• heredoc 내용에 들여쓰기 없음

오전 9시 30분

브랜치 및 환경변수 이슈

문제 1 - 브랜치명:

• 로컬: master 브랜치 사용 중
• 원격: main 브랜치 기대
• 해결: git branch -m master main 및 Actions 파일에 둘 다 지원

문제 2 - .env 파일:

• 초기 계획: Actions에서 자동 생성
• 실제: 51124 서버에 이미 .env 존재
• 해결: 자동 생성 코드 제거, 서버 .env 사용

51124 서버 실제 .env 구조:

# 개별 URL 변수 사용
BRAIN_SERVICE_URL=http://localhost:8001
SKILL_EMAIL_URL=http://localhost:8501
# (ROBEING_URLS, SKILL_URLS 형태 아님)

오전 10시 00분

2차 YAML 오류 (line 157)

문제: heredoc 종료 태그 들여쓰기 오류

# ❌ 잘못된 종료
            fi
            
DEPLOY_SCRIPT  # 들여쓰기 없음

# ✅ 올바른 종료
            fi
          DEPLOY_SCRIPT  # 정확한 들여쓰기

핵심 교훈: YAML heredoc 종료 태그는 시작할 때와 동일한 들여쓰기 필요

오전 10시 30분

최종 성공

완료된 작업:

1. ✅ robeing-monitor 서비스 구현
2. ✅ Gateway 프록시 설정
3. ✅ Gitea Actions 파이프라인 구성
4. ✅ 51124 서버 배포 준비

---

교훈

1. Gitea Actions YAML 작성 원칙

필수 사항:

• runs-on: self-hosted (NOT ubuntu-latest)
• SSH 포트 명시 (51124)
• 조직 시크릿 사용
• gitea.event 문법 (NOT github.event)

heredoc 주의사항:

# 올바른 heredoc 사용법
ssh user@host << 'DELIMITER'
  명령들...
DELIMITER  # 시작과 같은 들여쓰기

2. 환경변수 관리

원칙:

• 서버 .env 우선 사용
• Actions에서 .env 생성 지양
• 실제 서버 설정 확인 후 코드 작성

3. 브랜치 전략

on:
  push:
    branches:
      - main      # 우선
      - master    # fallback

4. 트러블슈팅 체크리스트

Gitea Actions 오류 시:

1. YAML 문법 검증: python3 -c "import yaml; yaml.safe_load(open('파일.yml'))"
2. heredoc 들여쓰기 확인
3. 브랜치명 확인
4. runner 설정 확인 (self-hosted)
5. 시크릿 설정 확인

5. 서비스 통합 아키텍처

51123 서버:
  - Gateway(8100) → 라우팅
  - PostgreSQL → 데이터
  
51124 서버:
  - robeing-monitor(9024) → 아이템 관리
  - 로빙들(8001, 10508, 10408)
  - 스킬들(8501, 8505, 8503)

---

다음 단계

1. 51124 서버 배포 확인
2. 프론트엔드 인벤토리 UI 개발
3. skill-email DB 연결 전환
4. 전체 통합 테스트

오전 10시 30분 - 프론트엔드 인벤토리 UI 개발

개발 순서

1. API 클라이언트 확장 (robeing-api.ts)

   • GmailCredentialItem 타입 정의
   • getGmailItems, equipGmailItem, unequipGmailItem, startGmailReauth, revokeGmailItem 함수 구현

2. Context 상태 관리 (item-context.tsx)

   • Redux 패턴으로 전역 상태 관리
   • 장착/해제/재인증/철회 액션 처리

3. UI 컴포넌트 구현

   • GmailPassportCard: 개별 아이템 카드
   • InventoryGrid: 아이템 목록 그리드
   • InventoryPage: 인벤토리 전체 페이지

4. 라우팅 통합

   • /inventory 라우트 추가
   • 게임 대시보드에 "인벤토리 열기" 버튼 추가

오전 10시 56분 - import 오류 수정

문제

Pre-transform error: Failed to resolve import "react-router-dom" from "src/pages/inventory.tsx"

원인

프로젝트에서 wouter 사용 중인데 react-router-dom import 시도

해결

// 잘못된 코드
import { useNavigate } from 'react-router-dom';

// 수정된 코드  
import { useLocation } from 'wouter';
const [, setLocation] = useLocation();

오전 11시 01분 - 보안 및 빌드 검증

console.log 제거

inventory-grid.tsx에서 console.log 2개 제거 (보안 검토)

빌드 테스트

npm run build
# ✓ built in 2.53s
# dist 폴더 정상 생성

오전 11시 03분 - Gitea Actions 설정 재수정

frontend-customer/.gitea/workflows/deploy.yml 수정

1. Line 12: github.ref → gitea.ref 변경
2. Line 63: VITE_API_URL=http://localhost:8001 → VITE_ROBEING_API_URL=https://ro-being.com/gateway 변경

오전 11시 10분 - 배포 완료

배포 결과

• ✅ Gitea Actions 자동 빌드 성공
• ✅ dist 디렉토리 생성 완료
• ✅ https://ro-being.com/inventory 접속 가능
• ✅ 프론트엔드 인벤토리 UI 정상 작동

---

참고 문서

• /plans/250819_gmail_item_implementation_plan.md
• /plans/250819_gmail_item_detailed_tasks.md
• /troubleshooting/250722_happybell80_skill-email_Actions설정실패.md
• /troubleshooting/250714_gitea_actions_setup.md