@roottale/cms-mcp 0.64.0 → 0.65.1

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # @roottale/cms-mcp
 
+## 0.65.1
+
+### Patch Changes
+
+- 1b2d623: 작성자 변경 웹훅이 실제 공개 주소를 갱신하며, 공개 글이 없거나 경로 상한을 넘으면 theme.updated로 전역 갱신하는 계약을 문서와 Next.js 예제에 반영합니다.
+- febb0f2: 유입 신호가 없는 방문을 출처 정보 없음으로 표시한다. 브라우저 방문 시작을 익명으로
+  첫 확인·재방문으로 분류해 수집하고, ROOT-ADMIN의 방문 유형 통계와 연동한다.
+  문서 새로고침·뒤로/앞으로 이동은 새 외부 유입에서 제외한다.
+- 0d9ee66: 유입 출처와 첫 도착 페이지를 동봉한 클릭 수집 계약을 추가하고 ROOT-ADMIN에 출처·캠페인별 버튼 클릭 흐름을 표시한다. 기존 클릭은 출처를 추정하지 않으며 외부 유입 집계는 pageview로 유지한다.
+- 973032a: 웹훅 실패 원인 확인, 재시도와 수동 복구의 운영 계약을 안내합니다.
+
+## 0.65.0
+
 ## 0.64.0
 
 ### Minor Changes

package/dist/index.js

@@ -1735,7 +1735,7 @@ function registerTools(server) {
 }
 
 // src/server.ts
-var VERSION = true ? "0.64.0" : "dev";
+var VERSION = true ? "0.65.1" : "dev";
 var SERVER_INSTRUCTIONS = `
 roottale-cms-mcp\uB294 RootTale CMS\uB97C \uC678\uBD80 \uC0AC\uC774\uD2B8(\uC8FC\uB85C Next.js)\uC5D0 \uC5F0\uB3D9\uD558\uACE0
 \uAE00\xB7\uC378\uB124\uC77C\xB7\uBCF8\uBB38 \uC774\uBBF8\uC9C0\uB97C \uC790\uB3D9\uD654\uD558\uAE30 \uC704\uD55C \uBB38\uC11C\xB7\uC608\uC2DC \uCF54\uB4DC\xB7API tool\uC744 \uC81C\uACF5\uD569\uB2C8\uB2E4.

package/docs/revalidation-webhooks.md

@@ -168,6 +168,9 @@ curl -sI -X POST https://<사이트 도메인>/api/revalidate
 
 - 게시물 생성/발행/수정/삭제/발행 취소
 - 게시물의 카테고리·태그 변경 (블로그 카드의 카테고리 라벨이 바뀌므로)
+- 작성자 정보 변경 → 해당 작성자의 공개 글과 상위 목록 주소를 담은 `post.updated`.
+  주소는 저장된 공개 경로를 사용하므로 `/reviews`·계층형 `/faq` 등도 포함됩니다.
+  공개 글이 없거나 조회·경로 상한을 넘으면 `theme.updated`로 전체 캐시를 갱신합니다.
 - 분류(taxonomy) 용어 생성/수정/순서 변경/삭제
 - 디자인 토큰 변경 → `theme.updated`
 - 상단 메뉴·헤더/푸터 메뉴·공지 배너·상담바·문의 게시판 설정 변경 → `theme.updated`
@@ -345,3 +348,16 @@ Content-Type: application/json
 | 401 `timestamp_out_of_window` | 서버 시계 동기화 (NTP) |
 | 일부 페이지만 갱신 | `alsoRevalidate`·동적 경로 콜백 누락 |
 | 글은 즉시인데 **설정(전화·주소·메뉴·디자인)만 늦게** 반영 | `revalidateTag` 주입과 조회의 `tags` 누락 (§1 "설정 저장") — 응답의 `revalidated.requestedTags`가 비어 있으면 주입이 빠진 것 |
+
+### 실패한 갱신 요청 관리
+
+ROOT-ADMIN의 사이트 설정 → 발행 알림 기록에서 미전달 건수, 가장 오래된 변경과
+조치가 필요한 원인을 확인할 수 있습니다. 일시적인 네트워크 오류·408·429·5xx는
+자동 재시도합니다. `Retry-After`가 있으면 지정한 대기 시간을 적용합니다(최대 24시간).
+422·인증·주소 오류는 원인을 수정한 뒤 **지금 다시 보내기**를 실행하세요.
+이미 성공한 목적지는 유지하고 실패한 목적지의 시도 횟수만 새로 시작합니다.
+
+수신측의 알려진 `reason`은 `http_422:model_path_mismatch`처럼 전송 기록에 남습니다.
+응답 본문이나 고객 콘텐츠는 기록하지 않습니다. 전달 성공은 무효화 요청이 접수됐다는
+뜻이므로, 실제 화면 반영이 의심되면 해당 공개 페이지도 확인해야 합니다. 수신 라우트는
+같은 요청이 다시 와도 안전하게 캐시를 무효화해야 합니다.

package/docs/theme-and-settings.md

@@ -355,6 +355,41 @@ SPA 전환과 섹션·스크롤·읽기·폼 감지는 `@roottale/analytics-runt
 | 현재 방문 여정 | 브라우저 `sessionStorage._rt_journey`(최대 30건) |
 | 문의에 귀속된 유입·여정 | PostgreSQL `inquiries.attribution`, `inquiries.journey` |
 
