@zalkera/client 0.13.0 → 0.13.1

package/llms.txt

@@ -62,6 +62,9 @@ await zalkera.submitInquiry(input, { clientIp: ip });
 - `getSiteConfig()` — 회사명·연락처·테마·SEO 기본값
 - `listCategories()` · `listPosts({category?,page?,size?,sort?})` · `getPost(slug)` · `recordPostView(slug,ctx)`
 - `getPage(slug)` · `listPages({page?,size?})`(열거 전용·본문 없음·sitemap 용·size 상한 100) · `listMenus()` (HEADER/FOOTER) · `getMediaUrl(id)`
+  - ⚠ 이 셋(`getPage`·`listPages`·`listMenus`)은 **섹션이 DB 에 있는 사이트**(`"content": "sections-db"`)의 표면이다.
+    **새로 만드는 사이트는 안 부른다** — 페이지·섹션·내비의 정본이 레포 파일이라 백엔드 왕복이 아예 없다(§4.8·§9.1).
+    계약은 append-only 라 메서드는 남지만, 소스 정본 레포에서 이걸 부르면 빈 결과로 화면이 비는 쪽이 정상이다.
 - `submitInquiry(input, ctx)` · `submitLead(input, ctx)`  ← ctx.clientIp 필수(서버)
 
 ### 커머스 — 카탈로그(공개)
