@zalkera/client 0.13.1 → 0.15.0

package/llms.txt

@@ -72,7 +72,17 @@ await zalkera.submitInquiry(input, { clientIp: ip });
 - `getProduct(slug)` → `ProductDetail { id, slug, name, description, productType, coverAssetId, seo, variants[] }`
   - `seo` 는 **JSON 문자열 패스스루**(백엔드가 검증 안 함·미설정이면 null). 권장 구조는 `{"title","description"}` —
     `SiteConfig.seoDefaults` 와 같은 모양이다. **파싱 실패해도 죽으면 안 된다**(`parseConfig` 로 읽고, 없으면 상품명으로 강하).
-- `listProductCategories()` → `ProductCategory[]`
+- `listProductCategories()` → `ProductCategory[]` — **전량 반환**(테넌트당 수십 건 규모라 페이지네이션이 없다).
+  `ProductCategory { id, parentId, slug, name, sortOrder }`
+  - **`sortOrder` 오름차순, 동률이면 `id` 오름차순으로 정렬해 준다** — 받아서 다시 정렬할 필요가 없다.
+  - `slug` 가 **참조 정본**이다. URL 정체성(`/c/{slug}`)이고, 테넌트를 옮겨도 뜻이 유지되는 자연키다.
+  - `parentId` 는 계층이다. 보장 표면은 **평면 사용을 전제**하고 트리 렌더는 자유다.
+  - **단건 조회 API 는 없다** — slug 로 찾을 때는 이 목록에서 고른다.
+- **좁히는 축은 id 다.** `listProducts({categoryId})` 로 갈래별 목록을 받는다 — 목록 API 는 slug 를 안 받는다.
+  slug → id 해소는 위 목록에서 한다. 없는 `categoryId` 는 **빈 목록이지 404 가 아니다**(존재 판정은 카테고리 목록의 몫).
+- ⚠ **소스에 숫자 id 를 적지 마라.** 업무 데이터를 가리키는 키는 `slug`/`handle` 뿐이다 — 숫자 id 는 테넌트마다
+  다른 값이라, 소스에 적는 순간 그 소스는 다른 테넌트로 옮겨갈 수 없다. 외양(소스)은 어디서든 구해 와서
+  올리는 물건이라는 것이 이 제품의 전제이고, 그 전제가 이 규칙을 요구한다.
 - **variant 가 판매 단위다.** 가격·재고·장바구니·주문은 전부 `variant.id` 기준. 단순 상품도 variant 1개.
   `ProductVariant { id, sku, optionSignature, price, compareAtPrice, currency, inStock, available }`
   - `optionSignature` 는 옵션 조합 표시용 문자열("레드/XL") — 단순 상품은 **빈 문자열**이라 그때는 안 그린다.
@@ -147,7 +157,7 @@ await zalkera.submitInquiry(input, { clientIp: ip });
   빈 배열은 truthy 라 `if (items)` 로 결측을 판별하면 안 된다 — `items.length` 을 봐라.
 - 위 가드로 **필수 값이 없으면 그 섹션만 안 그린다**. 페이지 전체가 죽으면 안 된다.
 - `mediaSrc(assetId)` → `/media/{id}` **경로 문자열**. 이미지는 전부 이걸 통한다.
-  전제: 프로젝트에 `app/media/[id]/route.ts` 프록시 라우트가 있어야 한다(템플릿에 있다).
+  전제: 프로젝트에 `app/media/[id]/route.ts` 프록시 라우트가 있어야 한다(**§4.9 에 전문**).
   이 헬퍼는 경로만 만든다 — 라우트를 안 만들면 이미지가 404 다.
 - `asHandle(v)` / `asHandleArray(v)` / `assetPath(v)` — **참조 방언**(계약 `contractRev` 4 의 `dialects`)을 읽는다.
   숫자 id 를 못 쓰는 자리에서 상품은 `handle`(= `ProductSummary.slug`), 에셋은 레포 `public/` **루트 절대 경로**로
