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

"""사이트 주소(네임스페이스) 규칙 — 확인(check)과 저장(POST)이 함께 쓰는 단 하나의 정의.

★ 주소는 한 번 정하면 AI 검색이 색인하는 영구 식별자다. 그래서
  - 규칙은 이 파일 한 곳에만 둔다. 확인과 저장이 서로 다른 규칙을 쓰면
    "쓸 수 있다고 해놓고 저장에서 튕기는" 최악의 화면이 나온다.
  - 클라이언트 검증은 믿지 않는다. 저장 직전에 서버가 이 규칙으로 다시 본다.

★ ASCII 소문자·숫자·하이픈만 받는다.
  한글 상호를 그대로 주소로 쓰면 경로는 퍼센트 인코딩(/s/%EC%8A%A4%ED%85%8C%EC%9D%B4),
  서브도메인은 퓨니코드(xn--…)가 된다 — 사장님이 전화로 불러줄 수도, 명함에 적을 수도 없는 주소다.
  (프론트 `shared/src/lib/slug.ts` 의 publishUrl 이 ASCII 슬러그면 서브도메인으로 낸다.)
"""
import re
from typing import Optional

# 3~50자. 처음과 끝은 영문 소문자·숫자여야 하고, 하이픈은 가운데에만 올 수 있다.
# (1 + 1~48 + 1 = 3~50자)
SLUG_PATTERN = re.compile(r"^[a-z0-9](?:[a-z0-9-]{1,48}[a-z0-9])$")
SLUG_MIN_LEN = 3
SLUG_MAX_LEN = 50

# 불가 사유 코드. 응답의 reason 으로 그대로 나가고, 프론트가 문구를 고른다.
REASON_LENGTH = "INVALID_LENGTH"      # 3~50자를 벗어남
REASON_FORMAT = "INVALID_FORMAT"      # 한글·대문자·언더스코어·연속 하이픈·양끝 하이픈
REASON_RESERVED = "RESERVED"          # 서비스가 선점한 이름
REASON_TAKEN = "TAKEN"                # 다른 사업장이 이미 쓰는 주소
REASON_LOCKED = "LOCKED"              # ★ 이미 발행됨 — 색인된 주소는 바꾸지 않는다

# 예약어. 두 부류가 섞여 있다.
#  1) 서비스가 실제로 쓰는 경로·서브도메인(/s, /healthz, api. …) — 내주면 사이트가 서로를 가린다.
#  2) 관용적으로 시스템을 뜻하는 이름(admin, root, www …) — 사장님 사이트가 이 주소를 갖고 있으면
#     방문자도 크롤러도 공식 홈페이지로 읽지 않는다.
RESERVED_SLUGS = frozenset({
    # 서비스 경로 / 인프라 서브도메인
    "s", "site", "sites", "api", "app", "admin", "www", "www2", "static", "assets", "cdn", "media",
    "img", "images", "css", "js", "files", "download", "downloads", "public", "dev", "stage", "staging",
    "test", "demo", "local", "localhost", "mail", "smtp", "imap", "pop", "ftp", "ns", "ns1", "ns2", "mx",
    "webmail", "vpn", "proxy", "gateway", "internal", "console", "dashboard", "manage", "management",
    # 서버가 실제로 서비스하는 엔드포인트
    "health", "healthz", "healthcheck", "status", "metrics", "robots", "sitemap", "llms", "favicon",
    "manifest", "feed", "rss", "opensearch", "well-known", "v1", "v2", "graphql", "openapi", "docs", "swagger",
    # 계정 / 정책 페이지
    "login", "logout", "signin", "signup", "register", "join", "auth", "oauth", "account", "accounts",
    "user", "users", "me", "my", "owner", "root", "system", "support", "help", "contact", "about",
    "terms", "privacy", "policy", "legal", "security", "billing", "payment", "pay", "order", "orders",
    # 도메인 리소스 이름 — 관리 API 경로와 같아 헷갈린다
    "place", "places", "fact", "facts", "faq", "faqs", "job", "jobs", "report", "reports", "unit", "units",
    "search", "index", "home", "main", "new", "edit", "delete", "create", "update",
    # 값이 비었을 때 프론트가 문자열로 흘려보내는 것들 — 주소로 들어오면 버그의 흔적이다
    "null", "undefined", "none", "nan", "true", "false",
})


def validate_slug(slug: Optional[str]) -> Optional[str]:
    """형식·예약어만 본다(중복은 DB 를 봐야 하므로 서비스가 판단한다).

    쓸 수 있으면 None, 아니면 REASON_* 를 돌려준다."""
    value = (slug or "").strip()
    if len(value) < SLUG_MIN_LEN or len(value) > SLUG_MAX_LEN:
        return REASON_LENGTH
    # 하이픈 연속은 정규식으로 막지 않는다(가운데 문자 집합이라 통과한다) — 여기서 따로 거른다.
    # a--b 는 퓨니코드 접두(xn--)와 모양이 겹쳐서 서브도메인으로 냈을 때 오해를 산다.
    if "--" in value:
        return REASON_FORMAT
    if not SLUG_PATTERN.fullmatch(value):
        return REASON_FORMAT
    if value in RESERVED_SLUGS:
        return REASON_RESERVED
    return None


def suggestions(slug: Optional[str], count: int = 9) -> list[str]:
    """`-2`, `-3` … 을 붙인 대안 후보. 실제로 쓸 수 있는지(중복)는 서비스가 DB 로 거른다.

    ★ 음차하거나 상호를 마음대로 줄이지 않는다 — 서버가 고른 주소는 사장님이 기억하지 못한다.
      사장님이 적어낸 이름을 그대로 두고 뒤에 숫자만 붙인다."""
    value = (slug or "").strip()
    result: list[str] = []
    for n in range(2, 2 + max(count, 0)):
        suffix = f"-{n}"
        # 50자 상한을 넘기지 않도록 앞을 자른다. 자른 끝이 하이픈이면 `a--2` 가 되므로 떼어낸다.
        base = value[: SLUG_MAX_LEN - len(suffix)].rstrip("-")
        candidate = f"{base}{suffix}"
        if validate_slug(candidate) is None:
            result.append(candidate)
    return result