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

import uuid
from datetime import datetime
from typing import Any, Optional

from pydantic import ConfigDict

from common.enums import (
    BuildStatus,
    JobStatus,
    PlaceCategory,
    PlaceStatus,
    PublishAction,
    PublishRejectReason,
    PublishResult,
    SiteStatus,
)
from common.models.gmodel import Res_PageProtocol, Res_WebPacketProtocol, WebPacketProtocol


class SiteProtocol(WebPacketProtocol):
    pass


class Req_StartBuild(SiteProtocol):
    """정적 빌드 시작.

    publish=true 면 발행 검수 게이트를 통과했을 때 바로 발행까지 한다.
    ★ 게이트를 통과하지 못하면 발행되지 않는다 — 우회 옵션은 없다."""

    publish: bool = False


class Res_StartBuild(Res_WebPacketProtocol):
    job_id: Optional[uuid.UUID] = None
    status: Optional[JobStatus] = None
    created: bool = True


class Req_Rollback(SiteProtocol):
    """예전 버전으로 공개 주소를 되돌린다.

    ★ 재굽기가 아니다 — 대상 버전이 디스크에 아직 있으면 심볼릭 링크만 돌린다. 지워졌으면
      (보관 정책, prerender.ts pruneOldVersions) site_versions.snapshot 으로 다시 굽고 나서
      돌린다. 어느 경우든 게이트를 다시 통과해야 한다(사장님이 이미 확인한 값이라 대개는
      그대로 통과한다)."""

    target_version: int


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

    site_version_id: uuid.UUID
    version: int
    build_status: BuildStatus
    unique_content_count: int = 0
    build_error: Optional[str] = None
    built_at: Optional[datetime] = None
    created_at: Optional[datetime] = None


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

    site_id: uuid.UUID
    place_id: uuid.UUID
    status: SiteStatus
    domain: Optional[str] = None
    # 사장님이 고른 템플릿. 화면이 발행 전에 "지금 어느 템플릿으로 나가는지"를 보여줄 근거다.
    template_id: Optional[str] = None
    # 저장된 디자인(색·서체·섹션). ★ 반드시 응답으로 내려줘야 한다 —
    # 에디터가 다시 열렸을 때 저장된 값을 읽을 곳이 없으면, 저장은 됐는데 화면은 기본값으로 돌아간다.
    # 저장할 때와 같은 모양 그대로 돌려준다(서버가 해석하지 않으므로 변형할 이유도 없다).
    theme: Optional[dict[str, Any]] = None
    current_version_id: Optional[uuid.UUID] = None
    published_at: Optional[datetime] = None
    # 발행 썸네일(Azure Blob 공개 URL). 대표 사진을 옮긴 것이고, 만들지 못했으면 없다.
    thumbnail_url: Optional[str] = None


class MySiteData(WebPacketProtocol):
    """내 사이트 목록의 한 줄 — 사업장(place) + 사이트(site).

    ★ render 는 여기 없다 — 보고서 **파일**을 읽는 값이라 줄 수만큼 파일 IO 가 된다(단건이 소유).
    ★ site_id 아래가 전부 None 이면 아직 사이트가 없는 사업장이다."""

    place_id: uuid.UUID
    name: str
    category: PlaceCategory
    place_status: PlaceStatus
    road_address: Optional[str] = None
    created_at: Optional[datetime] = None

    site_id: Optional[uuid.UUID] = None
    status: Optional[SiteStatus] = None
    domain: Optional[str] = None
    template_id: Optional[str] = None
    published_at: Optional[datetime] = None
    # 목록 카드의 그림. 발행에 성공해야 채워지고, 발행마다 `?v=` 가 바뀐다(site_thumbnail.public_url).
    # Azure 썸네일 저장소가 안 꺼져 있으면(로컬 개발) 빌더가 쓰는 대표 사진으로 대신 채운다
    # (site_service._my_site_row) — 이때는 `?v=` 가 없다.
    thumbnail_url: Optional[str] = None
    # 단건과 같은 규칙 — 노출값이 마지막 빌드보다 나중에 바뀌었으면 재발행 대상이다.
    needs_rebuild: bool = False


