⚙️ [기능추가][AI][Callback] AI서버 장소추출 구현완료에 따른 콜백 api 개발 필요

[Cassiiopeia]

📝 현재 문제점

• ⚙️ [기능추가][BE-Callback] 백엔드의 /api/ai/callback 연동 API 개발 필요 MapSy-AI#22
• AI 서버가 작업 완료했습니다

🛠️ 해결 방안 / 제안 기능

• 백엔드 서버는 이제 AI서버가 주는 장소정보 SNS 정보를 저장만 하면됩니다
• 기존처럼 백엔드에서 위도경도 그런 정보를 따로 추출할 필요는 없습니다

🙋‍♂️ 담당자

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

[Cassiiopeia]

Guide by SUH-LAB

브랜치

20260127_16_AI서버_장소추출_구현완료에_따른_콜백_api_개발_필요

커밋 메시지

AI서버 장소추출 구현완료에 따른 콜백 api 개발 필요 : feat : {변경 사항에 대한 설명} https://github.com/MapSee-Lab/MapSy-BE/issues/16

[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

[Cassiiopeia]

@suh-lab server build

[github-actions]

❌ 브랜치를 찾을 수 없습니다

항목	값
Issue	#16
브랜치	20260127_#16_AI서버_장소추출_구현완료에_따른_콜백_api_개발_필요

💡 확인 사항

1. 브랜치가 push되었는지 확인하세요
2. 브랜치명이 정확한지 확인하세요
3. 브랜치가 삭제되지 않았는지 확인하세요

---

🤖 이 댓글은 Preview 시스템에 의해 자동 생성되었습니다.

[Cassiiopeia]

@suh-lab server build

[github-actions]

❌ Issue Preview 배포 실패!

브랜치: 20260127_16_AI서버_장소추출_구현완료에_따른_콜백_api_개발_필요

단계	상태	소요 시간
🔨 프로젝트 빌드	✅ 완료	1분 24초
🐳 Docker 이미지 생성	✅ 완료	46초
🚀 서버 배포 & Health Check	❌ 실패	-

📋 빌드/배포 로그 확인

🔍 가능한 원인

• Gradle 빌드 실패
• Docker 이미지 빌드 실패
• 컨테이너 시작 실패 (Spring Boot 기동 오류)
• Health Check 타임아웃 (120초 내 기동 완료 안됨)

💡 다음 단계

1. 위 링크에서 빌드/배포 로그를 확인하세요
2. 문제를 수정한 후 다시 시도하세요: @suh-lab server build

---

🤖 이 댓글은 Issue Preview 시스템에 의해 자동 생성되었습니다.