Mina Choi
6784e59ca5
git 저장소가 없어 히스토리·협업 기반이 아예 없던 상태를 연다.
함께 문서를 재편했다. 그동안 문서가 있어도 "이 제품이 뭘 푸는가"와
"어떻게 도는가"를 담은 문서가 없어서, 목표 문장이 backend/frontend
README 두 곳에 복붙돼 있었다 — 상위 문서가 없어 아래로 샌 것이다.
신설
README.md 레포 진입점 + 문서 지도 + 문서 규칙 4가지
AGENTS.md 에이전트·신규 합류자용 함정 목록과 규약
(CLAUDE.md 는 여기로 걸린 심볼릭 링크)
docs/PRODUCT.md 제품 정의 — 문제·사용자·원칙·**non-goals**·성공 기준
docs/ARCHITECTURE.md payload 경계·발행 파이프라인·서빙 결정·앱 분리 설계
이동
backend/docs/DECISIONS.md → docs/DECISIONS.md
백엔드만의 결정이 아니다. 게다가 코드 주석 ~25곳이 이미
`docs/DECISIONS.md` 로 적고 있어 레포 루트 기준으로는 그게 맞다.
갱신
docs/DEPLOY.md 서빙 결정 반영 — nginx 정적 서빙이 지금 경로(3절),
Azure 는 나중에 켤 때(4절)로 분리
docs/ARCHITECTURE.md 사이트 = 한 장(2026-08-31) 구조 반영
docs/COLLECTION_SEO_AEO_FLOW.md
robots.txt·sitemap.xml 은 오리진 루트에만 굽는다는 점 명시
frontend/site/scripts/prerender.ts
헤더 주석의 렌더 보고서 경로가 실제(422줄)와 달라 수정
.gitignore
★ CLAUDE.md 를 더 이상 무시하지 않는다. 에이전트 지침은 팀과 모든
에이전트가 공유하는 규약이라 커밋해야 한다 — 무시하면 클론한 사람이
"배포 후 republish_all.py 필수" 같은 함정을 전달받지 못한다.
개인용 오버라이드는 ~/.claude/CLAUDE.md 에 둔다.
224 lines
8.2 KiB
Python
224 lines
8.2 KiB
Python
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 수
|