byuckchon-frontend-cli 1.9.1 → 1.9.3

package/README.md

@@ -180,10 +180,10 @@ FE 전반의 규칙(폴더 구조, 네이밍, 스웨거 → 코드 변환 규칙
 | 프레임워크 | 위치 |
 | --- | --- |
 | React (Vite/CRA 등) | `src/api/api-codegen.md` |
-| Next.js | `lib/api/api-codegen.md` |
+| Next.js | `src/lib/api/api-codegen.md` |
 
 - 이 파일은 `bc.config.json` 의 `docs` 에 자동 등록되어 **chat 시작 시 주입**됩니다.
-- 하나의 .md 로 React/Next 를 모두 다루며(차이는 위치뿐), 팀 규칙에 맞게 직접 다듬어 쓰면 됩니다.
+- 하나의 문서에 React의 axios 규칙과 Next.js의 fetch 및 Server/Client 경계 규칙이 함께 들어갑니다.
 - 이미 파일이 있으면 덮어쓰지 않습니다.
 
 ### OpenAPI / 코드 컨텍스트 — 자동 주입 (v1.4+)
@@ -193,6 +193,10 @@ FE 전반의 규칙(폴더 구조, 네이밍, 스웨거 → 코드 변환 규칙
 
 - **OpenAPI**: chat 시작 시 자동 fetch + 1시간 디스크 캐시 → 엔드포인트 요약을 시스템 프롬프트에 박음.
   - 헤더에 `openapi` 줄로 표시. 캐시 hit 면 `(cached)`, fresh fetch 면 `(live)`.
+  - **세션 중 서버가 스펙을 바꿔도 자동 대응 (v1.10+)**: `search_openapi` / `get_openapi_endpoint` 가
+    캐시에서 엔드포인트를 못 찾으면 **딱 한 번 최신본을 다시 받아 재검색**합니다 (`🔄 OpenAPI 스펙 새로고침`).
+    남용 방지를 위해 세션당 횟수·간격이 제한됩니다. "방금 스웨거 업데이트했어, 다시 읽어줘" 라고 하면
+    즉시 강제 새로고침(`refresh_openapi`)합니다.
 - **코드 인덱스**: chat 시작 시 인덱스 파일이 없으면 **백그라운드에서 자동 빌드**.
   - 빌드 중에는 화면에 `📚 인덱싱 중 ...` 진행 표시. 끝나면 `✓` 메시지 한 줄.
   - OpenAI 키가 없으면 빌드를 건너뛰고 도움 메시지를 띄움 (Anthropic 은 임베딩 API 미제공).

package/bin/index.js

@@ -28,7 +28,7 @@ const program = new Command();
 program
   .name('bc')
   .description('Byuckchon Frontend Workbench — 프로젝트 스타터 + AI 어시스턴트')
-  .version('1.9.0');
+  .version('1.10.0');
 
 program
   .command('init')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "byuckchon-frontend-cli",
-  "version": "1.9.1",
+  "version": "1.9.3",
   "description": "Byuckchon Frontend Workbench — project starter + AI chat + codebase RAG + OpenAPI codegen",
   "type": "module",
   "engines": {
@@ -10,12 +10,6 @@
     "byuckchon-frontend-cli": "./bin/index.js",
     "bc": "./bin/index.js"
   },
-  "scripts": {
-    "start": "node bin/index.js",
-    "chat": "node bin/index.js chat",
-    "init": "node bin/index.js init",
-    "config": "node bin/index.js config show"
-  },
   "dependencies": {
     "@ai-sdk/anthropic": "^3.0.85",
     "@ai-sdk/openai": "^3.0.73",
@@ -65,5 +59,11 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/RevolutionaryWarrior/byuckchon-frontend-cli.git"
+  },
+  "scripts": {
+    "start": "node bin/index.js",
+    "chat": "node bin/index.js chat",
+    "init": "node bin/index.js init",
+    "config": "node bin/index.js config show"
   }
-}
+}

package/src/ai/tools.js

@@ -44,6 +44,39 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
     return _openapiDocPromise;
   }
 
