SEO 아키텍처

Seo plugin은 검색엔진용 설정 저장소가 아니라, 현재 요청의 site context를 해석하고 최종 HTML, sitemap, robots, audit snapshot으로 반영하는 request-time SEO layer입니다.

Context 병합 순서

뒤 단계일수록 우선순위가 높습니다.

Platform default
  -> SaaS Product / Site default
  -> Tenant default
  -> SEO Scope default
  -> Page Rule
  -> Entity Provider
  -> Request Override

계층	저장/제공 위치	예시
Platform	`config('seo')`	기본 robots, title separator
SaaS/Site	`saas_products.settings.seo`	`newspaper.how` 기본 title
Tenant	`tenants.settings.seo`	custom domain tenant override
Scope	`plg_seo_scopes` 또는 provider	`scripture`의 dictionary scope
Page Rule	`plg_seo_page_rules`	`/articles/*` title template
Entity	`SeoMetaProviderInterface`	Article/Product/Post별 canonical
Request	controller/view override	검색 결과 페이지의 query-aware title

독립사이트 Resolution

같은 MSK 프로젝트 안에 여러 독립사이트가 있으면 host와 site slug가 SEO context의 핵심입니다.

current.saas_product
  -> host matches saas_products.settings.domains
  -> current.site matches saas_products.settings.site
  -> fallback 없음

이 순서를 사용하면 academy.how 프로젝트 안에서 생성된 newspaper.how가 newspaper 전용 settings.seo를 사용할 수 있습니다.

Managed Head

Seo middleware는 HTML response의 <head>를 가공합니다. SEO plugin이 소유한 tag만 replace/upsert하고, 다른 시스템 tag는 보존합니다.

Managed	보존
`<title>`	charset
`meta[name="description"]`	viewport
`meta[name="robots"]`	CSP
canonical / alternate	preload / preconnect
Open Graph / Twitter Card	favicon
verification meta	Analytics / Ads script
managed JSON-LD	프로젝트 고유 non-SEO meta

JSON-LD는 StructuredDataRegistry에서 하나의 schema.org @graph로 병합한 뒤 renderer가 안전하게 encode합니다.

Sitemap / Robots

/robots.txt와 /sitemap.xml은 현재 host/site 기준으로 출력됩니다.

robots raw text는 지원하지 않습니다.
sitemap에는 canonical URL만 포함합니다.
noindex/private/admin/auth/checkout/billing/legal/system path는 제외합니다.
콘텐츠 URL은 SeoSitemapProviderInterface로 확장합니다.

Audit

Audit은 실제 HTML을 가져와 구조화 snapshot과 issue list를 저장합니다.

URL guard
  -> fetch with timeout/redirect/body limit
  -> parse head/body summary
  -> detect issues
  -> store sanitized snapshot

보안 경계:

http/https만 허용
current host 또는 explicit allowlist만 허용
loopback/private/link-local/metadata IP 차단
redirect final URL 재검증
원본 HTML 전체 미저장

SEO와 접근성

SEO는 접근성/semantic HTML과 같이 봐야 합니다.

페이지 주제는 명확한 h1로 표현합니다.
section/article/nav/main/aside/footer를 의미에 맞게 사용합니다.
image alt와 link text를 성실히 작성합니다.
모든 element에 title attribute를 일괄 삽입하지 않습니다.
Audit은 title attribute 사용량을 수집하지만 자동 삽입 정책으로 해석하지 않습니다.

Context 병합 순서​

독립사이트 Resolution​

Managed Head​

Sitemap / Robots​

Audit​

SEO와 접근성​

관련 내부 문서​