UNPKG

@roottale/cms-mcp

Version:

RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.

631 lines (514 loc) • 31.9 kB
--- title: 콘텐츠 모델과 노출 관리 description: 페이지·글·정보 모델, 확장 필드, 배너·팝업을 API·MCP·CLI로 관리하는 방법 --- # 콘텐츠 모델과 노출 관리 RootTale의 콘텐츠 관리 단위는 다음과 같습니다. | 리소스 | 뜻 | 안정 식별자 | |---|---|---| | 콘텐츠 모델 | 페이지·글·정보의 구조와 화면 연결 | `model_key` | | 필드 그룹 | 모델에 붙는 구조화된 추가 필드 | `model_key` + `group_key` | | 항목 | 모델에 속한 실제 페이지·글·정보 | `post_id` | | 노출 슬롯 | FRONT가 선언한 배너·팝업 위치 계약 | `slot_key` | | 노출 캠페인 | 슬롯에 표시할 내용·기간·경로 | `exposure_id` | `source: "code"`인 모델·필드 그룹은 개발자 계약입니다. 구조를 API로 바꾸거나 삭제할 수 없습니다. 모델 상태만 활성화·비활성화할 수 있습니다. `source: "site"`인 리소스는 관리 API로 만들고 수정할 수 있습니다. ## 병원 비급여 자동 연동 병원 사이트는 미리닥 API의 전체 항목을 자동으로 읽고 ROOT-ADMIN에는 병원 수정·추가·숨김만 저장합니다. 사이트 콘텐츠 계약의 `contentAreas[].editor.kind`는 `fields`, 입력칸은 `table`이며, `table.source`에 `{ "provider": "miridoc", "institutionId": "<6자리 ID>" }`를 둡니다. 원본 조회는 문서를 쓰지 않습니다. 수정한 행은 다음 갱신 때 보존하고, 원천에서 빠진 수정본은 공개하지 않습니다. 기존 셀별 문서와 수정 이력은 `legacy` 키 매핑으로 보존합니다. 새 병원은 내부 `starter init --industry medical --miridoc-id <ID>`로 페이지·계약·푸터·미리보기를 함께 생성합니다. 기존 병원은 기존 URL·디자인에 같은 모듈을 연결합니다. 자료가 없는 기관은 병원 추가 내용을 사용합니다. 자동 자료의 범위·공개 경계·적용 순서는 [병원 공통 모듈](../examples/nextjs/hospital-fees/README.md)을 따릅니다. ## 권한 전체 자동화에는 API 키 프로필 `full_management`를 권장합니다. 세부 권한은 다음과 같이 분리됩니다. | 권한 | 허용 작업 | |---|---| | `cms:read` | 모델·필드·항목·노출 슬롯·캠페인 조회 | | `cms:write` | 항목 작성·수정·삭제 | | `cms:publish` | 항목 발행·발행 취소 | | `content-models:write` | site 모델·필드 그룹 관리, code 모델 상태 변경 | | `exposures:write` | 노출 캠페인 초안 작성·수정 | | `exposures:publish` | 노출 발행·보관, 발행 중 캠페인 수정 | 이전 키 프로필에는 새 쓰기 권한이 자동으로 추가되지 않습니다. 자동화에 필요한 권한을 명시해 새 키를 발급하세요. ## 콘텐츠 모델과 필드 그룹 모델 API: - `GET|POST /v1/cms/content-models` - `GET|PATCH|DELETE /v1/cms/content-models/{model_key}` - `GET|POST /v1/cms/content-models/{model_key}/field-groups` - `GET|PATCH|DELETE /v1/cms/content-models/{model_key}/field-groups/{group_key}` 수정·삭제는 응답의 `updated_at`을 `expected_updated_at`으로 다시 보내야 합니다. 다른 사용자가 먼저 바꿨다면 `409 version_conflict`가 납니다. 사용 중인 모델과 필드 그룹은 삭제할 수 없습니다. ```json { "key": "team-member", "label": "구성원", "cardinality": "collection", "preset": "entity", "presentation": { "kind": "detail", "detailPath": "/team/:slug", "templateKey": "team-member" }, "publication": null, "definition": {} } ``` 필드 그룹의 `definition`은 필드 배열과 검증 규칙을 담습니다. 정의되지 않은 `field_values` 키, 형식이 틀린 값, 다른 사이트 항목을 가리키는 관계 값은 저장되지 않습니다. 필수 칸에 빈 글자나 공백만 보내도 값이 없는 것으로 보고 저장하지 않습니다. ## 계층형 분류 모델 FAQ·도움말·문서처럼 목록 아래에 여러 단계의 분류 허브가 필요한 모델은 `presentation.kind: "category_tree"`를 사용합니다. 이 계약은 FAQ 전용 기능이 아니며 1~3단계 분류를 지원합니다. ```json { "key": "faq", "cardinality": "collection", "preset": "article", "presentation": { "kind": "category_tree", "basePath": "/faq", "categoryDepth": 2, "templateKey": "faq" } } ``` 기본은 `categoryDepth` 단계의 말단 분류에만 글을 붙입니다(위 예는 `/faq/{영역}/{질환}/{slug}`). 하위 분류가 필요한 영역만 나누고 나머지 영역에는 바로 글을 쓰려면 `"entryCategory": "leaf"`를 둡니다. 그러면 `categoryDepth`는 최대 단계가 되고, 하위 분류가 없는 분류면 어느 단계든 글을 붙일 수 있습니다. | `entryCategory` | 글을 붙일 수 있는 분류 | FAQ 주소 예 | |---|---|---| | 생략·`"deepest"` | `categoryDepth` 단계 말단만 | `/faq/{영역}/{질환}/{slug}` | | `"leaf"` | 하위가 없는 분류(최대 `categoryDepth` 단계) | `/faq/{영역}/{slug}`, `/faq/{영역}/{질환}/{slug}` | `leaf` 모델에서 글이 붙은 분류에 나중에 하위 분류가 생겨도 이미 붙은 글의 주소는 유지됩니다. 새로 고르거나 다시 발행할 때는 하위가 없는 분류를 골라야 합니다. 같은 상위 아래에서 하위 분류 slug와 글 slug는 겹칠 수 없습니다. FRONT는 공개 글의 `path`를 그대로 쓰고, 분류 허브 화면에서 하위 분류와 그 분류에 바로 붙은 글을 함께 보여 주면 됩니다. ### 여러 분류 중 대표 분류 선택 SDK 0.69.0부터 `categorySelection: "first"`로 여러 분류를 붙인 글의 대표 분류를 선택할 수 있습니다. 생략하면 기존의 한 분류 경로 규칙을 유지합니다. `first`는 **`termOrder` 오름차순 → 같은 순서이면 ID 오름차순**으로 고릅니다. 공개 응답의 `terms` 배열 순서는 바꾸지 않으므로 `terms.find(...)`나 이름 정렬로 대표 분류를 대신 고르지 마세요. `categoryCardinality: "exactly-one"`과는 함께 선언할 수 없습니다. ```json { "key": "blog", "cardinality": "collection", "preset": "article", "compatibilityCollectionKey": null, "presentation": { "kind": "category_tree", "basePath": "/insights", "categoryDepth": 1, "categorySelection": "first", "categoryCardinality": "multiple", "categoryFallbackSlug": "general", "reservedCategorySlugs": ["notices"], "categoryPath": "direct", "templateKey": "blog" } } ``` 이 예에서 분류를 하나도 붙이지 않은 글은 `/insights/general/{slug}`를 사용합니다. `categoryFallbackSlug`는 `first`인 1단계 모델에서만 지원하며, 실제 분류가 없을 때의 경로입니다. 잘못되거나 다른 모델에 속한 분류 참조를 대체하지 않습니다. `general`이라는 분류나 메타데이터 고정 경로를 만들 필요가 없습니다. fallback slug와 `reservedCategorySlugs`는 실제 분류 slug로 쓸 수 없고 서로 겹칠 수도 없습니다. 예약 주소의 페이지는 사이트가 별도로 구현합니다. `compatibilityCollectionKey: null`은 레거시 컬렉션에 연결하지 않겠다는 명시값입니다. 모델 key로 바꾸지 마세요. 글 조회에는 `modelKey: "blog"`를 사용하고, 링크에는 공개 응답의 `post.path`를 사용합니다. 분류 주소도 `fetchCategoryCounts()`의 `category.path`를 사용합니다. 서버는 활성 모델의 presentation과 해당 모델의 분류 계층으로 주소를 계산합니다. 모델이 없는 분류만 이전 `content_collections` 설정으로 계산하며, 예약 주소나 잘못된 계층의 `path: null`을 임의 URL로 대체하지 않습니다. 발행 글이 0건인 실제 분류도 응답에 포함되며 화면 공개·검색 색인 여부는 사이트의 동일한 정책으로 판단합니다. 분류 응답의 `collectionKey`는 원본 값을 보존합니다. 서버의 모델 선택은 정확한 모델 key를 우선하며 호환 컬렉션 key도 지원합니다. 위처럼 호환 key가 `null`인 `blog` 모델의 분류 범위에는 레거시 `null`과 `"blog"`가 모두 들어갑니다. 이 예시에서는 `(category.collectionKey ?? "blog") === "blog"`로 범위를 선택합니다. 이 범위와 `category.path`를 canonical·sitemap에서 함께 사용하고, `truncated: true`인 응답을 완전한 분류 계층으로 간주하지 마세요. 실행 예제는 `lib/content-policy.ts`의 `fetchBlogCategoryGraph`를 참고하세요. 분류 표시·브레드크럼에도 같은 선택이 필요하면 공개 core 헬퍼를 사용합니다. `modelCategories`에는 글에 붙은 분류만이 아닌 **해당 모델의 전체 분류**를 전달합니다. ```ts import { resolveCategoryTreeEntryCategory } from "@roottale/cms-core"; const selected = resolveCategoryTreeEntryCategory(presentation, post, modelCategories); // selected.kind === "category": selected.category와 selected.chain 사용 // selected.kind === "fallback": selected.slug 사용(실제 분류 ID는 없음) // selected === null: 유효한 분류 경로가 없음 ``` ### 편집기의 세부 주제 모델의 `editor.topic`은 URL 카테고리와 별개인 `content_topic` 선택 칸입니다. `label`은 칸 이름(기본 `콘텐츠 분류`), `levels`는 정확히 두 단계 이름이며 term의 `parentId`로 상위·하위를 나눕니다. 상위만 선택해도 됩니다. `required: "first-publish"`는 최초 발행·예약 때만 유효한 주제를 요구하고, `helpText`는 안내 문구, `card: false`는 카드 연결 설정과 결과를 숨깁니다. 생략하면 기존 편집기와 발행 정책을 유지합니다. 선택은 계속 `meta_json.contentEditor.primaryTermId` 하나에 저장합니다. 발행 취소는 발행일을 지울 수 있으므로 최초 발행 판정에는 현재 발행 상태·발행일과 과거 `published` revision을 함께 사용합니다. 설정 예시는 `examples/nextjs/connected-content.md`의 세부 주제 항목을 참고하세요. ### 목록·피드 규칙도 모델이 소유합니다 글 목록의 카테고리 모음, RSS 피드, 허브 주소 형식처럼 예전 `collections` 설정에만 있던 규칙은 이제 `detail`·`category_tree` presentation의 선택 필드로 선언합니다. 모두 생략 가능하며 기본값은 컬렉션이 없을 때의 동작과 같습니다. | 필드 | 의미 | 기본값 | |---|---|---| | `archives` | 카테고리 모음 주소(`{목록}/categories/{slug}` 또는 direct)를 발행·갱신 | `false` | | `feed` | RSS 피드에 포함 | `false` | | `categoryPath` | 카테고리 허브 주소 형식 — `namespaced` = `{목록}/categories/{slug}`, `direct` = `{목록}/{slug}` | `namespaced` | | `layout` | 목록 레이아웃 힌트(FRONT가 해석, 라우팅과 무관) | 없음 | `detail`의 목록 주소는 `detailPath`에서 `/:slug`를 뗀 부모 경로이고, `category_tree`는 `basePath`가 목록입니다. 예전 `collections` 응답은 호환을 위해 유지되지만 새 사이트는 모델 presentation만 읽으면 됩니다. ### 목록 화면(`listPaths`) 글을 목록으로 보여 주는 고정 화면이 따로 있으면 `listPaths`에 적습니다. 홈의 최근 사례나 회사소개의 인증서 갤러리처럼 모델 주소 밖에 있는 화면이 여기에 해당합니다. `data_only`·`detail`·`category_tree`에서 쓸 수 있습니다. - 글을 바꾸면 웹훅 `paths`에 이 화면들이 함께 실립니다. 상세 주소의 부모 목록은 자동으로 들어가므로 적지 않습니다. - 상세 주소가 없는 `data_only` 모델은 이 화면들만 갱신 대상이 되며, 글을 여러 개 담는 활성 모델(`page` 프리셋 제외)은 **`listPaths`를 1개 이상 적어야 저장됩니다**(없으면 `400 bad_request`, `details.reason: "list_paths_required"`). - **첫 화면이 기준 화면입니다.** 그 모델의 모든 글이 보이는 화면(예: `/experts`)을 먼저 적으세요. ROOT-ADMIN은 기준 화면의 소스(서버가 보낸 화면 데이터 포함)에 현재 제목이 있는지로 공개 반영을 확인하고, 나머지 화면(홈 등 일부만 보이는 화면)은 제목이 없으면 판정을 보류합니다. - 상세 모델의 추가 화면은 글 링크 기준으로 확인하고, 링크가 없으면 판정을 보류합니다. - 고정 경로만 쓸 수 있습니다(`:slug` 같은 변수 불가, 최대 20개). ```json { "key": "certificate", "preset": "entity", "presentation": { "kind": "data_only", "listPaths": ["/company/credentials", "/company"] } } ``` **RootTale 표준 블로그 주소** — RootTale이 만드는 사이트(스타터·`roottale init` 시드)의 `blog` 모델은 아래 규칙 하나를 씁니다: 글 `/blog/{category}/{slug}`, 카테고리 허브 `/blog/{category}`, 목록 `/blog`. 1단계 `category_tree`이고 글마다 카테고리를 정확히 하나 고릅니다(`categoryCardinality: "exactly-one"`). 옛 평면 주소 `/blog/{slug}`와 `/blog/categories/{slug}`는 FRONT가 정본으로 301 합니다. ```json { "kind": "category_tree", "basePath": "/blog", "categoryDepth": 1, "templateKey": "blog", "categoryPath": "direct", "categoryCardinality": "exactly-one", "archives": true, "feed": true } ``` 직접 만드는 사이트가 평면 상세 주소를 유지해도 됩니다 — 그때는 `detail` 규칙을 선언하고 FRONT 라우트를 그 규칙에 맞추면 됩니다. ```json { "kind": "detail", "detailPath": "/blog/:slug", "templateKey": "blog", "archives": true, "feed": true } ``` 공개 사이트는 `fetchCategories({ collectionKey: "faq" })`의 `id`와 `parentId`로 루트부터 말단까지의 분류 사슬을 만들고, `fetchPosts({ modelKey: "faq" })`의 글마다 말단 카테고리를 정확히 하나 연결합니다. 위 예시는 다음 주소를 표현합니다. - `/faq` - `/faq/headache` - `/faq/headache/migraine` - `/faq/headache/migraine/{slug}` ROOT-ADMIN은 발행·예약 시 선언한 깊이의 말단 분류인지 다시 검사합니다. 부모만 고르거나 복수 분류를 연결한 항목은 발행하지 않습니다. 분류 `slug`나 부모 관계를 바꾸는 일은 공개 주소 변경이므로 기존 발행 글이 있으면 일반 라우팅 변경 보호를 따릅니다. 코드로 배포하는 모델은 `editor`에서 저장 구조를 바꾸지 않고 ROOT-ADMIN의 기본 필드 이름과 분류 단계 이름만 바꿀 수 있습니다. ```json { "editor": { "labels": { "title": "질문", "excerpt": "짧은 답변", "body": "상세 답변", "categories": "질환 분류", "tags": "검색 태그" }, "categoryLevels": ["진료 영역", "세부 질환"] } } ``` `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만 표시됩니다. 아직 CMS에 글이나 초안이 없는 미래 콘텐츠는 `textarea`에 내부 콘텐츠 키 형식을 선언해 예약할 수 있습니다. ROOT-ADMIN은 전용 입력기에서 접두사·중복·최대 개수를 검사하며, 저장 API도 같은 규칙을 적용합니다. 값은 공개 `fields`에 줄바꿈 문자열로 그대로 제공되므로 고객 FRONT가 현재 발행 원장과 대조해 링크 노출을 결정합니다. ```json { "key": "field_related_content_keys", "name": "related_content_keys", "label": "미발행 FAQ 예약 키", "type": "textarea", "format": "internal_content_keys", "keyPrefix": "faq", "maxItems": 5 } ``` 키는 `faq.headache.migraine.aura-symptoms`처럼 영문 소문자·숫자·한글과 점· 하이픈으로 구성합니다. `keyPrefix`를 주면 해당 접두사로 시작하는 키만 저장할 수 있습니다. 이 필드 자체는 미발행 URL을 만들지 않습니다. ### 본문 안의 예약 내부 링크 글 본문에서는 다른 글을 텍스트 표기로 연결할 수 있고, 아직 발행되지 않은 글도 미리 연결해 둘 수 있습니다. ```text [[internal:{키}|표시 문구]] ``` **키는 대상 글의 정규 공개 경로 조각을 점으로 이은 것**입니다. 경로는 사이트맵· 단축링크와 같은 규칙으로 정해지므로 콘텐츠 유형에 관계없이 한 규칙입니다. | 공개 경로 | 키 | |---|---| | `/faq/headache/migraine/aura-symptoms` (계층형 분류 모델) | `faq.headache.migraine.aura-symptoms` | | `/column/headache/my-post` (카테고리 주소 컬렉션) | `column.headache.my-post` | | `/blog/my-post` (일반 컬렉션) | `blog.my-post` | | `/team/hong` (상세 프리셋 모델) | `team.hong` | 고정 페이지·`data_only` 모델처럼 글별 상세 주소가 없는 콘텐츠는 대상이 되지 않습니다. ROOT-ADMIN 편집기 도구 모음의 **내부 링크 삽입** 버튼이 이 표기를 대신 만들어 줍니다. 작성자는 콘텐츠 유형과 분류를 이름으로 고르고 글(초안 포함)을 목록에서 고르거나, 아직 없는 글의 slug만 적습니다. 각 글의 게시 주소 영역에는 다른 글에서 이 글을 연결할 때 쓰는 키가 복사 버튼과 함께 표시됩니다. 이 표기는 본문 `body_json`의 일반 텍스트로 저장되며 공개 API도 그대로 내보냅니다. 편집기 안에서는 칩으로 보여 주며(대상 글이 있으면 제목·발행 상태, 없으면 "아직 없는 글"), 저장 형식은 바뀌지 않습니다. **`@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`, 상세 주소가 없는 글은 `null`). 링크·사이트맵·내부 링크 키에 이 값을 그대로 쓰면 모델 규칙이 바뀌어도 FRONT 코드를 고칠 필요가 없습니다. 내부 링크 키는 이 경로의 조각을 점으로 이은 값과 같습니다. **주소가 바뀐 글도 자동으로 따라가게 하려면** 공개 글 응답의 `previous_slugs`(옛 slug 목록, 최신순 — `@roottale/cms-client`에서는 `previousSlugs`)를 함께 쓰세요. 현재 경로의 마지막 조각을 옛 slug로 바꾼 경로도 같은 글의 키로 등록하면, `[[internal:blog.old-slug|…]]` 처럼 옛 키로 남아 있는 본문도 현재 주소로 렌더됩니다(분류 이동은 이력이 없어 대상 밖). ## 페이지·글·정보 항목 항목 API는 기존 `/v1/cms/posts`를 그대로 쓰며 모든 응답에 `model_key`와 `field_values`가 포함됩니다. ```json { "model_key": "team-member", "title": "홍길동 세무사", "slug": "hong-gildong", "body_json": {"type":"doc","content":[]}, "field_values": { "position": "대표 세무사", "specialties": ["법인세", "상속세"] } } ``` - `page` 모델은 `type: "page"`, `article`·`entity` 모델은 `type: "post"`로 저장됩니다. `model_key`와 `type`이 다르면 요청을 거부합니다. - `entity` 항목에는 작성자·카테고리·태그를 붙일 수 없습니다. - 작성자를 사용하는 `article` 모델은 발행·예약 전에 활성 공개 작성자가 필요합니다. - 기존 자동화가 `model_key`를 생략하면 활성 page/article 모델이 정확히 하나일 때만 호환 처리됩니다. 후보가 여러 개면 `400 model_key_required`입니다. - 항목의 모델은 생성 뒤 바꿀 수 없습니다. 다른 모델로 옮기려면 새 항목을 만드세요. 공개 FRONT는 검증된 표시 값 `fields`를 읽습니다. 관리 자동화는 편집 가능한 원문 `field_values`를 사용합니다. ## 노출 슬롯과 캠페인 전용 관리 화면과 예약 시작·종료, 수정안 저장 및 공통 Next.js runtime 연결은 [팝업·배너와 예약 표시](popups-and-banners.md)를 따릅니다. 아래 단일 슬롯 조회는 이전 연동과의 호환용입니다. 노출 슬롯은 FRONT의 사이트 콘텐츠 계약에서 옵니다. 관리 API로 슬롯을 만들거나 수정할 수 없습니다. - `GET /v1/cms/exposure-slots` - `GET|POST /v1/cms/exposures` - `GET|PATCH /v1/cms/exposures/{exposure_id}` - `POST /v1/cms/exposures/{exposure_id}/publish` - `POST /v1/cms/exposures/{exposure_id}/archive` 생성은 항상 초안입니다. 수정·발행·보관은 `version`을 확인합니다. 발행 응답의 `overlap`은 같은 슬롯·경로·기간에 겹치는 캠페인 수와 ID를 알려 줍니다. 겹침은 오류가 아닙니다. 새 공통 runtime은 같은 위치의 유효한 항목을 순서대로 캐러셀로 표시합니다. 아래 호환용 단일 조회는 우선순위와 최신순으로 한 건을 선택합니다. ```json { "slot_key": "global-popup", "kind": "popup", "content": {"variant":"notice","title":"여름 휴무 안내"}, "starts_at": "2026-08-20T00:00:00.000Z", "ends_at": "2026-08-25T00:00:00.000Z", "target_paths": ["/"], "priority": 10, "repeat": "session" } ``` ## MCP와 CLI MCP는 각 HTTP 작업을 같은 이름의 도구로 제공합니다. - 모델: `listCmsContentModels`, `getCmsContentModel`, `createCmsContentModel`, `updateCmsContentModel`, `activateCmsContentModel`, `deactivateCmsContentModel`, `deleteCmsContentModel` - 필드: `listCmsFieldGroups`, `getCmsFieldGroup`, `createCmsFieldGroup`, `updateCmsFieldGroup`, `activateCmsFieldGroup`, `deactivateCmsFieldGroup`, `deleteCmsFieldGroup` - 항목: `listManagedCmsPosts`, `getManagedCmsPost`, `createCmsPost`, `updateCmsPost`, `publishCmsPost`, `unpublishCmsPost`, `deleteCmsPost` - 노출: `listCmsExposureSlots`, `listCmsExposures`, `getCmsExposure`, `createCmsExposure`, `updateCmsExposure`, `publishCmsExposure`, `archiveCmsExposure` CLI의 큰 JSON 입력은 camelCase 키를 쓰는 `--input-file`로 전달합니다. ```bash npx -y @roottale/cms-mcp cli models list npx -y @roottale/cms-mcp cli models create --input-file ./model.json npx -y @roottale/cms-mcp cli fields create team-member --input-file ./fields.json npx -y @roottale/cms-mcp cli entries create \ --model-key team-member --title "홍길동" --slug hong-gildong \ --body-file ./body.json --field-values-file ./values.json npx -y @roottale/cms-mcp cli exposure-slots list npx -y @roottale/cms-mcp cli exposures create --input-file ./exposure.json npx -y @roottale/cms-mcp cli exposures publish "<exposure-id>" ``` `posts`는 기존 스크립트 호환 별칭입니다. 새 자동화는 `entries`를 권장합니다. ## 공개 FRONT 연결 고객 FRONT는 `fetchContentModels()`와 `fetchPosts({ modelKey })`로 활성 모델과 항목을 읽습니다. 노출은 개발자가 `RootTaleExposureSlot`을 배치한 위치에만 표시됩니다. ```tsx import { RootTaleExposureSlot } from "@roottale/cms-renderer-next/server"; export default async function Layout({ children }: { children: React.ReactNode }) { return <> {children} <RootTaleExposureSlot apiKey={process.env.ROOTTALE_API_KEY!} slotKey="global-popup" path="/" allowedVariants={["notice"]} revalidate={60} /> </>; } ``` 공개 raw API는 다음 세 경로입니다. - `GET /v1/cms/public/content-models` - `GET /v1/cms/public/posts?model_key=team-member` - `GET /v1/cms/public/categories?collection_key=faq` (`id`, `parent_id` 포함) - `GET /v1/cms/public/exposures?slot_key=global-popup&path=%2Fabout` ## FRONT 전용 상세 주소로 사이트 열기 한 모델의 일부 형식만 별도 상세 화면을 쓰면 사이트 콘텐츠 계약의 해당 `models` 항목에 `siteLinkRules`를 선언합니다. 예를 들어 `blog`의 `content_format=media`는 다음처럼 연결합니다. ```json { "modelKey": "blog", "preset": "article", "siteLinkRules": [ { "field": "content_format", "equals": "media", "detailPath": "/news/media/:slug" } ] } ``` ROOT-ADMIN 글 목록·편집 화면의 공개/검수 사이트 열기가 저장된 `metaJson.acf` 값과 규칙을 대조합니다. 해당 형식만 선언한 내부 상세 주소로 열며, 다른 형식은 기존 주소를 유지합니다. 규칙이 충돌하거나 저장 주소가 없는 글에는 링크를 만들지 않습니다. 예시는 `examples/nextjs/cms/site-link-rules.example.json`에 있습니다. 이 선언은 글의 저장 주소·공개 API·주소 이력·리다이렉트를 바꾸지 않습니다. FRONT는 저장 주소를 검증하고 실제 상세·canonical·목록을 같은 전용 경로로 구현해야 합니다. 해당 FRONT 배포를 확인한 뒤 계약을 등록하세요. 관리자 링크를 고치기 위해 폐기한 개발 주소를 다시 열지 않습니다. ### 사진 중심 편집과 불필요한 입력 숨김 `editor.primaryImage`는 필드의 **name**으로 사진을 연결한다. `field`는 image 필드, `fallbackUrlField`는 기존 이미지 URL을 저장한 text/url 필드, `altField`는 대체 텍스트다. 연결한 필드만 제목 바로 아래 큰 미리보기·직접 업로드·보관함 선택으로 모으며, 기존 필드 저장값과 공개 API는 그대로 사용한다. 주소만 있는 이관 사진도 표시한다. 사진 제거는 선택한 미디어 연결과 대체 URL을 함께 비운다(미디어 파일 자체는 삭제하지 않는다). `editor.authorProfile`을 켜면 이 모델의 공개 글마다 글 작성자가 자동으로 만들어진다. 제목과 `imageField`·`bioField`(필드 name)가 이름·사진·소개가 되고 글 slug가 작성자 주소가 되며, 글을 고치면 따라오고 내리면 보관된다. `presentation.hiddenWhen`에 걸린 글은 빠진다. 글마다 어느 작성자로 낼지는 계속 직접 고른다. 사이트는 `RootTaleBlogPost`의 `authorHref`로 그 주소를 모델 상세 화면에 잇는다. `editor.hiddenSections`는 `body`, `excerpt`, `featuredImage`, `relatedContent`, `editorialReview`, `reservations` 중 홈페이지에서 사용하지 않는 편집 영역을 숨긴다. 기존 값은 지우지 않는다. `excerpt`가 발행 필수면 숨길 수 없다. 정보형 모델은 검색·관련 글 도구가 자동으로 빠지고, `body`·`featuredImage`까지 숨기면 비어 있는 「추가 입력」도 표시하지 않는다. 상세 주소가 있는 의료진 등의 검색 설정은 유지한다. ```json { "editor": { "labels": { "title": "공간명" }, "primaryImage": { "field": "photo", "fallbackUrlField": "image_url", "altField": "image_alt" }, "hiddenSections": ["body", "featuredImage"] } } ``` 콘텐츠 캘린더는 `preset: "article"`인 글의 예약·발행·마감 일정만 표시한다. 시설·의료진 같은 entity와 고정 페이지는 제외하며, 구 collection 연결도 모델의 `compatibilityCollectionKey`로 구분한다. 알 수 없는 모델은 표시하지 않는다. 모델과 collection이 없는 기존 일반 글·기획 초안은 계속 표시한다. ## 숨김 글과 화면 표기 확인 `data_only`·`detail`·`category_tree` presentation은 `listPaths`와 함께 `hiddenWhen: { field: "hidden", equals: true }`를 선택 선언할 수 있습니다. FRONT가 `acf.hidden === true`인 글을 숨기는 경우 사용합니다. 이 조건에 맞는 글은 제목으로 공개 여부를 검사하지 않습니다. 삭제 확인(`expect: absent`)으로 바꾸지 않으므로 메뉴 등에 같은 글자가 있어도 실패 경보를 만들지 않습니다. 조건이 없거나 숨김을 해제하면 기존 확인을 수행합니다. 이 선언 자체가 FRONT에서 글을 숨기지는 않습니다. FRONT가 저장된 제목을 다른 표기로 표시한다면 사이트 콘텐츠 계약에 규칙을 선언합니다. ```json { "displayTextRewrites": [ { "pattern": "도수기능치료실", "replacement": "기능회복치료실" } ] } ``` 규칙은 순서대로 적용합니다. 최대 20개이며 `pattern`은 200자 이하의 Unicode 정규식 (`gu`), `replacement`는 `$`를 포함하지 않는 100자 이하 문자열이어야 합니다. 잘못된 정규식과 제한 위반은 계약 등록에서 거절합니다. FRONT도 같은 규칙으로 렌더링해야 하며 CMS 원문은 바꾸지 않습니다. [표시 예시](../examples/nextjs/connected-content.md#화면-표기-규칙)를 참고하세요. ROOT-ADMIN은 변환된 제목을 확인 항목의 `expectedTitle`에 담아 상세·목록에서 비교합니다. 화면과 경보의 글 이름은 원문을 유지합니다. 규칙이 없는 기존 계약은 checksum이 그대로이며, 설치 계약을 읽지 못한 경우에는 원문으로 확인합니다. 공통 필드·검색 메타데이터 검사는 제목 변환의 대상이 아닙니다. FRONT 코드와 플랫폼 파서를 배포한 뒤 계약 version을 올려 등록하세요.