+### 유입 경로에서 버튼 클릭까지
+
+유입과 버튼 클릭을 연결하려면 같은 방문의 출처와 최초 도착 pathname을 클릭 이벤트에
+동봉합니다. `/v1/collect`는 `phone_click`, `email_click`, `chat_click`, `booking_click`,
+`cta_click`에 `attr: 1`이 있을 때 `rh`, `air`, `us`, `um`, `uc`, `rs`, `gc`, `ref`와
+`lp`를 받습니다. `lp`는 첫 도착 pathname이며 query·hash는 제거됩니다.
+기존 `data-track` 위임은 `data-track-attr="1"`, `data-track-lp`와 같은 속성을
+사용합니다. 수집기는 `trackAttr`·`trackLp`·`trackUs` 등 dataset 키도 같은 계약으로
+정규화하며, 기존 배너·서비스 링크 클릭 이벤트에도 적용합니다.
+
+출처는 현재 탭에서 유지하고 30분 동안 행동이 없으면 새 방문으로 시작합니다. 내부
+페이지 이동의 pageview에는 출처를 다시 붙이지 않습니다. 그래야 외부 유입 횟수가
+페이지 조회마다 늘어나지 않습니다. 클릭에는 저장한 출처를 붙여 보냅니다.
+[Next.js 클릭 예제](../examples/nextjs/lib/analytics-click.ts)는 전송 계약을 보여줍니다.
+SDK `data-track` 위임과 직접 호출을 한 버튼에 동시에 적용하면 중복 집계됩니다.
+
+ROOT-ADMIN의 통계 > 페이지·문의 성과에는 출처·캠페인 → 첫 도착 페이지 → 클릭한
+페이지·버튼을 묶은 표가 표시됩니다. 반복 클릭을 포함하며 전화 연결·예약 완료를
+의미하지 않습니다. 기존 기록에 출처를 추정해 붙이지 않습니다. 원본 referrer 경로,
+검색 입력값, 광고 클릭 ID는 보내지 말고 호스트·캠페인 라벨·광고 클릭 여부만 사용합니다.
+
+Analytics Engine의 blob10~15는 해당 클릭의 유입 출처를, blob20은 첫 도착 pathname을
+저장합니다. 페이지 유입 보고서는 계속 `pageview`만 읽습니다. 현재 20개 blob 슬롯을
+모두 사용하므로 추가 차원은 새 저장 설계를 검토해야 합니다.
+
+비콘은 사이트별 브라우저 저장소에 마지막 방문 시각만 두고, 30분 동안 움직임이 없으면
+다음 pageview를 새 방문으로 분류합니다. 최근 30일 기록이 없으면 `vst: 1`(첫 확인),
+기록이 있으면 `vst: 2`(재방문)를 **방문 시작 pageview 한 건에만** 보냅니다.
+저장소 접근이 막히면 이 필드를 보내지 않습니다. 수집 API는 검증된 값만 Analytics
+Engine `double2`에 기록합니다. ROOT-ADMIN은 이를 방문 횟수로 표시하며 사람 수로
+해석하지 않습니다. 기존 사이트 어댑터는 별도 ID나 `vst`를 만들 필요가 없습니다.
+첫 문서 조회가 새로고침이나 뒤로/앞으로 이동이면 비콘은 `nv: 1|2`를 함께 보내고,
+수집 API는 해당 조회를 새 외부 유입에서 제외합니다. SPA 이동에는 `nv`를 보내지
+않으며 페이지 조회수는 그대로 기록합니다.
+
 ## 사이트 지식 — 브랜드 보이스 (AI 에이전트용)
 
 이 사이트의 **브랜드 보이스**(어조·톤·화자)와 **용어 규칙**(금지어·교정어)을

