DOCS/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 서버 작업**:
```sql
-- 생성된 테이블들
- robeing_stats (레벨 관리)
- gmail_token (is_equipped, equipped_to 컬럼 추가)
- gmail_audit_logs (감사 로그)
```

**Gateway 수정**:
```python
# 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)**:
```yaml
# ❌ 잘못된 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 구조**:
```bash
# 개별 URL 변수 사용
BRAIN_SERVICE_URL=http://localhost:8001
SKILL_EMAIL_URL=http://localhost:8501
# (ROBEING_URLS, SKILL_URLS 형태 아님)
```

## 오전 10시 00분

### 2차 YAML 오류 (line 157)

**문제**: heredoc 종료 태그 들여쓰기 오류
```yaml
# ❌ 잘못된 종료
            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 주의사항**:
```yaml
# 올바른 heredoc 사용법
ssh user@host << 'DELIMITER'
  명령들...
DELIMITER  # 시작과 같은 들여쓰기
```

### 2. **환경변수 관리**

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

### 3. **브랜치 전략**

```yaml
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 시도

### 해결
```typescript
// 잘못된 코드
import { useNavigate } from 'react-router-dom';

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

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

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

### 빌드 테스트
```bash
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`