⚙️ [기능추가][BE-Callback] 백엔드의 /api/ai/callback 연동 API 개발 필요

[Cassiiopeia]

📝 현재 문제점

• 새로운 콜백 모델을 정의하고 url을 통한 sns 의 장소 추출 로직을 현재 구현된 여러 기능을 통합하여 하나의 api로 만들어야함

🛠️ 해결 방안 / 제안 기능

[클라이언트]
    |
    | POST /api/extract-places {contentId, snsUrl}
    v
[place_router.py]
    |
    | asyncio.create_task() → 즉시 {"received": true}
    v
[background_tasks.py::process_extraction_in_background_v2]
    |
    v
[integrated_workflow.py::run_integrated_workflow]
    |
    +---> [1] route_and_scrape(url) → SnsInfo
    |
    +---> [2] extract_place_names_with_ollama(caption) → ["장소1", "장소2"]
    |
    +---> [3] NaverMapScraper.search_and_scrape() → NaverPlaceInfo[]
    |
    v
[콜백 페이로드 변환]
    |
    | NaverPlaceInfo → PlaceDetailCallback
    | SnsInfo → SnsInfoCallback
    v
[send_callback_v2]
    |
    | POST api.mapsy.suhsaechan.kr/api/ai/callback
    v
[백엔드]

🙋‍♂️ 담당자

• 백엔드: @Cassiiopeia
• 프론트엔드: 이름
• 디자인: 이름

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260127_#22_백엔드의_api_ai_callback_연동_API_개발_필요

커밋 메시지

백엔드의 /api/ai/callback  연동 API 개발 필요 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSy-AI/issues/22

[Cassiiopeia]

구현 보고서: 통합 테스트 API (Instagram → LLM → 네이버 지도)

---

📌 작업 개요

Instagram URL만 입력하면 자동으로 장소 정보를 추출하는 통합 파이프라인 테스트 API 구현

• Instagram 파싱 → caption 추출
• Ollama LLM으로 장소명 추출
• 각 장소명을 네이버 지도에서 검색
• 모든 정보를 통합하여 반환

엔드포인트: POST /api/test/integrated-place-search

---

🎯 구현 목표

1. Instagram 게시물에서 caption 추출
2. Ollama LLM(gemma3:1b-it-qat)으로 장소명 추출
3. 추출된 각 장소명을 네이버 지도에서 검색하여 상세 정보 획득
4. SNS 정보 + LLM 추출 결과 + 네이버 지도 정보를 통합 응답

---

✅ 구현 내용

응답 모델 추가

• 파일: src/models/integrated_search.py
• 변경 내용: SnsInfo, IntegratedPlaceSearchResponse Pydantic 모델 생성
• 이유: 통합 파이프라인의 구조화된 응답을 위한 타입 정의

통합 검색 엔드포인트 추가

• 파일: src/apis/test_router.py
• 변경 내용: /integrated-place-search POST 엔드포인트 추가
• 이유: 전체 파이프라인을 단일 API 호출로 테스트 가능하도록 구현

---

🔧 주요 변경사항 상세

SnsInfo 모델

Instagram 메타데이터를 담는 Pydantic 모델

class SnsInfo(BaseModel):
    platform: str           # "instagram"
    content_type: str       # "post", "reel", "igtv"
    url: str                # 원본 URL
    author: str | None      # 작성자
    caption: str | None     # 게시물 본문
    likes_count: int | None # 좋아요 수
    comments_count: int | None
    posted_at: str | None
    hashtags: list[str]
    og_image: str | None
    image_urls: list[str]
    author_profile_image_url: str | None

IntegratedPlaceSearchResponse 모델

통합 검색 결과를 담는 응답 모델

class IntegratedPlaceSearchResponse(BaseModel):
    sns_info: SnsInfo                    # SNS 메타데이터
    extracted_place_names: list[str]     # LLM 추출 장소명
    has_places: bool                     # 장소 존재 여부
    place_details: list[NaverPlaceInfo]  # 네이버 지도 검색 결과
    total_extracted: int                 # 추출된 장소 수
    total_found: int                     # 네이버에서 찾은 장소 수
    failed_searches: list[str]           # 검색 실패한 장소명

통합 검색 파이프라인 (5단계)

