RootTale CMS 연동 개요

RootTale CMS는 어드민(admin.roottale.com)에서 콘텐츠를 작성·발행하고, 외부 고객 사이트(자체 도메인의 Next.js/Astro 등)가 공개 API(api.roottale.com)로 콘텐츠를 가져가는 헤드리스 구조입니다.

권장 연동 순서

getting-started.md — 키 발급 + 환경 설정
blog.md — /blog 목록·상세 페이지
search.md — 글·페이지 통합 검색 (선택)
revalidation-webhooks.md — 웹훅 등록 (발행 → 즉시 반영)
seo.md — RSS·사이트맵·동적 OG 이미지
theme-and-settings.md — ROOT-ANALYTICS 연결 (권장)
inquiries.md — 사이트별 여러 문의 폼과 유입·여정 저장 (선택)
menus.md — 어드민 관리 네비게이션 (선택)

어드민 (admin.roottale.com)            고객 사이트 (예: example.com)
  글 작성·발행 ──────────┐
                         ▼
              api.roottale.com  ◀── Bearer rtlk_cust_* ── 콘텐츠/설정 조회
                         │
  발행 웹훅 (ES256 서명) ─┴──────────▶ POST /api/revalidate → 캐시 즉시 갱신

단일 API 키 모델

연동 전체가 API 키 하나(rtlk_cust_*) 로 동작합니다:

기능	같은 키 하나로
블로그 글 목록/상세 조회	`fetchPosts` / `fetchPost`
발행 글·페이지 검색	`searchPosts` / `resolveSearchHitPath`
발행 웹훅 서명 검증 + 캐시 갱신	`createRevalidateRoute` (JWKS 공개키 — 별도 secret 보관 불필요). 설정 저장을 즉시 반영하려면 `revalidateTag` 주입 필수 — `revalidation-webhooks.md` §1
사이트별 여러 문의 폼 접수	`fetchInquiryForm`·`submitFormInquiry` — 키의 고객사·사이트 안에서 폼 ID와 버전으로 접수
기존 고정 필드 리드 접수	`submitInquiry` — 기존 연동 계약 유지
테마·블로그 표시·ROOT-ANALYTICS 설정 조회	`fetchTheme` / `fetchBlogSettings` / `fetchAnalyticsConfig`
사업장 정보·메뉴·콘텐츠 유형 조회	`fetchBusinessProfile` / `fetchMenu`·`fetchMenus` / `fetchCollections`
글 하단 공통 블록 조회	`fetchSitePatterns` + `selectSitePatternForSlot` (`RootTaleBlogPost`는 자동)

키는 서버 전용입니다. 브라우저로 노출되면 안 됩니다(NEXT_PUBLIC_* 금지). @roottale/cms-client는 브라우저에서 import 시 의도적으로 throw 합니다.

패키지 구성 (npm public)

패키지	역할
`@roottale/cms-client`	서버 전용 fetch 클라이언트 — 글/테마/설정 조회, 문의 접수, 웹훅 검증 (raw)
`@roottale/cms-renderer-next`	Next.js(RSC) 렌더러 — 블로그 컴포넌트, revalidate/RSS/sitemap 라우트 팩토리
`@roottale/cms-core`	블록 JSON 공통 코어 (렌더러가 의존)
`@roottale/analytics-runtime`	ROOT-ANALYTICS 비콘·동의·Next.js SPA 추적 런타임
`@roottale/cms-mcp`	본 MCP 서버 — 통합 문서·예시 코드·API 조회 tool

문서 맵

문서	내용
`getting-started.md`	API 키 발급, 환경변수, 패키지 설치, 첫 조회
`blog.md`	블로그 목록/상세 페이지 구현 (컴포넌트 또는 직접 fetch)
`search.md`	글·페이지 통합 검색, 실제 공개 주소 계산, 보안·캐시·장애 처리
`revalidation-webhooks.md`	발행 웹훅으로 near-real-time 캐시 갱신
`inquiries.md`	다중 폼·접수증·CRM 연동과 기존 리드 API
`menus.md`	메뉴(네비게이션) — 어드민 "디자인 > 메뉴" 트리를 헤더/푸터에 렌더
`seo.md`	RSS 피드, 사이트맵, JSON-LD, 동적 OG 이미지, 공개 검색, fleet 프로브
`theme-and-settings.md`	디자인 토큰, 블로그 표시 설정, 공통 블록(글 하단), ROOT-ANALYTICS
`api-reference.md`	HTTP API 레퍼런스 (비 JS 스택용 raw 엔드포인트)