@roottale/cms-mcp 0.56.0 → 0.58.0

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @roottale/cms-mcp
 
+## 0.58.0
+
+### Minor Changes
+
+- 28ef875: 콘텐츠 모델 `editor` 옵션 2개 추가 — `layout: "guided"`(ROOT-ADMIN 편집기를 분류 → 제목 →
+  요약 → 본문 → 커스텀 필드 순 한 열로 배치, FAQ용)와 `requiredFields: ["excerpt"]`(요약이 비면
+  발행·예약 차단, 초안 저장은 허용). 저장 구조와 공개 API 응답은 바뀌지 않는다. 문서:
+  `content-models-and-exposures.md` "코드로 배포하는 모델은 `editor`에서…" 절.
+- dd82c92: 공통 블록 표시 형태(presentation) — 블록의 모양(본문처럼/카드·배경색·링크 버튼·버튼 색)을 어드민이
+  정해 공개 API `presentation` 으로 내려준다. 사이트는 색·모양을 CSS 에 고정하지 않는다.
+  - `@roottale/cms-core`: `readSitePatternPresentation`·`sitePatternPresentationAttributes`·
+    `DEFAULT_SITE_PATTERN_PRESENTATION`.
+  - `@roottale/cms-client`: `CmsSitePattern.presentation`(구 서버는 기본값), `sitePatternPresentationAttributes`
+    (래퍼 data 속성 + `--rt-pattern-bg`·`--rt-pattern-btn-n` CSS 변수).
+  - `@roottale/cms-renderer-next`: `RootTaleBlogPost`·`RootTalePostPattern` 이 data 속성·변수를 얹고,
+    `cms-public.css` 가 카드/버튼 모양을 그 값으로만 그린다.
+
+## 0.57.0
+
+### Minor Changes
+
+- e222471: 본문 예약 내부 링크(`[[internal:키|문구]]`)를 공용 렌더러가 해석한다.
+  - `@roottale/cms-core`: 토큰 정규식·탐색(`findInternalContentLinkTokens`), 경로→키
+    (`internalContentKeyFromPath`), 발행 글 경로 색인(`internalContentPathIndex`, 옛 slug 포함),
+    텍스트·정화된 HTML 안의 토큰을 링크로 바꾸는 `renderInternalContentLinksInText/InHtml`.
+  - `@roottale/cms-renderer-next`: `RenderTiptap`·`RootTaleBlogPost` 에 `internalLinks`
+    (Map·함수) 옵션. `RootTaleBlogPost` 는 기본 `"auto"` — 본문에 토큰이 있을 때만
+    `fetchInternalContentPathIndex` 로 발행 글 경로 색인을 만들어 링크로 렌더한다.
+    대상이 없는 토큰은 문구만 남기고 `data-rt-internal-link-pending="키"` 를 단다.
+    `<code>`·`<pre>`·기존 링크 안은 건드리지 않는다.
+  - 문서: FRONT 가 토큰을 직접 해석하지 않아도 되는 경로를 안내한다.
+
+- 92d0ad4: 공통 블록(Site Patterns) — 여러 글의 같은 자리(글 하단)에 붙는 재사용 본문.
+  - `@roottale/cms-client`: 글 응답 `patternSlots`(자리 key → 블록 key | null, 구 서버는 빈
+    객체), `fetchSitePatterns`(발행 블록 목록, `GET /v1/cms/public/patterns`),
+    `selectSitePatternForSlot`, `SITE_PATTERNS_CACHE_TAG`(`SETTINGS_CACHE_TAGS` 에 포함 —
+    `theme.updated` 로 함께 갱신), `POST_FOOTER_PATTERN_SLOT`.
+  - `@roottale/cms-renderer-next`: `RootTaleBlogPost` 가 `patternSlots.post_footer` 블록을 본문
+    바로 아래에 자동으로 그린다(목록 요청 실패는 블록만 생략). 자체 글 화면용
+    `RootTalePostPattern` 서버 컴포넌트와 `.rt-cms-post-pattern` 스타일 추가.
+  - `@roottale/cms-core`: 자리 선언·배치 규칙 정규화·`resolvePatternSlots` (플랫폼 서버·어드민과
+    공유하는 순수 규칙).
+  - 문서: `theme-and-settings.md` "공통 블록", `api-reference.md` `GET /patterns`·`pattern_slots`.
+
 ## 0.56.0
 
 ### Patch Changes

