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

"""발행 사이트 SEO/AEO 준비도 채점.

점수는 검색 순위를 보장하는 외부 공인 점수가 아니라, 우리 빌더가 통제할 수 있는 신호의
완성도다. 같은 입력은 언제나 같은 결과를 내도록 순수 함수로 두어 UI와 발행 흐름이 서로
다른 기준을 말하지 않게 한다.
"""
from dataclasses import dataclass


@dataclass(frozen=True)
class AuditCheck:
    id: str
    group: str
    label: str
    points: int
    earned: int
    status: str
    detail: str
    recommendation: str | None = None

    def as_dict(self) -> dict:
        return self.__dict__.copy()


def _check(id, group, label, points, passed, detail, recommendation=None, partial=0):
    earned = points if passed else min(points, max(0, partial))
    status = "pass" if earned == points else ("warn" if earned > 0 else "fail")
    return AuditCheck(id, group, label, points, earned, status, detail, recommendation)


def evaluate(snapshot: dict, *, verified: bool, site=None, version=None, ai_checks: list | None = None) -> dict:
    place = snapshot.get("place") or {}
    facts = snapshot.get("facts") or []
    faqs = snapshot.get("faqs") or []
    media = snapshot.get("media") or []
    built = bool(version and getattr(version, "built_at", None))
    unique_count = int(getattr(version, "unique_content_count", 0) or 0) if version else 0
    domain = (getattr(site, "domain", None) or "").strip() if site else ""
    fact_count = len([f for f in facts if str(f.get("value") or "").strip()])
    sourced = len([f for f in facts if f.get("source_url") or f.get("verified_at")])
    image_with_alt = len([m for m in media if str(m.get("alt_text") or "").strip()])

    seo = [
        _check("built", "기술 SEO", "정적 HTML 빌드", 15, built,
               "크롤러가 자바스크립트 없이 읽을 수 있는 발행본이 있습니다." if built else "아직 빌드된 정적 발행본이 없습니다.",
               "사이트를 빌드·발행하세요."),
        _check("domain", "기술 SEO", "고유 주소와 canonical", 10, bool(domain),
               f"고유 주소 {domain}이 canonical 기준이 됩니다." if domain else "고유 사이트 주소가 정해지지 않았습니다.",
               "발행 전 사이트 주소를 확정하세요."),
        _check("machine_files", "기술 SEO", "robots·sitemap·구조화 데이터", 15, built,
               "robots.txt, sitemap.xml, JSON-LD가 발행본에 포함됩니다." if built else "기계용 파일은 빌드 시 생성됩니다.",
               "빌드를 완료해 기계용 파일을 생성하세요."),
        _check("address", "콘텐츠 SEO", "주소", 8, bool(place.get("road_address") or place.get("address")),
               "지역 검색에 사용할 주소가 있습니다." if place.get("road_address") or place.get("address") else "주소가 없습니다.",
               "도로명 주소를 확인하세요."),
        _check("phone", "콘텐츠 SEO", "전화번호", 7, bool(place.get("phone")),
               "전화 문의 답변에 사용할 번호가 있습니다." if place.get("phone") else "전화번호가 없습니다.",
               "공식 전화번호를 등록하세요."),
        _check("facts", "콘텐츠 SEO", "고유 정보량", 15, fact_count >= 8,
               f"확인된 사업장 정보가 {fact_count}건입니다.", "영업시간·가격·시설 등 확인된 정보를 8건 이상 채우세요.",
               partial=min(10, fact_count)),
        _check("images", "콘텐츠 SEO", "설명 있는 이미지", 10, image_with_alt >= 3,
               f"alt 설명이 있는 이미지가 {image_with_alt}장입니다.", "대표·내부·상품 사진을 3장 이상 승인하세요.",
               partial=min(6, image_with_alt * 2)),
        _check("unique", "신뢰·품질", "고유 콘텐츠", 10, unique_count > 0,
               f"최근 빌드의 고유 콘텐츠 판정은 {unique_count}건입니다." if version else "고유 콘텐츠를 판정할 빌드가 없습니다.",
               "복제 문구가 아닌 사업장 고유 소개·FAQ·사진을 추가하세요."),
        _check("verified", "신뢰·품질", "동일 업소 검증", 10, verified,
               "공식 사업장으로 검증되었습니다." if verified else "동일 업소 검증 전입니다.", "사업장 검증을 완료하세요."),
    ]

    aeo = [
        _check("entity", "엔티티", "사업장 엔티티 식별", 20, verified and bool(place.get("road_address") or place.get("address")),
               "상호와 검증된 주소로 사업장을 명확히 식별합니다." if verified else "사업장 정체성 신호가 부족합니다.",
               "사업장을 검증하고 공식 주소를 채우세요."),
        _check("geo", "엔티티", "좌표와 지역 문맥", 10, place.get("latitude") is not None and place.get("longitude") is not None,
               "좌표를 구조화 데이터에 제공할 수 있습니다." if place.get("latitude") is not None else "좌표가 없습니다.",
               "검증된 위도·경도를 등록하세요."),
        _check("answers", "답변 가능성", "확인된 사실", 20, fact_count >= 8,
               f"AI가 답변에 사용할 확인된 사실이 {fact_count}건입니다.", "고객이 자주 묻는 영업·이용 정보를 보강하세요.",
               partial=min(15, fact_count * 2)),
        _check("faq", "답변 가능성", "질문형 FAQ", 20, len(faqs) >= 3,
               f"발행 가능한 FAQ가 {len(faqs)}건입니다.", "실제 고객 질문과 짧고 단정적인 답변을 3건 이상 승인하세요.",
               partial=min(12, len(faqs) * 4)),
        _check("llms", "기계 가독성", "JSON-LD·llms.txt", 15, built,
               "구조화 데이터와 llms.txt가 생성되었습니다." if built else "빌드 전이라 기계용 요약이 없습니다.",
               "사이트를 빌드해 JSON-LD와 llms.txt를 생성하세요."),
        _check("sources", "신뢰성", "출처와 검증 시각", 10, fact_count > 0 and sourced == fact_count,
               f"확인된 정보 {fact_count}건 중 {sourced}건에 출처 또는 검증 시각이 있습니다.",
               "출처가 없는 정보는 사장님 확인을 거쳐 검증 시각을 남기세요.", partial=5 if sourced else 0),
        _check("freshness", "신뢰성", "최신 발행본", 5, built,
               "최근 빌드 시각을 검색엔진에 제공합니다." if built else "발행 시각 신호가 없습니다.", "변경 내용을 다시 빌드하세요."),
    ]

    ai_checks = ai_checks or []
    cited = sum(1 for row in ai_checks if getattr(row, "is_own_site_cited", False))
    return {
        "seo_score": sum(c.earned for c in seo),
        "aeo_score": sum(c.earned for c in aeo),
        "overall_score": round((sum(c.earned for c in seo) + sum(c.earned for c in aeo)) / 2),
        "checks": [c.as_dict() for c in (*seo, *aeo)],
        "summary": {
            "facts": fact_count, "faqs": len(faqs), "images_with_alt": image_with_alt,
            "built": built, "domain": domain or None,
        },
        "visibility": {"checks": len(ai_checks), "own_site_cited": cited},
        "disclaimer": "준비도 점수이며 검색 순위나 AI 인용을 보장하지 않습니다.",
    }