+  // ── live refetch (서버가 세션 도중 스펙을 바꾼 경우 대비) ──
+  // 남용 방지: 세션당 최대 횟수 + 최소 간격 throttle.
+  const REFRESH_MAX = 6;
+  const REFRESH_MIN_INTERVAL_MS = 10_000;
+  let _refreshCount = 0;
+  let _lastRefreshAt = 0;
+
+  /**
+   * 캐시를 무시하고 OpenAPI 스펙을 다시 fetch 한다.
+   * @returns {Promise<{ doc: object|null, refreshed: boolean, reason?: string }>}
+   */
+  async function refreshOpenApiDoc() {
+    if (!openapiSource) return { doc: null, refreshed: false, reason: 'no-source' };
+
+    const now = Date.now();
+    if (_refreshCount >= REFRESH_MAX) {
+      return { doc: await loadOpenApiDoc(), refreshed: false, reason: 'limit' };
+    }
+    if (now - _lastRefreshAt < REFRESH_MIN_INTERVAL_MS) {
+      return { doc: await loadOpenApiDoc(), refreshed: false, reason: 'throttled' };
+    }
+
+    _refreshCount += 1;
+    _lastRefreshAt = now;
+    _openapiDocPromise = getCachedOpenApi(openapiSource, { force: true })
+      .then((res) => res.doc ?? null)
+      .catch(() => null);
+
+    const doc = await _openapiDocPromise;
+    onEvent({ kind: 'openapi_refreshed', ok: !!doc });
+    return { doc, refreshed: true };
+  }
+
   function safePath(p) {
     if (!p || typeof p !== 'string') {
       throw new Error('path 가 비어있습니다');
@@ -188,7 +221,11 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
   // ─────────── OpenAPI 툴 ───────────
 
   async function searchOpenApi({ query, limit = 40 }) {
-    const doc = await loadOpenApiDoc();
+    let doc = await loadOpenApiDoc();
+    if (!doc) {
+      // 첫 로드 실패면 한 번 live refetch 시도.
+      ({ doc } = await refreshOpenApiDoc());
+    }
     if (!doc) {
       return {
         ok: false,
@@ -197,11 +234,25 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
           '(NestJS 는 보통 /api/docs 가 아니라 /api/docs-json).',
       };
     }
-    const hits = searchEndpoints(doc, query, { limit });
+
+    let hits = searchEndpoints(doc, query, { limit });
+    let refreshed = false;
+
+    // 캐시된 스펙에서 못 찾으면 → 서버에서 방금 추가됐을 수 있으니 딱 한 번 live refetch 후 재검색.
+    if (hits.length === 0) {
+      const r = await refreshOpenApiDoc();
+      if (r.refreshed && r.doc) {
+        refreshed = true;
+        doc = r.doc;
+        hits = searchEndpoints(doc, query, { limit });
+      }
+    }
+
     return {
       ok: true,
       query,
       count: hits.length,
+      refreshed,
       endpoints: hits.map((e) => ({
         method: e.method,
         path: e.path,
@@ -210,17 +261,63 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
       })),
       hint:
         hits.length === 0
-          ? '매치 없음. 다른 키워드로 재시도하거나, query 를 비워 전체 목록을 받아 path 를 직접 고르세요.'
-          : '상세 스키마가 필요하면 get_openapi_endpoint(path, method) 를 호출하세요.',
+          ? (refreshed
+              ? '최신 스펙을 다시 받아왔는데도 매치가 없습니다. 다른 키워드로 재시도하거나 query 를 비워 전체 목록을 확인하세요.'
+              : '매치 없음. 다른 키워드로 재시도하거나, query 를 비워 전체 목록을 받아 path 를 직접 고르세요.')
+          : (refreshed
+              ? '캐시엔 없던 항목을 최신 스펙에서 찾았습니다. 상세는 get_openapi_endpoint(path, method).'
+              : '상세 스키마가 필요하면 get_openapi_endpoint(path, method) 를 호출하세요.'),
     };
   }
 
   async function getOpenApiEndpoint({ path: epPath, method }) {
-    const doc = await loadOpenApiDoc();
+    let doc = await loadOpenApiDoc();
+    if (!doc) {
+      ({ doc } = await refreshOpenApiDoc());
+    }
     if (!doc) {
       return { ok: false, error: 'OpenAPI 스펙을 불러올 수 없습니다.' };
     }
-    return getEndpoint(doc, epPath, method);
+
+    let result = getEndpoint(doc, epPath, method);
+
+    // 못 찾으면 → 최신 스펙으로 한 번 더.
+    if (!result.ok) {
+      const r = await refreshOpenApiDoc();
+      if (r.refreshed && r.doc) {
+        const retry = getEndpoint(r.doc, epPath, method);
+        if (retry.ok) result = { ...retry, refreshed: true };
+        else result = { ...retry, refreshed: true };
+      }
+    }
+    return result;
+  }
+
+  async function refreshOpenApi() {
+    if (!openapiSource) {
+      return { ok: false, error: 'bc.config.json 에 api.openapi 가 설정되어 있지 않습니다.' };
+    }
+    const r = await refreshOpenApiDoc();
+    if (!r.doc) {
+      return {
+        ok: false,
+        refreshed: r.refreshed,
+        error:
+          r.reason === 'throttled'
+            ? '방금 새로고침했습니다. 잠시 후 다시 시도하세요.'
+            : '스펙을 다시 받아오지 못했습니다 (네트워크/URL 확인).',
+      };
+    }
+    const count = (r.doc.paths ? Object.keys(r.doc.paths).length : 0);
+    return {
+      ok: true,
+      refreshed: r.refreshed,
+      reason: r.refreshed ? undefined : r.reason,
+      paths: count,
+      message: r.refreshed
+        ? `최신 OpenAPI 스펙을 다시 받아왔습니다 (path ${count}개).`
+        : '최근에 이미 새로고침되어 캐시를 재사용했습니다.',
+    };
   }
 
   // ─────────── Figma 툴 ───────────
@@ -381,6 +478,20 @@ export function buildTools({ projectRoot, effective, onEvent = () => {}, openapi
       }),
       execute: getOpenApiEndpoint,
     }),
