o2o-site-AEO/solution/backend/services/publish_gate.py

"""발행 검수 게이트 — 사이트가 나가기 전에 반드시 통과해야 하는 검사.

이 파일이 절대규칙 1~3 을 코드로 강제하는 유일한 자리다. 여기를 우회하는 발행 경로를 만들면 안 된다.

    ★ 규칙 1  미검증 fact 는 응답에 포함하지 않는다.
              특히 체크인·취사·반려동물·취소 규정 — 틀린 채로 발행되면 실제 예약 클레임이 난다.
    ★ 규칙 2  고유 콘텐츠가 1건도 없으면 발행 API 가 거부한다. 같은 템플릿 대량 생성은 스팸 판정 대상.
    ★ 규칙 3  구조화 데이터(JSON-LD) 값 = 화면에 보이는 값. 불일치 시 빌드 실패.
    + 업종 스키마의 required 필드가 비면 발행하지 않는다(빈 껍데기 페이지 방지).

게이트는 **판정만** 한다. 스냅샷을 만들거나 빌드하지 않는다 — 그래야 테스트가 쉽고,
빌드 경로가 바뀌어도 규칙은 한 곳에 남는다.
"""
from dataclasses import dataclass, field

from common.category_schema import get_schema
from common.enums import PUBLISHABLE_FACT_STATUSES, FactStatus, PlaceCategory, PublishRejectReason


@dataclass
class GateResult:
    """검수 결과. passed 가 False 면 reason 과 detail 이 publish_logs 에 그대로 실린다."""

    passed: bool
    reason: PublishRejectReason | None = None
    detail: dict = field(default_factory=dict)

    def as_log(self) -> dict:
        return {"reason": self.reason.name if self.reason else None, **self.detail}


def check_facts_verified(facts: list) -> GateResult:
    """★ 규칙 1 — 노출 대상 fact 가 전부 검증됐는가.

    facts 는 '사이트에 실을 예정인' fact 행 목록이다. 하나라도 VERIFIED/CORRECTED 가 아니면 거부한다.
    호출측이 이미 필터링했더라도 여기서 다시 본다 — 필터를 빠뜨린 경로가 생겨도 여기서 막힌다."""
    bad = [
        {"key": f["key"] if isinstance(f, dict) else f.key,
         "status": FactStatus(f["status"] if isinstance(f, dict) else f.status).name}
        for f in facts
        if FactStatus(f["status"] if isinstance(f, dict) else f.status) not in PUBLISHABLE_FACT_STATUSES
    ]
    if bad:
        return GateResult(False, PublishRejectReason.UNVERIFIED_FACT, {"unverified": bad[:20], "count": len(bad)})
    return GateResult(True)


def check_required_fields(category: PlaceCategory, facts: list) -> GateResult:
    """업종 스키마의 required 필드가 다 있는가. 없으면 빈 껍데기 페이지가 된다."""
    schema = get_schema(category)
    required = set(schema.required_keys("place"))
    have = {
        (f["key"] if isinstance(f, dict) else f.key)
        for f in facts
        if str(f["value"] if isinstance(f, dict) else f.value or "").strip()
    }
    missing = sorted(required - have)
    if missing:
        return GateResult(
            False, PublishRejectReason.REQUIRED_FACT_MISSING,
            {"missing": missing, "labels": [schema.get(k).label for k in missing if schema.get(k)]},
        )
    return GateResult(True)


def check_unique_content(unique_content_count: int | None) -> GateResult:
    """렌더러가 '고유 콘텐츠 0건' 으로 거부했을 때 사유 코드를 붙이는 자리.

    evaluate() 는 이걸 부르지 않는다(얇은 콘텐츠로 발행을 막지 않기로 했다).
    부르는 곳은 build_service — 렌더 보고서가 실패로 왔을 때 그 이유를 되짚는다.

    이 가게에만 있는 것(소개문·FAQ·객실 설명·사진 alt·템플릿 아닌 fact 값)이 0이면
    같은 템플릿 대량 생성으로 보인다. 그건 스팸 판정 대상이고, 판정되면 사이트가 통째로 무의미해진다.

    ★ None 은 '0건' 이 아니라 '재지 못했다' 다. 렌더러가 디스크·번들 문제로 죽으면 계수가
      없는 채로 보고서가 온다 — 그걸 0 으로 읽으면 디스크 오류에 NO_UNIQUE_CONTENT 라는
      엉뚱한 사유가 붙는다. 판정하지 않고 통과시키고, 진짜 사유는 report.error 가 말한다."""
    if unique_content_count is None:
        return GateResult(True)
    if unique_content_count <= 0:
        return GateResult(False, PublishRejectReason.NO_UNIQUE_CONTENT, {"unique_content_count": unique_content_count})
    return GateResult(True)


def check_jsonld_matches(mismatches: list) -> GateResult:
    """★ 규칙 3 — 구조화 데이터 값이 화면 값과 같은가.

    JSON-LD 는 AI 검색이 읽는 값이고 화면은 사람이 읽는 값이다. 둘이 다르면
    '검색엔진에만 다른 말을 하는' 상태가 된다 — 클로킹으로 취급될 수 있고, 무엇보다 거짓이다."""
    if mismatches:
        return GateResult(False, PublishRejectReason.JSONLD_MISMATCH, {"mismatches": list(mismatches)[:20]})
    return GateResult(True)


def evaluate(
    category: PlaceCategory, facts: list, unique_content_count: int | None, mismatches: list
) -> GateResult:
    """게이트 전체. **처음 걸린 것에서 멈춘다** — 운영자가 하나씩 고치게 사유를 하나만 준다.

    순서는 심각도 순: 미검증(클레임) → JSON-LD 불일치(거짓).

    ★ unique_content_count 는 받되 여기서 막지 않는다 — 얇은 콘텐츠는 '틀린 것' 이 아니다
      (test_evaluate_does_not_block_thin_content). 실제로 페이지 쓰기를 거부하는 쪽은
      렌더러이고, 그 사유는 build_service 가 check_unique_content 로 되짚어 라벨을 붙인다.

    ★ 업종 필수 항목 누락은 **막지 않는다**(2026-08-27 결정).
      막아야 할 것은 "틀린 정보가 나가는 것"이지 "정보가 덜 찬 것"이 아니다.
      영업시간이 비어 있어도 주소·전화가 확인된 페이지는 그 자체로 쓸모가 있고,
      사장님은 발행 뒤에 언제든 채워 넣을 수 있다(채우면 재빌드된다).
      대신 무엇이 비었는지는 계속 알려준다 — warnings 로 내려보내 화면이 띄운다.
    """
    for result in (
        check_facts_verified(facts),
        check_jsonld_matches(mismatches),
    ):
        if not result.passed:
            return result

    # 통과했지만 비어 있는 필수 항목은 경고로 실어 보낸다(발행은 진행된다).
    required = check_required_fields(category, facts)
    if not required.passed:
        return GateResult(True, None, {"warning": PublishRejectReason.REQUIRED_FACT_MISSING.name,
                                       **(required.detail or {})})
    return GateResult(True)