package/dist/index.js

@@ -1559,7 +1559,7 @@ function registerTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.56.0" : "dev";
+var VERSION = true ? "0.58.0" : "dev";
 var SERVER_INSTRUCTIONS = `
 roottale-cms-mcp\uB294 RootTale CMS\uB97C \uC678\uBD80 \uC0AC\uC774\uD2B8(\uC8FC\uB85C Next.js)\uC5D0 \uC5F0\uB3D9\uD558\uACE0
 \uAE00\xB7\uC378\uB124\uC77C\xB7\uBCF8\uBB38 \uC774\uBBF8\uC9C0\uB97C \uC790\uB3D9\uD654\uD558\uAE30 \uC704\uD55C \uBB38\uC11C\xB7\uC608\uC2DC \uCF54\uB4DC\xB7API tool\uC744 \uC81C\uACF5\uD569\uB2C8\uB2E4.

package/docs/api-reference.md

@@ -284,6 +284,7 @@ tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다
                "author_profile_id": "site-author-id",
                "author_name": "공통 작성자", "author_slug": "writer",
                "terms": [{ "taxonomy": "category", "name": "…", "slug": "…" }],
+               "pattern_slots": { "post_footer": "clinic-guide" },
                "published_at": "…" } ],
   "has_more": false,
   "next_cursor": null
@@ -294,6 +295,11 @@ tenant/site 경로, 크기, 형식을 검증한 뒤 미디어를 등록합니다
 > 미설정이면 `null`. 카테고리(`terms`)는 섹션 안의 주제로 아카이브에만 쓰입니다 →
 > [콘텐츠 유형 (Collections)](./collections.md).
 
+`pattern_slots` = 공통 블록 자리별 블록 key(자리 key → `GET /patterns` 의 `key` 또는
+`null`). 어드민 배치 규칙을 서버가 이 글의 `collection_key`에 맞춰 계산한 결과이며,
+선언된 자리(현재 `post_footer` = 글 하단)는 항상 키로 존재합니다. 글 상세·미리보기
+응답에도 같은 필드가 붙습니다 → 아래 `GET /v1/cms/public/patterns` 참고.
+
 `author_profile_id`는 사이트 공통 공개 작성자 ID입니다. 이름·사진·소개·작가 주소는
 같은 원장의 `author_name`·`author_image_url`·`author_bio`·`author_slug`로
 제공됩니다. 기존 `author_id`는 하위 호환용이므로 새 연동에서는 공개 작성자
@@ -439,6 +445,30 @@ settings.siteProfile.defaultOgImageUrl` 순으로 우선합니다. `logo_url`·
 "검색·공유 표시 > 메인 홈 검색 노출")으로, `null` 이면 사이트 이름(theme
 `site_name`)·`site_description` 으로 폴백하세요(`seo.md` "메인 홈 메타데이터").
 