+    refresh_openapi: tool({
+      description:
+        '연결된 OpenAPI(Swagger) 스펙을 캐시 무시하고 서버에서 다시 받아온다. ' +
+        '사용자가 "방금 스웨거(백엔드 API) 를 업데이트했다 / 다시 읽어라" 라고 하거나, ' +
+        'search_openapi 가 분명히 있어야 할 엔드포인트를 못 찾을 때 호출. ' +
+        '(search_openapi / get_openapi_endpoint 는 못 찾으면 자동으로 한 번 새로고침하므로, ' +
+        '명시적 요청이 있을 때만 직접 부르면 된다.)',
+      inputSchema: jsonSchema({
+        type: 'object',
+        properties: {},
+        additionalProperties: false,
+      }),
+      execute: refreshOpenApi,
+    }),
     write_file: tool({
       description:
         '새 파일을 만들거나 기존 파일을 통째로 덮어쓴다. 새 파일을 만들기 전에 반드시 1) 비슷한 기존 파일을 read_file 로 보고 2) 같은 폴더 컨벤션(barrel 파일, 네이밍, import 순서) 을 따른다.',

package/src/commands/adopt.js

@@ -145,7 +145,7 @@ export async function adoptCommand(opts = {}) {
   console.log(chalk.green(`\n  ✓ ${CONFIG_PATHS.projectFileName} 작성 완료.`));
   console.log(chalk.dim(`    ${targetFile}`));
 
-  // API 코드 컨벤션 .md 를 API 루트(src/api | lib/api)에 깐다 (이미 있으면 유지).
+  // API 코드 컨벤션 .md 를 API 루트(src/api | src/lib/api)에 깐다 (이미 있으면 유지).
   try {
     const { relPath, written } = await scaffoldApiConventionDoc({
       projectRoot: cwd,

package/src/commands/chat.js

@@ -121,6 +121,9 @@ export async function chatCommand(opts = {}) {
           '가져와서 zod/타입/요청 함수를 만든다. ' +
           '예: 사용자가 "inquiries" 라고 하면 search_openapi("inquiries") 로 ' +
           '`/api/admin/inquiries` 같은 실제 경로를 찾아낸다. ' +
+          '스펙은 캐시(최대 1시간)라 서버가 방금 바꿨으면 오래됐을 수 있다 — ' +
+          'search_openapi/get_openapi_endpoint 는 못 찾으면 자동으로 한 번 최신본을 다시 받아온다. ' +
+          '사용자가 "방금 스웨거 업데이트했어/다시 읽어" 라고 하면 `refresh_openapi()` 를 먼저 호출한다. ' +
           '이미 `*.gen.ts` 가 있으면 그걸 import 해서 쓰는 것도 좋다.';
       }
     } catch {
@@ -264,6 +267,12 @@ async function runOnce({ cfg, resolved, system, prompt }) {
     effective: cfg.effective,
     openapiSource: cfg.effective.api?.openapi ?? null,
     onEvent: (ev) => {
+      if (ev.kind === 'openapi_refreshed') {
+        console.log(
+          chalk.dim(ev.ok ? '  🔄 OpenAPI 스펙 새로고침' : '  ⚠️  OpenAPI 새로고침 실패'),
+        );
+        return;
+      }
       const label =
         ev.kind === 'write_created'
           ? '🆕'
@@ -489,6 +498,12 @@ async function runReadlineFallback({ cfg, resolved, system, session, openapiInfo
       effective: cfg.effective,
       openapiSource: cfg.effective.api?.openapi ?? null,
       onEvent: (ev) => {
+        if (ev.kind === 'openapi_refreshed') {
+          console.log(
+            chalk.dim(ev.ok ? '\n  🔄 OpenAPI 스펙 새로고침' : '\n  ⚠️  OpenAPI 새로고침 실패'),
+          );
+          return;
+        }
         const label =
           ev.kind === 'write_created'
             ? '🆕 생성'

package/src/generators/apiConventionDoc.js

@@ -9,15 +9,15 @@ const TEMPLATE_PATH = path.resolve(
 
 /**
  * 프레임워크에 맞는 API 루트 폴더.
- * - Next.js → lib/api
+ * - Next.js → src/lib/api
  * - 그 외 React 계열 → src/api
  */
 export function apiRootForFramework(framework) {
-  return framework === 'next' ? 'lib/api' : 'src/api';
+  return framework === 'next' ? 'src/lib/api' : 'src/api';
 }
 
 /**
- * API 코드 컨벤션 .md 를 프로젝트의 API 루트(`src/api` 또는 `lib/api`)에 깐다.
+ * API 코드 컨벤션 .md 를 프로젝트의 API 루트(`src/api` 또는 `src/lib/api`)에 깐다.
  *
  * @param {object} args
  * @param {string} args.projectRoot

package/src/generators/createProject.js

@@ -26,7 +26,7 @@ export async function createProject(config) {
   await createPackageJson(rootDir, config);
   await createBaseFiles(rootDir, config);
   await createReadme(rootDir, config);
-  // API 코드 컨벤션 .md 를 프레임워크에 맞는 API 루트(src/api | lib/api)에 깐다.
+  // API 코드 컨벤션 .md 를 프레임워크에 맞는 API 루트(src/api | src/lib/api)에 깐다.
   await scaffoldApiConventionDoc({ projectRoot: rootDir, framework: config.framework });
   await createBcConfig(rootDir, config);
 

package/src/openapi/cache.js

@@ -23,8 +23,13 @@ function keyFor(input) {
  *
  * - 네트워크 실패 시: 만료된 캐시라도 있으면 그걸로 폴백 (offline-friendly).
  * - 캐시는 .bc/cache/openapi-<hash>.json 에 저장.
+ *
+ * @param {string} input  OpenAPI URL 또는 파일 경로
+ * @param {object} [opts]
+ * @param {boolean} [opts.force]  true 면 TTL 무시하고 무조건 live refetch (캐시 갱신).
+ *                                서버가 세션 도중 스펙을 바꿨을 때 사용.
  */
-export async function getCachedOpenApi(input) {
+export async function getCachedOpenApi(input, { force = false } = {}) {
   const dir = await getCacheDir();
   const file = path.join(dir, `openapi-${keyFor(input)}.json`);
 
@@ -39,7 +44,7 @@ export async function getCachedOpenApi(input) {
     /* miss */
   }
 
-  if (cachedFresh && cached) {
+  if (!force && cachedFresh && cached) {
     return { doc: cached, cached: true, source: input };
   }
 

package/src/ui/ChatApp.js

@@ -871,6 +871,18 @@ export function ChatApp({
 
       // 툴 실행 이벤트는 채팅에 시스템 메시지로 표시 (사용자가 무엇이 일어났는지 보게).
       const onToolEvent = (ev) => {
+        if (ev.kind === 'openapi_refreshed') {
+          setMessages((m) => [
+            ...m,
+            {
+              role: 'system-info',
+              text: ev.ok
+                ? '🔄 OpenAPI 스펙 새로고침 (서버에서 최신본 다시 받음)'
+                : '⚠️  OpenAPI 새로고침 실패 (네트워크/URL 확인)',
+            },
+          ]);
+          return;
+        }
         const labels = {
           write_created: '🆕 생성',
           write_overwritten: '✏️  덮어씀',

package/templates/conventions/api-codegen.md

@@ -4,7 +4,8 @@
 > 사용자가 Swagger JSON(또는 엔드포인트)을 제공하면, AI 는 이 문서의 규칙에 맞춰
 > `api / zod / type / service / index` 파일을 생성한다.
 >
-> 스택: `@tanstack/react-query` + `axios`. **React / Next.js 공용**이며, 차이는 §0 의 "위치"뿐이다.
+> 대상: React(Vite/CRA 등), Next.js App Router
+> 스택: `@tanstack/react-query` + React는 `axios`, Next.js는 native `fetch`.
 
 ---
 
@@ -16,30 +17,25 @@
 2. **기존 코드 우선.** 공용 유틸(`cacheConfig`, `queryKey`, `captureSentryError`, `metaSchema`,
    `PaginationParams` 등)은 새로 만들지 말고 그대로 가져다 쓴다. import 경로가 확실치 않으면
    `search_code` 로 실제 export 위치를 확인한다.
-3. **5파일 세트는 항상 함께.** `api / zod / type / service / index` 를 한 번에 생성한다.
+3. **계약 파일은 항상 함께.** React는 `api / zod / type / service / index`를 한 번에 생성한다.
+   Next.js는 공용 `zod / type`, 서버 기본 호출 파일, 필요한 경우 Client 호출 파일과 service를 생성한다.
+   이미 같은 리소스가 있으면 기존 파일 구성과 이름을 우선한다.
 
 ---
 
-## 0. 위치 & 폴더 구조 ⚠️ (React vs Next 차이는 여기뿐)
+## 0. 위치 & 폴더 구조
 
-API 코드의 **루트 위치는 프레임워크마다 다르다.**
-
-| 프레임워크 | API 루트 |
-| --- | --- |
-| **React** (Vite/CRA 등) | `src/api` |
-| **Next.js** | `lib/api` |
-
-> 그 외 폴더/파일 구조와 규칙은 **완전히 동일**하다. 아래 예시는 `src/api` 기준이며,
-> Next 면 `src/api` 를 `lib/api` 로 바꿔 읽으면 된다.
+API 루트는 React에서 `src/api`, Next.js에서 `src/lib/api`다.
 
 리소스(도메인) 하나당 폴더 하나. 폴더명은 **소문자**(여러 단어는 kebab-case: `favorite-stores`).
 
 ```
-src/api/                      # (Next: lib/api/)
-├── instance.ts               # axios 인스턴스 (interceptor 포함)
+src/api/                      # Next.js: src/lib/api/
+├── instance.ts               # React: axios 인스턴스
 ├── index.ts                  # 모든 API 모듈 export
 └── user/                     # 리소스 폴더 (소문자)
-    ├── user.api.ts           # axios 호출 함수 (순수 함수)
+    ├── user.api.ts           # React: axios / Next.js: Server fetch 호출
+    ├── user.api.client.ts    # Next.js: Client 호출이 필요할 때만 생성
     ├── user.zod.ts           # 응답/요청 zod 스키마
     ├── user.type.ts          # zod 로부터 추론한 타입 + 입력 타입
     ├── user.service.ts       # react-query 훅 (use~) — 비즈니스 로직
@@ -51,6 +47,67 @@ src/api/                      # (Next: lib/api/)
 
 ---
 
+## Next.js 전용 규칙 — Server/Client 경계
+
+> 이 섹션의 **Next.js**는 프레임워크다. 문서의 **next(무한스크롤)**와는 관련이 없다.
+
+Next.js App Router는 API 코드를 생성하기 전에 실행 환경을 분류한다.
+
+| 환경 | 사용처 | 허용 의존성 |
+| --- | --- | --- |
+| Server | Server Component, Route Handler, Server Action | `cookies`, `headers`, 서버 토큰, `serverAuthHttp` |
+| Client | `'use client'`, React Query hook | 브라우저 API, `clientAuthHttp` |
+| 공용 | type, 순수 zod schema, 직렬화 가능한 상수 | 서버/브라우저 전용 의존성 없음 |
+
+### 공용 barrel에서 Server 모듈을 내보내지 않는다
+
+Client Component가 공용 `index.ts`를 가져올 때 그 barrel이 Server 모듈까지 export하면 다음 오류가 발생할 수 있다.
+
+```text
+This module cannot be imported from a Client Component module.
+It should only be used from a Server Component.
+```
+
+```ts
+// src/lib/api/http/index.ts
+export * from './httpBase';
+export * from './publicHttp';
+export * from './clientAuthHttp';
+// 금지: export * from './serverAuthHttp';
+```
+
+`serverAuthHttp`와 Server API는 barrel을 거치지 않고 절대경로로 직접 import한다.
+
+```ts
+import { serverAuthHttp } from '@/lib/api/http/serverAuthHttp';
+```
+
+- Server 파일은 가능하면 `import 'server-only';`로 경계를 표시한다.
+- 인증 호출은 Server를 기본으로 하고 Client에서도 호출해야 할 때만 `*.client.ts`를 만든다.
+- Client service는 Client 호출 파일만 import하며 Server 파일을 간접 참조하지 않는다.
+- `useQuery`/`useMutation`을 export하는 service는 Client 전용이다.
+- type과 zod schema만 Server/Client가 공유한다.
+
+### HTTP와 인증 컨텍스트를 분리한다
+
+- `serverAuthHttp`: 서버 쿠키·헤더·비공개 토큰 사용. 공용 barrel export 금지.
+- `clientAuthHttp`: 브라우저에 노출 가능한 인증 상태만 사용.
+- `publicHttp`: 양쪽에서 안전할 때만 공용 사용.
+- 기존 fetch wrapper를 먼저 찾는다. 없으면 자동 생성하지 말고 fetch/auth 방식을 사용자에게 묻는다.
+- `cookies()`/`headers()`는 모듈 최상위가 아니라 요청 함수 내부에서 호출한다.
+- 서버 비밀값에 `NEXT_PUBLIC_`을 붙이지 않는다.
+- 기존 Route Handler/BFF, base URL, CORS, Edge Runtime 정책을 확인하고 재사용한다.
+
+### 캐시와 전달 값을 구분한다
+
+- React Query 무효화는 Client 캐시만 갱신한다.
+- Next.js의 `fetch` cache/`next`, `revalidatePath`/`revalidateTag`, Cache Components는 기존 정책을 따른다.
+- 사용자별 인증 응답을 전역 캐시하지 않는다.
+- Server에서 Client로 응답 wrapper, `Headers`, `Error`, 함수 등을 전달하지 않고 JSON 직렬화 가능한 data만 전달한다.
+- Server Action은 요청받았거나 기존 프로젝트가 같은 패턴을 사용할 때만 만든다.
+
+---
+
 ## 1. 가장 먼저 — "next(무한스크롤)" 인지 판단하라
 
 > 여기서 말하는 "next" 는 **프레임워크 Next.js 가 아니라**, **커서 기반 무한스크롤 패턴**을 가리킨다.
@@ -76,13 +133,17 @@ src/api/                      # (Next: lib/api/)
 
 ### 2-1. `user.api.ts` — 순수 호출 함수
 
-- `import baseInstance from '../instance';` 사용 (axios 인스턴스).
-- 함수는 `async`, 내부에서 `const { data } = await baseInstance.X(...)` 후 `return data;`.
-- 응답 본문이 없는 경우(`204 No Content`) 는 `return data` 생략 가능.
-- 쿼리스트링은 `{ params }`, path 파라미터는 템플릿 리터럴.
+- React는 `baseInstance`(axios)를 사용한다.
+- Next.js는 Server 파일에서 기존 `serverAuthHttp`를 절대경로로 import한다. Client 호출이 필요할 때만
+  `*.client.ts`를 만들고 기존 `clientAuthHttp`를 사용한다. wrapper가 없으면 자동 생성하지 않는다.
+- React는 `const { data } = await baseInstance.X(...)` 후 `data`를 반환한다.
+- Next.js는 fetch wrapper의 generic에 응답 타입을 전달하고 JSON data를 반환받는다.
+- 쿼리스트링은 기존 wrapper 규칙(axios의 `{ params }`, fetch wrapper의 `searchParams` 등)을 따른다.
+  path 파라미터는 템플릿 리터럴을 사용한다.
 - **여기서는 zod 파싱을 하지 않는다.** (파싱은 service 의 queryFn 책임)
 
 ```ts
+// React
 import baseInstance from '../instance';
 
 const RESOURCE = '/api/user';
@@ -106,6 +167,18 @@ export const deleteUser = async (userId: string) => {
 };
 ```
 
+```ts
+// Next.js Server
+import { serverAuthHttp } from '@/lib/api/http/serverAuthHttp';
+import type { UserItem } from './user.type';
+
+const RESOURCE = '/api/user';
+
+export const getUser = async (userId: string) => {
+  return serverAuthHttp<UserItem>(`${RESOURCE}/${userId}`);
+};
+```
+
 ### 2-2. `user.zod.ts` — 스키마
 
 - `import { z } from 'zod';`
@@ -213,6 +286,7 @@ export const useDeleteUser = () => {
 ### 2-5. `index.ts` (리소스) — 노출
 
 - **`service` 와 `type` 만** 재노출 (`api`, `zod` 는 노출하지 않음).
+- Next.js에서는 Server 호출 파일을 Client가 접근 가능한 barrel에서 재노출하지 않는다.
 
 ```ts
 export * from './user.service';
@@ -230,6 +304,7 @@ export * from './user';
 
 ### 2-7. `src/api/instance.ts` — axios 인스턴스
 
+- React 전용 규칙이다.
 - 이미 있으면 **건드리지 않는다.** baseURL/interceptor 설정이 여기 모여 있다.
 - 새 리소스는 항상 이 `baseInstance` 를 import 해서 쓴다.
 
@@ -374,7 +449,7 @@ export const useGetUser = (options?: Record<string, any>) => {
 
 ## 7. 생성 시 체크리스트 ✅
 
-1. [ ] 위치를 맞췄다 (React `src/api` / Next `lib/api`).
+1. [ ] 위치를 맞췄다 (React `src/api` / Next.js `src/lib/api`).
 2. [ ] 엔드포인트가 **next(무한스크롤)** 인지 판단했다. (§1)
 3. [ ] `api / zod / type / service / index` 5파일을 모두 만들었다.
 4. [ ] Swagger 응답을 zod 로 정확히 매핑(nullable/optional/enum/date/$ref).
@@ -385,6 +460,8 @@ export const useGetUser = (options?: Record<string, any>) => {
 9. [ ] 리소스 `index.ts` + 루트 `index.ts` 노출 추가.
 10. [ ] next 면 `useInfiniteQuery` + `metaSchema` + `select` 평탄화 적용.
 11. [ ] 공용 유틸을 재사용하고, Swagger 에 없는 필드를 추측으로 만들지 않았다.
+12. [ ] Next.js면 Server/Client 환경을 분류하고 Server 모듈을 공용 barrel에서 내보내지 않았다.
+13. [ ] Next.js면 기존 fetch/auth wrapper와 캐시·runtime 정책을 확인했다.
 
 ---
 
@@ -397,4 +474,5 @@ export const useGetUser = (options?: Record<string, any>) => {
 - ❌ Swagger 의 `nullable` 무시하고 필수로 선언.
 - ❌ 일반 목록인데 `useInfiniteQuery` 사용 (또는 그 반대).
 - ❌ 공용 타입/유틸(`metaSchema`, `PaginationParams`)을 중복 재정의.
-- ❌ React 인데 `lib/api`, Next 인데 `src/api` 에 만드는 위치 실수.
+- ❌ React와 Next.js의 API 루트 또는 axios/fetch 규칙을 혼용.
+- ❌ Next.js 공용 `index.ts`에서 Server 전용 API나 `serverAuthHttp`를 export.