@roottale/cms-mcp 0.72.1 → 0.74.0

package/examples/nextjs/components/site-inquiry-form.tsx

@@ -2,6 +2,7 @@
 
 import { useState, useTransition, type FormEvent, type ReactNode } from "react";
 import { readAttribution } from "@roottale/cms-client/attribution";
+import { readJourney, trackCustomEvent, trackFormError } from "@roottale/analytics-runtime";
 import type { InquiryAnswer, InquiryFormField, PublishedInquiryForm, SubmitFormInquiryResult } from "@roottale/cms-client/server";
 
 import { submitSiteForm, type SiteFormAttempt } from "../lib/actions/submit-site-form";
@@ -19,6 +20,7 @@ export function SiteInquiryForm({
 
   function onSubmit(event: FormEvent<HTMLFormElement>) {
     event.preventDefault();
+    trackCustomEvent("form_submit_attempt", { form_id: formKey });
     const data = new FormData(event.currentTarget);
     // 결과가 불명확하면 answers/version/동의/attribution과 key 모두 유지한다.
     // 보안 토큰만 새 위젯 결과로 교체할 수 있다.
@@ -29,6 +31,8 @@ export function SiteInquiryForm({
         privacyConsent: data.get("privacyConsent") === "on",
         idempotencyKey: crypto.randomUUID(),
         attribution: readAttribution(),
+        // 최초 제출 시 스냅샷을 고정한다. 재시도에서는 같은 제출 내용을 유지한다.
+        journey: readJourney(),
       }),
       turnstileToken: text(data.get("cf-turnstile-response")) || undefined,
     };
@@ -37,12 +41,28 @@ export function SiteInquiryForm({
       try {
         const response = await submitSiteForm(formKey, nextAttempt);
         setResult(response);
+        if (response.ok) {
+          // 실제 접수 성공 응답에서만 완료를 기록한다.
+          trackCustomEvent("lead_submit", { form_id: formKey });
+        } else {
+          const fields = Object.keys(response.fieldErrors);
+          if (fields.length > 0) {
+            for (const key of fields) trackFormError(formKey, "invalid", key);
+          } else {
+            const code = response.kind === "transport" ? "network"
+              : response.status === 429 ? "rate_limited"
+              : response.status === 401 || response.status === 403 ? "verification"
+              : response.status !== null && response.status >= 500 ? "server" : "unknown";
+            trackFormError(formKey, code);
+          }
+        }
         // 저장되지 않았음이 명확한 입력/인증 오류만 편집을 다시 허용한다.
         // 409 충돌과 5xx, 응답 유실은 같은 제출을 보존한다.
         // 앞선 응답이 불확실했다면 뒤의 인증/검증 실패로 기존 제출을 지우지 않는다.
         if (attempt === null && !response.ok && response.kind === "api" && response.status !== null
           && [400, 401, 403, 404, 422, 429].includes(response.status)) setAttempt(null);
       } catch {
+        trackFormError(formKey, "network");
         // 사이트 Server Action의 응답 자체가 끊겨도 기존 key를 유지한다.
         setResult({
           ok: false, kind: "transport", code: "network_error", status: null,
@@ -62,7 +82,7 @@ export function SiteInquiryForm({
   );
 
   return (
-    <form onSubmit={onSubmit}>
+    <form onSubmit={onSubmit} data-track-form={formKey}>
       <h2>{form.definition.title}</h2>
       <fieldset disabled={pending || attempt !== null}>
         <legend>문의 내용</legend>

package/examples/nextjs/external-source-sync.md

@@ -0,0 +1,53 @@
+# 외부 원장 원고 연결 예제
+
+동기화 작업은 서버의 관리 API 키로 실행한다. 공개 사이트나 브라우저에 쓰기 키를
+전달하지 않는다. 아래 예제의 ID·key는 해당 사이트의 기존 값으로 바꾼다.
+
+`POST https://api.roottale.com/v1/cms/posts`
+
+```json
+{
+  "site_id": "site-id",
+  "model_key": "article",
+  "author_profile_id": "site-author-id",
+  "source_key": "notion:stable-page-id",
+  "title": "검수한 제목",
+  "slug": "stable-article-slug",
+  "body_json": { "type": "doc", "content": [{ "type": "paragraph", "content": [{ "type": "text", "text": "검수한 본문" }] }] },
+  "category_ids": ["existing-category-id"],
+  "publish": false
+}
+```
+
+201은 생성, 200은 같은 키로 먼저 생성된 글이다. 후자의 본문을 생성 요청으로
+덮어쓰지 않는다. 응답을 잃어버렸을 때도 같은 키로 재요청한다.
+
+기존 글을 수정할 때는 `PATCH /v1/cms/posts/{id}`에 조회한 버전을 함께 보낸다.
+
+```json
+{
+  "site_id": "site-id",
+  "expected_updated_at": "2026-10-16T01:00:00.000Z",
+  "title": "검수한 수정 제목"
+}
+```
+
+409이면 사용자의 변경을 먼저 확인한다. SEO는 `GET/PATCH /v1/cms/metadata/post/{id}`와
+`expected_version`을 사용하고, 발행은 `POST /v1/cms/posts/{id}/publish`에 최신
+`expected_updated_at`을 보낸다. 공개 주소는 CMS의 `path`를 기준으로 계산한다.
+응답을 받았다는 사실과 실제 사이트 반영 완료는 다르므로 등록된 revalidation도 확인한다.
+
+원장에서 선택한 관련 글만 노출하려면 이 예제의 블로그 상세와 미리보기 페이지의
+`RootTaleBlogPost` 옵션을 함께 바꾼다. 명시적 `related_posts`는 계속 표시되고
+카테고리 기반 자동 추천만 꺼진다.
+
+```tsx
+<RootTaleBlogPost
+  apiKey={process.env.ROOTTALE_API_KEY!}
+  slugOrId={post.id}
+  relatedPostsCount={0}
+/>
+```
+
+전문: [관리 API](../../docs/api-reference.md), [SEO 계약](../../docs/seo.md),
+[웹훅 연결](../../docs/revalidation-webhooks.md).

package/examples/nextjs/hospital-fees/README.md

@@ -0,0 +1,72 @@
+# 병원 공통 비급여 자동 연동
+
+병원 홈페이지의 비급여는 미리닥 API를 기본 자료로 사용한다. ROOT-ADMIN의
+`사이트 내용`에서 원본과 확인일을 보고, 병원 수정·추가·숨김만 별도로 저장한다.
+원본 조회나 갱신은 CMS 문서를 쓰지 않는다. 병원마다 같은 기능을 제공하되 기관 ID로 구분한다.
+`content-area.json`은 편집 계약, `files/`는 고객에게 납품하는 공개 소스다.
+
+## 신규·기존 병원 적용
+
+신규는 `pnpm starter:init <빈 경로> --industry medical --miridoc-id <6자리 기관 ID>`로
+생성한다. 미리닥 `/h/<ID>`에서 기관명·주소·연락처를 확인한 뒤 ID를 연결한다.
+공개 `/guide/non-covered`, 편집 slug `non-covered-fees`, 빈 보완 초안, 미리보기,
+푸터 링크를 Materializer의 manifest·외부 receipt로 추적한다. 생성만으로 운영에 쓰지 않는다.
+
+기존 병원은 기존 주소·디자인·문서를 유지하며 `content-area.json`을 계약의
+`contentAreas`에 합친다. table의 `source.institutionId`를 설정하고 `lib/root-admin`의
+공개 읽기와 `NonCoveredFees`의 검색·분류·HTML 표를 연결한다. 기존 preview 라우트에는
+비급여 분기만 합친다. 고객 저장소는 비공개 플랫폼 패키지를 import하지 않는다.
+
+공통 읽기 정본은 `packages/site-content-contract/src/miridoc-fees.ts`다.
+`node scripts/sync-hospital-fees-runtime.mjs`로 이 모듈의 복사본을 동기화한다.
+JavaScript 고객은 `--javascript <대상 파일>`, 일치 검사는 `--check`를 쓴다.
+
+## 자동 자료와 병원 수정본
+
+- 읽기 API: `GET https://miridoc.com/api/v1/institutions/<ID>/non-covered`.
+  인증정보 없이 공개 기관 스냅샷의 **전체 행**을 읽는다. 화면 더 보기 API를 쓰지 않는다.
+- 현재 원천은 심평원의 병원급 비급여 신고 자료다. 의원급·누락 항목은 자동 자료가
+  없을 수 있다. `no_source`·`not_loaded`와 503 장애를 구분한다. 보완 금액을 만들지 않는다.
+- 원천 행은 `md-…` ID, 자동 분류는 `mdg-…` ID다. 병원 추가 행은 UUIDv7이다.
+  원천의 금액·날짜 변경은 행 ID를 유지한다. 명칭·원천 순번 등 정체성이 달라지면
+  이전 수정본을 자동 승계하지 않는다. 원천에서 빠진 수정본은 관리자에서 보관·확인하고 공개에서 제외한다.
+- 원본의 **수정**을 누르면 해당 행 전체의 병원 수정본을 만든다. 저장 후에는 그 행에
+  수정값을 사용한다. **수정본 삭제 · 자동값 복원**을 저장하면 원천을 다시 따른다.
+  원천 분류·순서는 그대로 유지한다. 병원 추가 행만 분류 이동·순서를 관리한다.
+- 기존 문서는 병원 안내로 보존한다. 원천과 코드·이름이 같아도 임의로 덮지 않는다.
+  중복 항목의 정리는 병원이 원문과 새 자료를 대조한 뒤 한다.
+- CMS 보완 문서가 없거나 비공개여도 자동 자료는 계속 표시한다. 보완 내용만 제외된다.
+  자동 항목의 숨김은 그 행의 수정본에서 관리하고 전체 자동 연결은 계약에서 해제한다.
+
+## 저장·공개 경계
+
+`kind: "table"` 값은 `[{ id, title, rows: [{ id, cells: string[], hidden?: boolean }] }]`
+JSON 문자열이다. 금액·코드 앞자리 0·공란·범위·날짜를 보존한다. 병원 수정·추가는
+100분류·1,000행, 셀당 2,000자, 문서 값 합계 500,000자까지다. 자동 원본의 한도는 별도다.
+셀별 구 문서는 table의 `legacy`에 그룹·행·셀 키를 매핑한다. 첫 저장 때 변환하며,
+기존 수정 이력도 같은 방식으로 읽는다. 누락·혼합·중복 입력은 부분 저장하지 않는다.
+
+기존 저장·발행 권한, 동시 수정 검사, 수정 이력·복원, 서명 웹훅을 사용한다.
+인증된 preview는 현재 초안과 원천을 합치며 CMS 공개본으로 초안을 덮지 않는다.
+no-store·noindex·no-referrer 및 분석 제외를 유지한다. 공개 표의 숨김 행은 서버에서
+제거하고 브라우저 데이터에도 보내지 않는다. 수정 행과 자동 출처·확인일은 구분한다.
+장애는 예전 로컬 금액이나 정상 빈 표로 바꾸지 않는다.
+
+## 배포 순서
+
+운영 반영은 사용자 승인 후 실행한다. 미리닥 원천 행 ID를 담은 기관 스냅샷 재발행과
+API 배포 → ROOT-ADMIN → 기존 계약·보완 문서 백업 및 계약 병합 → 병원 사이트 순서다.
+API는 이전 ID 없는 스냅샷을 503으로 처리하므로 선행 배포 없이 사이트만 전환하지 않는다.
+기존 초안·발행본은 임의로 덮거나 일괄 발행하지 않는다. 최초 보완 문서도 동일 slug가
+없을 때만 `cms/non-covered-fees-page.json`으로 생성한다.
+
+미리닥의 기존 수집 주기를 따르며 API 공유 캐시와 홈페이지 데이터 재검증은 각각 5분이다.
+병원 수정은 사이트의 기존 서명 웹훅으로 반영한다. 출시 전에는 실제 기관 식별,
+미리보기·저장·숨김·복원·원천 삭제·장애·390px 화면을 확인한다. 미리보기 도메인은 noindex를 유지한다.
+
+## 테스트 실행 위치
+
+MCP 서버의 검사는 `pnpm --filter @roottale/cms-mcp test`로 실행한다.
+`files/tests/non-covered.test.tsx`는 고객에게 생성되는 Next.js 테스트이므로 생성된
+병원 사이트에서 `pnpm exec vitest run tests/non-covered.test.tsx`로 실행한다.
+생성된 사이트의 `pnpm test`와 CI에도 포함되며, MCP 서버에 React 의존성을 추가하지 않는다.

package/examples/nextjs/hospital-fees/content-area.json

@@ -0,0 +1,43 @@
+{
+  "key": "non-covered-fees",
+  "pageSlug": "non-covered-fees",
+  "label": "비급여 진료비",
+  "path": "/guide/non-covered",
+  "editor": {
+    "kind": "fields",
+    "fields": [
+      {
+        "key": "fees",
+        "label": "비급여 항목",
+        "group": "비급여 진료비",
+        "kind": "table",
+        "table": {
+          "columns": [
+            "분류",
+            "명칭",
+            "코드",
+            "구분",
+            "비용",
+            "최저비용",
+            "최고비용",
+            "치료재료대 포함여부",
+            "약제비 포함여부",
+            "특이사항",
+            "최종변경일"
+          ],
+          "nameColumn": 1,
+          "maxRows": 1000,
+          "source": {
+            "provider": "miridoc"
+          }
+        }
+      },
+      {
+        "key": "note",
+        "label": "비용 안내",
+        "group": "비급여 진료비",
+        "kind": "multiline"
+      }
+    ]
+  }
+}

package/examples/nextjs/hospital-fees/files/app/guide/non-covered/page.tsx

@@ -0,0 +1,16 @@
+import { getNonCoveredFees } from "../../../lib/root-admin/non-covered-fees";
+import { NonCoveredFees } from "../../../features/site/non-covered/NonCoveredFees";
+import { getRouteMetadata } from "../../../lib/root-admin/metadata";
+import { connection } from "next/server";
+
+export const revalidate = 60;
+export const generateMetadata = () => getRouteMetadata("non-covered");
+
+export default async function NonCoveredPage() {
+  await connection();
+  const schedule = await getNonCoveredFees();
+  return <main id="main-content" className="reading-page">
+    <header className="page-heading"><h1>비급여 진료비 안내</h1><p>항목명이나 코드로 비용을 확인하세요. 금액의 단위는 원입니다.</p></header>
+    <NonCoveredFees {...schedule} />
+  </main>;
+}

package/examples/nextjs/hospital-fees/files/app/preview/post/[id]/page.tsx

@@ -0,0 +1,34 @@
+import type { Metadata } from "next";
+import { notFound } from "next/navigation";
+import { fetchPostPreview } from "@roottale/cms-client/server";
+import { getRootAdminConnection } from "../../../../lib/root-admin/config";
+import { feeScheduleFromPost } from "../../../../lib/root-admin/non-covered-fees";
+import { NonCoveredFees } from "../../../../features/site/non-covered/NonCoveredFees";
+import contract from "../../../../cms/site-content-contract.json";
+
+export const dynamic = "force-dynamic";
+export const revalidate = 0;
+export const metadata: Metadata = {
+  title: "비급여 진료비 미리보기",
+  robots: { index: false, follow: false, noarchive: true },
+  referrer: "no-referrer",
+};
+
+export default async function FeePreviewPage({ params, searchParams }: {
+  params: Promise<{ id: string }>;
+  searchParams: Promise<{ token?: string | string[] }>;
+}) {
+  const [{ id }, { token }] = await Promise.all([params, searchParams]);
+  const connection = getRootAdminConnection();
+  if (!connection || typeof token !== "string" || !token || token.length > 4096) notFound();
+  // The API verifies the signed snapshot. Never log the token or fetch the published version here.
+  const post = await fetchPostPreview({ apiKey: connection.apiKey, baseUrl: connection.apiBase, token })
+    .catch(() => null);
+  const area = contract.contentAreas.find((item) => item.key === "non-covered-fees");
+  if (!post || post.id !== id || post.slug !== area?.pageSlug || !post.preview) notFound();
+  return <main id="main-content" className="reading-page">
+    <p role="status">미리보기입니다. 이 화면을 열어도 내용이 저장되거나 홈페이지에 공개되지 않습니다.</p>
+    <header className="page-heading"><h1>비급여 진료비 안내</h1><p>항목명이나 코드로 비용을 확인하세요. 금액의 단위는 원입니다.</p></header>
+    <NonCoveredFees {...await feeScheduleFromPost(post, true)} />
+  </main>;
+}

package/examples/nextjs/hospital-fees/files/cms/non-covered-fees-page.json

@@ -0,0 +1,12 @@
+{
+  "type": "page",
+  "slug": "non-covered-fees",
+  "title": "비급여 진료비",
+  "status": "draft",
+  "body_json": { "type": "doc", "content": [
+    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "fees" }] },
+    { "type": "paragraph", "content": [{ "type": "text", "text": "[]" }] },
+    { "type": "heading", "attrs": { "level": 2 }, "content": [{ "type": "text", "text": "note" }] },
+    { "type": "paragraph", "content": [] }
+  ] }
+}

package/examples/nextjs/hospital-fees/files/components/site/SiteAnalytics.tsx

@@ -0,0 +1,16 @@
+"use client";
+
+import { usePathname } from "next/navigation";
+import { RootTaleAnalytics } from "@roottale/analytics-runtime/react";
+import { RootTaleAnalyticsNextAdapter } from "@roottale/analytics-runtime/next";
+import type { RootAnalyticsRuntime } from "../../lib/root-admin/analytics";
+
+/** Draft URLs contain a preview token, so no analytics runtime is mounted on preview pages. */
+export function SiteAnalytics({ runtime }: { runtime: RootAnalyticsRuntime }) {
+  const pathname = usePathname();
+  if (!pathname || pathname === "/preview" || pathname.startsWith("/preview/")) return null;
+  return <>
+    <RootTaleAnalytics manifest={runtime.manifest} collectUrl={runtime.collectUrl} siteId={runtime.siteId} />
+    <RootTaleAnalyticsNextAdapter />
+  </>;
+}

package/examples/nextjs/hospital-fees/files/features/site/non-covered/NonCoveredFees.tsx

@@ -0,0 +1,32 @@
+"use client";
+import { useId, useState } from "react";
+import type { FeeGroup } from "../../../lib/root-admin/miridoc-fees";
+import styles from "./nonCoveredFees.module.css";
+
+const normalize = (value: string) => value.normalize("NFKC").toLocaleLowerCase().replace(/\s+/g, "");
+export function NonCoveredFees({ groups, columns, note, source }: { groups: FeeGroup[]; columns: string[]; note: string;
+  source?: { name: string; dataset: string; via: string; url: string; checkedOn: string | null; notice: string } | null }) {
+  const id = useId(); const [query, setQuery] = useState(""); const [category, setCategory] = useState("");
+  const term = normalize(query);
+  const visible = groups.map((group) => ({ ...group, rows: group.rows.filter((row) => !row.hidden) })).filter((group) => group.rows.length);
+  const filtered = visible.filter((group) => !category || group.id === category).map((group) => ({ ...group,
+    rows: group.rows.filter((row) => !term || normalize(`${group.title} ${row.cells.join(" ")}`).includes(term)),
+  })).filter((group) => group.rows.length);
+  const count = filtered.reduce((sum, group) => sum + group.rows.length, 0);
+  return <section className={styles.schedule} aria-label="비급여 항목">
+    <div className={styles.filters}>
+      <label htmlFor={`${id}-search`}>항목명·코드 검색<input id={`${id}-search`} type="search" value={query} onChange={(event) => setQuery(event.target.value)} /></label>
+      <label htmlFor={`${id}-category`}>분류 선택<select id={`${id}-category`} value={category} onChange={(event) => setCategory(event.target.value)}><option value="">전체 분류</option>{visible.map((group) => <option key={group.id} value={group.id}>{group.title}</option>)}</select></label>
+      {query || category ? <button type="button" onClick={() => { setQuery(""); setCategory(""); }}>검색 초기화</button> : null}
+    </div>
+    <p role="status">{count}개 항목 · 단위: 원</p>
+    {filtered.map((group) => <section key={group.id}><h2>{group.title}</h2><div className={styles.scroll} role="region" aria-label={`${group.title} 비용표`} tabIndex={0}>
+      <table><caption>{group.title} (단위: 원)</caption><thead><tr>{columns.map((column, index) => <th key={index} scope="col">{column}</th>)}</tr></thead>
+        <tbody>{group.rows.map((row) => <tr key={row.id}>{row.cells.map((cell, index) => index === 1 ? <th key={index} scope="row">{cell}{row.origin === "hospital-override" ? <small> · 병원 수정</small> : null}</th> : <td key={index}>{cell}</td>)}</tr>)}</tbody>
+      </table></div></section>)}
+    {!count ? <p>{query || category ? "일치하는 항목이 없습니다. 다른 항목명이나 코드로 검색해 주세요." : "현재 공개된 비급여 항목이 없습니다."}</p> : null}
+    {note ? <p className={styles.note}>{note}</p> : null}
+    {source ? <div className={styles.note}><p>자동 연동 출처: {source.name} {source.dataset} · {source.via} 제공{source.checkedOn ? ` · 확인일 ${source.checkedOn}` : ""}</p>
+      <p>{source.notice} 병원에서 수정·추가한 내용은 병원 안내 기준입니다.</p><a href={source.url} target="_blank" rel="noreferrer">미리닥 원본 확인</a></div> : null}
+  </section>;
+}

package/examples/nextjs/hospital-fees/files/features/site/non-covered/nonCoveredFees.module.css

@@ -0,0 +1,11 @@
+.schedule { display: grid; gap: 1.5rem; min-width: 0; }
+.schedule > section { min-width: 0; }
+.filters { display: flex; flex-wrap: wrap; align-items: end; gap: 1rem; min-width: 0; }
+.filters label { display: grid; gap: .5rem; flex: 1 1 12rem; min-width: 0; }
+.filters input, .filters select, .filters button { min-height: 2.75rem; padding: .5rem .75rem; border: 1px solid currentColor; border-radius: .25rem; background: transparent; color: inherit; font: inherit; }
+.filters input, .filters select { width: 100%; min-width: 0; }
+.scroll { overflow-x: auto; max-width: 100%; }
+.scroll table { width: 100%; min-width: 68rem; border-collapse: collapse; font-size: .875rem; }
+.scroll th, .scroll td { padding: .75rem; border-bottom: 1px solid #cbd5e1; text-align: left; white-space: pre-line; }
+.scroll thead { background: #f1f5f9; color: #0f172a; }
+.note { white-space: pre-line; }

package/examples/nextjs/hospital-fees/files/lib/root-admin/content-table.ts

@@ -0,0 +1,51 @@
+export interface FeeGroup { id: string; title: string; rows: { id: string; cells: string[]; hidden?: boolean }[] }
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function textContent(value: unknown): string {
+  if (value === undefined) return "";
+  if (!Array.isArray(value) || value.length > 1) throw new Error("비급여 입력값 오류");
+  if (!value.length) return "";
+  const node: unknown = value[0];
+  if (!record(node) || node.type !== "text" || typeof node.text !== "string") throw new Error("비급여 입력값 오류");
+  return node.text;
+}
+export function readFeeFields(body: unknown): Record<string, string> {
+  if (!record(body) || body.type !== "doc" || !Array.isArray(body.content) || body.content.length > 6000 || body.content.length % 2) throw new Error("비급여 문서 오류");
+  const blocks: unknown[] = body.content;
+  const values: Record<string, string> = {};
+  for (let i = 0; i < blocks.length; i += 2) {
+    const heading = blocks[i]; const paragraph = blocks[i + 1];
+    if (!record(heading) || heading.type !== "heading" || !record(heading.attrs) || heading.attrs.level !== 2 || !record(paragraph) || paragraph.type !== "paragraph") throw new Error("비급여 입력칸 오류");
+    const key = textContent(heading.content);
+    if (!/^[a-z][a-z0-9-]{0,79}$/.test(key) || Object.hasOwn(values, key)) throw new Error("비급여 입력칸 중복 또는 형식 오류");
+    values[key] = textContent(paragraph.content);
+  }
+  if (JSON.stringify(values).length > 500_000) throw new Error("비급여 문서 크기 초과");
+  return values;
+}
+
+/** Public table contract. Invalid input fails instead of publishing a partial price list. */
+export function readFeeGroups(value: string, columnCount: number): FeeGroup[] {
+  if (value.length > 500_000) throw new Error("비급여 표 크기 초과");
+  const groups: unknown = JSON.parse(value);
+  if (!Array.isArray(groups) || groups.length > 100) throw new Error("비급여 분류 형식 오류");
+  const ids = new Set<string>(); let count = 0;
+  function identity(value: unknown) {
+    if (typeof value !== "string" || !/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,99}$/.test(value) || ids.has(value)) throw new Error("비급여 식별자 오류");
+    ids.add(value);
+  }
+  for (const group of groups) {
+    if (!group || typeof group !== "object" || typeof group.title !== "string" || !group.title.trim() || group.title.trim().length > 100 || !Array.isArray(group.rows)) throw new Error("비급여 분류 오류");
+    identity(group.id);
+    for (const row of group.rows) {
+      if (!row || !Array.isArray(row.cells) || row.cells.length !== columnCount ||
+          row.cells.some((cell: unknown) => typeof cell !== "string" || cell.length > 2000) || !row.cells[1]?.trim() ||
+          (row.hidden !== undefined && typeof row.hidden !== "boolean")) throw new Error("비급여 항목 오류");
+      identity(row.id);
+      if (++count > 1000) throw new Error("비급여 항목 수 초과");
+    }
+  }
+  return groups as FeeGroup[];
+}

package/examples/nextjs/hospital-fees/files/lib/root-admin/miridoc-client.ts

@@ -0,0 +1,10 @@
+import "server-only";
+import { fetchMiridocFees } from "./miridoc-fees";
+
+export async function loadMiridocFees(institutionId: string, preview = false) {
+  // Optional loopback-only fixture; customers cannot configure an arbitrary upstream URL.
+  const fixture = process.env.MIRIDOC_FEES_FIXTURE_ORIGIN;
+  if (fixture && !/^http:\/\/(127\.0\.0\.1|localhost):\d{1,5}$/.test(fixture)) throw new Error("비급여 검사 서버 주소 오류");
+  return fetchMiridocFees(institutionId, { fetchImpl: (url, init) => fetch(fixture ? `${fixture}${new URL(String(url)).pathname}` : url,
+    { ...init, ...(preview ? { cache: "no-store" as const } : { next: { revalidate: 300, tags: ["non-covered-fees"] } }) }) });
+}

package/examples/nextjs/hospital-fees/files/lib/root-admin/miridoc-fees.ts

@@ -0,0 +1,89 @@
+/** Portable public feed contract. Also distributed with the hospital website module. */
+export type FeeRow = { id: string; cells: string[]; hidden?: boolean; origin?: 'miridoc' | 'hospital' | 'hospital-override' };
+export type FeeGroup = { id: string; title: string; rows: FeeRow[] };
+export interface MiridocFeeFeed {
+  schemaVersion: 1;
+  institution: { id: string; name: string; typeName: string; url: string };
+  status: 'available' | 'no_source' | 'not_loaded';
+  checkedOn: string | null;
+  rowCount: number;
+  groups: { id: string; title: string; rows: { id: string; code: string; name: string; label: string; amountWon: number; appliedOn: string }[] }[];
+  source: { name: string; dataset: string; via: string; url: string };
+  notice: string;
+  version: string;
+}
+const record = (value: unknown): value is Record<string, unknown> => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const text = (value: unknown, max = 2000): value is string => typeof value === 'string' && value.length <= max;
+const date = (value: unknown): value is string => typeof value === 'string' && /^\d{4}-\d{2}-\d{2}$/.test(value) &&
+  Number.isFinite(Date.parse(value)) && new Date(value).toISOString().slice(0, 10) === value;
+export const isMiridocRow = (id: string) => /^md-[a-f0-9]{32}$/.test(id);
+
+/** Reject partial/mismatched snapshots instead of quietly dropping prices. */
+export function parseMiridocFees(value: unknown, institutionId: string): MiridocFeeFeed {
+  const fail = () => { throw new Error('미리닥 비급여 응답을 확인할 수 없습니다.'); };
+  if (!/^[a-z0-9]{6}$/.test(institutionId) || !record(value) || value.schemaVersion !== 1 ||
+      !record(value.institution) || value.institution.id !== institutionId || !text(value.institution.name, 200) ||
+      !text(value.institution.typeName, 100) || value.institution.url !== `https://miridoc.com/h/${institutionId}` ||
+      !['available', 'no_source', 'not_loaded'].includes(String(value.status)) ||
+      !(value.checkedOn === null || date(value.checkedOn)) || !Number.isInteger(value.rowCount) ||
+      !text(value.version, 64) || !/^[a-f0-9]{64}$/.test(value.version) || !text(value.notice) ||
+      !record(value.source) || value.source.name !== '건강보험심사평가원' || value.source.dataset !== '비급여진료비정보' ||
+      value.source.via !== '미리닥' || value.source.url !== value.institution.url || !Array.isArray(value.groups) || value.groups.length > 1000) return fail();
+  const ids = new Set<string>(); let count = 0;
+  for (const group of value.groups) {
+    if (!record(group) || !text(group.id, 100) || !/^mdg-[a-zA-Z0-9_-]{1,80}$/.test(group.id) || ids.has(group.id) ||
+        !text(group.title, 100) || !group.title.trim() || !Array.isArray(group.rows)) return fail();
+    ids.add(group.id);
+    for (const row of group.rows) {
+      if (!record(row) || !text(row.id, 100) || !isMiridocRow(row.id) || ids.has(row.id) ||
+          !text(row.code, 100) || !row.code || !text(row.name) || !row.name.trim() || !text(row.label) ||
+          typeof row.amountWon !== 'number' || !Number.isSafeInteger(row.amountWon) || row.amountWon < 0 || !date(row.appliedOn)) return fail();
+      ids.add(row.id); if (++count > 10000) return fail();
+    }
+  }
+  if (count !== value.rowCount || (value.status === 'available' ? !count || !date(value.checkedOn) : count !== 0)) return fail();
+  return value as unknown as MiridocFeeFeed;
+}
+
+export async function fetchMiridocFees(institutionId: string, options: { fetchImpl?: typeof fetch; signal?: AbortSignal } = {}) {
+  if (!/^[a-z0-9]{6}$/.test(institutionId)) throw new Error('미리닥 의료기관 ID를 확인해 주세요.');
+  const response = await (options.fetchImpl ?? fetch)(`https://miridoc.com/api/v1/institutions/${institutionId}/non-covered`, {
+    headers: { Accept: 'application/json' }, signal: options.signal ?? AbortSignal.timeout(8000), redirect: 'error',
+  });
+  if (!response.ok) throw new Error(`미리닥 비급여를 불러오지 못했습니다 (${response.status}).`);
+  // Bound memory before parsing external data; a failed feed must not become a partial list.
+  const reader = response.body?.getReader();
+  if (!reader) throw new Error('미리닥 응답이 비어 있습니다.');
+  const chunks: Uint8Array[] = []; let size = 0;
+  try {
+    for (;;) {
+      const { done, value } = await reader.read(); if (done) break;
+      size += value.byteLength;
+      if (size > 8_000_000) throw new Error('미리닥 응답 크기를 초과했습니다.');
+      chunks.push(value);
+    }
+  } catch (error) { await reader.cancel(); throw error; } finally { reader.releaseLock(); }
+  const bytes = new Uint8Array(size); let offset = 0;
+  for (const chunk of chunks) { bytes.set(chunk, offset); offset += chunk.byteLength; }
+  return parseMiridocFees(JSON.parse(new TextDecoder().decode(bytes)), institutionId);
+}
+
+export function miridocFeeGroups(feed: MiridocFeeFeed): FeeGroup[] {
+  return feed.groups.map(group => ({ id: group.id, title: group.title, rows: group.rows.map(row => ({
+    id: row.id,
+    cells: [group.title, row.name, row.code, row.label, row.amountWon.toLocaleString('ko-KR'), '', '', '', '', '', row.appliedOn],
+  })) }));
+}
+
+/** Store only hospital edits/additions. Missing source rows are never resurrected by old overrides. */
+export function mergeMiridocFees(feed: MiridocFeeFeed, local: FeeGroup[]): FeeGroup[] {
+  const edits = new Map(local.flatMap(group => group.rows).filter(row => isMiridocRow(row.id)).map(row => [row.id, row]));
+  const automatic = miridocFeeGroups(feed).map(group => ({ ...group, rows: group.rows.map(row => {
+    const edit = edits.get(row.id);
+    return edit ? { ...edit, origin: 'hospital-override' as const } : { ...row, origin: 'miridoc' as const };
+  }) }));
+  const added = local.map(group => ({ ...group, id: `local-${group.id}`, title: `병원 안내 · ${group.title}`,
+    rows: group.rows.filter(row => !isMiridocRow(row.id)).map(row => ({ ...row, origin: 'hospital' as const })),
+  })).filter(group => group.rows.length);
+  return [...automatic, ...added];
+}

package/examples/nextjs/hospital-fees/files/lib/root-admin/non-covered-fees.ts

@@ -0,0 +1,37 @@
+import "server-only";
+import { fetchPageBySlug } from "@roottale/cms-client/server";
+import contract from "../../cms/site-content-contract.json";
+import { getRootAdminConnection } from "./config";
+import { readFeeFields, readFeeGroups } from "./content-table";
+import { mergeMiridocFees } from "./miridoc-fees";
+import { loadMiridocFees } from "./miridoc-client";
+
+function feeContract() {
+  const area = contract.contentAreas.find((item) => item.key === "non-covered-fees");
+  const table = area?.editor.fields.find((field) => field.kind === "table");
+  if (!area || !table?.table) throw new Error("비급여 CMS 연결 계약이 필요합니다.");
+  return { area, table, columns: table.table.columns };
+}
+
+export async function feeScheduleFromPost(post: { bodyJson?: unknown } | null, preview = false) {
+  const { table, columns } = feeContract();
+  const values = post ? readFeeFields(post.bodyJson) : {};
+  if (post && !Object.hasOwn(values, table.key)) throw new Error("비급여 표 입력값이 없습니다.");
+  const local = post ? readFeeGroups(values[table.key], columns.length) : [];
+  const institutionId = table.table?.source?.institutionId;
+  const feed = institutionId ? await loadMiridocFees(institutionId, preview) : null;
+  const groups = (feed ? mergeMiridocFees(feed, local) : local)
+    .map(group => ({ ...group, rows: group.rows.filter(row => !row.hidden) })).filter(group => group.rows.length);
+  return { groups, columns, note: values.note ?? "비용은 병원에 문의해 주세요.",
+    source: feed ? { ...feed.source, checkedOn: feed.checkedOn, notice: feed.notice } : null };
+}
+
+export async function getNonCoveredFees() {
+  const { area } = feeContract();
+  const connection = getRootAdminConnection();
+  if (!connection) return feeScheduleFromPost(null);
+  // Network errors reach Next so a temporary outage cannot replace a published price list with empty data.
+  const post = await fetchPageBySlug({ apiKey: connection.apiKey, baseUrl: connection.apiBase,
+    slug: area.pageSlug, revalidate: 60, signal: AbortSignal.timeout(8000) });
+  return feeScheduleFromPost(post?.status === "published" ? post : null);
+}

package/examples/nextjs/hospital-fees/files/tests/non-covered.test.tsx

@@ -0,0 +1,69 @@
+import { renderToStaticMarkup } from "react-dom/server";
+import { buildManifest } from "@roottale/analytics-runtime";
+import { afterEach, beforeEach, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({ preview: vi.fn(), published: vi.fn(), pathname: "/guide/non-covered" }));
+vi.mock("server-only", () => ({}));
+vi.mock("@roottale/cms-client/server", () => ({ fetchPostPreview: mocks.preview, fetchPageBySlug: mocks.published }));
+vi.mock("next/navigation", () => ({ usePathname: () => mocks.pathname, notFound: () => { throw new Error("not found"); } }));
+vi.mock("@roottale/analytics-runtime/react", () => ({ RootTaleAnalytics: () => <span>analytics-runtime</span> }));
+vi.mock("@roottale/analytics-runtime/next", () => ({ RootTaleAnalyticsNextAdapter: () => <span>analytics-adapter</span> }));
+vi.mock("../lib/root-admin/miridoc-client", () => ({ loadMiridocFees: async () => ({
+  groups: [], status: "no_source", checkedOn: null, source: {name:"건강보험심사평가원",dataset:"비급여진료비정보",via:"미리닥",url:"https://miridoc.com/h/t5rqt3"},notice:"자료 없음",
+}) }));
+const { default: PreviewPage, metadata } = await import("../app/preview/post/[id]/page");
+const { SiteAnalytics } = await import("../components/site/SiteAnalytics");
+const { readFeeGroups } = await import("../lib/root-admin/content-table");
+const { feeScheduleFromPost } = await import("../lib/root-admin/non-covered-fees");
+
+const groups = [{ id: "group", title: "검사", rows: [
+  { id: "visible", cells: ["", "미리보기 항목", "0001", "", "98,765", "", "", "", "", "", ""] },
+  { id: "hidden", cells: ["", "숨긴 항목", "0002", "", "0", "", "", "", "", "", ""], hidden: true },
+] }];
+beforeEach(() => {
+  vi.stubEnv("ROOTTALE_API_KEY", "fixture");
+  mocks.preview.mockResolvedValue({ id: "fee", slug: "non-covered-fees", preview: { expiresAt: "2099-01-01", sourceStatus: "draft" },
+    bodyJson: { type: "doc", content: [
+      { type: "heading", attrs: { level: 2 }, content: [{ type: "text", text: "fees" }] },
+      { type: "paragraph", content: [{ type: "text", text: JSON.stringify(groups) }] },
+    ] } });
+});
+afterEach(() => { vi.unstubAllEnvs(); vi.clearAllMocks(); });
+
+it("실제 미리보기 진입은 현재 초안의 표를 그리며 공개본을 다시 읽지 않는다", async () => {
+  const html = renderToStaticMarkup(await PreviewPage({ params: Promise.resolve({ id: "fee" }), searchParams: Promise.resolve({ token: "fixture" }) }));
+  expect(html).toContain("미리보기 항목");
+  expect(html).toContain("98,765");
+  expect(html).not.toContain("숨긴 항목");
+  expect(mocks.published).not.toHaveBeenCalled();
+  expect(metadata).toMatchObject({ robots: { index: false, follow: false }, referrer: "no-referrer" });
+});
+
+it("토큰 없이 또는 다른 글 ID로는 초안을 열 수 없다", async () => {
+  await expect(PreviewPage({ params: Promise.resolve({ id: "fee" }), searchParams: Promise.resolve({}) })).rejects.toThrow("not found");
+  expect(mocks.preview).not.toHaveBeenCalled();
+  await expect(PreviewPage({ params: Promise.resolve({ id: "other" }), searchParams: Promise.resolve({ token: "fixture" }) })).rejects.toThrow("not found");
+});
+
+it("분석 설정이 있어도 미리보기에서 런타임과 페이지 추적을 실행하지 않는다", () => {
+  const runtime = { manifest: buildManifest({ siteId: "fixture", tags: [] }), siteId: "fixture", collectUrl: "/collect" };
+  mocks.pathname = "/preview/post/fee";
+  expect(renderToStaticMarkup(<SiteAnalytics runtime={runtime} />)).toBe("");
+  mocks.pathname = "/guide/non-covered";
+  const html = renderToStaticMarkup(<SiteAnalytics runtime={runtime} />);
+  expect(html).toContain("analytics-runtime");
+  expect(html).toContain("analytics-adapter");
+});
+
+it("문자열 금액과 코드·정상 빈 표를 보존하며 잘못된 셀 수와 중복 ID는 거부한다", () => {
+  expect(readFeeGroups(JSON.stringify(groups), 11)[0].rows[0].cells.slice(2, 5)).toEqual(["0001", "", "98,765"]);
+  expect(readFeeGroups("[]", 11)).toEqual([]);
+  expect(() => readFeeGroups(JSON.stringify(groups), 10)).toThrow();
+  expect(() => readFeeGroups(JSON.stringify([...groups, ...groups]), 11)).toThrow();
+});
+
+it("숨긴 금액은 브라우저로 전달하는 표 데이터에서도 제외한다", async () => {
+  const post = await mocks.preview();
+  const schedule = await feeScheduleFromPost(post, true);
+  expect(schedule.groups.flatMap(group => group.rows).map(row => row.id)).toEqual(["visible"]);
+});