@roottale/cms-mcp
Version:
RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.
160 lines (128 loc) • 8.74 kB
Markdown
# 사업장 정보와 고정 원고 연결
실제로 사용하는 사업장 입력만 사이트 계약에 선언한다. 기존 계약에 합치고 version을
올린다. 관리자와 API 파서를 먼저 배포한 뒤 동기화한다.
```json
{
"businessProfileFields": ["name", "telephone", "faxNumber", "address", "geo", "openingHours", "profiles"],
"contentAreas": [{
"key": "visit-copy",
"pageSlug": "visit-copy",
"label": "방문 안내",
"path": "/guide",
"editor": {
"kind": "fields",
"fields": [
{ "key": "visit-lead", "label": "방문 안내 문구", "group": "방문 안내", "kind": "multiline" },
{ "key": "visit-photo", "label": "방문 안내 사진", "group": "방문 안내", "kind": "image" }
]
}
}]
}
```
`fields` 문서는 H2(key)와 paragraph(value) 쌍으로 저장한다. 최초 문서는 초안으로
등록하며 같은 slug가 있으면 기존 값을 보존한다. 계약의 key를 바꾸거나 재사용하면
기존 저장값과의 연결이 달라지므로 내용 이관을 먼저 준비한다.
접수 마감은 `null`을 빈 키로 정리하지 않는다.
```ts
import { fetchBusinessProfile, type BusinessOpeningHours } from "@roottale/cms-client/server";
const profile = await fetchBusinessProfile({
apiKey: process.env.ROOTTALE_API_KEY!,
siteId: process.env.NEXT_PUBLIC_ROOTTALE_SITE_ID,
});
function receptionLabel(row: BusinessOpeningHours): string | null {
if (!Object.hasOwn(row, "receptionCloses")) {
// 이전 데이터: 이 사이트에 확인된 기존 세션 안내가 있으면 별도로 대조한다.
return null;
}
return row.receptionCloses ? `접수 마감 ${row.receptionCloses}` : null;
}
const hours = profile?.openingHours.map((row) => ({
...row,
receptionLabel: receptionLabel(row),
}));
```
공개 시간·전화·주소는 같은 서버 조회 결과를 내비게이션·본문·푸터·JSON-LD에 전달한다.
`theme.updated` 웹훅에서 기존 `BUSINESS_CACHE_TAG`를 갱신한다. 현재 안내와 CMS가
정상 응답한 빈 목록을 섞지 않도록 미연결·장애와 명시적 숨김을 구분한다.
토큰 미리보기는 공개용 통계·팝업 provider와 레이아웃을 분리한다. API의 토큰 인증 뒤
응답 글 ID도 요청 ID와 대조하고 `private, no-store`, `noindex`, `no-referrer`를 적용한다.
초안 표시를 위한 변환 함수를 공개 목록의 검수 판정에 사용하지 않는다.
ROOT-ADMIN의 사이트 내용 편집기는 `sitePreview` 설정이 준비되면 현재 입력값으로
사이트 미리보기를 연다. 이 동작은 글을 저장·발행하지 않고 기존 미리보기 토큰을
발급한다. 사이트에서 토큰 응답의 `bodyJson`을 해당 `contentAreas.pageSlug`의 화면에
적용해야 한다. 일반 본문에 내부 입력 key를 출력하지 않는다. 공개 페이지 조회와
미리보기 문서 적용 경로를 구분하고, 미리보기 내용으로 공개 캐시를 갱신하지 않는다.
## 미리보기 배포의 검색·공유 연결 확인
HTTPS `*.roottale.app`은 배포 수준에서 검색을 차단한다. 검색·공유 설치 검사와
변경 후 확인은 일반 robots meta 또는 `X-Robots-Tag` 응답 헤더에 `noindex`가
있어야 통과하고, 배포가 추가한
`nofollow`를 허용한다. CMS가 요구한 `nofollow`가 빠졌거나 제목·설명·공유 이미지·
계약 표식이 다르면 계속 실패한다. 크롤은 허용하여 검색엔진이 `noindex`를 읽게 한다.
페이지별 SEO 설정을 변경해도 미리보기 배포의 검색 차단은 유지된다.
정식 도메인으로 전환하면 일반 robots 비교와 새 주소의 설치 검증을 다시 적용한다.
검색 메타데이터 검사는 비동기 head 응답을 최대 20초 기다린다. 일반 본문 검사는
기존 5초를 유지하며, 주기 확인은 마지막 요청과 결과 처리 시간을 남겨 두고 시작을 멈춘다.
## 편집 상태와 연결 메뉴
사이트 내용 편집 중 서버 응답으로 다른 버전이 도착하면 입력값과 원래 저장 버전을
함께 유지한다. 저장 충돌은 새 버전 번호로 재시도하여 덮어쓰지 않는다. 저장 성공,
되돌리기 또는 확인한 이력 복원 후 새 서버 내용을 받아들인다. 저장 성공 후에는
새 저장본이 도착할 때까지 입력을 잠가 다음 편집이 이전 버전으로 저장되지 않게 한다.
사업장 정보의 고객 메뉴는 `businessProfileFields`를 서버와 클라이언트 모두에 전달하여
판정한다. 모델의 `editor.hiddenSections`에 `reservations`가 있으면 예약 입력을 숨기되
저장된 예약 키는 보존한다. 관련 글의 미선택 동작은 사이트마다 다르므로 편집기가
자동 추천을 약속하지 않는다.
`titleFromFields`를 쓰는 새 정보 항목은 제목 칸이 없어도 주소를 생성한다.
자동 주소는 영문·숫자·하이픈을 사용하고, AI 응답 전 또는 한글 대체 응답일 때에도
서버의 중복 주소 검사로 최종 주소를 정한다. 기존 주소와 수동 입력은 보존한다.
검색·공유 설정 목록에서는 별도의 검색 설정 계약이 없는 `contentAreas` 저장 문서를
제외한다. 같은 화면의 실제 고정 경로를 골라 검색 제목·설명을 편집한다. 별도 페이지나
게시물 메타데이터 계약이 있는 문서는 계속 표시하며, 원문·기존 설정·내보내기는 보존한다.
### 기존 반복 목록의 화면 편집 연결
`visualEditing`을 연결할 때 필드 그룹을 먼저 등록하고 계약 등록의 dry-run을 확인한다.
필드 key는 중첩 깊이와 관계없이 유일해야 한다. 등록 단계에서 고정 `page` 템플릿을
포함해 관리자와 같은 필드 해석·섹션 검사를 수행한다.
기존 글에 반복행 `_id`가 없으면 관리자에서 작업본을 열 때 누락된 ID만 자동 저장한다.
미리보기는 저장된 작업본 ID로 행 주소를 만들고 공개 사이트에는 다음 발행 때 반영된다.
행 순번으로 ID를 대신하거나 공개 렌더에서 임시 ID를 생성하지 않는다.
자세한 연결 규칙은 [실제화면 콘텐츠 편집](../../docs/visual-content-editing.md)을 따른다.
## 화면 표기 규칙
사이트가 CMS 문구를 다른 표기로 보여 준다면 같은 규칙을 사이트 콘텐츠 계약의
`displayTextRewrites`에도 선언한다. 다음은 계약에 선언한 배열을 사이트에서 소비하는 예시다.
플랫폼 내부에서는 `/site-content-contract`의 `applyDisplayTextRewrites`가 같은 처리를 한다.
```ts
const displayTextRewrites = [
{ pattern: "도수기능치료실", replacement: "기능회복치료실" },
];
// 이 배열을 기존 사이트 계약의 displayTextRewrites에도 포함한다.
function displayTitle(title: string): string {
return displayTextRewrites.reduce(
(text, rule) => text.replace(new RegExp(rule.pattern, "gu"), () => rule.replacement),
title,
);
}
// JSX: <h2>{displayTitle(post.title)}</h2>
```
규칙은 20개 이하, pattern은 200자 이하, replacement는 100자 이하이며 `$`를 허용하지
않는다. 계약 파서가 정규식의 `gu` 컴파일도 검사한다. 글 원문과 경보 이름은 유지되고
공개 화면 확인만 변환된 제목을 기대한다. FRONT에서 숨기는 히어로 모델이라면
presentation에 `hiddenWhen: { field: "hidden", equals: true }`도 선언하고 렌더링에서
`acf.hidden === true`인 항목을 제외한다. 숨김 글은 제목 검사 계획을 만들지 않는다.
## 글 모델의 세부 주제
칼럼 모델의 기존 `editor`에 다음 설정을 합친다. 주소를 결정하는 category 설정은
유지하고 주제 목록은 사이트 공통 `custom / content_topic` term으로 등록한다.
```json
{
"topic": {
"label": "세부 주제",
"levels": ["영역", "질환"],
"required": "first-publish",
"helpText": "영역만 선택하거나 해당 질환까지 선택하세요."
}
}
```
안내 카드를 쓰지 않는 FAQ는 `required`를 생략하고 `card: false`를 넣는다.
상위만 고르면 상위 ID, 하위를 고르면 하위 ID가 `contentEditor.primaryTermId`에 저장된다.
관리 API로 처음 발행하는 글은 `meta_json.contentEditor.primaryTermId`에 그 ID를 보내야 한다.
기존 `contentEditor`의 다른 값은 보존한다(PATCH는 namespace 단위 병합).
주제를 비워도 초안은 저장되며, 발행·예약 요청은 `model_topic_required` 오류를 반환한다.
발행 이력이 있는 글의 재발행은 이 필수 검사에서 제외한다.