UNPKG

@roottale/cms-mcp

Version:

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

519 lines (428 loc) • 33.1 kB
--- title: 실제화면 콘텐츠 편집 description: 기존 사이트 템플릿에 필드 주소와 저장된 draft 미리보기를 연결하는 방법 --- # 실제화면 콘텐츠 편집 ROOT-ADMIN의 실제화면 편집은 고객 사이트가 소유한 JSX와 디자인을 그대로 사용합니다. 사이트는 편집 가능한 DOM에 안정된 필드 주소를 붙이고, 인증된 미리보기 라우트에서 저장된 draft를 같은 템플릿으로 렌더합니다. 입력과 저장은 관리자 패널에서 처리하며 iframe 안의 문구를 임시로 바꾸지 않습니다. ## 1. 편집할 템플릿 등록 사이트 콘텐츠 계약에 `visualEditing`을 추가합니다. 기존 `models`와 모델의 필드 정의를 재사용하며, 이 선언은 템플릿·섹션과 편집 가능한 필드의 배치만 설명합니다. 전체 계약의 나머지 속성은 그대로 유지합니다. `visualEditing`을 선언하지 않은 사이트에는 편집 화면·안내 카드·콘텐츠 버전 응답을 추가하지 않습니다. 기존 공개 필드 포맷·경로 계산·웹훅과 revalidate 동작을 유지합니다. DB의 콘텐츠 버전 트리거도 선언 사이트에만 버전과 수정 시각을 갱신합니다. ```ts visualEditing: { previewPath: "/preview/content/:id", templateVersion: "site-2026-10-19", templates: [{ key: "condition-detail", modelKey: "condition", create: true, sections: [ { key: "intro", label: "소개", fieldKeys: ["field_hero"] }, { key: "comparison", label: "비교표", fieldKeys: ["field_comparison"], allowHide: true, allowDelete: true }, ], }], }, ``` `previewPath`는 `:id`를 정확히 한 번 포함하는 내부 경로입니다. 관리자는 이 경로를 사이트 주소(`sitePreview.baseUrl`, 없으면 대표 도메인)에서 엽니다. 글 미리보기 방식(`sitePreview.mode`)을 바꿀 필요는 없습니다. `templateVersion`은 실제 배포 템플릿과 함께 갱신합니다. 템플릿 key와 그 안의 섹션 key는 중복할 수 없으며, `modelKey`는 등록된 모델 또는 기본 `page`여야 합니다. `create: true`는 모델마다 하나만 허용하며 새 상세 페이지 생성에 사용할 템플릿을 뜻합니다. `fieldKeys`는 기존 `cms-fields` 정의의 key를 깊이와 무관하게 참조하며 한 템플릿 안에 한 번만 배치합니다. 그룹·반복 key는 그 하위값 전체를 지정합니다. 여러 섹션이 공유하는 상위 그룹 전체는 편집할 수 없고, 한 섹션이 독점하는 상위 그룹·반복 목록만 컴파일러가 전체 편집 컨트롤을 제공합니다. `allowHide`·`allowDelete`를 켜지 않은 섹션에는 그 작업을 제공하지 않습니다. 공개 API는 글의 실제 `templateKey`·`modelKey`가 이 계약의 템플릿과 일치할 때 코드가 소유하는 구조화 필드를 제공합니다. 사이트의 고정 레이아웃 속성도 유지하되 수정 허용 여부는 등록된 필드 정의로 별도 검증합니다. 임의 템플릿 이름을 조회에 붙여 편집 가능한 모델로 바꾸지 않습니다. 공개 글 조회와 미리보기의 `fields`는 반복행 `_id`와 코드 소유 중첩 값을 유지하면서, 등록된 `image`·`file` 필드만 일반 공개 필드와 같은 `{ id, url, variants, alt }` 형태로 제공합니다. `gallery`는 이 객체의 배열입니다. 그룹·반복·유연한 콘텐츠 안의 미디어에도 같은 규칙을 적용하며, 등록되지 않은 중첩 값은 변환하지 않습니다. 해석할 수 없는 미디어는 `image`·`file`에서 `null`, `gallery`에서 해당 항목 제외로 처리합니다. 사이트는 이미지의 `url` 또는 `variants`를 렌더에 사용합니다. 관리자 선택·저장 값은 계속 미디어 UUID(갤러리는 UUID 배열)이며, `post_object`·`relationship`·`taxonomy`·`user` 값은 템플릿에서 기존 raw ID를 유지합니다. ### 묶음 구성 템플릿의 `sections[].label`에 앞뒤 공백을 포함한 ` › `를 넣으면 하위 묶음으로 표시합니다. 예를 들어 `검진 › 준비 안내`는 검진 안의 준비 안내 묶음입니다. 묶음은 첫 등장 순서로 표시하며, 최대 3단계로 읽습니다. 3단계를 넘는 부분은 마지막 단계에 합칩니다. 같은 경로는 합치되 숨김·삭제 기능이나 상태가 있는 묶음은 따로 표시합니다. 맨 위 묶음은 15개 이하, 한 묶음의 자기 칸은 20칸 이하를 권장합니다. 등록 도구는 기준을 넘거나 묶음 이름에 줄바꿈·연속 공백이 있으면 경고하며, 등록을 막지는 않습니다. 칸 이름은 값을 보지 않아도 뜻을 알 수 있게 씁니다. 같은 부모 아래 같은 이름의 칸이 여러 개면 목록에 자동으로 번호를 붙입니다. 입력칸의 이름과 저장 값은 바뀌지 않습니다. ### 배경 영상 필드 영상 선택칸은 `{ type: "file", mediaKind: "video" }`로 정의합니다. `mediaKind`가 없으면 기존 입력 방식이 유지됩니다. 저장 값은 미디어 UUID이며 공개 글 조회와 저장된 draft 미리보기는 같은 값을 제공합니다. ```ts { id: "영상 미디어 UUID", url: "https://cdn.example/pc.mp4", alt: null, variants: { mobile: "https://cdn.example/mobile.mp4", poster: "https://cdn.example/pc.jpg", mobilePoster: "https://cdn.example/mobile.jpg", }, } ``` `url`은 PC용 H.264 MP4입니다. 모바일용 주소는 `variants.mobile`, 각 첫 장면 사진은 `poster`·`mobilePoster`에 있습니다. 소리는 없습니다. 배경 재생에는 `muted`·`playsInline`·`autoPlay`와 poster를 지정하고 모바일 화면에서는 모바일용 주소를 사용하세요. 실제화면 편집 주소는 영상 요소를 감싼 선택 가능한 컨테이너에 붙이면 됩니다. 영상 업로드·삭제는 ROOT-ADMIN에서 루트테일 직원만 수행합니다. 고객은 올라온 영상을 선택하거나 필드 연결만 제거합니다. REST·CLI·MCP 업로드는 계속 이미지와 PDF만 지원하며 영상 삭제도 거절합니다. 직원이 선택한 60초 이하 MP4·MOV·M4V·WebM을 브라우저에서 PC 최대 1920·모바일 최대 854로 줄여 무음 MP4와 JPG 두 장을 올립니다. 압축된 영상은 파일당 50MB까지이며 원본 파일은 전송하지 않습니다. 주소 없는 `data_only` 모델의 글(`type: "post"`)도 `models[].templateKey`와 `visualEditing.templates`를 같은 key로 연결하면 실제화면 편집기로 엽니다. 새 항목은 해당 모델의 글 목록에서 만들며 관리용 제목과 표시 순서를 저장합니다. PC·모바일 미리보기는 동일한 영상 공개 값 계약을 사용합니다. ### 기존 사이트를 연결할 때 `content-model:sync`는 dry-run에서 바뀔 항목을 보여 줍니다. 검색 노출이 켜진 분류를 끄는 변경은 `--allow-hub-demotion` 없이는 멈추므로, 노출을 유지하려면 파일에 `"hubPromoted": true`를 넣으세요. 먼저 `content-model:sync`로 사이트 필드 그룹을 등록한 뒤 `site:content-contract:sync`로 화면 편집 계약을 등록합니다. 필드 key는 해석된 그룹 전체에서 중첩 깊이와 관계없이 유일해야 합니다. `fieldKeys`에 없는 key를 쓰거나 여러 섹션이 같은 값을 편집하도록 선언하면 등록 단계에서 템플릿과 문제 key를 표시하고 중단합니다. 이 검사는 dry-run과 `--apply`에 모두 적용하며 고정 페이지의 `page` 모델도 포함합니다. 관리자와 같은 공개 상태·모델·템플릿·분류·컬렉션 조건으로 코드 그룹, DB 그룹, override를 해석합니다. 아직 글이 없는 템플릿과 생성용 템플릿은 분류·컬렉션이 없는 초기 상태도 검사합니다. 필드 그룹이 없으면 `content-model:sync`를 먼저 실행하라는 안내가 표시됩니다. `visualEditing`이 없는 계약과 `--exposure-slots`만 등록하는 경로에는 이 검사를 적용하지 않습니다. 기존 글의 반복행에 `_id`가 없어도 목록 전체를 수동으로 다시 저장할 필요는 없습니다. 관리자가 화면 편집 작업본을 열면 정의된 `repeater`·`flexible_content`의 누락 ID를 중첩 행까지 UUIDv7으로 채워 **작업본에만** 저장합니다. 기존 작업본과 이력 복원· 공개 내용으로 다시 시작할 때도 같은 규칙을 적용합니다. 기존 ID와 행 순서, 값, 코드 소유 값은 보존하고 정의에 없는 배열은 바꾸지 않습니다. 잘못되거나 중복된 ID는 자동 교체하지 않고 오류로 알립니다. 이 준비 작업만으로 공개 글이나 발행 상태는 바뀌지 않습니다. ID는 다음 발행 때 공개 응답에 함께 반영됩니다. ID만 추가한 내용을 고객의 미저장 수정으로 표시하지 않으며, 이미 모든 ID가 있으면 저장이나 작업본 버전 증가도 없습니다. 미리보기 토큰과 PC·모바일 렌더 영수증은 보정이 끝난 저장 버전을 기준으로 발급합니다. 공개 사이트에서는 첫 발행 전에도 기존 콘텐츠를 그대로 렌더하고, 편집 주소는 인증된 작업본의 ID를 사용합니다. ## 2. 필드 주소 연결 RSC에서도 사용할 수 있는 `visualEditAttributes`는 `data-rt-edit` 속성을 만듭니다. 공개 렌더에는 두 번째 인자 `false`를 전달합니다. 주소는 실제 등록한 모델의 필드 정의와 일치해야 하며, 임의 HTML에 주소를 붙여도 저장 권한이 생기지 않습니다. ```tsx import { visualEditAttributes } from "@roottale/cms-renderer-next/visual-edit"; <h1 {...visualEditAttributes({ entityId: post.id, fieldKey: "title", // 기존 필드 정의의 leaf key path: ["hero", "title"], // ACF 루트부터 시작하는 전체 저장 경로 }, isPreview)}> {hero.title} </h1> <td {...visualEditAttributes({ entityId: post.id, fieldKey: "description", path: ["comparison", "rows", `@${row._id}`, "description"], itemId: row._id, // 선택 사항. 경로의 마지막 @id와 같아야 함 }, isPreview)}> {row.description} </td> ``` 반복 항목의 `_id`는 저장된 UUIDv7을 그대로 사용합니다. 배열 순번을 주소나 영속 React key로 쓰지 않습니다. 중첩 반복 항목은 각 단계에 `@<id>`를 넣습니다. 표 행을 위아래로 옮겨도 같은 행의 주소가 유지됩니다. 그룹 전체나 반복 목록을 편집하는 주소는 그 필드의 경로에서 끝납니다. 섹션 숨김·삭제는 `post.contentEditor.sectionStates[sectionId]`를 읽어 템플릿에서 반영합니다. `sectionId`는 사이트 계약의 안정된 코드 key입니다. `hidden`과 `deleted`는 공개 템플릿에서 출력하지 않지만, 관리자는 섹션 트리에서 다시 표시하거나 복원할 수 있습니다. 디자인 클래스·배치·라우트 코드는 편집 필드로 노출하지 않습니다. ## 3. 인증된 draft를 실제 템플릿으로 렌더 기존 [토큰 미리보기](blog.md)의 `fetchPostPreview({ apiKey, token })`를 사용합니다. 항상 동적 렌더하고 캐시하지 않습니다. URL의 글 ID와 응답 ID를 대조하고, 토큰이 만료되거나 draft 버전이 대체되면 새 미리보기를 요청하도록 안내합니다. 권한 없는 요청에 고정 fixture나 발행 글을 대신 내보내지 않습니다. 실제화면 편집 토큰의 응답에는 `post.preview.visualTarget`이 있습니다. ```ts type VisualPreviewTarget = { entityId: string; draftId: string; draftVersion: number; contractVersion: string; templateVersion: string; }; type VisualRenderReceipt = VisualPreviewTarget & { dependencyVersions: Record<string, string>; }; ``` `visualTarget`의 계약·템플릿 버전이 배포된 사이트와 일치하는지 서버에서 확인합니다. 플랫폼 이관 도구의 `--runtime-receipt /absolute/site/cms/content-runtime-receipt.json`은 검증한 계약의 정규화 해시와 템플릿 버전을 생성합니다. 이 파일을 사이트 코드와 함께 배포하고 `visualTarget.contractVersion`·`templateVersion`을 대조합니다. 계약을 바꾸면 이 파일도 다시 생성합니다. 비공개 플랫폼 스키마를 고객 코드에 복제하지 않습니다. 일치할 때만 bridge를 붙입니다. `dependencyVersions`에는 그 렌더에서 실제로 읽은 공개 공통 문구·관련 콘텐츠·CTA 대상의 ID와 `contentVersion`을 문자열로 기록합니다. 추측한 버전이나 요청 URL의 값을 그대로 복사하지 않습니다. 의존 콘텐츠가 없는 템플릿은 빈 객체를 쓸 수 있습니다. 본문과 영수증에 서로 다른 조회 결과를 쓰지 않습니다. 아래 순수 함수는 `@roottale/cms-core/visual-edit`에서 가져옵니다. 이 경로를 직접 쓰면 사이트의 의존성에도 `@roottale/cms-core`를 등록합니다. renderer의 `visual-edit` 경로에서도 같은 함수를 재공개합니다. `checkPreviewCompatibility`는 영수증의 `schemaVersion === 1`, target과 영수증의 계약 버전 일치, target·영수증·배포 템플릿의 버전 일치를 함께 검사합니다. ```tsx import { checkPreviewCompatibility, visualEditorOrigins } from "@roottale/cms-core/visual-edit"; import { RootTaleVisualEditBridge } from "@roottale/cms-renderer-next/visual-edit"; // 인증·ID 대조를 마친 서버 컴포넌트에서 배포 영수증과 템플릿을 확인합니다. if (!checkPreviewCompatibility(post.preview.visualTarget, runtimeReceipt, templateVersion)) { return <p>미리보기 갱신이 필요합니다. 사이트 계약을 다시 설치해 주세요.</p>; } const allowedOrigins = visualEditorOrigins( process.env.CONTENT_EDITOR_ALLOWED_ORIGINS?.split(",") ?? [], ); const receipt = { ...post.preview.visualTarget, dependencyVersions }; return <> <ExistingSiteTemplate post={post} sharedContent={sharedContent} isPreview /> <RootTaleVisualEditBridge receipt={receipt} allowedOrigins={allowedOrigins} allowedPaths={["/", "/conditions/headache"]} /> </>; ``` `allowedOrigins`는 실제 관리자 origin의 명시적 허용목록입니다. 기본값은 `https://admin.roottale.com`이며 로컬 개발에서는 필요한 localhost origin만 추가합니다. 운영 관리자 origin은 `https://admin.roottale.com`입니다. 추가 origin은 `allowedOrigins` prop에 넣거나, 사이트 서버 env `CONTENT_EDITOR_ALLOWED_ORIGINS`를 쉼표로 분리해 전달합니다. 예: `https://admin.roottale.com,http://localhost:3000`. URL 경로 없이 scheme·host·port까지 정확히 적고 로컬 포트는 실제 관리자 포트로 바꿉니다. env 변경 뒤 사이트를 재배포합니다. ```tsx import { visualEditorOrigins } from "@roottale/cms-core/visual-edit"; const allowedOrigins = visualEditorOrigins( process.env.CONTENT_EDITOR_ALLOWED_ORIGINS?.split(",") ?? [], ); // 인증된 서버 컴포넌트에서 전달 <RootTaleVisualEditBridge receipt={receipt} allowedOrigins={allowedOrigins} /> ``` 고객 사이트의 `next.config.ts`에서 미리보기 라우트에 같은 목록을 허용합니다. 실제 previewPath가 다르면 `source`도 맞춥니다. 기존 CSP를 유지하면서 `frame-ancestors` 지시문을 아래처럼 변경하고, 프록시/CDN에서 추가한 CSP도 함께 맞춥니다. ```ts import { visualEditorOrigins } from "@roottale/cms-core/visual-edit"; const editorOrigins = visualEditorOrigins( process.env.CONTENT_EDITOR_ALLOWED_ORIGINS?.split(",") ?? [], ); export default { async headers() { return [{ source: "/preview/:path*", headers: [{ key: "Content-Security-Policy", value: `frame-ancestors ${editorOrigins.join(" ")}`, }] }]; }, }; ``` `visualEditorOrigins(extra)`는 env를 읽지 않는 순수 함수입니다. 운영 관리자 origin을 기본으로 포함하고 추가 HTTPS URL과 loopback HTTP URL을 origin으로 정규화합니다. HTTP는 `localhost`·`127.0.0.1`·`[::1]`만 허용하며 그 밖의 HTTP origin과 중복·와일드카드·인증정보를 제외합니다. CSP와 bridge에는 같은 목록을 전달합니다. 기존 전역 `X-Frame-Options: DENY`/`SAMEORIGIN`은 미리보기 라우트에서 제외합니다. `ALLOW-FROM`은 사용하지 않습니다. CSP는 HTML meta가 아닌 HTTP 응답 헤더로 보냅니다. 브라우저 Network에서 미리보기 응답의 CSP와 프레임 차단 오류를 확인합니다. iframe을 허용하는 CSP도 같은 origin으로 제한합니다. `allowedPaths`는 탐색할 수 있는 정확한 내부 경로입니다. 클릭은 관리자에 이동 요청을 보내며, 실제 폼 제출·외부 이동은 실행하지 않습니다. 공통 푸터나 목록 카드처럼 다른 엔티티의 주소를 누르면 관리자가 서버에서 권한과 계약의 모델을 확인한 뒤 해당 글의 편집 화면을 엽니다. 현재 문서에는 쓰지 않습니다. 관리자가 미리보기 URL의 fragment에 연결 session과 origin을 넣습니다. bridge는 parent window·origin·session·증가하는 sequence·정확한 target을 검증하고 `ready`와 `rendered`를 보냅니다. fragment 자체는 콘텐츠 조회 권한이 아니며 서버는 기존 미리보기 토큰으로 권한을 검증합니다. 공개 페이지에는 bridge를 넣지 않습니다. 직접 메시지를 연결하는 경우 `cms-core/visual-edit`의 `createVisualEditMessage({ session, sequence, target }, payload)`로 envelope를 조립합니다. 수신 시 source·origin을 먼저 확인하고 `parseVisualEditMessage(data)`로 파싱한 다음, `isCurrentVisualEditMessage(message, { session, sequence: lastIncoming, target })`로 세션·증가 순서·정확한 대상을 비교합니다. 통과한 메시지의 sequence만 호출자가 기록합니다. 연결 단계·재시도·타임아웃은 관리자 책임이며 이 함수들은 React나 env에 의존하지 않습니다. 기존 `messageSchema`와 protocol version 1은 그대로 유지합니다. ## 4. 저장·미리보기·발행 확인 같은 화면 폭에서 미리보기와 공개 화면의 배치·글꼴·현재 메뉴 표시를 대조합니다. 미리보기 전용 분기에서 블록 구조를 바꾸지 않습니다. 편집 표시는 인라인 `span`으로 붙이고, 현재 메뉴처럼 주소에 따라 달라지는 표시도 공개 주소를 기준으로 맞춥니다. 입력은 기존 모델의 필드 패널을 통해 저장합니다. 저장 후 draft 버전이 올라가면 새 토큰 URL로 iframe을 다시 열고 RSC를 다시 실행합니다. 관리자는 현재 선택과 스크롤 위치를 복구하며, 옛 화면을 최신 저장 결과로 표시하지 않습니다. 저장되지 않은 입력이 없으면 발행할 수 있습니다. PC와 모바일의 렌더 영수증은 화면 상태를 안내하는 데 쓰며 발행을 막지 않습니다. 다른 사용자가 먼저 저장한 경우 충돌을 표시하고 최신 문서를 다시 불러옵니다. 과거 이력 복원도 새 draft를 만들며 검토 후 별도로 발행합니다. 사이트는 [공통 콘텐츠 캐시 갱신](revalidation-webhooks.md)의 `contentEditing: true`와 `CONTENT_EDITING_CACHE_TAG`를 연결해야 합니다. 새 글 발행 뒤 기존 상세 페이지의 관련 목록과 CTA까지 같은 공개 데이터로 다시 생성되어야 합니다. Next.js의 최소 템플릿 예시는 `examples/nextjs/components/VisualContentPreview.tsx`에 있습니다. 로컬 fixture에서 클릭 → 필드 입력 → 저장 → PC·모바일 재렌더 → 발행의 흐름과, 잘못된 origin·옛 draft 영수증이 거절되는지를 확인합니다. fixture용 권한 우회는 운영 라우트에 추가하지 않습니다. 플랫폼 첫 배포는 저장소 `docs/content-editing-rollout.md`의 절차를 따릅니다. 0151 이후 운영 migration을 적용·확인한 다음 main에 merge합니다. 관리자는 Vercel에서 별도로 배포되므로 Worker의 migrate job만으로 관리자 배포 순서를 보장할 수 없습니다. ## 5. 사이트 연결 계약 다음 사이트를 연결할 때는 아래 다섯 책임을 사이트 안에서 정합니다. 설계 배경은 [코드 구조 설계 2.5·2.6절](https://github.com/RootTale/roottale-docs/blob/main/docs/design/root-admin-visual-content-editor-code-structure.md#25-사이트-연결-계약-headnerve부터)에 정리되어 있습니다(내부 저장소). 실제 연결에 필요한 규칙은 이 절을 기준으로 적용합니다. 1. **문서 원천:** 공개 API의 `CmsPostContent`를 사이트 문서로 바꾸는 `documentFromPost`를 하나 둡니다. 로컬 fixture는 읽을 때 같은 API 타입으로 변환해 이 함수를 거칩니다. `contentEditor`·`contractPageKey`는 SDK 타입을 그대로 사용합니다. 전체 목록은 `fetchAllPosts({ ...options, limit: 100, maxPages: 100, cursorGuard: "repeated" })`로 가져옵니다. 상한·커서 검사 방식은 사이트에서 명시하고 실패한 부분 목록을 공개하지 않습니다. 2. **편집 상태 해석:** 공개·미리보기 조회의 `post.contentEditorResult`로 원본 부재와 해석 실패를 구분합니다. 결과가 없으면 기본 상태를 쓰고 `success: false`면 실패로 처리합니다. 선언 사이트에서 저장 상태의 해석이 실패하면 API는 `content_editor: null`을 보내고 SDK는 실패 결과를 보존합니다. 기존 `contentEditor`는 잘못된 값을 `undefined`로 바꾸므로 부재 판단의 근거로 단독 사용하지 않습니다. 원시 입력은 `parseContentEditorState(raw)`를 씁니다. 사이트에 파서 사본을 두거나 잘못된 상태를 빈 상태로 바꿔 숨기지 않습니다. 3. **정책 값:** 콘텐츠 모드·관리 모델·공통 모델·공개 런타임·캐시 태그를 이름 있는 원장에 둡니다. 새 페이지 경로는 계약 모델의 `detailPath`에서 계산합니다. 관련 글의 대표 주제 합성·표시 개수·메뉴 규칙은 해당 사이트 정책으로 남깁니다. 4. **템플릿 조립:** 공개 화면과 인증된 미리보기가 같은 조립 함수를 호출합니다. CMS 값으로 화면을 조립할 때 다른 질환의 원문 객체를 대신 넘기거나 캐시된 객체를 수정하지 않습니다. 5. **공개 동작 맥락과 실패 경계:** 섹션 표시·공통 문서·메뉴·관련 콘텐츠는 `content` 같은 명시 prop이나 함수 인자로 전달합니다. 객체 정체성에 공개 동작을 숨기지 않습니다. CMS 모드에서 본문 필수 맥락이 없으면 실패합니다. 공통 헤더·푸터 조회 실패를 격리해 기본 안내를 유지하는 정책은 별도 함수와 테스트로 명시합니다. 이 예외를 본문에 확대하지 않습니다. ### 편집 주소 규칙 문구 조각 하나에 편집 주소 하나를 붙입니다. 한 부모 요소의 주소로 여러 조각을 대신하지 않습니다. 저장 키 생성과 런타임 주소 계산은 사이트 안의 같은 함수를 사용하고, 기존 저장 키의 번호를 바꾸거나 재사용하지 않습니다. key와 저장 path는 서로 다른 값입니다. 필드 키 명명법·camel/snake 변환·원문 추출 도구는 사이트에 둡니다. 반복행은 순번 대신 저장된 UUID와 `@<id>` 전체 경로를 사용하고, 편집 주소는 미리보기에서만 출력합니다. ### 커버리지 세 층 | 층 | 사이트에서 준비할 검사 | 통과 조건 | | --- | --- | --- | | ① 연결 | 모든 섹션·반복행을 채운 fixture를 템플릿별로 렌더합니다. 공통 문서는 `previewTargetId` 없는 맥락으로 렌더합니다. | 계약 필드가 주소로 출력되거나 이유 있는 명시 예외에 포함됩니다. | | ② 유효성 | 전체 주소(`@id` 포함), 문서 값·필드 정의, 실제 조회한 섹션 키를 수집합니다. | 주소가 계약·실제 반복행과 일치하고 화면 섹션이 계약의 부분집합입니다. | | ③ 도달 | 대표 화면에서 주소를 클릭하거나 관리자 포커스를 보내 필드 선택을 확인합니다. | 해당 필드가 선택됩니다. jsdom으로 재현하지 못하면 브라우저 QA 항목으로 남깁니다. | ①②의 비교는 SDK를 사용합니다. fixture 생성·렌더·예외 목록·③ 도달 검사는 사이트 테스트에 둡니다. ```ts import { coverageReport } from "@roottale/cms-core/visual-edit"; const result = coverageReport(contract, { documents: documents.map((document) => ({ id: document.id, templateKey: document.templateKey, fields: document.fields, fieldDefinitions: definitionsFor(document.templateKey), })), addresses: renderedAddresses, sections: observedSections, // { template, key }[] }, exceptions); // { templateKey, fieldKey, reason }[] expect(result.missingFields).toEqual([]); expect(result.invalidAddresses).toEqual([]); expect(result.invalidSections).toEqual([]); expect(result.invalidExceptions).toEqual([]); ``` 이 예외 목록은 미연결 필드만 허용합니다. 계약에 없는 주소·섹션, 잘못된 반복행, 중복·잘못된 예외를 숨기지 않습니다. `fieldDefinitions`는 사이트가 설치한 필드 정의의 `key`·`name`·`type`·`subFields`·`layouts`이며 비공개 플랫폼 검증 코드를 복사할 필요가 없습니다. 계약이 그룹·반복 컨테이너를 선언하면 편집기가 생성하는 자식 주소도 허용합니다. `flexible_content`는 `layouts: [{ name, subFields }]`와 실제 행의 `__layout`을 대조하며 다른 레이아웃 필드를 연결하면 실패합니다. ## 공통 문구의 공개 반영 확인 공개 주소가 없는 `shared: true` 모델은 제목 포함 여부로 확인할 수 없습니다. 모델에 다음 선택 설정을 등록하면 발행 웹훅 전달 후 지정된 공개 HTML의 실제 문구를 비교합니다. `detailPath`가 있는 모델에는 이 설정을 사용할 수 없습니다. 기존 계약은 설정 없이 그대로 동작합니다. ```json { "sharedFieldVerification": { "paths": ["/news"], "fields": [{ "key": "field_phone", "path": ["clinic", "phone"], "sectionKey": "clinic", "visibilitySectionKey": "footer", "normalization": "phone" }] } } ``` `paths`는 동일 사이트의 고정 공개 경로 1~3개입니다. 필드는 최대 50개이며, `key`는 해당 모델의 실제화면 편집 템플릿에 등록된 필드, `path`는 ACF 루트부터의 저장 경로입니다. `sectionKey`는 그 필드가 속한 편집 섹션입니다. 다른 섹션의 표시 상태도 영향을 준다면 `visibilitySectionKey`를 지정합니다. 두 섹션 중 하나가 숨김·삭제 상태이거나 문서가 미발행이면 그 필드가 공개 HTML에 없어야 합니다. 선언한 값이 저장 데이터에서 누락되면 확인 실패로 처리합니다. 공개 텍스트 자체에 `data-rt-field-check="문서ID:필드key"`를 붙이고 가장 가까운 상위 영역에 `data-rt-shared-section="모델key:섹션key"`를 붙입니다. [`SharedFieldOutput`](../examples/nextjs/components/shared-field-output.tsx) 예제처럼 실제 값만 렌더합니다. CMS 원문·기대값·해시를 숨은 HTML이나 속성에 복제해서는 안 됩니다. 코드 대체값을 표시할 때 CMS 문서 표식을 붙이면 안 됩니다. `text`는 Unicode NFC와 공백만 정규화하고, `phone`은 공백·괄호·점·하이픈만 제거합니다. 그 외 글자와 대소문자는 그대로 비교합니다. 같은 필드가 여러 번 있으면 모두 일치해야 하며, 스크립트·템플릿·숨김·`aria-hidden` 요소의 값은 인정하지 않습니다. 검증 작업에는 문구의 SHA-256만 저장합니다. HTTP 실패·누락·오래된 문구는 기존 반영 확인의 재시도와 결과 표시에 연결됩니다. 문서의 새 수정이나 계약 체크섬 변경이 생기면 이전 결과는 폐기합니다. 대표 경로에는 해당 공통 필드가 항상 등장하는 화면을 선택합니다. 페이지 자체의 별도 숨김 설정이나 조건에 따라 필드가 빠지는 화면은 선택하지 않습니다. 이 검사는 지정한 문구의 서버 HTML 반영을 확인하며, CSS 가시성·이미지·링크 목적지·전체 사이트를 검사하는 기능은 아닙니다. 사이트에 표식을 먼저 배포한 뒤 새 계약을 등록합니다. 계약 버전·runtime receipt도 함께 갱신하고, 기존 고객 콘텐츠를 다시 가져와 덮어쓰지 않습니다. ## 사이트 내용 영역 연결 H2 key와 문단 문자열로 저장하는 `contentAreas`의 `fields` 편집기도 실제화면 편집에 연결할 수 있습니다. 사이트 계약의 `visualEditing.contentAreas`에 **영역 key**를 명시합니다. 목록에 없는 영역은 기존 입력 폼을 계속 사용합니다. ```ts contentAreas: [{ key: "hospital-intro", pageSlug: "area-hospital-intro", path: "/about", label: "병원 소개", editor: { kind: "fields", fields: [ { key: "f-intro-title", group: "소개", label: "제목", kind: "text" }, { key: "f-intro-body", group: "소개", label: "설명", kind: "multiline" }, { key: "f-intro-image", group: "사진", label: "사진 주소", kind: "image" }, { key: "f-intro-link", group: "연결", label: "링크 주소", kind: "link" }, ] }, }], visualEditing: { previewPath: "/preview/content/:id", templateVersion: "hospital-1", templates: [], contentAreas: ["hospital-intro"], }, ``` `templates`가 비어 있어도 영역을 연결할 수 있지만 둘 다 비어 있으면 거부합니다. 영역 key는 중복 없이 등록하며 `editor.kind`는 `fields`여야 합니다. 켠 영역끼리는 공개 `path`가 같을 수 없습니다. 같은 `/` 경로에 여러 영역이 있다면 하나만 연결합니다. 등록 도구의 dry-run은 연결할 영역의 저장 페이지가 없는지도 알려 줍니다. 영역에는 별도 필드 그룹 등록이 필요하지 않습니다. 편집 대상은 `type: "page"`이며 `slug`가 해당 영역의 `pageSlug`인 글입니다. 기존 고정 페이지·모델의 편집 템플릿 연결이 있으면 그 연결을 우선합니다. 사이트가 출력할 주소는 key와 한 단계 path가 같습니다. ```tsx <h2 {...visualEditAttributes({ entityId: post.id, fieldKey: "f-intro-title", path: ["f-intro-title"], }, isPreview)}>{values["f-intro-title"]}</h2> ``` 값은 계속 `posts.bodyJson`의 H2 key + paragraph 문자열에 저장합니다. ACF로 옮기지 않습니다. 미리보기는 토큰이 가리키는 저장 작업본의 `bodyJson`을 읽어 공개 화면과 같은 컴포넌트로 그립니다. [영역 미리보기 예제](../examples/nextjs/components/ContentAreaVisualPreview.tsx)를 참고하세요. 화면에 출력하지 않는 입력칸은 `visualEditing.hiddenContentAreaFields`로 숨깁니다. 예: `hiddenContentAreaFields: { "hospital-intro": ["f-intro-image"] }`. 영역 key는 `visualEditing.contentAreas`에 연결돼 있어야 하고, 필드 key는 해당 영역의 `editor.fields`에 중복 없이 등록돼 있어야 합니다. 전체 `editor.fields` 정의는 유지하세요. 숨긴 칸은 패널에서 제외하고 서버에서도 변경을 거부합니다. 다른 칸을 저장해도 숨긴 값은 보존합니다. 편집할 칸이 남지 않은 구획(표만 있는 구획 포함)은 목록에 표시하지 않습니다. ### 묶음 구성 사이트 내용 영역의 `field.group`도 템플릿과 같은 ` › ` 경로 규칙을 따릅니다. 예를 들어 `검진 › 준비 안내`로 하위 묶음을 만들며 첫 등장 순서로 표시합니다. 맨 위 15개 이하, 한 묶음의 자기 칸 20칸 이하를 권장하고 숨긴 칸은 점검에서 뺍니다. 칸 이름은 값 없이도 뜻을 알 수 있게 씁니다. 같은 부모 아래 이름이 겹치면 목록에서 자동 번호로 구분합니다. 등록됐지만 값이 없는 key는 빈 입력칸으로 보이고, 실제로 수정하기 전에는 문서에 추가하지 않습니다. 저장 시 수정하지 않은 값과 원래 노드 순서를 유지합니다. 영역 숨김·삭제·반복 추가와 기본 정보·검색 설정은 제공하지 않으며 해석할 수 없는 본문은 사유와 함께 읽기 전용으로 엽니다. 이미지와 링크는 미디어 ID가 아닌 URL 문자열입니다. `/`로 시작하는 사이트 내부 주소와 HTTPS 주소를 허용하며 링크에는 `tel:`도 사용할 수 있습니다. 실행 URL과 인증정보가 든 주소는 거부합니다. HTTPS 이미지는 패널에서도 미리 봅니다. 상대 이미지 주소는 사이트 미리보기에서 확인하세요. `table`은 패널에 내지 않고 저장된 값을 보존합니다. 표 변경 요청은 거부하므로 표 편집이 필요한 화면은 실제화면 편집에 연결하지 않고 기존 폼을 사용하세요.