docs: Add troubleshooting for Google login CORS and routing fix (2025-11-14)

troubleshooting/251114_google_login_cors_routing_fix.md

@@ -0,0 +1,104 @@
+# Google 로그인 CORS 및 라우팅 문제 해결
+
+**날짜**: 2025-11-14
+**작성자**: admin
+**관련 파일**: 
+- `auth-server/app/main.py`
+- `auth-server/app/routes/auth.py`
+- `auth-server/.env`
+
+---
+
+## 문제 상황
+
+### 1. OPTIONS Preflight 400 Bad Request
+프론트엔드(https://ro-being.com)에서 Google 로그인 후 `/auth/verify` 엔드포인트 호출 시 CORS preflight (OPTIONS) 요청이 400 에러 발생
+
+**에러 로그**:
+```
+INFO:     172.21.0.1:44082 - "OPTIONS /auth/verify HTTP/1.0" 400 Bad Request
+```
+
+**원인**:
+- CORS_ALLOW_ORIGINS에 `https://ro-being.com`이 누락됨
+- 설정된 origin: host.docker.internal, api.ro-being.com, auth.ro-being.com만 허용
+
+### 2. /auth/verify 라우트 404 Not Found
+프론트엔드에서 `/auth/verify` 호출 시 라우트를 찾지 못함
+
+**원인**:
+- auth router에 prefix가 설정되지 않음 (main.py:100)
+- routes/auth.py에서 `/auth/verify`로 중복 prefix 사용 (15, 20번째 줄)
+- 실제 경로: `/auth/auth/verify`로 매칭 실패
+
+## 해결 방안
+
+### 1. 라우팅 구조 수정
+
+**main.py:100** - auth router에 prefix 추가:
+```python
+# Before: app.include_router(auth.router, tags=["Auth"])
+# After:
+app.include_router(auth.router, prefix="/auth", tags=["Auth"])
+```
+
+**routes/auth.py:15, 20, 82** - 중복 prefix 제거:
+```python
+# Before: @router.options("/auth/verify")
+# After:
+@router.options("/verify")
+
+# Before: @router.post("/auth/verify")
+# After:
+@router.post("/verify")
+
+# Before: @router.get("/auth/health")
+# After:
+@router.get("/health")
+```
+
+### 2. CORS 설정 업데이트
+
+**auth-server/.env:70, 77** - ro-being.com 도메인 추가:
+```bash
+# Before:
+CORS_ALLOW_ORIGINS=http://host.docker.internal:3000,...,https://auth.ro-being.com
+
+# After:
+CORS_ALLOW_ORIGINS=https://ro-being.com,http://host.docker.internal:3000,...,https://auth.ro-being.com
+```
+
+## 구현 완료
+
+**커밋**: `2dd1fb2`
+**일시**: 2025-11-14 16:08 KST
+**브랜치**: main
+
+**테스트 결과**:
+```bash
+$ curl -i -X OPTIONS https://auth.ro-being.com/auth/verify \
+  -H "Origin: https://ro-being.com"
+
+HTTP/2 200
+access-control-allow-origin: https://ro-being.com
+access-control-allow-credentials: true
+access-control-allow-methods: GET, POST, OPTIONS, PUT, DELETE, PATCH
+```
+
+## 교훈
+
+### 1. FastAPI 라우터 prefix 설계
+- 라우터 등록 시 prefix를 사용하면 개별 라우트는 상대 경로만 사용
+- 중복 prefix 방지를 위해 라우터 계층 구조 명확히 설계 필요
+- 참고: `311_FastAPI_구조_원칙.md`
+
+### 2. CORS 설정 검증
+- 새 도메인 배포 시 CORS_ALLOW_ORIGINS에 반드시 추가
+- OPTIONS preflight 요청은 실제 요청 전에 발생하므로 우선 검증 필요
+- nginx와 FastAPI 양쪽에서 CORS 처리 가능하나 FastAPI 레벨에서 처리 권장
+
+### 3. .env 파일 동기화
+- docker compose restart는 .env 변경사항을 반영하지 않음
+- .env 수정 후 반드시 `docker compose down && up -d` 실행 필요
+- 환경변수 변경은 컨테이너 재생성 필수
+