---
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을 올려 등록하세요.
