🚀 Deploy 20260118-v1.0.1

CHANGELOG.json

@@ -1,11 +1,36 @@
 {
   "metadata": {
-    "lastUpdated": "2026-01-18T12:11:27Z",
-    "currentVersion": "0.1.3",
+    "lastUpdated": "2026-01-18T12:31:21Z",
+    "currentVersion": "1.0.1",
     "projectType": "python",
-    "totalReleases": 5
+    "totalReleases": 6
   },
   "releases": [
+    {
+      "version": "1.0.1",
+      "project_type": "python",
+      "date": "2026-01-18",
+      "pr_number": 15,
+      "raw_summary": "## Summary by CodeRabbit\n\n* **새로운 기능**\n  * Geocoding API 엔드포인트 추가 - 주소를 좌표(위도/경도)로 변환\n  * 카카오맵 및 Nominatim 제공자 지원\n  * 다중 제공자 자동 폴백 기능\n  * 장소 정보의 누락된 좌표 자동 채우기\n\n* **업데이트**\n  * 버전 1.0.1 출시",
+      "parsed_changes": {
+        "새로운_기능": {
+          "title": "새로운 기능",
+          "items": [
+            "Geocoding API 엔드포인트 추가 - 주소를 좌표(위도/경도)로 변환",
+            "카카오맵 및 Nominatim 제공자 지원",
+            "다중 제공자 자동 폴백 기능",
+            "장소 정보의 누락된 좌표 자동 채우기"
+          ]
+        },
+        "업데이트": {
+          "title": "업데이트",
+          "items": [
+            "버전 1.0.1 출시"
+          ]
+        }
+      },
+      "parse_method": "markdown"
+    },
     {
       "version": "0.1.3",
       "project_type": "python",

CHANGELOG.md

@@ -1,7 +1,22 @@
 # Changelog
 
-**현재 버전:** 0.1.3  
-**마지막 업데이트:** 2026-01-18T12:11:27Z  
+**현재 버전:** 1.0.1  
+**마지막 업데이트:** 2026-01-18T12:31:21Z  
+
+---
+
+## [1.0.1] - 2026-01-18
+
+**PR:** #15  
+
+**새로운 기능**
+- Geocoding API 엔드포인트 추가 - 주소를 좌표(위도/경도)로 변환
+- 카카오맵 및 Nominatim 제공자 지원
+- 다중 제공자 자동 폴백 기능
+- 장소 정보의 누락된 좌표 자동 채우기
+
+**업데이트**
+- 버전 1.0.1 출시
 
 ---
 

CLAUDE.md

@@ -96,6 +96,53 @@ URL → sns_router → get_audio → get_transcription (STT) → get_video_narra
 - `ocrText`: 비디오 텍스트 (현재 비활성화)
 - `result`: 최종 추출된 장소들
 
+## 공통 유틸리티 사용 가이드
+
+새로운 기능 구현 시 `src/utils/common.py`의 공통 함수를 우선 사용합니다.
+
+### HTTP 요청 (외부 API 호출)
+
+외부 API 호출 시 반드시 `http_get_json()` 사용:
+
+```python
+from src.utils.common import http_get_json
+
+# ✅ 올바른 사용
+data = await http_get_json(
+    url="https://api.example.com/data",
+    params={"query": "value"},
+    headers={"Authorization": "Bearer token"},
+    timeout=10.0  # 기본 10초
+)
+
+# ❌ 직접 httpx 사용 금지
+async with httpx.AsyncClient() as client:
+    response = await client.get(url)  # 타임아웃, 예외처리 누락 위험
+```
+
+**장점**:
+- 타임아웃 자동 적용 (기본 10초)
+- 예외 처리 일관성 (TimeoutException, HTTPStatusError, RequestError)
+- CustomError로 변환되어 API 레이어에서 처리 용이
+
+### API Key 검증
+
+```python
+from src.utils.common import verify_api_key
+from fastapi import Depends
+
+@router.post("/endpoint")
+async def endpoint(api_key: str = Depends(verify_api_key)):
+    # X-API-Key 헤더 자동 검증
+```
+
+### 기타 유틸리티
+
+- `validate_url_length()`: URL 길이 검증
+- `mask_sensitive_data()`: 로그 출력 시 민감 데이터 마스킹
+- `convert_to_bytesio()`: bytes/BytesIO 타입 변환
+- `validate_image_stream()`: 이미지 스트림 유효성 검증
+
 ## 설정
 
 `.env`에 필요한 환경 변수:
@@ -104,6 +151,7 @@ URL → sns_router → get_audio → get_transcription (STT) → get_video_narra
 - `YOUTUBE_API_KEY`: YouTube Data API 키
 - `INSTAGRAM_POST_DOC_ID`, `INSTAGRAM_APP_ID`: Instagram API 설정
 - `BACKEND_CALLBACK_URL`, `BACKEND_API_KEY`: 콜백 엔드포인트 설정
+- `KAKAO_REST_API_KEY`: 카카오 로컬 API 키 (Geocoding 용)
 - `SMB_*`: SMB 파일 서버 설정 (선택사항)
 
 ## 참고사항

src/apis/geocoding_router.py

@@ -0,0 +1,42 @@
+"""src.apis.geocoding_router
+Geocoding API 라우터 - 주소 → 위도/경도 변환
+"""
+import logging
+
+from fastapi import APIRouter, Depends, HTTPException
+
+from src.models.geocoding_models import GeocodingRequest, GeocodingResponse
+from src.services.geocoding_service import geocode_with_kakao
+from src.utils.common import verify_api_key
+from src.core.exceptions import CustomError
+
+logger = logging.getLogger(__name__)
+router = APIRouter(prefix="/api", tags=["Geocoding API"])
+
+
+@router.post("/geocode", response_model=GeocodingResponse, status_code=200)
+async def geocode(
+    request: GeocodingRequest,
+    api_key: str = Depends(verify_api_key)
+):
+    """
+    주소를 위도/경도로 변환 (카카오 API)
+
+    - 인증: X-API-Key 헤더 필요
+    - POST /api/geocode
+    - Body: {"address": "서울시 강남구 테헤란로 123"}
+    - 성공: 200 + GeocodingResponse
+    - 실패: 404 (주소 못 찾음), 401 (인증 실패)
+    """
+    logger.info(f"Geocoding 요청: address='{request.address}'")
+
+    try:
+        result = await geocode_with_kakao(request.address)
+        return GeocodingResponse(
+            address=request.address,
+            latitude=result.latitude,
+            longitude=result.longitude,
+            provider=result.provider
+        )
+    except CustomError as error:
+        raise HTTPException(status_code=404, detail=error.message)

src/apis/test_router.py

@@ -2,12 +2,22 @@
 테스트 API 라우터 - SNS 스크래핑 테스트용
 """
 import logging
-from fastapi import APIRouter
+from fastapi import APIRouter, HTTPException
 from pydantic import BaseModel, Field
 
 from src.services.scraper.scrape_router import route_and_scrape
 from src.services.scraper.platforms.naver_map_scraper import NaverMapScraper
 from src.services.scraper.platforms.google_map_scraper import GoogleMapScraper
+from src.models.geocoding_models import (
+    GeocodingTestRequest,
+    GeocodingResponse,
+    GeocodingProvider
+)
+from src.services.geocoding_service import (
+    geocode_with_kakao,
+    geocode_with_nominatim
+)
+from src.core.exceptions import CustomError
 
 logger = logging.getLogger(__name__)
 router = APIRouter(prefix="/api/test", tags=["테스트 API"])
@@ -103,3 +113,32 @@ async def scrape_google_map(request: GoogleMapSearchRequest):
 
     logger.info(f"스크래핑 완료: {result.name} ({result.place_id})")
     return result
+
+
+@router.post("/geocode", response_model=GeocodingResponse, status_code=200)
+async def test_geocode(request: GeocodingTestRequest):
+    """
+    주소를 위도/경도로 변환 (테스트용 - provider 선택 가능)
+
+    - POST /api/test/geocode
+    - Body: {"address": "서울시 강남구", "provider": "kakao"}
+    - provider: "kakao" (기본) | "nominatim"
+    - 성공: 200 + GeocodingResponse
+    - 실패: 404 (주소 못 찾음)
+    """
+    logger.info(f"Geocoding 테스트 요청: address='{request.address}', provider='{request.provider.value}'")
+
+    try:
+        if request.provider == GeocodingProvider.KAKAO:
+            result = await geocode_with_kakao(request.address)
+        else:
+            result = await geocode_with_nominatim(request.address)
+
+        return GeocodingResponse(
+            address=request.address,
+            latitude=result.latitude,
+            longitude=result.longitude,
+            provider=result.provider
+        )
+    except CustomError as error:
+        raise HTTPException(status_code=404, detail=error.message)

src/core/config.py

@@ -13,6 +13,9 @@ class Settings(BaseSettings):
     BACKEND_API_KEY: str
     ENVIRONMENT: str = "dev"  # dev: 로컬, prod: 서버환경
 
+    # 카카오 API
+    KAKAO_REST_API_KEY: str
+
     # SMB 설정
     SMB_HOST: str = ""
     SMB_PORT: int = 445
@@ -22,5 +25,5 @@ class Settings(BaseSettings):
     SMB_REMOTE_DIR: str = ""  # 원격 디렉토리 경로 (예: "romrom/images")
     SMB_DOMAIN: str = ""  # 도메인 (선택적)
 
-    model_config = SettingsConfigDict(env_file=".env")
+    model_config = SettingsConfigDict(env_file=".env", extra="ignore")
 settings = Settings()

src/main.py

@@ -8,6 +8,7 @@
 from src.core.logging import setup_logging
 from src.apis.place_router import router as place_router
 from src.apis.test_router import router as test_router
+from src.apis.geocoding_router import router as geocoding_router
 
 # 로깅 초기화
 setup_logging(log_level="INFO")
@@ -47,6 +48,7 @@ async def lifespan(app: FastAPI):
 # 라우터 등록
 app.include_router(place_router)
 app.include_router(test_router)
+app.include_router(geocoding_router)
 
 
 @app.middleware("http")

src/models/geocoding_models.py

@@ -0,0 +1,33 @@
+"""src.models.geocoding_models
+Geocoding API 요청/응답 스키마
+"""
+from enum import Enum
+from pydantic import BaseModel, Field
+
+
+class GeocodingProvider(str, Enum):
+    """Geocoding 제공자"""
+    KAKAO = "kakao"
+    NOMINATIM = "nominatim"
+
+
+class GeocodingRequest(BaseModel):
+    """메인 API 요청 (카카오 전용)"""
+    address: str = Field(..., description="변환할 주소", min_length=1)
+
+
+class GeocodingTestRequest(BaseModel):
+    """테스트 API 요청 (provider 선택 가능)"""
+    address: str = Field(..., description="변환할 주소", min_length=1)
+    provider: GeocodingProvider = Field(
+        default=GeocodingProvider.KAKAO,
+        description="Geocoding 제공자 선택"
+    )
+
+
+class GeocodingResponse(BaseModel):
+    """Geocoding 응답"""
+    address: str = Field(..., description="입력된 주소")
+    latitude: float = Field(..., description="위도")
+    longitude: float = Field(..., description="경도")
+    provider: str = Field(..., description="사용된 제공자")