Step	작업	로깅
1/5	요청 수신	URL 로깅
2/5	Instagram 파싱	author, caption 길이 로깅
3/5	LLM 장소 추출	추출된 장소 수 로깅
4/5	네이버 지도 검색	각 검색 진행률 및 성공/실패 로깅
5/5	결과 통합	총 추출/발견 수 로깅

특이사항:

• 모든 로깅은 INFO 레벨 사용
• 각 로그에 [통합 검색] Step N/5: 접두사로 진행 상황 추적 가능
• 네이버 지도 검색은 개별 실패 허용 (failed_searches에 기록하고 계속 진행)

---

📦 파일 변경 목록

파일	작업
src/models/integrated_search.py	신규 생성
src/apis/test_router.py	엔드포인트 추가

---

🧪 테스트 및 검증

API 호출 예시

curl -X POST http://localhost:8001/api/test/integrated-place-search \
  -H "Content-Type: application/json" \
  -d '{"url": "https://www.instagram.com/p/ABC123/"}'

기대 응답

{
  "sns_info": {
    "platform": "instagram",
    "content_type": "post",
    "author": "jamsilism",
    "caption": "저장해두면 도움 되는 송파 판초밥 맛집4...",
    "likes_count": 7434,
    "hashtags": ["스시호", "사사노하", "맛집"]
  },
  "extracted_place_names": ["스시호", "사사노하", "김태완스시"],
  "has_places": true,
  "place_details": [
    {
      "place_id": "1234567",
      "name": "스시호",
      "category": "초밥,롤",
      "latitude": 37.5012,
      "longitude": 127.1234,
      "address": "서울 송파구 가락로 98길"
    }
  ],
  "total_extracted": 3,
  "total_found": 2,
  "failed_searches": ["김태완스시"]
}

로그 출력 예시

[통합 검색] Step 1/5: 요청 수신 - url=https://instagram.com/p/...
[통합 검색] Step 2/5: Instagram 파싱 시작
[통합 검색] Step 2/5: Instagram 파싱 완료 - author=jamsilism, caption 길이=234
[통합 검색] Step 3/5: LLM 장소 추출 시작 - caption 길이=234
[통합 검색] Step 3/5: LLM 장소 추출 완료 - 추출된 장소 수=3
[통합 검색] Step 4/5: 네이버 지도 검색 시작 - 검색할 장소 수=3
[통합 검색] Step 4/5: 네이버 지도 검색 (1/3) - query=스시호
[통합 검색] Step 4/5: 검색 성공 - 스시호 (1234567)
[통합 검색] Step 4/5: 네이버 지도 검색 (2/3) - query=사사노하
[통합 검색] Step 4/5: 검색 성공 - 사사노하 (2345678)
[통합 검색] Step 4/5: 네이버 지도 검색 (3/3) - query=김태완스시
[통합 검색] Step 4/5: 검색 실패 - query=김태완스시, error=...
[통합 검색] Step 4/5: 네이버 지도 검색 완료 - 성공=2, 실패=1
[통합 검색] Step 5/5: 결과 통합 완료 - 총 추출=3, 총 발견=2

---

📌 에러 처리 전략

단계	에러 상황	처리 방식
Instagram 파싱	실패	HTTPException(400) - 전체 중단
caption 없음	빈 caption	빈 결과 반환 (정상 응답)
LLM 추출	API 실패	빈 배열 반환 (기존 로직)
네이버 검색	개별 실패	failed_searches에 추가, 계속 진행

핵심 원칙: Instagram 파싱 실패만 전체 중단, 나머지는 부분 실패 허용

---

📌 참고사항

• 응답 시간: 네이버 지도 검색은 Playwright 브라우저 사용으로 장소당 약 5초 소요
• 순차 검색: Playwright 리소스 제한으로 병렬 검색 불가, 순차 처리
• 향후 개선: 브라우저 풀 구현으로 병렬 검색, 캐싱으로 중복 검색 방지 가능

[Cassiiopeia]

MapSy AI 서버 API 문서

📌 개요

MapSy AI 서버는 SNS(Instagram, YouTube) 콘텐츠에서 장소 정보를 자동 추출하는 FastAPI 기반 서비스입니다.
요청은 비동기로 처리되며, 결과는 콜백 URL을 통해 백엔드로 전달됩니다.

---

1. AI 서버 엔드포인트

POST /api/extract-places

SNS 콘텐츠 URL에서 장소 정보를 추출하는 비동기 API

인증

