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 에 둔다.
110 lines
5.5 KiB
Python
110 lines
5.5 KiB
Python
"""발행 검수 게이트 — 사이트가 나가기 전에 반드시 통과해야 하는 검사.
|
|
|
|
이 파일이 절대규칙 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) -> GateResult:
|
|
"""고유 콘텐츠 품질 진단용. 발행 게이트에서는 더 이상 호출하지 않는다.
|
|
|
|
이 가게에만 있는 것(소개문·FAQ·객실 설명·사진 alt·템플릿 아닌 fact 값)이 0이면
|
|
같은 템플릿 대량 생성으로 보인다. 그건 스팸 판정 대상이고, 판정되면 사이트가 통째로 무의미해진다."""
|
|
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, mismatches: list) -> GateResult:
|
|
"""게이트 전체. **처음 걸린 것에서 멈춘다** — 운영자가 하나씩 고치게 사유를 하나만 준다.
|
|
|
|
순서는 심각도 순: 미검증(클레임) → JSON-LD 불일치(거짓).
|
|
|
|
★ 업종 필수 항목 누락은 **막지 않는다**(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)
|