@@ -345,6 +348,70 @@ if (booking.orderNo) {                  // status=PENDING
   홉을 `{ clientIp }` 로 넘긴다(안 넘기면 방문자 전원 429 — §4.6·문의와 동일 관용구).
 - 선례: `components/LeadForm.tsx`(아일랜드·UTM 캡처) · `app/api/lead/route.ts`(BFF·201 관통).
 
+### 4.8 콘텐츠 파일로 그리는 고정 페이지 (`"content": "source"` · 권장)
+
+사이트의 얼굴을 레포가 정본으로 가질 때의 배선이다. 파일 형상·방언은 §9.1·§9.2, 아래는 그것을 읽는 코드다.
+**라우트는 하나면 된다** — 페이지가 늘어도 `content/` 에 json 이 느는 것이지 라우트가 늘지 않는다.
+
+```ts
+// content/index.ts — 이 디렉터리의 유일한 코드. **정적 import** 라야 dev HMR + standalone 트레이싱을 얻는다.
+import home from "./pages/home.json";
+import about from "./pages/about.json";
+import nav from "./nav.json";
+
+// 값을 unknown 으로 둔다: 손으로 고치는 파일이라 형상이 틀릴 수 있고, 판정·강하는 로더 한 곳이 한다.
+// 여기서 타입을 주장하면 틀린 json 하나가 **빌드를 세운다** — 계약은 "틀린 부분만 안 그린다" 다.
+export const pages: Record<string, unknown> = { home, about };
+export { nav };
+```
+
+```ts
+// lib/content.ts — **절대 throw 하지 않는다.**
+import { asString } from "@zalkera/client";
+import { pages } from "../content";
+
+export interface ContentSection { type: string; config: unknown }   // config 는 **객체**다
+
+export function loadPageContent(slug: string) {
+  const raw = pages[slug];
+  if (raw == null || typeof raw !== "object" || Array.isArray(raw)) return null;
+  const r = raw as Record<string, unknown>;
+  const sections = (Array.isArray(r.sections) ? r.sections : []).flatMap((s): ContentSection[] => {
+    if (s == null || typeof s !== "object") return [];
+    const type = asString((s as Record<string, unknown>).type)?.trim();
+    return type ? [{ type, config: (s as Record<string, unknown>).config }] : [];   // config 는 그대로 넘긴다
+  });
+  return { title: asString(r.title)?.trim() || slug, seo: r.seo, sections };
+}
+
+export const pageSlugs = (): string[] => Object.keys(pages);   // sitemap·generateStaticParams 가 읽는다
+```
+
+```tsx
+// app/[slug]/page.tsx — 전 페이지를 이 하나가 그린다. 백엔드 왕복이 없다.
+export const dynamic = "force-static";
+export function generateStaticParams() { return pageSlugs().map((slug) => ({ slug })); }
+
+export default async function StaticPage({ params }: { params: Promise<{ slug: string }> }) {
+  const { slug } = await params;
+  const page = loadPageContent(slug);
+  if (!page) notFound();
+  if (slug === "home") redirect("/");           // 홈의 정본 주소는 루트다(같은 내용이 두 URL 로 색인되면 손해)
+  return (
+    <main>
+      <JsonLd data={webPageJsonLd({ title: page.title, slug }, siteUrl())} />
+      <h1>{page.title}</h1>
+      <SectionList sections={page.sections} />  {/* 정렬하지 않는다 — 배열 순서가 화면 순서다 */}
+    </main>
+  );
+}
+```
+
+- 상품 참조 섹션(`SERVICE_MENU`·`BOOKING_CTA`)이 있으면 `SectionList` 가 `listProducts` 를 **1회** 부르고
+  `slug`(= handle)를 키로 맵을 만들어 각 섹션에 넘긴다. 조회가 실패해도 페이지는 산다 — 그 섹션만 빠진다.
+- 홈(`app/page.tsx`)은 `loadPageContent("home")` 의 섹션이 있으면 그것을 그리고, 없으면 커머스 골격으로
+  강하한다. 콘텐츠 없는 것은 **정상**이다(커머스 테넌트).
+
 ## 5. 흔한 실수(하지 말 것)
 
 - ❌ 클라이언트 컴포넌트에서 `@zalkera/client` import → baseUrl 노출. ✅ 서버에서만.
@@ -360,6 +427,14 @@ if (booking.orderNo) {                  // status=PENDING
 - ❌ **`var(--oneq-*)` 참조**(정의처 없는 죽은 레거시 토큰). ✅ 테넌트 색은 토큰 유틸리티(`bg-primary`·
   `text-primary` 등, §8)로 쓴다.
 - ❌ 서버에서 `submitInquiry`/`submitLead`/`recordPostView` 부를 때 clientIp 누락 → 방문자 전원 rate-limit.
+- ❌ **콘텐츠 파일 사이트에서 페이지를 라우트로 신설**(`app/오시는길/page.tsx` 를 새로 짜기). ✅ `content/pages/<slug>.json`
+  **+ 매니페스트 1행**이면 끝이고 라우팅·sitemap 은 이미 있다(§4.8). 라우트를 새로 짜면 그 페이지만 계약 밖으로
+  나가 다음번 "말로 고치기"가 다시 tsx 탐색이 된다 — 실측된 회귀다.
+- ❌ **소스 파일에 숫자 id 적기**(`"assetId": 12`·`"productIds": [3,7]`). ✅ 소스 방언으로 — 에셋은 `public/`
+  루트 절대 경로, 상품은 handle(§9.2). 숫자 id 는 테넌트 스코프라 그 소스를 재업로드하면 의미를 잃는다.
+- ❌ **콘텐츠 파일에 `sortOrder` 를 넣거나 읽은 뒤 정렬**. ✅ 배열 순서가 곧 화면 순서다(§9.1).
+- ❌ **콘텐츠 json 을 런타임 `fs.readFile` 로 읽기.** ✅ `content/index.ts` 정적 import — fs 로 읽으면 dev HMR 이
+  안 돌고 `next build`(standalone) 산출물에서 페이지가 통째로 사라진다.
 - ❌ **상품·후기·게시글 등 도메인 데이터를 하드코딩**(리터럴 배열·목업 후기 등). ✅ 반드시 `@zalkera/client`
   로 조회한다. 계약에 없는 데이터(예: slug→productId 매핑이 없어 후기를 못 붙임)면 **하드코딩으로 때우지
   말고 그 사실을 보고**한다. 하드코딩한 데이터는 프리뷰·실사이트에서 실데이터와 갈라져 첫인상을 죽인다.
@@ -392,7 +467,8 @@ if (booking.orderNo) {                  // status=PENDING
   라우트가 동적 렌더로 강등돼 크롤러 방문마다 서버 렌더가 돈다. 더 넓히려면 `/products/page/[n]` 같은
   **정적 세그먼트**로 늘려라. 본보기: `src/app/products/page.tsx` · `src/app/blog/page.tsx`.
 - ✅ **예약(시술) 사이트의 목록 보장은 `SERVICE_MENU` 섹션이 낸다.** 섹션 어휘 `SERVICE_MENU` 는 계약상
-  `jsonLd: "ItemList"` 이고(`SECTION_CONTRACT` · `contractRev` 2 이상), config 의 `productIds` **순서 그대로**
+  `jsonLd: "ItemList"` 이고(`SECTION_CONTRACT` · `contractRev` 2 이상), config 의 상품 참조 배열
+  (DB 방언 `productIds` · 소스 방언 `products` — §9.2) **순서 그대로**
   목록 그래프를 낸다 — 원장이 정한 노출 순서를 기계에도 같은 순서로 준다. 시술 목록의 정위치는 **홈의 이
   섹션**이지 별도 라우트가 아니다: 뷰티 사이트에 목록 라우트를 강제하는 것은 디자인 자유를 깎으면서 얻는
   것이 없어서, 예약 유형의 목록 보장은 이 산출로 충족한다(`FAQ_LIST`↔`FAQPage` 와 같은 선례 — 목록의 정본이
@@ -573,39 +649,120 @@ CI validator **S6** 가 좌변 잔존을 error 로 막는다.
 
 ## 9. 섹션 어휘 — 페이지는 데이터로 그린다
 
-고정 페이지(`getPage(slug)`)는 본문 HTML 만 있는 게 아니라 **섹션 배열**을 갖는다. 각 섹션은 `type`(코드 enum)과
-`config`(타입별 JSON)뿐이고, 백엔드는 config 를 **파싱하지 않는다** — 스키마는 프론트 계약이다.
+고정 페이지는 본문 HTML 한 덩어리가 아니라 **섹션 배열**이다. 각 섹션은 `type`(코드 enum)과 `config`(타입별
+JSON)뿐이고, 백엔드는 config 를 **파싱하지 않는다** — 스키마는 프론트 계약이다.
+
+**왜 이 구조인가**: 콘텐츠가 마크업에 박히지 않고 계약을 타므로, 테넌트가 "말로" 고친 것이 재코딩 없이
+반영된다("FAQ 에 배송 질문 추가해줘"). **마크업에 문구를 하드코딩하면 이 경로가 죽는다** — 문구 한 줄을
+고치는 일이 컴포넌트 트리 탐색이 되고, 그 탐색이 곧 토큰이다.
+
+**그 배열이 사는 곳은 둘이고, 어느 쪽인지는 레포가 선언한다.**
+
+```json
+// package.json
+"zalkera": { "styling": "tailwind-tokens", "content": "source" }
+```
+
+| 선언 | 의미 |
+|---|---|
+| `"source"` | 사이트의 얼굴(페이지·섹션·문구·섹션 이미지·내비)의 정본이 **레포 파일**. **템플릿과 v2 팩 태생이 이 형상**이다(카탈로그에 v1 팩이 남아 있는 동안 그쪽 태생은 `sections-db` 다) |
+| `"sections-db"` | 전환기 표기 — 섹션이 백엔드에 있고 `getPage(slug)` 가 준다(구 프리셋 태생 사이트) |
+| 미선언 | 안전 기본 — **선언이 없으면 이 계약을 안 쓰는 레포로 본다**(계약 검사도 걸지 않는다) |
+
+> ⚠ 이 선언은 **지금은 계약 표기일 뿐**이다. 콘솔이 이 값을 읽어 페이지·섹션 폼을 감추는 배선은
+> **아직 서지 않았다** — 그때까지는 선언과 무관하게 콘솔 폼이 보인다. 레시피가 실물을 앞지르지
+> 않으려고 그대로 적는다.
+
+두 거처는 **같은 어휘·같은 config 키**를 쓴다. 다른 것은 참조를 적는 방언 하나뿐이다(§9.2).
+
+### 9.1 소스 정본 (`"content": "source"`) — 권장 형상
+
+```
+content/
+  index.ts          # 이 디렉터리의 유일한 코드 — 페이지 json 을 정적 import 해 slug→맵으로 내놓는다
+  nav.json          # { "header": [{label, href}], "footer": [...] }
+  pages/home.json   # 페이지당 1파일. 키가 곧 URL 경로(home → /, about → /about)
+```
+
+```json
+// content/pages/home.json
+{
+  "title": "홈",
+  "seo": { "title": "…", "description": "…" },
+  "sections": [
+    { "type": "HERO", "config": { "title": "…", "asset": "/images/hero.png" } },
+    { "type": "SERVICE_MENU", "config": { "products": ["care-basic", "gel-onecolor"] } }
+  ]
+}
+```
+
+- **배열 순서가 화면 순서다.** `sortOrder` 키는 **없다** — 정렬하지 마라. 순서를 정하는 곳이 둘이면
+  "후기를 위로 올려줘"가 매번 어느 쪽을 고치는지 판별 문제가 된다.
+- **`config` 는 객체다**(문자열이 아니다). 두 거처를 하나의 소비자로 읽으려면 `readConfig` 를 쓴다 —
+  문자열이든 객체든 받는다.
+- **정적 import 매니페스트를 우회하지 마라.** 런타임 `fs` 로 읽으면 ⑴ dev 에서 json 을 고쳐도 HMR 이
+  안 돌고(확인이 비싸지면 재시도가 늘고 그게 곧 토큰이다) ⑵ `next build`(standalone) 산출물에 콘텐츠가
+  트레이싱되지 않아 **개시된 사이트에서만** 페이지가 사라진다.
+- **페이지 신설 = json 1개 + 매니페스트 1행.** 라우트를 새로 짜지 마라 — `src/app/[slug]/page.tsx` 하나가
+  전 페이지를 그리고 `src/app/sitemap.ts` 가 매니페스트에서 등재한다. 라우트를 새로 짜면 그 페이지만
+  계약 밖으로 나가 "말로 고치기"가 다시 tsx 탐색이 된다.
+- **로더는 절대 throw 하지 않는다.** json 은 사람과 AI 가 손으로 고치는 파일이라 형상이 틀릴 수 있다 —
+  틀린 곳만 안 그려지고 페이지는 산다. 문구 하나 잘못 고쳤다고 사이트가 500 이면 "말로 고친다"가 성립 안 한다.
+- 이 계약을 **안 지킨 레포도 정상으로 돈다.** 문구를 tsx 에 직접 든 레포도 개시·발행·"말로 고치기"가
+  전부 동작한다 — 강제가 아니라 권장이고, 검사는 위 선언을 **스스로 했을 때만** 격상된다.
+
+### 9.2 참조 방언 — 소스는 숫자 id 를 못 쓴다
+
+DB 는 자기가 발급한 숫자 id 를 쓰고, **소스는 그 id 를 알 수 없으므로** 사람이 읽고 쓰는 참조를 쓴다.
+**거처가 방언을 정한다.**
+
+| 참조 | DB 방언(`sections-db`) | 소스 방언(`source`) |
+|---|---|---|
+| 에셋 | `assetId`·`*AssetId` : number → `mediaSrc(id)` | `asset`·`*Asset` : `"/images/hero.png"` → `assetPath(v)` |
+| 상품 1개 | `productId` : number | `product`·`*Product` : handle 문자열 |
+| 상품 배열 | `productIds` : number[] | `products`·`*Products` : handle 문자열 배열 |
+
+- **handle = `ProductSummary.slug`.** 소스가 DB 카탈로그를 가리키는 **유일한 안정 키**다.
+- ❌ **소스에 숫자 id 를 적지 마라.** 테넌트 스코프 값이라, 고객이 그 소스를 소유하고 다른 테넌트에
+  재업로드하는 순간 의미를 잃는다.
+- `assetPath` 는 **레포 루트 절대 경로만** 통과시킨다(스킴·`//`·`..`·역슬래시 → `undefined`). 이미지 실물은
+  레포 `public/` 에 둔다. 원격 이미지는 계약 영역이 아니라 자유 영역이다.
+- `asHandleArray` 는 **배열 순서를 보존한다** — 그 순서가 노출 순서의 원장이다.
+- 상품 상세의 커버(`coverAssetId`)는 소스 방언에서도 여전히 숫자 id 다. 그건 카탈로그가 발급한 값이지
+  소스가 적는 값이 아니다 — 섹션 이미지와 상품 이미지는 다른 축이다.
+- **아래 §9.4 어휘 표의 `config` 선언은 DB 방언 표기다.** 소스에 적을 때 이 표로 옮겨 적는다.
+  키의 **의미**는 두 방언이 같다.
+
+### 9.3 DB 정본 (`"content": "sections-db"`) — 전환기
 
 ```ts
 const page = await zalkera.getPage("home");
 page.sections // [{ type: "HERO", sortOrder: 0, config: "{\"title\":\"…\"}" }, …]
 ```
 
-**왜 이 구조인가**: 콘텐츠가 마크업에 박히지 않고 계약을 타므로, 테넌트가 콘솔에서·"말로" 고친 것이 재코딩 없이
-반영된다("FAQ 에 배송 질문 추가해줘"). **마크업에 문구를 하드코딩하면 이 경로가 죽는다.**
+- `config` 가 **문자열**이다(컬럼 저장 형상). `parseConfig` 또는 `readConfig` 로 읽는다.
+- **`sortOrder` 로 한 번 더 정렬한다.** 서버가 정렬해 주지만 순서가 틀리면 화면에서 바로 티가 난다.
+- **key 는 `type`+`sortOrder`+index 로 짠다.** `PageSection` 계약에 id 가 없다(실측).
+
+### 9.4 어휘 (12종) — 두 거처 공통
 
 **규약**
-- `config` 는 **문자열**이다. 파싱은 `parseConfig` + `asString`/`asId`/`asIdArray`/`asObjectArray` 로 한다
-  (이 패키지가 export — 절대 throw 하지 않는다). 필수 필드가 없으면 **그 섹션만 안 그린다**.
-  페이지 전체가 죽으면 안 된다.
-- **미지 타입은 조용히 건너뛴다.** 어휘는 append-only 라 백엔드가 타입을 늘려도 옛 사이트가 깨지지 않아야 한다.
+- 파싱 헬퍼는 이 패키지가 준다: `readConfig`/`parseConfig` + `asString`/`asId`/`asIdArray`/`asObjectArray`
+  + 방언 헬퍼 `asHandle`/`asHandleArray`/`assetPath`. **절대 throw 하지 않는다** — 필수 필드가 없으면
+  **그 섹션만 안 그린다**. 페이지 전체가 죽으면 안 된다.
+- **미지 타입은 조용히 건너뛴다.** 어휘는 append-only 라 타입이 늘어도 옛 사이트가 깨지지 않아야 한다.
   `default:` 에서 에러·경고를 내지 마라 — 그게 계약이다.
-- 이미지는 `assetId`(숫자)다. `mediaSrc(id)`(이 패키지 export)로 프록시 경유해 그린다.
-- **모든 href 는 `safeLinkUrl()` 을 태운다.** 콘솔 입력이라 `javascript:` 가 들어올 수 있다(저장형 XSS).
+- **모든 href 는 `safeLinkUrl()` 을 태운다.** 콘솔 입력·손으로 고친 json 이라 `javascript:` 가 들어올 수 있다(저장형 XSS).
 - 자유 HTML 은 없다 — plain text + 줄바꿈뿐(`whitespace-pre-wrap`).
+- **디스패치는 직접 짠다** — `type` 으로 컴포넌트를 고르는 `switch` 하나면 된다.
 - 타입·키를 **지어내지 마라.** 계약 정본은 백엔드 레포의 `doc/contracts/section-vocabulary.json` 이고,
-  이 패키지가 export 하는 `SECTION_CONTRACT` 는 그것을 npm 으로 실어 나르는 **운반체**다(`src/sections.ts`
+  이 패키지가 export 하는 `SECTION_CONTRACT` 는 그것을 npm 으로 실어 나르는 **운반체**다(`sections.ts`
   KDoc 이 같은 말을 한다). 코드에서 읽을 것은 `SECTION_CONTRACT` 가 맞지만, 어휘를 **늘리는** 결정은
   정본 쪽에서 난다 — 필요한 어휘가 없으면 만들지 말고 **보고**한다.
 
-**디스패치는 직접 짠다** — `type` 으로 컴포넌트를 고르는 `switch` 하나면 된다. 위 규약에 더해 둘을 지켜라:
-
-- **`sortOrder` 로 한 번 더 정렬한다.** 서버가 정렬해 주지만 순서가 틀리면 화면에서 바로 티가 나는 종류다.
-- **key 는 `type`+`sortOrder`+index 로 짠다.** `PageSection` 계약에 id 가 없어(실측) 순수 인덱스보다 낫다.
-
-**어휘 (12종)** — `vertical` 은 콘솔 픽커 그룹핑용이지 사용 제한이 아니다(GENERAL 은 뷰티 테넌트도 쓴다).
+`vertical` 은 콘솔 픽커 그룹핑용이지 사용 제한이 아니다(GENERAL 은 뷰티 테넌트도 쓴다).
 
-| type | vertical | config (필수는 굵게) | JSON-LD |
+| type | vertical | config — **DB 방언 표기**(필수는 굵게 · 소스 방언 대응은 §9.2) | JSON-LD |
 |---|---|---|---|
 | `HERO` | GENERAL | eyebrow?, **title**, subtitle?, ctaLabel?, ctaHref?, assetId? | — |
 | `FEATURE_GRID` | GENERAL | title?, **items**[{icon?, **title**, body?}] | — |
@@ -615,7 +772,7 @@ page.sections // [{ type: "HERO", sortOrder: 0, config: "{\"title\":\"…\"}" },
 | `TESTIMONIALS` | GENERAL | title?, **items**[{**quote**, author?, role?, assetId?}] | **없음(의도)** |
 | `FAQ_LIST` | GENERAL | title?, **items**[{**question**, **answer**}] | `FAQPage` |
 | `LEAD_CTA` | GENERAL | title?, body?, interest?, quick? | — (`submitLead` 계약) |
-| `SERVICE_MENU` | BEAUTY | productIds?, categorySlug? | — |
+| `SERVICE_MENU` | BEAUTY | **productIds**(rev 3 부터 필수), categorySlug? | `ItemList`(rev 2 부터) |
 | `BEFORE_AFTER_GALLERY` | BEAUTY | **items**[{**beforeAssetId**, **afterAssetId**, caption?}] | — |
 | `BOOKING_CTA` | BEAUTY | **productId**, label? | — |
 | `DOCTOR_INTRO` | BEAUTY | **name**, title?, photoAssetId?, bio? | — |
@@ -628,6 +785,10 @@ page.sections // [{ type: "HERO", sortOrder: 0, config: "{\"title\":\"…\"}" },
 - `LEAD_CTA` 는 템플릿의 `components/LeadForm` 을 그대로 쓴다(UTM·클릭ID 추적·레이트리밋 안내 동봉).
   전환 부품을 두 벌 만들지 마라. 이 섹션은 **`id="lead"` 앵커**를 갖는다 — 원페이지 랜딩에서 히어로 CTA 를
   `"ctaHref": "#lead"` 로 여기에 걸 수 있다. 앵커를 지우면 그 버튼이 조용히 아무 데도 안 간다.
+- `SERVICE_MENU` 는 상품 참조가 **필수**다(rev 3). 참조가 0 이면 렌더러가 그 섹션을 안 그려서 **개시 직후
+  조용히 사라진다** — 시술 목록의 AEO 보장(`ItemList`·§5.1)이 그 섹션에 걸려 있으므로 보장까지 함께 죽는다.
+  소스 방언에서는 `config.products` 의 **handle 배열 순서를 그대로** 그린다(정렬하지 마라 — 그 배열이 노출
+  순서의 원장이고, `ItemList` 도 같은 순서로 나가야 한다).
 - `LOGO_WALL` 에 실존 기업 로고를 넣지 마라 — 사용 허락이 있는 것만.
 
 **아이콘 — 큐레이션 맵의 키 문자열만**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zalkera/client",
-  "version": "0.13.0",
+  "version": "0.13.1",
   "description": "zalkera 헤드리스 CMS 공개 API 클라이언트 (테넌트 사이트용)",
   "license": "MIT",
   "author": "Credium Co., Ltd.",