class Res_MySites(Res_PageProtocol):
    sites: list[MySiteData] = []


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

    publish_log_id: uuid.UUID
    action: PublishAction
    result: PublishResult
    reject_reason: Optional[PublishRejectReason] = None
    detail: Optional[Any] = None
    created_at: Optional[datetime] = None


class Req_SiteTemplate(SiteProtocol):
    """템플릿 선택 저장.

    ★ 서버는 값을 검증하지 않는다. 템플릿 목록은 프론트(배리에이션 레지스트리)가 소유하므로
      여기서 화이트리스트를 두면 템플릿을 하나 늘릴 때마다 백엔드를 같이 고쳐야 한다.
      잘못된 키가 들어와도 발행 잡이 업종 기본으로 떨어뜨린다 — 화면이 깨지지 않는다."""

    template_id: str = ""


class Req_SiteTheme(SiteProtocol):
    """디자인(색·서체·섹션) 저장. 에디터 좌측 패널과 [디자인] 탭이 만든 결과 그대로 온다.

    ★ Req_SiteTemplate 과 같은 철학이다 — 서버는 값을 해석하지도 검증하지도 않는다.
      섹션 목록도, 배리에이션 키도, 색 토큰 이름도 프론트(배리에이션 레지스트리)가 소유한다.
      여기에 화이트리스트를 두면 프론트에 섹션이나 배리에이션이 하나 늘 때마다 백엔드를 같이 고쳐야 하고,
      그 사이 사장님이 고른 값은 조용히 버려진다. 모르는 값이 들어와도 발행 잡이 업종 기본으로
      떨어뜨리므로 화면은 깨지지 않는다.

    ★ 그래서 필드를 펼치지 않고 dict 하나로 받는다. 계약은 이렇다:
        {"theme": {"colors": {...}, "fontStyle": "...", "look": {...}, "colorPaletteId": "...", "sections": [...]}}
      sections 는 {id, name, enabled, locked, variantId?, body?, data?} 의 목록이고 **배열 순서가 곧 섹션 순서**다
      (별도 order 필드가 없다). variantId·본문 body·붙여넣기 JSON data 는 값이 있을 때만 키가 붙는다.
      pydantic 으로 모양을 고정하면 프론트가 항목을 추가한 순간 백엔드가 그걸 조용히 떨어뜨린다 —
      서버는 배달부지 심판이 아니다.

    ★ colorPaletteId 는 **에디터 복원 전용**이다. 사장님이 고른 색 프리셋 id 이고,
      발행 렌더러는 이걸 안 쓰고 해석된 colors 만 쓴다. DB 에는 저장하고 응답으로도 그대로 돌려주지만,
      발행 payload 의 theme 에는 싣지 않는다 — 발행 계약(SitePayload.SiteTheme)에 없는 필드다.

    ★ templateId 는 이 body 에 없다. sites.template_id 컬럼과 POST /template 이 계속 담당한다 —
      두 곳에 두면 어느 쪽이 진짜인지 갈린다.

    ★ 딱 하나 막는 것은 크기다. 해석하지 않는 값을 그대로 보관한다는 건 곧 무엇이든 들어올 수 있다는
      뜻이라, 상한이 없으면 jsonb 컬럼 하나가 DB 와 스냅샷을 통째로 부풀린다.
      상한(services/site_service._THEME_MAX_BYTES)은 서비스가 직렬화 크기로 잰다 —
      필드 개수로 재면 값 하나가 긴 경우를 못 막는다.
    """

    theme: dict[str, Any] = {}


class RenderStatusData(WebPacketProtocol):
    """정적 페이지가 실제로 구워졌는지. 프리렌더가 남긴 보고서를 그대로 옮긴다.

    ★ 발행 기록(DB)과 실제 페이지(파일)는 다른 곳에 산다. 이게 없으면 프리렌더가 깨져도
      DB 는 "발행됨"이라 말하고 사장님은 [사이트 열기] 를 눌러야 404 로 알게 된다."""

    # PENDING(아직) · STALE(낡음) · OK · FAILED
    state: str = "PENDING"
    rendered_at: Optional[str] = None
    rendered_version: Optional[int] = None
    error: Optional[str] = None


