o2o-site-AEO/solution/backend/router/v1/place/protocol.py

import uuid
from datetime import datetime
from decimal import Decimal
from typing import Optional

from pydantic import ConfigDict

from common.enums import ExternalPlaceSource, JobStatus, LinkChannel, PlaceCategory, PlaceStatus, SourceType
from common.models.gmodel import Res_PageProtocol, Res_WebPacketProtocol, WebPacketProtocol


# 라우터 폴더마다 protocol.py 를 두고 Req_/Res_ 를 정의한다 (protocol 규약).
class PlaceProtocol(WebPacketProtocol):
    pass


class Req_CreatePlace(PlaceProtocol):
    # 상호명 하나로 시작한다. 나머지는 카카오 로컬 검증이 채운다.
    name: str = ""
    category: PlaceCategory = PlaceCategory.LODGING
    owner_user_id: Optional[uuid.UUID] = None


class Req_VerifyPlace(PlaceProtocol):
    """카카오 로컬 조회 결과를 사업장에 박제한다(동일 업소 확정).

    ★ 이 단계를 통과해야 수집이 열린다.
      external_place_id 는 소스에 따라 없을 수 있다 — 네이버는 고유 장소 id 를 주지 않는다.
      그 경우 상호명 + 도로명주소가 중복 판정 키가 되므로 road_address 를 반드시 채워야 한다."""

    source: ExternalPlaceSource = ExternalPlaceSource.NAVER
    external_place_id: str = ""
    # 외부 장소 DB 가 함께 준 업체 홈페이지 URL. 있으면 공식 홈페이지 채널로 자동 등록한다.
    # (네이버 지역검색 응답의 link 가 이것 — Perplexity 로는 잘 안 잡히는 채널이라 여기서 건진다.)
    place_url: Optional[str] = None
    road_address: Optional[str] = None
    address: Optional[str] = None
    phone: Optional[str] = None
    latitude: Optional[Decimal] = None
    longitude: Optional[Decimal] = None
    region_code: Optional[str] = None


class Req_VerifyPlaceByUrl(PlaceProtocol):
    """네이버 플레이스 URL 하나로 동일 업소를 확정한다.

    ★ 왜 이 경로가 필요한가
      상호 검색으로 place id 를 자동 해석하는 경로는 실패한다(실측: '롯데호텔 서울').
      Perplexity 도 네이버 플레이스를 못 찾는다 — 안내 페이지를 물어온 적도 있다.
      그런데 사장님은 **자기 가게 주소를 이미 알고 있다.** 붙여넣게 하는 것이 가장
      정확하고 빠르며, 그 붙여넣기 자체가 "이 가게가 맞다"는 사람의 확인이다.

      서버는 그 URL 로 네이버 상세를 읽어 상호·주소·좌표를 가져온다 — 사장님이 손으로
      옮겨 적게 하지 않는다(오타가 곧 남의 가게가 된다).
    """

    url: str = ""


class Req_UpdatePlace(PlaceProtocol):
    name: Optional[str] = None
    owner_user_id: Optional[uuid.UUID] = None
    status: Optional[PlaceStatus] = None


class Req_CreateUnit(PlaceProtocol):
    name: str = ""
    sort_order: int = 0


class Req_CreateLink(PlaceProtocol):
    channel: LinkChannel = LinkChannel.ETC
    url: str = ""
    title: Optional[str] = None
    discovered_by: SourceType = SourceType.OWNER


class PlaceData(WebPacketProtocol):
    model_config = ConfigDict(from_attributes=True)

    place_id: uuid.UUID
    name: str
    category: PlaceCategory
    status: PlaceStatus
    owner_user_id: Optional[uuid.UUID] = None
    external_source: Optional[ExternalPlaceSource] = None
    external_place_id: Optional[str] = None
    road_address: Optional[str] = None
    address: Optional[str] = None
    phone: Optional[str] = None
    latitude: Optional[Decimal] = None
    longitude: Optional[Decimal] = None
    region_code: Optional[str] = None
    verified_at: Optional[datetime] = None
    content_updated_at: Optional[datetime] = None   # ★ 노출값 변경 시각 — 개별 재빌드 대상 판별
    created_at: Optional[datetime] = None


class UnitData(WebPacketProtocol):
    model_config = ConfigDict(from_attributes=True)

    unit_id: uuid.UUID
    place_id: uuid.UUID
    name: str
    sort_order: int = 0


class LinkData(WebPacketProtocol):
    model_config = ConfigDict(from_attributes=True)

    link_id: uuid.UUID
    place_id: uuid.UUID
    channel: LinkChannel
    url: str
    title: Optional[str] = None
    discovered_by: SourceType
    discovered_at: Optional[datetime] = None
    confirmed_at: Optional[datetime] = None   # ★ NULL = 크롤링 대상 아님


