---
title: RootTale CMS 연동 개요
description: 연동 아키텍처, 단일 API 키 모델, 패키지 구성, 문서 맵
---

# RootTale CMS 연동 개요

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

## 권장 연동 순서

1. `getting-started.md` — 키 발급 + 환경 설정
2. `blog.md` — `/blog` 목록·상세 페이지
3. `search.md` — 글·페이지 통합 검색 (선택)
4. `revalidation-webhooks.md` — 웹훅 등록 (발행 → 즉시 반영)
5. `seo.md` — RSS·사이트맵·동적 OG 이미지
6. `theme-and-settings.md` — ROOT-ANALYTICS 연결 (권장)
7. `inquiries.md` — 사이트별 여러 문의 폼과 유입·여정 저장 (선택)
8. `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`](https://www.npmjs.com/package/@roottale/cms-client) | 서버 전용 fetch 클라이언트 — 글/테마/설정 조회, 문의 접수, 웹훅 검증 (raw) |
| [`@roottale/cms-renderer-next`](https://www.npmjs.com/package/@roottale/cms-renderer-next) | Next.js(RSC) 렌더러 — 블로그 컴포넌트, revalidate/RSS/sitemap 라우트 팩토리 |
| [`@roottale/cms-core`](https://www.npmjs.com/package/@roottale/cms-core) | 블록 JSON 공통 코어 (렌더러가 의존) |
| [`@roottale/analytics-runtime`](https://www.npmjs.com/package/@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 엔드포인트) |