+## GET /v1/cms/public/patterns
+
+공통 블록(여러 글의 같은 자리에 붙는 재사용 본문) 중 **발행 상태** 목록. 어느 글의
+어느 자리에 놓을지는 글 응답의 `pattern_slots`가 이미 말해 주므로, 사이트는
+`pattern_slots[slot]` 값으로 이 목록에서 `key`를 찾아 `body_json`(Tiptap 문서)을 글
+본문과 같은 렌더러·정화 경로로 그리면 됩니다. 목록이 비었거나 요청이 실패해도 글은
+정상 열려야 합니다(블록만 생략).
+
+```json
+{ "tenant_id": "…", "site_id": "…",
+  "patterns": [ { "id": "…", "key": "clinic-guide", "name": "병원 안내",
+                  "description": "글 하단 공통 안내", "body_json": { "type": "doc", "content": [ … ] },
+                  "presentation": { "layout": "card", "background": "#f8f9fa",
+                                    "link_style": "buttons", "button_colors": ["#03c75a", "#1a1a1a", "#666666"] },
+                  "status": "published", "updated_at": "…" } ] }
+```
+
+- 자리 key: `post_footer`(글 하단, 본문 바로 아래). 새 자리는 문서와 함께 추가됩니다.
+- `presentation` = 어드민이 정한 표시 형태(`layout` plain|card, `background` hex, `link_style`
+  text|buttons, `button_colors` hex 순서 — 마지막 문단의 링크에 차례로, 모자라면 마지막 색 반복).
+  사이트는 이 값을 래퍼의 data 속성·CSS 변수로 옮겨 그리고, 색·모양을 따로 고정하지 않습니다.
+- 캐시: `Cache-Control: private, max-age=10`. 어드민에서 블록·배치 규칙을 저장하면
+  `theme.updated` 웹훅이 오므로 설정류 캐시와 함께 지우세요(`revalidation-webhooks.md`).
+
 ## GET /v1/cms/public/categories
 
 분류(카테고리)와 **분류별 발행 글 수**. 글 수는 서버가 SQL로 세므로 글이 몇 건이든

package/docs/blog.md