헤더	값	필수
X-API-Key	AI 서버 API Key	✓

요청 본문

{
  "contentId": "550e8400-e29b-41d4-a716-446655440000",
  "snsUrl": "https://www.instagram.com/p/ABC123/"
}

필드	타입	필수	설명
contentId	UUID	✓	콘텐츠 고유 식별자
snsUrl	string	✓	SNS 원본 URL (Instagram, YouTube 등)

즉시 응답 (200 OK)

{
  "received": true,
  "message": "Processing started"
}

에러 응답

상태 코드	설명
401	API Key 누락 또는 불일치

---

2. 콜백 엔드포인트 (백엔드에서 구현 필요)

POST /api/ai/callback

AI 서버가 처리 완료 후 호출하는 콜백

인증

헤더	값
X-API-Key	백엔드 API Key

---

2-1. SUCCESS 콜백

{
  "contentId": "550e8400-e29b-41d4-a716-446655440000",
  "resultStatus": "SUCCESS",
  "snsInfo": {
    "platform": "INSTAGRAM",
    "contentType": "reel",
    "url": "https://www.instagram.com/reel/ABC123/",
    "author": "username",
    "caption": "여기 정말 맛있어! #맛집 #서울",
    "likesCount": 1234,
    "commentsCount": 56,
    "postedAt": "2024-01-15T10:30:00Z",
    "hashtags": ["맛집", "서울"],
    "thumbnailUrl": "https://...",
    "imageUrls": ["https://..."],
    "authorProfileImageUrl": "https://..."
  },
  "placeDetails": [
    {
      "placeId": "11679241",
      "name": "늘푸른목장 잠실본점",
      "latitude": 37.5112,
      "longitude": 127.0867,
      "address": "서울 송파구 백제고분로9길 34 1F",
      "roadAddress": "서울 송파구 백제고분로9길 34 1F",
      "category": "소고기구이",
      "description": "된장찌개와 냉면으로 완성하는 한상차림",
      "rating": 4.42,
      "visitorReviewCount": 1510,
      "blogReviewCount": 1173,
      "businessStatus": "영업 중",
      "businessHours": "24:00에 영업 종료",
      "openHoursDetail": ["월 11:30 - 24:00", "화 11:30 - 24:00"],
      "holidayInfo": "연중무휴",
      "phoneNumber": "02-3431-4520",
      "homepageUrl": "http://example.com",
      "naverMapUrl": "https://map.naver.com/p/search/늘푸른목장/place/11679241",
      "reservationAvailable": true,
      "subwayInfo": "잠실새내역 4번 출구에서 412m",
      "directionsText": "잠실새내역 4번 출구에서 맥도널드 골목 끼고...",
      "amenities": ["단체 이용 가능", "주차", "발렛파킹"],
      "keywords": ["소고기", "한우", "회식"],
      "tvAppearances": ["줄서는식당 14회 (24.05.13)"],
      "menuInfo": ["경주갈비살", "한우된장밥"],
      "imageUrl": "https://...",
      "imageUrls": ["https://..."]
    }
  ],
  "statistics": {
    "extractedPlaceNames": ["늘푸른목장", "강남역"],
    "totalExtracted": 2,
    "totalFound": 1,
    "failedSearches": ["강남역"]
  }
}

---

2-2. FAILED 콜백

{
  "contentId": "550e8400-e29b-41d4-a716-446655440000",
  "resultStatus": "FAILED",
  "snsInfo": null,
  "placeDetails": [],
  "statistics": null,
  "errorMessage": "SNS 스크래핑 실패: 유효하지 않은 URL"
}

---

3. 모델 상세 정의

AiCallbackRequest (콜백 최상위)

필드	타입	필수	설명
contentId	UUID	✓	원본 요청의 contentId
resultStatus	"SUCCESS" | "FAILED"	✓	처리 결과 상태
snsInfo	SnsInfoCallback	SUCCESS 시 필수	SNS 콘텐츠 정보
placeDetails	PlaceDetailCallback[]	-	장소 상세 정보 리스트
statistics	ExtractionStatistics	-	추출 처리 통계
errorMessage	string	FAILED 시	실패 사유

---

SnsInfoCallback

