docs: Gmail 아이템 구현 및 Gitea Actions 트러블슈팅 문서 작성

- robeing-monitor 구현 과정
- Gitea Actions YAML 오류 해결
- heredoc 들여쓰기 이슈 정리
- 환경변수 관리 교훈

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

@@ -0,0 +1,210 @@
+# 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_tokens)
+```
+
+## 오전 8시 00분
+
+### 테이블 생성 및 Gateway 수정
+
+**51123 서버 작업**:
+```sql
+-- 생성된 테이블들
+- robeing_stats (레벨 관리)
+- gmail_tokens (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
+# (ROBING_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. 전체 통합 테스트
+
+---
+
+## 참고 문서
+
+- `/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`