@@ -239,7 +249,7 @@ export async function POST(req: Request) {
    if (session.widget) {
      // 위젯형(토스) — 내 사이트에서 결제창을 띄우고, 성공 콜백 파라미터를 confirm 으로 넘긴다
      //   widget = { vendor:"TOSS_PAYMENTS", clientKey, orderId, amount, orderName }
-     //   → 템플릿의 checkout/page.tsx(openWidget)·payment/complete/page.tsx 를 그대로 쓴다
+     //   → 결제창 페이지에서 openWidget, 성공 리다이렉트 페이지에서 confirm (이 절의 흐름 그대로)
      await zalkera.confirmPayment(orderNo, { paymentKey }, access);   // BFF 경유
    } else {
      redirect(session.paymentUrl);   // 리다이렉트형(PG 결제창으로 이동)
@@ -263,7 +273,8 @@ export async function POST(req: Request) {
 >
 > 관용구는 소비자에 따라 둘이다:
 > - **브라우저(쿠키 있음)** = `` `co-${session.cartSessionKey}` `` **+ 체크아웃 성공 응답에서 카트 쿠키 회전**
->   (템플릿 `rotateCartSessionKey`). **회전 없이 카트키를 멱등키로 쓰지 마라** — 카트 쿠키는 30일이라
+>   (체크아웃 BFF 응답에 `response.cookies.set(CART_COOKIE, randomUUID(), {httpOnly:true, sameSite:"lax",
+>   secure, path:"/", maxAge: 30일})`). **회전 없이 카트키를 멱등키로 쓰지 마라** — 카트 쿠키는 30일이라
 >   회전이 없으면 위의 "영구 재사용"이 그대로 실현된다(실측 사고). 회전을 응답에 실으면 Set-Cookie 가
 >   성공 도달과 원자적으로 묶여서, 응답 유실 시엔 옛 키가 살아남아 재시도가 원주문을 재생한다 —
 >   **인메모리 "시도당 키"보다 이 쪽이 안전하다**(새로고침에 안 죽는다).
@@ -298,8 +309,8 @@ const shipment = await zalkera.getShipment(orderNo, { phone }); // 배송 상태
 // 1) 슬롯 보여주기 — 공개(비로그인 가능).
 // ⚠️ 이 RSC 직독 샘플은 **요청마다 렌더되는 동적 라우트에서만** 신선하다. 상품 상세가 ISR
 //    (force-static + revalidate=N)이면 슬롯이 프리렌더에 구워져 N초 낡은 시간표를 보여주고
-//    SLOT_FULL 을 만든다 — 그땐 **클라이언트 아일랜드 + BFF 프록시**로 내려라(템플릿
-//    BookingPanel + /api/booking/availability 가 그 선례다. 볼라틸한 데이터는 클라이언트 아일랜드로).
+//    SLOT_FULL 을 만든다 — 그땐 **클라이언트 아일랜드 + BFF 프록시**로 내려라(예약 패널을
+//    "use client" 로 두고 /api/booking/availability 가 대신 조회. 볼라틸한 데이터는 아일랜드로).
 const slots = await zalkera.availability({
   productId: product.id,               // slug 아님 — getProduct(slug).id
   from: new Date().toISOString(),
@@ -346,7 +357,6 @@ if (booking.orderNo) {                  // status=PENDING
   깨므로 금지(하나라도 있으면 `tracking` 을 채우고, 전무면 undefined).
 - **BFF 필수**: 브라우저에서 `submitLead` 직호출 금지(§2). route handler 에서 `x-forwarded-for` 첫
   홉을 `{ clientIp }` 로 넘긴다(안 넘기면 방문자 전원 429 — §4.6·문의와 동일 관용구).
-- 선례: `components/LeadForm.tsx`(아일랜드·UTM 캡처) · `app/api/lead/route.ts`(BFF·201 관통).
 
 ### 4.8 콘텐츠 파일로 그리는 고정 페이지 (`"content": "source"` · 권장)
 
@@ -412,6 +422,208 @@ export default async function StaticPage({ params }: { params: Promise<{ slug: s
 - 홈(`app/page.tsx`)은 `loadPageContent("home")` 의 섹션이 있으면 그것을 그리고, 없으면 커머스 골격으로
   강하한다. 콘텐츠 없는 것은 **정상**이다(커머스 테넌트).
 
+### 4.9 미디어 프록시 라우트 (`/media/{id}`) — **필수 부품**
+
+`mediaSrc(assetId)` 는 `/media/{id}` **경로 문자열만** 만든다. 그 경로를 받는 라우트는 프로젝트가 갖는다.
+**안 만들면 사이트의 이미지가 전부 404 다.** 아래를 `app/media/[id]/route.ts` 로 그대로 복사해라.
+
+왜 프록시가 필요한가 — 백엔드 공개 미디어는 둘 다 브라우저·크롤러가 직접 못 쓴다:
+- `/api/public/media/{id}/url` → **수 분 뒤 만료되는 presigned URL**. ISR 로 캐시된 HTML 안에서 죽고,
+  JSON-LD 에 넣으면 크롤러가 캐시한 뒤 깨진 이미지가 된다.
+- `/api/public/media/{id}/raw` → 안정 URL 이지만 **`X-Tenant` 헤더를 요구**한다(없으면 400). 크롤러도
+  `<img>` 도 그 헤더를 못 보낸다.
+
+```ts
+import {NextResponse} from "next/server";
+
+export async function GET(_req: Request, {params}: {params: Promise<{id: string}>}) {
+    const {id} = await params;
+    // id 를 URL 에 이어붙이므로 숫자만 통과시킨다(경로 주입 차단).
+    if (!/^\d+$/.test(id)) return new NextResponse(null, {status: 404});
+
+    // **미설정이면 여기서 죽는다.** 빈 헤더로 백엔드를 부르면 임의 테넌트에 조용히 붙거나
+    // 전 이미지가 400 이 되는데, 둘 다 원인이 안 보인다.
+    const base = process.env.ZALKERA_API_BASE;
+    const tenant = process.env.ZALKERA_TENANT;
+    if (!base || !tenant) throw new Error("ZALKERA_API_BASE·ZALKERA_TENANT 미설정");
+
+    let res: Response;
+    try {
+        res = await fetch(`${base}/api/public/media/${id}/raw`, {
+            headers: {"X-Tenant": tenant},
+            // 302 를 따라가면 이미지 바이트가 이 런타임을 통과한다 — Location 만 필요하다.
+            redirect: "manual",
+            cache: "no-store",
+        });
+    } catch {
+        return new NextResponse(null, {status: 502});
+    }
+
+    const location = res.headers.get("location");
+    // 302+Location 이 없으면(없는 id·타 테넌트 id) 그대로 없는 것으로 취급한다.
+    if (!location) return new NextResponse(null, {status: res.status === 404 ? 404 : 502});
+
+    return NextResponse.redirect(location, {status: 302, headers: {"Cache-Control": "no-store"}});
+}
+```
+
+- **바이트를 스트리밍하지 마라.** 그러면 모든 이미지 트래픽이 Next 런타임을 통과해 밀도 비용이 붙는다.
+  바이트는 스토리지→브라우저 직행하고, 이미지뷰당 서명 요청 1회만 낸다.
+- **`no-store` 를 지켜라** — 302 대상이 곧 만료되므로 이 응답을 캐시하면 죽은 링크를 재사용한다
+  (이미지 바이트는 스토리지 응답 헤더로 브라우저가 캐시한다).
+
+### 4.10 JSON-LD 부품 — **그대로 복사해서 쓴다**
+
+§5.1 이 요구하는 그래프를 만드는 부품이다. 재발명하지 마라 — 아래가 정본이고, 지어낸 필드·빈 값은
+구조화 데이터 정책 위반(리치결과 박탈)이다. **값이 없으면 필드를 통째로 뺀다**(널·0 을 넣지 않는다).
+
+삽입 컴포넌트(서버 컴포넌트로 유지 — `"use client"` 금지):
+
+```tsx
+export function JsonLd({data}: {data: object}) {
+    return (
+        <script
+            type="application/ld+json"
+            // `<` 를 유니코드 이스케이프 — 데이터에 `</script>` 가 섞여도 스크립트가 조기 종료되지
+            // 않는다(JSON-LD 삽입의 고전적 XSS 벡터). JSON.stringify 는 이걸 해주지 않는다.
+            dangerouslySetInnerHTML={{__html: JSON.stringify(data).replace(/</g, "\\u003c")}}
+        />
+    );
+}
+```
+
+빌더 — 전부 순수 함수다(평범한 객체를 반환한다):
+
+```ts
+import type {PostDetail, ProductDetail, RatingSummary, SiteConfig} from "@zalkera/client";
+
+/** 상품 상세. **variant 마다 Offer 하나** — 우리는 항상 variant 단위로 판다(옵션 없는 상품도 default 1개). */
+export function productJsonLd(product: ProductDetail, rating?: RatingSummary | null, siteBase = "", returnPolicy?: object | null) {
+    const url = `${siteBase}/products/${product.slug}`;
+    const offers = product.variants.map((v) => ({
+        "@type": "Offer", url, price: v.price, priceCurrency: v.currency,
+        availability: v.inStock ? "https://schema.org/InStock" : "https://schema.org/OutOfStock",
+        ...(v.sku ? {sku: v.sku} : {}),
+        ...(v.optionSignature ? {name: v.optionSignature} : {}),   // 단순 상품은 빈 문자열 — 이름을 안 붙인다
+        ...(returnPolicy ? {hasMerchantReturnPolicy: returnPolicy} : {}),
+    }));
+    return {
+        "@context": "https://schema.org", "@type": "Product", name: product.name, url,
+        // 페이지가 그리는 그 이미지 — **안정 URL(`/media/{id}`)**. presigned 는 만료돼 크롤러 캐시가 죽는다.
+        ...(product.coverAssetId != null ? {image: [`${siteBase}/media/${product.coverAssetId}`]} : {}),
+        ...(product.description ? {description: product.description} : {}),
+        ...(offers.length > 0 ? {offers} : {}),
+        // 후기 0건이면 aggregateRating 자체를 뺀다 — ratingValue:0 은 "0점짜리 상품"이라는 거짓 진술이다.
+        ...(rating && rating.reviewCount > 0
+            ? {aggregateRating: {"@type": "AggregateRating", ratingValue: rating.averageRating, reviewCount: rating.reviewCount}}
+            : {}),
+    };
+}
+
+/** 사이트 주체 — 홈에 1회. 업태는 **명시 입력값으로만** 좁힌다(테마 선택은 업태 진술이 아니다). */
+export function organizationJsonLd(config: SiteConfig, siteBase: string, type?: string) {
+    return {
+        "@context": "https://schema.org",
+        // 모르는 값·미설정은 Organization — 거짓 진술보다 덜 구체적인 진술이 낫다.
+        // 온라인 전용 몰에 LocalBusiness 를 붙이지 마라(주소·영업시간을 요구하는 타입이다).
+        "@type": type ?? (config.businessType === "BEAUTY" ? "BeautySalon" : "Organization"),
+        name: config.companyName, url: siteBase,
+        ...(config.tel ? {telephone: config.tel} : {}),
+        ...(config.email ? {email: config.email} : {}),
+        ...(config.address ? {address: {"@type": "PostalAddress", streetAddress: config.address, addressCountry: "KR"}} : {}),
+    };
+}
+
+/** 블로그·공지 상세. **author 를 넣지 마라** — 데이터에도 화면에도 없다(지어내면 위반). */
+export function blogPostingJsonLd(post: PostDetail, siteBase: string) {
+    return {
+        "@context": "https://schema.org", "@type": "BlogPosting",
+        headline: post.title, url: `${siteBase}/blog/${post.slug}`,
+        ...(post.publishedAt ? {datePublished: post.publishedAt} : {}),
+        ...(post.summary ? {description: post.summary} : {}),
+        ...(post.coverAssetId != null ? {image: [`${siteBase}/media/${post.coverAssetId}`]} : {}),
+    };
+}
+
+/** 고정 페이지(회사소개·이용안내 등). 없으면 순수 마케팅 사이트는 인용될 노드가 홈 하나뿐이 된다. */
+export function webPageJsonLd(page: {title: string; slug: string}, siteBase: string, description?: string) {
+    return {
+        "@context": "https://schema.org", "@type": "WebPage",
+        name: page.title, url: `${siteBase}/${page.slug}`,   // name 은 페이지가 그리는 <h1> 과 같은 값
+        ...(description ? {description} : {}),
+    };
+}
+
+function itemListNode(items: Array<{name: string; url: string}>) {
+    return {
+        "@type": "ItemList",
+        // position 은 **화면에 보이는 그 순서** — 원장이 정한 노출 순서를 기계에도 같은 순서로 준다.
+        itemListElement: items.map((item, i) => ({"@type": "ListItem", position: i + 1, name: item.name, url: item.url})),
+    };
+}
+
+/**
+ * 목록 표면(상품 목록·시술 메뉴·글 목록). **요약형** — 각 항목은 url 로 상세를 가리키고 이름만 든다.
+ * 가격·재고를 여기 복제하지 마라: 같은 사실이 두 곳에 있으면 갈라지고 갈라진 쪽이 거짓이 된다.
+ * 가격의 정본은 상세의 `Offer` 다.
+ */
+export function itemListJsonLd(items: Array<{name: string; url: string}>) {
+    return {"@context": "https://schema.org", ...itemListNode(items)};
+}
+
+/**
+ * 카테고리 페이지 — `ItemList` 를 `mainEntity` 로 **품는다**(나란히 내면 "이 페이지가 곧 그 목록"이
+ * 안 전해진다). **상품 0건이어도 낸다** — 이 페이지의 주어가 이 카테고리 하나라 "지금 0건"이 참인
+ * 진술이기 때문이다(카탈로그 전체 목록에서 빈 ItemList 를 빼는 것과 갈리는 자리다).
+ */
+export function collectionPageJsonLd(category: {name: string; slug: string}, items: Array<{name: string; url: string}>, siteBase: string, description?: string) {
+    return {
+        "@context": "https://schema.org", "@type": "CollectionPage",
+        name: category.name, url: `${siteBase}/c/${category.slug}`,
+        ...(description ? {description} : {}),
+        mainEntity: itemListNode(items),   // 중첩 노드에 @context 를 다시 달지 않는다
+    };
+}
+
+/** 경로 이동 — 검색결과에 `홈 > 상품 > 이름` 으로 노출된다. items 는 표시순. */
+export function breadcrumbJsonLd(items: Array<{name: string; url: string}>) {
+    return {
+        "@context": "https://schema.org", "@type": "BreadcrumbList",
+        itemListElement: items.map((item, i) => ({"@type": "ListItem", position: i + 1, name: item.name, item: item.url})),
+    };
+}
+```
+
+**환불 정책**(`MerchantReturnPolicy`)을 Offer 에 붙이면 구글이 "무료 반품·N일 이내"를 리치결과에 노출하고
+AI 에이전트가 "이 가게 환불 되나"를 읽는다. 두 규율이 중요하다:
+- **금액은 `config.defaultReturnShippingFee`(운영 값)** 를 쓴다 — 정책 문구가 아니라. 실제 차감액과
+  표시가 갈리면 표시 의무 위반이다.
+- **기간(`windowDays`)이 없으면 정책 전체를 내지 않는다** — 구글이 `merchantReturnDays` 를 요구하고,
+  창구를 모르는 채 "반품 됨"만 주장하는 건 무의미하다.
+
+```ts
+export function merchantReturnPolicyJsonLd(config: SiteConfig, windowDays?: number) {
+    // 구글이 정수를 요구한다. 7.5·-1 을 흘리면 정책 노드 전체가 무효 판정된다.
+    if (windowDays == null || !Number.isInteger(windowDays) || windowDays < 0) return null;
+    const fee = config.defaultReturnShippingFee;
+    return {
+        "@type": "MerchantReturnPolicy", applicableCountry: "KR",
+        returnPolicyCategory: "https://schema.org/MerchantReturnFiniteReturnWindow",
+        merchantReturnDays: windowDays, returnMethod: "https://schema.org/ReturnByMail",
+        ...(fee != null && fee > 0
+            ? {returnFees: "https://schema.org/ReturnShippingFees",
+               returnShippingFeesAmount: {"@type": "MonetaryAmount", value: fee, currency: "KRW"}}
+            : {returnFees: "https://schema.org/FreeReturn"}),   // 0원이면 무료 반품 — 그 사실이 노출된다
+    };
+}
+```
+
+> 테넌트 커머스 정책은 **스키마리스 JSON** 이라 소비 쪽에서 방어적으로 읽어라. 최상위 한 겹만 보면
+> 부족하다 — `{"returns":{"notes":{"ko":"…","en":"…"}}}` 같은 다국어 객체가 흔한 확장 모양인데, 그걸
+> 그대로 React 자식으로 그리면 *"Objects are not valid as a React child"* 로 페이지가 500 이 된다.
+> **필드별로 `typeof` 를 확인**하고 형에 안 맞으면 그 필드만 버려라(절 전체를 버리지 않는다).
+> 정책은 부가 정보이므로 파싱 실패가 페이지를 죽이면 안 된다.
+
 ## 5. 흔한 실수(하지 말 것)
 
 - ❌ 클라이언트 컴포넌트에서 `@zalkera/client` import → baseUrl 노출. ✅ 서버에서만.
@@ -444,7 +656,7 @@ export default async function StaticPage({ params }: { params: Promise<{ slug: s
   실시간·개인화 데이터(라이브 재고·개인화)는 **클라이언트 컴포넌트(아일랜드)**로 가져오고, 상태 변경
   (장바구니·주문)은 **BFF route handler** 로 한다. 신선도는 **온디맨드 revalidate**(백엔드 데이터 변경 시
   `POST /api/revalidate`)로 지킨다. 동적 SSR 이 꼭 필요하면(예: 검색) **정당화 주석**(`// zalkera-allow-dynamic:
-  <이유>`)이 필요하다 — 서버 동적 렌더는 상시 런타임 원가라 CI validator(§5)가 SEO 라우트에서 강제 차단한다.
+  <이유>`)이 필요하다 — 서버 동적 렌더는 **상시 런타임 원가**라 SEO 라우트에서는 기본이 아니다.
 
 ## 5.1 산출물 규범 — 발견되는 사이트 (필수)
 
@@ -454,8 +666,8 @@ export default async function StaticPage({ params }: { params: Promise<{ slug: s
 - ✅ **SEO 페이지에 JSON-LD(schema.org) 필수.** 상품 상세 = `Product` + variant 마다 `Offer`(price·
   priceCurrency·availability) + 후기 있으면 `AggregateRating`. 홈 = `Organization`(오프라인 점포면
   `LocalBusiness`, 뷰티샵이면 `BeautySalon` 으로 좁힌다). 목록·상세엔 `BreadcrumbList`.
-  템플릿의 `src/components/JsonLd.tsx`(안전 직렬화 + `productJsonLd`/`organizationJsonLd`/
-  `breadcrumbJsonLd` 헬퍼)를 **그대로 쓴다 — 재발명 금지**.
+  **§4.10 의 부품**(안전 직렬화 + `productJsonLd`/`organizationJsonLd`/`breadcrumbJsonLd`)을
+  **그대로 복사해 쓴다 — 재발명 금지**.
 - ✅ **목록 라우트도 그래프를 낸다 — `ItemList`.** 상품 목록(`/products`)·글 목록(`/blog`)은 **화면에 그리는
   바로 그 순서·그 항목**으로 `ItemList` 를 낸다(`itemListJsonLd`). 왜 목록에도 그래프가 필요한가: 상세 N건만
   있으면 "이 가게가 무엇을 파는가"를 기계가 한 번에 못 받고 상세를 하나씩 발견해야 한다 — 목록은 그 N건을
@@ -465,28 +677,33 @@ export default async function StaticPage({ params }: { params: Promise<{ slug: s
   내지 않는다**(빈 목록을 그래프로 주장하지 않는다 — "페이지에 없는 것을 쓰지 마라"의 목록판). 목록에도
   `BreadcrumbList` 를 함께 낸다. 그리고 목록은 **ISR 로 유지한다** — 정렬·필터를 `searchParams` 로 받는 순간
   라우트가 동적 렌더로 강등돼 크롤러 방문마다 서버 렌더가 돈다. 더 넓히려면 `/products/page/[n]` 같은
-  **정적 세그먼트**로 늘려라. 본보기: `src/app/products/page.tsx` · `src/app/blog/page.tsx`.
+  **정적 세그먼트**로 늘려라.
+- ✅ **카테고리 목록 = `CollectionPage`(`mainEntity` 로 `ItemList`).** 카테고리 라우트(`/c/{slug}`)는 그 묶음이
+  **무엇의 모음인지**를 말하는 `CollectionPage` 를 내고, 그 안에 실제 항목을 `mainEntity` 로 품은 `ItemList` 를
+  넣는다(`collectionPageJsonLd`). 상품 목록의 `ItemList` 와 나누는 이유는 층이 다르기 때문이다 — `/products` 는
+  "이 가게가 파는 것 전부"이고 카테고리는 "그중 이 갈래"라, 후자에는 **묶음 자체의 이름·설명**이 붙는다.
+  목록과 같은 규율을 그대로 따른다: 각 `ListItem` 은 `url` + **이름만** 들고 가는 요약형(가격의 정본은 상세의
+  `Offer` 다), **항목이 0건이면 그래프를 내지 않는다**, `BreadcrumbList` 를 함께 내고 **ISR 로 유지**한다.
+  카테고리가 하나도 없는 사이트는 이 라우트를 내비·sitemap 에 올리지 않는다 — 열면 빈 선반이 된다.
 - ✅ **예약(시술) 사이트의 목록 보장은 `SERVICE_MENU` 섹션이 낸다.** 섹션 어휘 `SERVICE_MENU` 는 계약상
   `jsonLd: "ItemList"` 이고(`SECTION_CONTRACT` · `contractRev` 2 이상), config 의 상품 참조 배열
   (DB 방언 `productIds` · 소스 방언 `products` — §9.2) **순서 그대로**
   목록 그래프를 낸다 — 원장이 정한 노출 순서를 기계에도 같은 순서로 준다. 시술 목록의 정위치는 **홈의 이
   섹션**이지 별도 라우트가 아니다: 뷰티 사이트에 목록 라우트를 강제하는 것은 디자인 자유를 깎으면서 얻는
   것이 없어서, 예약 유형의 목록 보장은 이 산출로 충족한다(`FAQ_LIST`↔`FAQPage` 와 같은 선례 — 목록의 정본이
-  그 섹션의 배열이라 다른 데서 다시 만들면 두 벌이 되고 갈라진다). 본보기:
-  `src/components/sections/ServiceMenuSection.tsx`.
+  그 섹션의 배열이라 다른 데서 다시 만들면 두 벌이 되고 갈라진다).
 - ✅ **CMS 고정 페이지(`/[slug]`)를 비워 두지 마라 — `WebPage` + `BreadcrumbList`.** 홈은 `Organization`,
   상품은 `Product`, 글은 `BlogPosting` 을 내는데 콘솔·시드가 만든 서브페이지(회사소개·이용안내 등)만 그래프가
   비기 쉽다. 순수 마케팅 사이트는 **그 서브페이지가 콘텐츠의 전부**라, 비어 있으면 답변 엔진이 인용할 노드가
   홈 하나뿐이 된다. `name` 은 페이지가 그리는 `<h1>` 과 같은 값으로, `description` 은 SEO 오버라이드가
   **실제로 있을 때만** 붙인다(`datePublished`·`author`·`image` 는 그 페이지에 그런 것이 없으므로 내지 않는다).
-  서브페이지의 `BreadcrumbList` 는 홈 아래 1뎁스(`홈 > 회사소개`)다. 본보기: `src/app/[slug]/page.tsx` ·
-  `webPageJsonLd`.
+  서브페이지의 `BreadcrumbList` 는 홈 아래 1뎁스(`홈 > 회사소개`)다. 그래프는 `webPageJsonLd`(§4.10)로 낸다.
 - ✅ **`sitemap.ts`·`robots.ts` 필수.** sitemap 엔 **실제로 존재하는 공개 라우트만** — 홈 · **목록 라우트
   (`/products`·`/blog`)** · 상품 상세 · 글 상세 · 콘텐츠 페이지. 목록 라우트를 빼면 카탈로그의 허브가 크롤러에게
   안 알려져 상세 N건을 개별 발견에만 맡기게 된다. 반대로 **비어 있는 목록은 싣지 않는다** — 상품 0건에
   `/products` 를, 글 0건에 `/blog` 를 실으면 크롤러에게 빈 페이지를 색인시키는 것이라 위 `ItemList` 규칙과
-  같은 판단이다(둘 다 "없는 것을 있다고 말하지 않는다"). 본보기 `src/app/sitemap.ts` 가 목록 API 를 훑어
-  이 조건부 등재를 한다. robots 는 세션·쓰기 경로(`/api/`·`/cart`·`/checkout`·`/mypage`·`/orders`·`/login`·
+  같은 판단이다(둘 다 "없는 것을 있다고 말하지 않는다"). **목록 API 를 훑어 0건이면 빼는 조건부 등재**를
+  `sitemap.ts` 안에서 한다. robots 는 세션·쓰기 경로(`/api/`·`/cart`·`/checkout`·`/mypage`·`/orders`·`/login`·
   `/auth`)만 막고 공개 카탈로그는 전부 연다. **AI 크롤러(GPTBot·ClaudeBot 등)를 막지 마라** — 발견 경로를
   우리 손으로 닫는 것이다.
 - ✅ **절대 URL.** JSON-LD·sitemap·robots 는 상대경로 불가. 단일 사이트는 env(`ZALKERA_SITE_URL`),
@@ -496,7 +713,7 @@ export default async function StaticPage({ params }: { params: Promise<{ slug: s
 - ❌ **페이지에 없는 것을 JSON-LD 에 쓰지 마라.** 구조화 데이터는 **보이는 내용만** 서술한다. 후기 0건인데
   `aggregateRating`, 렌더하지도 않는 `image`, 지어낸 브랜드·재고는 전부 구조화 데이터 정책 위반(리치결과 박탈).
   값이 없으면 **그 필드를 통째로 뺀다**(널·0 을 넣지 않는다).
-- ✅ **상품 이미지는 `/media/{id}` 안정 URL 로.** 템플릿의 `src/app/media/[id]/route.ts` 가 `X-Tenant` 를 붙여
+- ✅ **상품 이미지는 `/media/{id}` 안정 URL 로.** §4.9 의 프록시 라우트가 `X-Tenant` 를 붙여
   백엔드를 부르고 302 Location 만 넘긴다(바이트는 스토리지→브라우저 직행 — Next 런타임에 태우지 마라).
   `<img src={`/media/${product.coverAssetId}`} loading="lazy">` + JSON-LD `image` 둘 다 이 URL 을 쓴다.
   `next/image` 는 최적화 프록시가 바이트를 런타임에 태우므로 금지(쓰려면 `unoptimized`).
@@ -512,9 +729,7 @@ export default async function StaticPage({ params }: { params: Promise<{ slug: s
 ```bash
 npx zalkera-aeo-check https://개시된사이트 --category BOOKING   # 0=통과 · 1=미충족 · 2=실행 불가
 npx zalkera-aeo-check https://개시된사이트 --site-wide-only     # 보장 주장이 없는 사이트(사이트 축만)
-# 템플릿에서 출발한 프로젝트라면 같은 검사기를 이렇게도 부른다:
-npm run check:aeo -- https://개시된사이트 --category BOOKING
-npm run check:aeo -- --print-guarantees                        # 잣대 해석만 확인(크롤 없음)
+npx zalkera-aeo-check --print-guarantees                        # 잣대 해석만 확인(크롤 없음)
 ```
 
 - ❌ 배송 전(PAID)에 후기 작성 시도 → `NOT_DELIVERED_YET`(409). ✅ 주문이 **DELIVERED 이상**일 때만
@@ -569,15 +784,83 @@ catch (e) {
 
 ## 8. 스타일 규약 — Tailwind v4 + 테마 토큰 (필수)
 
-템플릿은 **Tailwind v4** 와 **테마 토큰**으로 스타일한다. 화면을 그릴 때 아래를 지킨다 — 어기면
-생성물이 초라해지거나(생짜 HTML) 테넌트의 "말로 색 바꾸기"가 깨진다. CI validator(S1~S5)가 강제한다.
+잘커라 사이트는 **Tailwind v4** 와 **테마 토큰**으로 스타일한다. 화면을 그릴 때 아래를 지킨다 — 어기면
+생성물이 초라해지거나(생짜 HTML) 테넌트의 "말로 색 바꾸기"가 깨진다.
+
+> 이 절은 **규약이지 게이트가 아니다.** 어떤 스택으로 짜든 사이트는 개시된다 — 판정 잣대는 §5.1 의
+> 산출물 검사(`zalkera-aeo-check`)뿐이고 소스를 보지 않는다. 다만 테마 토큰을 안 쓰면 테넌트가
+> 콘솔에서 색을 바꿔도 화면이 안 따라온다(그건 검사기가 아니라 **기능이 빠지는** 것이다).
 
 **스택 — 이것만 쓴다**
 - ✅ **Tailwind v4 유틸리티 클래스로만** 스타일한다. CSS 파일은 `src/app/globals.css` **하나뿐**이다 —
-  새 `.css` 파일·CSS Modules·CSS-in-JS 를 추가하지 마라(S3·S5).
-- ❌ 인라인 `style={{}}`(S2), 웹폰트·외부 스타일 CDN 추가, `tailwind.config.*` 생성(v4 는 config 없이 돈다).
+  새 `.css` 파일·CSS Modules·CSS-in-JS 를 추가하지 마라.
+- ❌ 인라인 `style={{}}`, 웹폰트·외부 스타일 CDN 추가, `tailwind.config.*` 생성(v4 는 config 없이 돈다).
   인라인 style 은 **CSS 변수 주입**(`style={{"--x":v}}`) 한 용례에만 허용된다(루트 layout 의 테마 주입이 그것).
 
+**토큰 정의 — `globals.css` 의 `@theme` 블록 (없으면 아래 유틸리티가 존재하지 않는다)**
+
+Tailwind v4 는 config 없이 돌고 토큰을 **CSS 에서** 선언한다. 이 블록이 없으면 `bg-primary`·`text-muted` 같은
+클래스가 **그냥 안 먹는다**(에러도 안 난다). §4.9 의 미디어 라우트와 같은 부류의 필수 부품이라 전문을 싣는다.
+
+```css
+@import "tailwindcss";
+
+@theme {
+    /* 테넌트 오버라이드 지점 — themeColors 가 <html> inline style 로 이 값들을 덮는다 */
+    --color-primary: oklch(20.8% 0.042 265.755);            /* slate-900 — 테넌트 색이 얹히기 전 기본 */
+    --color-primary-foreground: #ffffff;                     /* primary 위 글자색(서버가 명도로 산출) */
+    --color-secondary: oklch(55.4% 0.046 257.417);
+    --color-background: #ffffff;
+    --color-foreground: oklch(20.8% 0.042 265.755);
+
+    /* slate 중립 스케일에서 파생 — 테넌트 오버라이드 대상이 아니다(콘솔 스키마에 키가 없다) */
+    --color-muted: oklch(55.4% 0.046 257.417);
+    --color-border: oklch(92.9% 0.013 255.508);
+    --color-surface: oklch(98.4% 0.003 247.858);
+    --color-danger: oklch(57.7% 0.245 27.325);
+
+    /* 웹폰트 다운로드 없음 — 시스템 스택. font knob 이 --font-sans 를 덮는다 */
+    --font-sans: ui-sans-serif, system-ui, -apple-system, "Apple SD Gothic Neo",
+        "Malgun Gothic", "Noto Sans KR", sans-serif;
+
+    /* radius knob — 무단위 배수가 스케일 전체를 곱한다. sharp=0 · soft=1(기본) · round=2.
+       var() 폴백 1 이라 knob 미주입 시에도 Tailwind 기본 스케일과 정확히 일치한다. */
+    --radius-knob: 1;
+    --radius:     calc(0.25rem  * var(--radius-knob, 1));
+    --radius-sm:  calc(0.25rem  * var(--radius-knob, 1));
+    --radius-md:  calc(0.375rem * var(--radius-knob, 1));
+    --radius-lg:  calc(0.5rem   * var(--radius-knob, 1));
+    --radius-xl:  calc(0.75rem  * var(--radius-knob, 1));
+    --radius-2xl: calc(1rem     * var(--radius-knob, 1));
+
+    /* density knob — 이 베이스가 전 여백을 스케일한다(cozy=0.25rem 기본 · compact=0.22rem) */
+    --spacing: 0.25rem;
+}
+```
+
+루트 `layout` 이 이 값들을 덮어 쓰는 것이 "말로 색 바꾸기"의 전부다:
+
+```tsx
+const {cssVars} = parseThemeColors(config.themeColors);   // §3 계약 헬퍼 — 화이트리스트 파서
+return <html lang="ko" style={cssVars}>{/* … */}</html>;
+```
+
+`@theme` 만으로는 부족하다. Tailwind preflight 가 제목·폼 요소를 리셋하므로, **base 레이어가 없으면
+아래 레시피의 "`<h1>` 그대로"·"폼은 맨 요소 그대로"가 본문 크기 제목과 생짜 input 을 낳는다.**
+같은 파일에 이어 둔다:
+
+```css
+@layer base {
+    h1 { @apply text-2xl font-semibold tracking-tight; }
+    h2 { @apply text-lg font-semibold tracking-tight; }
+    a  { @apply underline-offset-4 hover:underline; }   /* 색은 상속 — 액센트 남발 금지 */
+    input, select, textarea {
+        @apply w-full rounded-lg border border-border bg-background px-3 py-2 text-sm
+               placeholder:text-muted focus:outline-2 focus:outline-primary;
+    }
+}
+```
+
 **토큰 — 색은 토큰으로만**
 | 유틸리티 | 뜻 |
 |---|---|
@@ -588,7 +871,7 @@ catch (e) {
 | `border-border` | 경계선 | `bg-surface` | 카드·필드 배경 | `text-danger` | 오류 |
 
 - ✅ 테넌트 브랜드색은 **`primary` 토큰으로만** 표현한다. ❌ hex 하드코딩(`bg-[#e91e63]`)은 콘솔의
-  "말로 색 바꾸기"를 죽인다(S4).
+  "말로 색 바꾸기"를 죽인다.
 - ✅ 중립 명도 단계가 토큰 표에 없으면 **slate 스케일만**(`text-slate-400` 등). ❌ gray·zinc·stone 혼용,
   유채색 팔레트(rose·emerald 등) 직접 사용 금지 — 새 색이 필요하면 **지어내지 말고 보고**한다.
 - 간격·타이포·라운드·섀도는 **Tailwind 기본 스케일**(`p-4`·`text-2xl`·`rounded-lg`·`shadow-sm`)을 쓴다.
@@ -596,7 +879,7 @@ catch (e) {
 
 **레시피**
 - 페이지 `<main className="py-8">` · 섹션 `<section className="mb-12">` · 제목은 base 가 크기를 주므로 `<h1>` 그대로.
-- 버튼은 `src/components/ui/Button`(`<Link>`·`<a>` 에는 `buttonClasses(variant)` 문자열) · 카드는 `ui/Card`.
+- 버튼·카드는 **프리미티브 한 벌**을 만들어 재사용한다(화면마다 새로 만들지 마라).
 - 폼 필드(`<input>`·`<select>`·`<textarea>`)는 base 레이어가 스타일하므로 **맨 요소 그대로** 쓴다.
 
 **절제 — 화려하게 만들지 마라**
@@ -604,7 +887,8 @@ catch (e) {
 
 **전역 토큰 knob — 말로 폰트·모서리·밀도 바꾸기 (계약버전 2)**
 색 외에 **폰트·모서리 둥글기·여백 밀도**도 테넌트가 콘솔에서 "말로" 바꾼다(`site.theme.update`). 값은 **enum**
-뿐이며 `src/lib/theme.ts` 매핑 테이블이 CSS 변수로 변환해 색과 같은 경로(`<html>` inline 주입)로 전 화면에 반영된다.
+뿐이며 **이 패키지의 `parseThemeColors`**(§3 계약 헬퍼)가 CSS 변수로 변환해 색과 같은 경로
+(`<html>` inline 주입)로 전 화면에 반영된다. 매핑 테이블을 직접 만들지 마라 — 그 함수가 정본이다.
 
 | knob | enum 값 | 효과 |
 |---|---|---|
@@ -617,22 +901,22 @@ catch (e) {
 - 새 knob 값(예: 다른 폰트)이 필요하면 **지어내지 말고 보고**한다 — enum 확장은 계약버전 증가를 동반한다.
 
 **테마 동작 — 배선을 건드리지 마라**
-- 테넌트 색은 `getSiteConfig().themeColors` → **루트 `layout` 이 `<html>` 의 CSS 변수로 주입**한다. 이 배선
-  (layout 의 테마 주입·`src/lib/theme.ts`)을 제거·우회하지 마라. **색 변경에 코드 수정이 필요하면 설계 위반**이다 —
+- 테넌트 색은 `getSiteConfig().themeColors` → `parseThemeColors` → **루트 `layout` 이 `<html>` 의 CSS
+  변수로 주입**한다. 이 배선을 제거·우회하지 마라. **색 변경에 코드 수정이 필요하면 설계 위반**이다 —
   콘솔에서 색을 바꾸면 재코딩 없이 반영되는 것이 정상이다.
 
-**UI 프리미티브 관용구 — 있는 것을 쓴다**
+**UI 프리미티브 관용구 — 한 벌만 만들어 재사용한다**
 - `cn(...)` = `twMerge(clsx(...))`. 조건부 클래스와 **덮어쓰기**(`cn("px-4", props.className)` 에서 `px-6` 이 이김)를
   둘 다 처리한다. 문자열 이어붙이기로 대체하지 마라 — 덮어쓰기가 조용히 안 먹는다.
-- 변형(variant)은 **cva** 로 선언한다(`ui/Button.tsx` 가 본보기). 조건문으로 클래스 문자열을 조립하지 마라.
-- `ui/Button`(버튼) · `buttonClasses(variant)`(`<Link>`·`<a>` 용 문자열) · `ui/Card`(카드) · `ui/Icon`(아이콘).
+- 변형(variant)은 **cva** 로 선언한다. 조건문으로 클래스 문자열을 조립하지 마라.
+- 버튼·카드·아이콘은 **프리미티브 한 벌**로 두고 화면마다 새로 만들지 마라. `<Link>`·`<a>` 에는
+  같은 변형을 **클래스 문자열로 내주는 헬퍼**를 함께 둔다(버튼 컴포넌트를 앵커로 감싸지 않는다).
 - 새 프리미티브가 정말 필요하면 shadcn/ui 에서 **발췌**해 온다(CLI 상시 설치 아님). 발췌물은 아래 재작성 표를
   적용하고 `asChild`/`Slot` 을 제거해 **Radix 의존 0** 을 유지한 뒤 `src/components/ui/` 에 커밋한다.
 
 **shadcn 발췌 재작성 표 — 남의 토큰 어휘는 반입 금지**
 shadcn 소스는 자기 변수층(`--card`·`--muted-foreground` …)을 전제한다. 우리는 그 층을 들이지 않는다(토큰 레이어가
-둘이 되면 테넌트 색 주입의 우선순위가 사람 머리에 얹힌다). 발췌 시 **좌변을 우변으로 기계적으로 바꾼다**.
-CI validator **S6** 가 좌변 잔존을 error 로 막는다.
+둘이 되면 테넌트 색 주입의 우선순위가 사람 머리에 얹힌다). 발췌 시 **좌변을 우변으로 기계적으로 바꾼다** — 아래 표가 그 규범이다.
 
 | shadcn | 우리 |
 |---|---|
@@ -665,7 +949,7 @@ JSON)뿐이고, 백엔드는 config 를 **파싱하지 않는다** — 스키마
 
 | 선언 | 의미 |
 |---|---|
-| `"source"` | 사이트의 얼굴(페이지·섹션·문구·섹션 이미지·내비)의 정본이 **레포 파일**. **템플릿과 v2 팩 태생이 이 형상**이다(카탈로그에 v1 팩이 남아 있는 동안 그쪽 태생은 `sections-db` 다) |
+| `"source"` | 사이트의 얼굴(페이지·섹션·문구·섹션 이미지·내비)의 정본이 **레포 파일**. **새로 만드는 사이트는 이 형상을 쓴다**(v1 팩 태생 사이트가 남아 있는 동안 그쪽은 `sections-db` 다) |
 | `"sections-db"` | 전환기 표기 — 섹션이 백엔드에 있고 `getPage(slug)` 가 준다(구 프리셋 태생 사이트) |
 | 미선언 | 안전 기본 — **선언이 없으면 이 계약을 안 쓰는 레포로 본다**(계약 검사도 걸지 않는다) |
 
@@ -782,8 +1066,17 @@ page.sections // [{ type: "HERO", sortOrder: 0, config: "{\"title\":\"…\"}" },
   SSR 마크업에 실린다**(AI 답변엔진이 읽는다). 아코디언 라이브러리를 쓰지 마라. `FAQPage` JSON-LD 를 함께 낸다.
 - `TESTIMONIALS` 에 **`Review`·`AggregateRating` 을 내지 마라.** 자사 사이트의 자사 후기에 별점을 붙이는 것은
   self-serving reviews 정책 위반이라 제재 대상이다. 이건 빠뜨린 게 아니라 결정이다.
-- `LEAD_CTA` 는 템플릿의 `components/LeadForm` 을 그대로 쓴다(UTM·클릭ID 추적·레이트리밋 안내 동봉).
-  전환 부품을 두 벌 만들지 마라. 이 섹션은 **`id="lead"` 앵커**를 갖는다 — 원페이지 랜딩에서 히어로 CTA 를
+- `LEAD_CTA` 의 리드 폼은 **클라이언트 아일랜드**(`"use client"`)로 만들고 `/api/lead` BFF 로 POST 한다
+  (`clientIp` 는 서버가 XFF 에서 붙인다). 전환 부품을 두 벌 만들지 마라 — 하나로 재사용한다. 요건 넷:
+  · **연락처 필수 · 이메일 선택**(문의 폼과 반대다). 본문은 `{name, phone, email?, message?, interest,
+    isQuick, consentMarketing, tracking}`.
+  · **UTM·클릭ID 8키**를 `tracking` 으로 동봉한다 — `utm_source`·`utm_medium`·`utm_campaign`·
+    `utm_adgroup`·`utm_content`·`fbclid`·`gclid`·`nclid`. 하나라도 있으면 채운다.
+  · **캡처는 mount 후 `window.location.search`** 로 한다. 랜딩이 force-static ISR 일 수 있어 RSC 에서
+    `searchParams` 를 읽으면 정적 셸이 깨진다 — `useSearchParams()` 도 같은 이유로 금지.
+  · **`TOO_MANY_REQUESTS` 안내를 반드시 넣는다**(공개 폼이라 레이트리밋이 흔하다). 400 은 `errors[]` 를
+    필드별로 표시하고, 성공 시 입력만 비우고 **`tracking` 은 유지**한다(같은 방문의 재제출도 같은 유입 귀속).
+  이 섹션은 **`id="lead"` 앵커**를 갖는다 — 원페이지 랜딩에서 히어로 CTA 를
   `"ctaHref": "#lead"` 로 여기에 걸 수 있다. 앵커를 지우면 그 버튼이 조용히 아무 데도 안 간다.
 - `SERVICE_MENU` 는 상품 참조가 **필수**다(rev 3). 참조가 0 이면 렌더러가 그 섹션을 안 그려서 **개시 직후
   조용히 사라진다** — 시술 목록의 AEO 보장(`ItemList`·§5.1)이 그 섹션에 걸려 있으므로 보장까지 함께 죽는다.
@@ -792,8 +1085,9 @@ page.sections // [{ type: "HERO", sortOrder: 0, config: "{\"title\":\"…\"}" },
 - `LOGO_WALL` 에 실존 기업 로고를 넣지 마라 — 사용 허락이 있는 것만.
 
 **아이콘 — 큐레이션 맵의 키 문자열만**
-`FEATURE_GRID` 의 `icon` 은 아래 32개 중 하나다. 렌더는 `ui/Icon` 의 맵 lookup 이고 **미지 이름은 아이콘 영역을
-생략**한다(죽지 않는다·기본 글리프도 안 쓴다 — 틀린 아이콘보다 없는 아이콘이 낫다).
+`FEATURE_GRID` 의 `icon` 은 아래 32개 중 하나다. 렌더러는 **이 키 → 글리프 맵 lookup** 으로 짜고,
+**미지 이름은 아이콘 영역을 생략**한다(죽지 않는다·기본 글리프로 때우지도 않는다 — 틀린 아이콘보다
+없는 아이콘이 낫다).
 
 ```
 shield-check  rocket      line-chart  trending-up  users        user-check  clock     calendar-check