필드	타입	필수	설명
platform	enum	✓	INSTAGRAM, YOUTUBE, YOUTUBE_SHORTS, TIKTOK, FACEBOOK, TWITTER
contentType	string	✓	post, reel, video, shorts 등
url	string	✓	원본 SNS URL
author	string	-	작성자 ID
caption	string	-	게시물 본문
likesCount	integer	-	좋아요 수
commentsCount	integer	-	댓글 수
postedAt	string	-	게시 날짜 (ISO 8601)
hashtags	string[]	-	해시태그 리스트
thumbnailUrl	string	-	대표 이미지 URL
imageUrls	string[]	-	이미지 URL 리스트
authorProfileImageUrl	string	-	작성자 프로필 이미지 URL

---

PlaceDetailCallback

기본 정보

필드	타입	필수	설명
placeId	string	✓	네이버 Place ID
name	string	✓	장소명
category	string	-	카테고리
description	string	-	한줄 설명

위치 정보

필드	타입	설명
latitude	float	위도
longitude	float	경도
address	string	주소
roadAddress	string	도로명 주소
subwayInfo	string	지하철 정보
directionsText	string	찾아가는 길

평점/리뷰

필드	타입	설명
rating	float	별점 (0.0~5.0)
visitorReviewCount	integer	방문자 리뷰 수
blogReviewCount	integer	블로그 리뷰 수

영업 정보

필드	타입	설명
businessStatus	string	영업 상태
businessHours	string	영업 시간 요약
openHoursDetail	string[]	요일별 상세 영업시간
holidayInfo	string	휴무일 정보

연락처/링크

필드	타입	설명
phoneNumber	string	전화번호
homepageUrl	string	홈페이지 URL
naverMapUrl	string	네이버 지도 URL
reservationAvailable	boolean	예약 가능 여부 (기본: false)

부가 정보

필드	타입	설명
amenities	string[]	편의시설 목록
keywords	string[]	키워드/태그
tvAppearances	string[]	TV 방송 출연 정보
menuInfo	string[]	대표 메뉴
imageUrl	string	대표 이미지 URL
imageUrls	string[]	이미지 URL 목록

---

ExtractionStatistics

필드	타입	설명
extractedPlaceNames	string[]	LLM이 추출한 장소명 리스트
totalExtracted	integer	LLM이 추출한 장소 수
totalFound	integer	네이버 지도에서 찾은 장소 수
failedSearches	string[]	검색 실패한 장소명

---

4. 처리 흐름

[백엔드]
    |
    | POST /api/extract-places {contentId, snsUrl}
    | Header: X-API-Key
    v
[AI 서버] ─── 즉시 응답: {"received": true, "message": "Processing started"}
    |
    | 백그라운드 처리
    |
    +─► [1] SNS 스크래핑 (Playwright)
    |        └─► platform, contentType, author, caption 등 추출
    |
    +─► [2] LLM 장소명 추출 (Ollama)
    |        └─► caption에서 장소명 ["장소1", "장소2"] 추출
    |
    +─► [3] 네이버 지도 검색
    |        └─► 각 장소명 검색 → 상세 정보 수집
    |
    v
[AI 서버]
    |
    | POST /api/ai/callback
    | Header: X-API-Key
    v
[백엔드]

---

5. 테스트 방법

cURL 요청 예시

curl -X POST http://localhost:8001/api/extract-places \
  -H "Content-Type: application/json" \
  -H "X-API-Key: {API_KEY}" \
  -d '{
    "contentId": "550e8400-e29b-41d4-a716-446655440000",
    "snsUrl": "https://www.instagram.com/p/ABC123/"
  }'

즉시 응답

{
  "received": true,
  "message": "Processing started"
}

---

6. 참고 사항

항목	내용
콜백 타임아웃	10초
콜백 성공 기준	2xx 상태 코드
빈 배열 처리	null 대신 빈 배열 [] 반환
SUCCESS 필수 필드	snsInfo는 반드시 포함

---

7. 관련 파일

파일	설명
src/apis/place_router.py	/api/extract-places 엔드포인트
src/models/place_extraction_request.py	요청 모델
src/models/callback_request.py	콜백 모델 (AiCallbackRequest, SnsInfoCallback, PlaceDetailCallback 등)
src/services/background_tasks.py	백그라운드 처리 및 콜백 전송
src/services/integrated_workflow.py	통합 파이프라인

---

8. Swagger 문서

• Swagger UI: http://localhost:8001/docs/swagger
• ReDoc: http://localhost:8001/docs/redoc