class Res_Site(Res_WebPacketProtocol):
    site: Optional[SiteData] = None
    current_version: Optional[SiteVersionData] = None
    # ★ 노출값이 바뀐 뒤 다시 빌드하지 않았으면 True — 개별 재빌드 대상이라는 표시.
    needs_rebuild: bool = False
    # ★ 빌드(DB)와 렌더(정적 파일)는 다른 단계다. 빌드가 됐다고 페이지가 있는 게 아니다.
    render: RenderStatusData = RenderStatusData()


class Res_SiteVersions(Res_WebPacketProtocol):
    versions: list[SiteVersionData] = []


class Res_PublishLogs(Res_WebPacketProtocol):
    logs: list[PublishLogData] = []


class AuditCheckData(WebPacketProtocol):
    id: str
    group: str
    label: str
    points: int
    earned: int
    status: str
    detail: str
    recommendation: Optional[str] = None


class Res_SeoAudit(Res_WebPacketProtocol):
    seo_score: int = 0
    aeo_score: int = 0
    overall_score: int = 0
    checks: list[AuditCheckData] = []
    summary: dict[str, Any] = {}
    visibility: dict[str, int] = {}
    disclaimer: str = ""


class Req_SiteSlug(SiteProtocol):
    """사이트 주소(네임스페이스) 예약.

    ★ 서버가 상호명으로 자동 확정하지 않는다 — 사장님이 고른다.
      주소는 AI 검색이 색인하는 영구 식별자라, 한 번 정해지면 되돌리는 비용이 사장님 몫이 된다."""

    slug: str = ""


class Res_SlugCheck(Res_WebPacketProtocol):
    """주소 사용 가능 확인. UI 가 타이핑 중에 호출한다."""

    available: bool = False
    # 불가 사유(services/site_slug 의 REASON_*): INVALID_LENGTH / INVALID_FORMAT / RESERVED / TAKEN.
    reason: Optional[str] = None
    # 이름 자체는 멀쩡한데 못 쓰는 경우(예약어·중복)에만 대안을 하나 준다.
    suggestion: Optional[str] = None


class Res_SiteSlug(Res_WebPacketProtocol):
    """주소 저장 결과. 거부됐으면 왜/대안을 check 와 같은 코드로 돌려준다."""

    site: Optional[SiteData] = None
    reason: Optional[str] = None
    suggestion: Optional[str] = None


class Req_SiteStatus(SiteProtocol):
    """발행 상태 전이. ★ 해지는 삭제가 아니라 상태 전이다 —
    색인된 페이지를 갑자기 404 로 만들면 그 자리를 다시 OTA 가 가져간다.

    ★ 기본값을 두지 않는다. SUSPEND 가 기본이던 동안에는 필드 이름을 틀리게 보내도
      (`{"status": 5}` 처럼) 422 가 아니라 **발행 중지가 실행됐다** — 파괴적인 전이가
      '아무것도 안 적었을 때' 의 자리에 있었다(실측 2026-09-15).
      무엇을 할지는 부르는 쪽이 적는다."""

    action: PublishAction


class ShowcaseItem(WebPacketProtocol):
    """랜딩 쇼케이스 카드 한 장. **로그인 없이 나가는 값이다.**

    ★ 여기 있는 것은 전부 이미 발행된 페이지에 적혀 있는 것뿐이다.
      place_id·소유자·전화번호·상세 주소는 절대 싣지 않는다 — 사이트 한 곳을 여는 것과
      발행 업소 명단을 통째로 긁는 것은 다른 일이다. 지역도 시·군·구까지만 준다."""

    name: str
    category: PlaceCategory
    # "강원특별자치도 양양군" 수준. 주소를 못 읽으면 없다.
    region: Optional[str] = None
    # 발행 주소. 랜딩과 발행본이 한 오리진이라 루트 상대경로로 준다(`/s/<slug>`).
    url: str
    # 없으면 화면이 글자 카드로 떨어진다(썸네일은 발행의 부수 효과라 실패할 수 있다).
    thumbnail_url: Optional[str] = None


class Res_Showcase(Res_WebPacketProtocol):
    items: list[ShowcaseItem] = []