@@ -420,6 +420,7 @@ export async function getPost(slug: string) {
 | `authorName` | 작성자 표시명 |
 | `authorSlug` | 작가 아카이브 slug(`/blog/author/{slug}`) — 미발급 작가는 `null` |
 | `metaJson` | 부가 메타 — `metaJson.seo`에 SEO 오버라이드 |
+| `patternSlots` | 공통 블록 자리별 블록 key(`{ post_footer: "clinic-guide" }`) — `RootTaleBlogPost`가 자동 렌더, 자체 화면은 `fetchSitePatterns` + `selectSitePatternForSlot`(`theme-and-settings.md` "공통 블록") |
 
 ### 정적 경로 사전 생성 + 메타데이터
 

package/docs/content-models-and-exposures.md

@@ -173,6 +173,26 @@ ROOT-ADMIN은 발행·예약 시 선언한 깊이의 말단 분류인지 다시
 `categoryLevels`의 개수는 `categoryDepth`와 같아야 합니다. 최종 선택에서는 말단
 분류 ID 하나만 기존 카테고리 관계로 저장됩니다.
 
+FAQ처럼 **요약이 본문보다 앞서고 분류가 주소를 정하는 모델**은 `editor.layout`을
+`"guided"`로 두면 ROOT-ADMIN 편집 화면이 작성 순서 한 열로 바뀝니다 — 분류 →
+제목 → 요약 → 본문 → 커스텀 필드. 주소·검색결과·공유 이미지·표시 옵션은 "공개
+설정" 한 곳으로 접히고, 오른쪽 발행 설정에는 작성자·태그만 남습니다. 생략하거나
+`"default"`면 일반 글 배치(제목 → 본문 → 발행 설정 → 검색·공유 설정)입니다.
+`editor.requiredFields`에 `"excerpt"`를 적으면 요약이 비어 있을 때 발행·예약을
+막고(초안 저장은 됩니다) 편집기에 필수 표시(`*`)를 붙입니다. 제목은 항상 필수라
+적지 않습니다. 저장 구조·공개 API 응답은 두 옵션 모두 바꾸지 않습니다.
+
+```json
+{
+  "editor": {
+    "layout": "guided",
+    "requiredFields": ["excerpt"],
+    "labels": { "title": "질문", "excerpt": "요약 답변", "body": "상세 답변" },
+    "categoryLevels": ["영역", "질환"]
+  }
+}
+```
+
 관계형 커스텀 필드는 `postType`과 함께 `modelKey`를 지정하면 선택 대상을 같은
 콘텐츠 모델로 좁힐 수 있습니다. 예를 들어 `relationship` 필드에
 `"postType": "post", "modelKey": "faq"`를 선언하면 관련 FAQ만 표시됩니다.
@@ -225,9 +245,32 @@ ROOT-ADMIN 편집기 도구 모음의 **내부 링크 삽입** 버튼이 이 표
 이 글을 연결할 때 쓰는 키가 복사 버튼과 함께 표시됩니다.
 
 이 표기는 본문 `body_json`의 일반 텍스트로 저장되며 공개 API도 그대로 내보냅니다.
-해석은 고객 FRONT의 몫입니다 — 텍스트 구간에서 표기를 찾아, 현재 발행 원장의 글
-경로를 같은 규칙으로 키로 바꿔 대조한 뒤 있으면 링크로, 없으면 표시 문구만
-렌더링하세요. `code`·`pre`·이미 링크된 구간과 속성값은 변환하지 않는 것을 권장합니다.
+편집기 안에서는 칩으로 보여 주며(대상 글이 있으면 제목·발행 상태, 없으면 "아직 없는
+글"), 저장 형식은 바뀌지 않습니다.
+
+**`@roottale/cms-renderer-next` 를 쓰면 따로 구현할 것이 없습니다.** `RootTaleBlogPost`
+는 본문에 표기가 있을 때만 발행 글 경로 색인을 만들어(`fetchInternalContentPathIndex`,
+옛 slug 포함) 링크로 렌더합니다. 대상이 없는 표기는 문구만 남기고
+`<span class="rt-internal-link rt-internal-link--pending" data-rt-internal-link-pending="키">`
+로 표시하므로 배포 QA 에서 찾을 수 있습니다. 링크는 `<a class="rt-internal-link">` 입니다.
+`code`·`pre`·이미 링크된 구간과 속성값은 변환하지 않습니다.
+
+```tsx
+// 기본값 internalLinks="auto" — 필요할 때만 색인을 만든다.
+<RootTaleBlogPost apiKey={apiKey} slugOrId={slug} />
+
+// 여러 글을 한 페이지에서 그리는 등 색인을 직접 관리하려면:
+import { fetchInternalContentPathIndex, RenderTiptap } from "@roottale/cms-renderer-next/server";
+const internalLinks = await fetchInternalContentPathIndex({ apiKey, revalidate: 300 });
+<RenderTiptap doc={post.bodyJson} internalLinks={internalLinks} />
+
+// 끄려면 internalLinks={false} — 표기가 텍스트 그대로 나옵니다.
+```
+
+렌더러를 쓰지 않는 FRONT 는 직접 해석합니다 — 텍스트 구간에서 표기를 찾아, 현재 발행
+원장의 글 경로를 같은 규칙으로 키로 바꿔 대조한 뒤 있으면 링크로, 없으면 표시 문구만
+렌더링하세요(`@roottale/cms-core` 의 `findInternalContentLinkTokens`·
+`internalContentPathIndex`·`renderInternalContentLinksInHtml` 을 그대로 쓸 수 있습니다).
 
 **글의 주소는 계산하지 말고 읽으세요.** 공개 글 응답의 `path`(`@roottale/cms-client`
 에서는 `post.path`)가 플랫폼이 저장한 정규 공개 경로입니다(예 `/column/my-post`,

package/docs/overview.md

@@ -41,6 +41,7 @@ RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발
 | 상담문의(리드) 접수 | `submitInquiry` — 키가 테넌트를 식별 |
 | 테마·블로그 표시·ROOT-ANALYTICS 설정 조회 | `fetchTheme` / `fetchBlogSettings` / `fetchAnalyticsConfig` |
 | 사업장 정보·메뉴·콘텐츠 유형 조회 | `fetchBusinessProfile` / `fetchMenu`·`fetchMenus` / `fetchCollections` |
+| 글 하단 공통 블록 조회 | `fetchSitePatterns` + `selectSitePatternForSlot` (`RootTaleBlogPost`는 자동) |
 
 키는 **서버 전용**입니다. 브라우저로 노출되면 안 됩니다(`NEXT_PUBLIC_*` 금지).
 `@roottale/cms-client`는 브라우저에서 import 시 의도적으로 throw 합니다.
@@ -66,5 +67,5 @@ RootTale CMS는 어드민(`admin.roottale.com`)에서 콘텐츠를 작성·발
 | `inquiries.md` | 상담문의(리드) 폼 연동 |
 | `menus.md` | 메뉴(네비게이션) — 어드민 "디자인 > 메뉴" 트리를 헤더/푸터에 렌더 |
 | `seo.md` | RSS 피드, 사이트맵, JSON-LD, 동적 OG 이미지, 공개 검색, fleet 프로브 |
-| `theme-and-settings.md` | 디자인 토큰, 블로그 표시 설정, ROOT-ANALYTICS |
+| `theme-and-settings.md` | 디자인 토큰, 블로그 표시 설정, 공통 블록(글 하단), ROOT-ANALYTICS |
 | `api-reference.md` | HTTP API 레퍼런스 (비 JS 스택용 raw 엔드포인트) |

package/docs/revalidation-webhooks.md

@@ -105,8 +105,9 @@ const menu = await fetchMenu({ apiKey, slug: "primary", tags: [MENUS_CACHE_TAG]
 | `fetchMenu` / `fetchMenus` | `MENUS_CACHE_TAG` | 디자인 > 메뉴 |
 | `fetchBlogSettings` | `BLOG_SETTINGS_CACHE_TAG` | 설정 > 블로그 |
 | `fetchCollections` | `COLLECTIONS_CACHE_TAG` | 설정 > 콘텐츠 유형 |
+| `fetchSitePatterns` | `SITE_PATTERNS_CACHE_TAG` | 콘텐츠 도구 > 공통 블록 |
 
-다섯 개를 한 벌로 묶은 `SETTINGS_CACHE_TAGS` 배열도 있습니다. 수신 라우트는
+이들을 한 벌로 묶은 `SETTINGS_CACHE_TAGS` 배열도 있습니다. 수신 라우트는
 설정 저장 신호(`theme.updated`) 한 번에 **이 목록 전체**를 지웁니다 — 무엇이
 바뀌었는지 웹훅 본문에 없기 때문이며, 쓰지 않는 이름표를 지우는 것은 아무 일도
 일어나지 않으므로 해가 없습니다.

package/docs/theme-and-settings.md

@@ -22,8 +22,9 @@ description: 어드민에서 관리하는 디자인 토큰, 블로그 표시 옵
 | `fetchMenu` / `fetchMenus` | `MENUS_CACHE_TAG` |
 | `fetchBlogSettings` | `BLOG_SETTINGS_CACHE_TAG` |
 | `fetchCollections` | `COLLECTIONS_CACHE_TAG` |
+| `fetchSitePatterns` | `SITE_PATTERNS_CACHE_TAG` |
 
-다섯 개를 한 벌로 묶은 `SETTINGS_CACHE_TAGS` 배열도 내보냅니다. 이름표를 지우는
+이들을 한 벌로 묶은 `SETTINGS_CACHE_TAGS` 배열도 내보냅니다. 이름표를 지우는
 쪽(웹훅 수신 라우트) 배선은 `revalidation-webhooks.md` §1 "설정 저장"을
 따르세요 — **양쪽을 다 해야** 즉시 반영이 됩니다.
 
@@ -139,6 +140,55 @@ const display = resolvePostDisplay(settings, post);
 `authorProfileBio`·`authorProfileImageUrl`·`authorCardDescription`은 항상
 `null`이며 새 코드에서 사용하지 마세요.
 
+## 공통 블록 (글 하단) — fetchSitePatterns
+
+어드민 **콘텐츠 도구 > 공통 블록**에서 만든 재사용 본문(병원 안내·상담 CTA 등)을
+여러 글의 같은 자리에 붙입니다. "어느 글의 어느 자리에 어떤 블록"은 어드민의
+배치 규칙(콘텐츠 유형별)으로 정하고, **서버가 글 응답의 `patternSlots`(자리 →
+블록 key | null)로 계산해 내려주므로 사이트는 규칙을 몰라도 됩니다.** 현재
+자리는 글 하단 `post_footer` 하나입니다.
+
+- `RootTaleBlogPost`(cms-renderer-next 0.57+)는 본문 바로 아래에 자동으로 그립니다
+  — 추가 코드가 필요 없습니다.
+- 자체 글 화면을 만든 사이트는 `RootTalePostPattern` 서버 컴포넌트를 본문 아래에
+  두거나, 아래처럼 직접 조회해 글 본문과 **같은 렌더러·정화 경로**로 그립니다.
+
+```ts
+import {
+  SITE_PATTERNS_CACHE_TAG,
+  POST_FOOTER_PATTERN_SLOT,
+  fetchPost,
+  fetchSitePatterns,
+  selectSitePatternForSlot,
+} from "@roottale/cms-client/server";
+
+const post = await fetchPost({ apiKey, slugOrId });
+// post.patternSlots → { post_footer: "clinic-guide" } 처럼 자리별 블록 key
+const patterns = post?.patternSlots?.[POST_FOOTER_PATTERN_SLOT]
+  ? await fetchSitePatterns({ apiKey, tags: [SITE_PATTERNS_CACHE_TAG] }).catch(() => [])
+  : [];
+const footer = selectSitePatternForSlot(post?.patternSlots, patterns);
+// footer?.bodyJson 을 본문과 같은 Tiptap 렌더러로 그린다(없으면 아무것도 그리지 않음)
+```
+
+```tsx
+// 자체 글 화면 + 공용 렌더러 조합
+import { RootTalePostPattern } from "@roottale/cms-renderer-next/server";
+<RootTalePostPattern apiKey={apiKey} post={post} />
+```
+
+블록의 **표시 형태**(`presentation`: `layout` 본문처럼/카드, `background` 카드 배경색,
+`linkStyle` 글자/버튼, `buttonColors` 버튼 색 순서)도 어드민이 정해 내려줍니다. 사이트
+CSS 에 색·모양을 고정하지 말고 `sitePatternPresentationAttributes(pattern.presentation)`
+가 주는 data 속성(`data-pattern-layout`, `data-pattern-link-style`)과 CSS 변수
+(`--rt-pattern-bg`, `--rt-pattern-btn-1..n`)를 래퍼에 얹은 뒤 그 값만 읽으세요.
+`RootTaleBlogPost`·`RootTalePostPattern` 은 이미 그렇게 그립니다.
+
+블록 목록은 `rt-site-patterns` 캐시 이름표를 가지며, 어드민에서 블록·배치 규칙을
+저장하면 `theme.updated` 웹훅이 다른 설정과 함께 지웁니다(`createRevalidateRoute`
+에 `revalidateTag` 주입 필요 — 위 "저장 즉시 반영" 참고). 미발행·삭제된 블록은
+`patternSlots` 에서 이미 `null` 이므로 사이트가 따로 걸러낼 필요가 없습니다.
+
 ## 비즈니스 프로필 (로컬 SEO) — fetchBusinessProfile
 
 어드민 **운영 > 비즈니스 프로필**에서 저장한 사업장 정보(이름·별칭·업종·

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.56.0",
+  "version": "0.58.0",
   "type": "module",
   "description": "RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.",
   "bin": {