package/examples/nextjs/app/api/revalidate/route.ts

@@ -1,3 +1,5 @@
+// 갱신 요청은 재전송될 수 있으므로 캐시 무효화를 멱등으로 유지한다.
+// 수신 오류의 공개 reason 코드는 관리자 전송 기록에서 확인할 수 있다.
 // RootTale 발행 웹훅 수신 — ES256 서명 검증 후 Next.js 캐시 revalidate.
 // 어드민 "내 사이트 > 배포"에 https://<도메인>/api/revalidate 로 등록한다.
 import { revalidatePath, revalidateTag } from "next/cache";
@@ -18,6 +20,8 @@ export const POST = createRevalidateRoute({
   apiKey: process.env.ROOTTALE_API_KEY!,
   apiBase: process.env.ROOTTALE_API_BASE,
   revalidate: revalidateBlogPath,
+  // theme.updated는 설정 저장 외에 작성자 변경의 전역 갱신에도 쓰인다.
+  // 특정 글이나 modelKey가 없더라도 캐시 이름표와 루트 layout을 갱신해야 한다.
   // 설정(디자인 토큰·상단 메뉴·사업장 정보·블로그 표시 설정) 저장 시 그 값을
   // 담고 있는 fetch 캐시를 지운다. **이 주입이 없으면** revalidatePath 만으로는
   // fetch 캐시(Data Cache)가 안 지워져서 설정 변경이 최대 `revalidate` 초만큼

package/examples/nextjs/lib/analytics-click.ts

@@ -0,0 +1,26 @@
+import { trackCustomEvent } from "@roottale/analytics-runtime";
+
+/** 사이트 어댑터가 최초 진입에서 수집해 현재 탭에 유지한 출처. */
+export type VisitEntry = {
+  lp: string;
+  ref: 0 | 1;
+  rh?: string;
+  air?: string;
+  us?: string;
+  um?: string;
+  uc?: string;
+  rs?: string;
+  gc?: 1;
+};
+
+/** data-track 자동 위임을 쓰지 않는 예약 버튼의 onClick 예제. */
+// 방문 유형(vst)은 비콘이 방문 시작 pageview에만 자동으로 보냅니다.
+// 클릭 이벤트에는 붙이지 않아 방문 횟수가 중복되지 않습니다.
+export function trackBookingFromEntry(entry: VisitEntry, placement: string) {
+  trackCustomEvent("booking_click", {
+    ...entry,
+    attr: 1,
+    trackProvider: "naver",
+    trackPlacement: placement,
+  });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-mcp",
-  "version": "0.64.0",
+  "version": "0.65.1",
   "type": "module",
   "description": "RootTale CMS MCP server and CLI for models, entries, exposures, media, integration docs, and public API access.",
   "bin": {