class Res_PlaceList(Res_PageProtocol):
    places: list[PlaceData] = []


class Res_Place(Res_WebPacketProtocol):
    place: Optional[PlaceData] = None


class Res_UnitList(Res_WebPacketProtocol):
    units: list[UnitData] = []


class Res_Unit(Res_WebPacketProtocol):
    unit: Optional[UnitData] = None


class Res_LinkList(Res_WebPacketProtocol):
    links: list[LinkData] = []
    confirmed: int = 0    # 크롤링 가능한 링크 수


class Res_Link(Res_WebPacketProtocol):
    link: Optional[LinkData] = None


class Req_StartCollect(PlaceProtocol):
    """수집 시작. 몇 분 걸리므로 동기로 처리하지 않고 잡을 적재한 뒤 즉시 응답한다."""

    # 확정된 채널 URL 만 크롤링한다. 비우면 이 사업장의 확정 링크 전체.
    link_ids: list[uuid.UUID] = []
    # 이미 확보한 fact 를 다시 긁을지. 기본은 아니오(외부 API 호출 비용을 아낀다).
    force: bool = False
    # 상호·주소로 공개 채널 URL 을 Perplexity 에서 추가 탐색할지.
    # 기본 False — 사용자가 화면에서 명시적으로 선택한 회차에만 유료 검색을 실행한다.
    discover_channels: bool = False


class Res_StartCollect(Res_WebPacketProtocol):
    """수집 잡 적재 결과. 클라이언트는 job_id 로 GET /v1/job/{job_id} 를 폴링한다."""

    job_id: Optional[uuid.UUID] = None
    status: Optional[JobStatus] = None
    # 이미 같은 사업장 수집이 돌고 있어 새로 만들지 않았다면 False (기존 잡의 id 를 돌려준다).
    created: bool = True
    confirmed_links: int = 0


class Req_StartVision(PlaceProtocol):
    """사진 분석 시작. 사진 20~50장이라 몇 분 걸린다 — 잡으로 처리한다."""

    # 이미 분석된 사진도 다시 태울지. 기본은 아니오(같은 사진 재분석은 요금만 나간다).
    force: bool = False


class Res_StartVision(Res_WebPacketProtocol):
    job_id: Optional[uuid.UUID] = None
    status: Optional[JobStatus] = None
    created: bool = True
    pending_media: int = 0    # 분석 대상 사진 수


# ---- 동일 업소 후보 (UI 가 사람에게 고르게 한다) ----------------------------
class PlaceCandidate(WebPacketProtocol):
    """외부 장소 DB 에서 찾은 후보 1건. UI 가 이걸 카드로 그려 사람이 고른다."""

    external_place_id: Optional[str] = None   # 네이버는 안 준다
    name: str = ""
    road_address: Optional[str] = None
    address: Optional[str] = None
    phone: Optional[str] = None               # 네이버는 안 준다
    latitude: Optional[Decimal] = None
    longitude: Optional[Decimal] = None
    category_name: Optional[str] = None
    place_url: Optional[str] = None           # 업체 홈페이지 — 확정 시 공식 채널로 등록된다
    naver_place_url: Optional[str] = None     # 자동 발견한 네이버 플레이스. 없으면 UI가 URL 입력을 요청한다


class Res_VerifyCandidates(Res_WebPacketProtocol):
    """동일 업소 후보 목록.

    ★ 자동 판정을 신뢰하지 않는다. outcome 이 MATCHED 여도 후보를 전부 내려보내
      UI 가 사람에게 확인시킬 수 있게 한다 — 남의 가게가 섞이면 그게 제일 비싼 실수다."""

    source: Optional[ExternalPlaceSource] = None
    outcome: str = ""            # matched | ambiguous | no_candidate
    reason: Optional[str] = None  # 판정 근거(name_exact / name_duplicate / name_no_exact …)
    auto_selectable: bool = False  # True 면 UI 가 '이거 맞나요?' 한 번만 물어도 된다
    candidates: list[PlaceCandidate] = []


class Req_StartCopy(PlaceProtocol):
    """소개문·FAQ 생성 시작.

    ★ 확인된 fact 만 근거로 쓴다. 근거가 없으면 생성하지 않는다(유료 호출조차 안 한다)."""

    pass


class Res_StartCopy(Res_WebPacketProtocol):
    job_id: Optional[uuid.UUID] = None
    status: Optional[JobStatus] = None
    created: bool = True
    grounded_facts: int = 0   # 근거로 쓸 수 있는 확인된 fact 수