@xfilecom/xframe 0.1.34 → 0.1.36

package/bin/xframe.js

@@ -442,10 +442,9 @@ function executeDbPull(cwd) {
   return false;
 }
 
-/** 모노레포 템플릿 tsconfig 의 @xfilecom/front-core 경로 → 생성 앱의 node_modules 기준 */
-const TEMPLATE_FRONT_CORE_TS_PATH = '../../../../front-core/src/index.ts';
-const SCAFFOLD_FRONT_CORE_TS_PATH = '../../node_modules/@xfilecom/front-core';
-
+/**
+ * 구 스캐폴드 tsconfig 의 paths.@xfilecom/front-core 제거 → 설치된 패키지(node_modules) 기준 해석.
+ */
 function patchWebTsconfigFrontCorePath(targetRoot) {
   for (const sub of ['client', 'admin']) {
     const p = path.join(targetRoot, 'web', sub, 'tsconfig.json');
@@ -456,17 +455,20 @@ function patchWebTsconfigFrontCorePath(targetRoot) {
     } catch {
       continue;
     }
-    const arr = j?.compilerOptions?.paths?.['@xfilecom/front-core'];
-    if (Array.isArray(arr) && arr[0] === TEMPLATE_FRONT_CORE_TS_PATH) {
-      j.compilerOptions.paths['@xfilecom/front-core'] = [SCAFFOLD_FRONT_CORE_TS_PATH];
-      fs.writeFileSync(p, `${JSON.stringify(j, null, 2)}\n`, 'utf8');
+    const paths = j?.compilerOptions?.paths;
+    if (!paths || !Object.prototype.hasOwnProperty.call(paths, '@xfilecom/front-core')) {
+      continue;
+    }
+    delete paths['@xfilecom/front-core'];
+    if (Object.keys(paths).length === 0) {
+      delete j.compilerOptions.paths;
     }
+    fs.writeFileSync(p, `${JSON.stringify(j, null, 2)}\n`, 'utf8');
   }
 }
 
 /**
- * Vite 에서 @xfilecom/front-core 를 node_modules 패키지 "루트"만 alias 하면
- * `tokens.css` 같은 서브패스가 exports 를 타지 못해 깨짐 → alias 제거 후 npm 기본 해석.
+ * 구 템플릿 Vite 의 @xfilecom/front-core → 소스 디렉터리 alias 제거(npm 패키지·exports 사용).
  */
 function patchWebViteFrontCoreAlias(targetRoot) {
   for (const sub of ['client', 'admin']) {

package/defaults.json

@@ -1,4 +1,4 @@
 {
-  "backendCore": "^1.0.14",
-  "frontCore": "^0.2.20"
+  "backendCore": "^1.0.16",
+  "frontCore": "^0.2.22"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/xframe",
-  "version": "0.1.34",
+  "version": "0.1.36",
   "description": "Scaffold full-stack app: Nest + @xfilecom/backend-core, Vite/React + @xfilecom/front-core",
   "license": "UNLICENSED",
   "bin": {

package/template/README.md

@@ -25,7 +25,7 @@ Nest API (`@xfilecom/backend-core`) + Vite/React client·admin (`@xfilecom/front
 ## `shared/` (설정·스키마·SQL·endpoint)
 
 - **`shared/config/api`**, **`shared/config/web/client`**, **`shared/config/web/admin`**: YAML (`application.yml` + `application-<env>.yml`)
-- **`web/shared`**: `components`, `hooks`, `stores` (zustand), `methods`, `lib`, `types`, `constants`, `utils`
+- **`web/shared`**: `store/` (RootStore·session·cache), `params/` (ParamStore), `api/` (client·request·methods), `context/` (StoreProvider), `components`, `hooks`, `methods`, `lib`, `types`, `constants`, `utils`
 - **`shared/schema`**, **`shared/sql`**, **`shared/endpoint`**: 팀이 채우는 자산(README 참고)
 
 자세한 설명은 `shared/README.md` 참고.

package/template/apps/api/src/main.ts

@@ -5,7 +5,21 @@ import type { INestApplication } from '@nestjs/common';
 import { AppModule } from './app.module';
 import { appConfig } from './config.loader';
 
-function applyCors(app: INestApplication): void {
+function parsePositivePort(v: string | number | undefined): number | undefined {
+  const n = typeof v === 'number' ? v : Number(v);
+  return Number.isFinite(n) && n > 0 ? n : undefined;
+}
+
+/** `PORT`(syncEnvKeys) → `server.port`(YAML) → 기본값 */
+function resolveListenPort(): number {
+  return (
+    parsePositivePort(process.env.PORT) ??
+    parsePositivePort(appConfig.server?.port) ??
+    3000
+  );
+}
+
+function applyCorsFromConfig(app: INestApplication): void {
   const cors = appConfig.cors;
   if (cors?.enabled === false) {
     return;
@@ -19,26 +33,52 @@ function applyCors(app: INestApplication): void {
   app.enableCors({ origin: origin === true, credentials });
 }
 
-function applyHttp(app: INestApplication): void {
+function applyHttpFromConfig(app: INestApplication): void {
   const prefix = appConfig.http?.globalPrefix;
   if (prefix != null && String(prefix).trim() !== '') {
     app.setGlobalPrefix(String(prefix).replace(/^\/+|\/+$/g, ''));
   }
 }
 
+/**
+ * Nest 인스턴스에 직접 걸 수 있는 설정만 반영합니다.
+ * - DB 연결·JWT·인터셉터 등: `config.loader`의 syncEnvKeys + `AppModule`(CoreModule)
+ */
+function applyNestAppFromConfig(app: INestApplication): void {
+  applyCorsFromConfig(app);
+  applyHttpFromConfig(app);
+}
+
+function logStartupFromConfig(port: number): void {
+  const base = appConfig.http?.publicBaseUrl?.replace(/\/$/, '');
+  const pfx = appConfig.http?.globalPrefix
+    ? `/${String(appConfig.http.globalPrefix).replace(/^\/+|\/+$/g, '')}`
+    : '';
+  const env =
+    process.env.APP_ENV ??
+    appConfig.app?.env ??
+    process.env.NODE_ENV ??
+    'development';
+  const dbOn = appConfig.core?.database?.auto === true;
+  const dbHost = appConfig.database?.host;
+  const dbName = appConfig.database?.name;
+  const jwtGuard = appConfig.core?.guards?.jwt === true;
+  const sqlEp = appConfig.core?.sqlEndpoint?.enabled === true;
+  // eslint-disable-next-line no-console
+  console.log(
+    `[api] listen :${port} env=${env}` +
+      (base ? ` public=${base}${pfx}` : '') +
+      ` cors=${appConfig.cors?.enabled !== false ? 'on' : 'off'}` +
+      ` db=${dbOn ? 'auto' : 'off'}${dbHost ? `@${dbHost}` : ''}${dbName ? `/${dbName}` : ''}` +
+      ` jwtGuard=${jwtGuard} sqlEndpoint=${sqlEp}`,
+  );
+}
+
 async function bootstrap() {
   const app = await NestFactory.create(AppModule);
-  applyCors(app);
-  applyHttp(app);
-  const port = Number(process.env.PORT) || 3000;
-  const base = appConfig.http?.publicBaseUrl?.replace(/\/$/, '');
+  applyNestAppFromConfig(app);
+  const port = resolveListenPort();
   await app.listen(port);
-  if (base) {
-    const pfx = appConfig.http?.globalPrefix
-      ? `/${String(appConfig.http.globalPrefix).replace(/^\/+|\/+$/g, '')}`
-      : '';
-    // eslint-disable-next-line no-console
-    console.log(`Listening ${base}${pfx} (port ${port})`);
-  }
+  logStartupFromConfig(port);
 }
 bootstrap();

package/template/shared/endpoint/README.md

@@ -1,4 +1,33 @@
 # Endpoint / API 계약
 
-- OpenAPI `openapi.yaml`, 공유 요청·응답 타입, 라우트 prefix 규칙 등을 둡니다.
+- **`endpoint.ts`** — `EndpointDef`, `HttpMethod`, 엔드포인트 상수(예: `healthEndpoint`). 프론트 `sendRequest`·백엔드 라우트와 동일 경로를 맞출 때 사용합니다.
+
+### `EndpointDef` 필드 요약
+
+| 필드 | Nest | 프론트 |
+|------|------|--------|
+| `method`, `path` | 라우트와 맞추기 | `sendRequest` URL·HTTP 메서드 |
+| `post` | 무시 | **응답 본문**(`axios`의 `response.data`와 동일 한 덩어리)만 인자로 받아 가공 후 반환 |
+| `showIndicator` | 무시 | `sendMessage` 시 옵션 미지정이면 전역 로딩 기본값 |
+| `timeoutMs` | 무시 | 해당 요청만 axios `timeout` |
+
+**응답 가공**은 엔드포인트 단위 `post` 와, `web/shared` 의 `ApiMethodConfig`·`RootStore.execute` 의 `unwrapDataArray` / `post(result, stores)` 를 함께 쓸 수 있습니다. 같은 데이터를 두 번 벗기지 않도록 한쪽만 쓰는 것을 권장합니다.
+
+`post` 예시 — 인자는 **HTTP 본문 JSON**이지, axios `Response` 객체가 아닙니다.
+
+```ts
+import { unwrapResponseData, type EndpointDef } from '@shared/endpoint';
+
+export const itemEndpoint: EndpointDef = {
+  method: 'GET',
+  path: '/items/:id',
+  post: unwrapResponseData, // 또는 (body) => (body as { data: Item }).data
+  showIndicator: true,
+  timeoutMs: 10_000,
+};
+```
+
+- OpenAPI `openapi.yaml`, 공유 요청·응답 타입, 라우트 prefix 규칙 등도 이 디렉터리·형제 파일에 둘 수 있습니다.
 - 실제 Nest `Controller`는 `apps/api/src`에 두고, 여기서는 **계약·문서**를 단일 소스로 유지하는 패턴을 권장합니다.
+
+임포트: `import { healthEndpoint, type EndpointDef } from '@shared/endpoint';`

package/template/shared/endpoint/endpoint.ts

@@ -0,0 +1,55 @@
+/**
+ * HTTP API 엔드포인트 정의 — Nest(`@shared/*`)와 Vite(`@shared/*` alias) 공통.
+ * `web/` 옆 루트 `shared/endpoint/` 에 두어 백엔드 라우트·프론트 axios 경로를 한곳에서 맞춥니다.
+ *
+ * Nest 는 주로 `method`·`path` 만 쓰고, `post`·`showIndicator`·`timeoutMs` 등은 프론트 `sendRequest` / RootStore `sendMessage` 가 참고합니다.
+ */
+
+export type HttpMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+
+/**
+ * 백엔드 `CommonResponseDto` 류 `{ data: T, code?, error? }` 에서 `data` 만 꺼냄.
+ * 해당 필드가 없으면 본문 그대로 반환.
+ */
+export function unwrapResponseData(body: unknown): unknown {
+  if (body !== null && typeof body === 'object' && 'data' in body) {
+    return (body as { data: unknown }).data;
+  }
+  return body;
+}
+
+export interface EndpointDef {
+  method: HttpMethod;
+  /** 상대 경로. `:id` 는 sendRequest 의 params 로 치환 */
+  path: string;
+
+  /**
+   * axios 가 파싱한 **응답 본문**(`response.data`)만 넘어옵니다. AxiosResponse 전체가 아닙니다.
+   * `{ data: T }` 언래핑은 `unwrapResponseData` 또는 `(body) => (body as { data: T }).data` 패턴을 쓰세요.
+   */
+  post?: (body: unknown) => unknown;
+
+  /**
+   * RootStore.sendMessage 에서 `options.showIndicator` 가 없을 때 기본값.
+   * `sendRequest` 직호출 시에는 axios 훅만 쓰므로 이 필드는 무시됩니다.
+   */
+  showIndicator?: boolean;
+
+  /** 이 요청만 다른 타임아웃(ms). 미설정 시 apiClient 기본값 */
+  timeoutMs?: number;
+}
+
+export const healthEndpoint: EndpointDef = {
+  method: 'GET',
+  path: '/health',
+  /** health 는 인디케이터 없이 조용히 호출하는 경우가 많음 */
+  showIndicator: false,
+};
+
+export const appMetaEndpoint: EndpointDef = {
+  method: 'GET',
+  path: '/app-meta',
+  post: unwrapResponseData,
+  showIndicator: false,
+  timeoutMs: 10_000,
+};

package/template/shared/endpoint/index.ts

@@ -0,0 +1,2 @@
+export type { HttpMethod, EndpointDef } from './endpoint';
+export { healthEndpoint, appMetaEndpoint, unwrapResponseData } from './endpoint';

package/template/web/admin/src/App.tsx

@@ -1,15 +1,10 @@
 import { Badge, Text } from '@xfilecom/front-core';
-import {
-  Shell,
-  useHealthStatus,
-  FALLBACK_API_BASE_URL,
-} from '__WEB_SHARED_WORKSPACE__';
+import { Shell, useHealthStatus } from '__WEB_SHARED_WORKSPACE__';
 
-const apiBase = import.meta.env.VITE_API_BASE_URL || FALLBACK_API_BASE_URL;
 const title = import.meta.env.VITE_APP_TITLE || '__PACKAGE_NAME__ (admin)';
 
 export function App() {
-  const { text, error } = useHealthStatus(apiBase);
+  const { text, error } = useHealthStatus();
 
   return (
     <Shell

package/template/web/admin/src/main.tsx

@@ -4,10 +4,21 @@ import '@xfilecom/front-core/tokens.css';
 import '@xfilecom/front-core/base.css';
 import '__WEB_SHARED_WORKSPACE__/styles/xfc-theme.css';
 import '__WEB_SHARED_WORKSPACE__/styles/app.css';
+import {
+  StoreProvider,
+  configureApi,
+  FALLBACK_API_BASE_URL,
+} from '__WEB_SHARED_WORKSPACE__';
 import { App } from './App';
 
+configureApi({
+  baseURL: import.meta.env.VITE_API_BASE_URL || FALLBACK_API_BASE_URL,
+});
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
-    <App />
+    <StoreProvider>
+      <App />
+    </StoreProvider>
   </React.StrictMode>,
 );

package/template/web/admin/tsconfig.json

@@ -10,7 +10,7 @@
     "paths": {
       "__WEB_SHARED_WORKSPACE__": ["../shared/src/index.ts"],
       "__WEB_SHARED_WORKSPACE__/*": ["../shared/src/*"],
-      "@xfilecom/front-core": ["../../../../front-core/src/index.ts"]
+      "@shared/*": ["../../shared/*"]
     },
     "allowImportingTsExtensions": true,
     "resolveJsonModule": true,

package/template/web/admin/vite.config.ts

@@ -7,13 +7,8 @@ import react from '@vitejs/plugin-react';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-/**
- * xframe 레포 안 템플릿: …/packages/xframe/packages/front-core/src
- * (`npx @xfilecom/xframe <dir>` 생성 시 CLI 가 front-core alias·const 를 제거 → npm exports 로 해석)
- */
-const frontCoreSrc = path.resolve(__dirname, '../../../..', 'front-core', 'src');
-
 const webSharedSrc = path.resolve(__dirname, '../shared/src');
+const rootSharedSrc = path.resolve(__dirname, '../../shared');
 
 function readYaml(file: string): Record<string, unknown> {
   if (!existsSync(file)) return {};
@@ -69,7 +64,7 @@ export default defineConfig(({ mode }) => {
     plugins: [react()],
     resolve: {
       alias: {
-        '@xfilecom/front-core': frontCoreSrc,
+        '@shared': rootSharedSrc,
         '__WEB_SHARED_WORKSPACE__': webSharedSrc,
       },
     },

package/template/web/client/src/App.tsx

@@ -1,20 +1,15 @@
 import { useState } from 'react';
 import { Badge, Button, Stack, Text } from '@xfilecom/front-core';
-import {
-  Shell,
-  useHealthStatus,
-  FALLBACK_API_BASE_URL,
-} from '__WEB_SHARED_WORKSPACE__';
+import { Shell, useHealthStatus } from '__WEB_SHARED_WORKSPACE__';
 import { FrontCoreShowcase } from './FrontCoreShowcase';
 
-const apiBase = import.meta.env.VITE_API_BASE_URL || FALLBACK_API_BASE_URL;
 const title = import.meta.env.VITE_APP_TITLE || '__PACKAGE_NAME__';
 
 type Tab = 'api' | 'atoms';
 
 export function App() {
   const [tab, setTab] = useState<Tab>('atoms');
-  const { text, error } = useHealthStatus(apiBase);
+  const { text, error } = useHealthStatus();
 
   return (
     <Shell

package/template/web/client/src/main.tsx

@@ -4,10 +4,21 @@ import '@xfilecom/front-core/tokens.css';
 import '@xfilecom/front-core/base.css';
 import '__WEB_SHARED_WORKSPACE__/styles/xfc-theme.css';
 import '__WEB_SHARED_WORKSPACE__/styles/app.css';
+import {
+  StoreProvider,
+  configureApi,
+  FALLBACK_API_BASE_URL,
+} from '__WEB_SHARED_WORKSPACE__';
 import { App } from './App';
 
+configureApi({
+  baseURL: import.meta.env.VITE_API_BASE_URL || FALLBACK_API_BASE_URL,
+});
+
 ReactDOM.createRoot(document.getElementById('root')!).render(
   <React.StrictMode>
-    <App />
+    <StoreProvider>
+      <App />
+    </StoreProvider>
   </React.StrictMode>,
 );

package/template/web/client/tsconfig.json

@@ -10,7 +10,7 @@
     "paths": {
       "__WEB_SHARED_WORKSPACE__": ["../shared/src/index.ts"],
       "__WEB_SHARED_WORKSPACE__/*": ["../shared/src/*"],
-      "@xfilecom/front-core": ["../../../../front-core/src/index.ts"]
+      "@shared/*": ["../../shared/*"]
     },
     "allowImportingTsExtensions": true,
     "resolveJsonModule": true,

package/template/web/client/vite.config.ts

@@ -7,15 +7,12 @@ import react from '@vitejs/plugin-react';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 
-/**
- * xframe 레포 안 템플릿: …/packages/xframe/packages/front-core/src
- * (`npx @xfilecom/xframe <dir>` 생성 시 CLI 가 front-core alias·const 를 제거 → npm exports 로 해석)
- */
-const frontCoreSrc = path.resolve(__dirname, '../../../..', 'front-core', 'src');
-
 /** file:../shared 복사본이 아닌 워크스페이스 web/shared/src (플레이스홀더 패키지 이름과 동일 키) */
 const webSharedSrc = path.resolve(__dirname, '../shared/src');
 
+/** 루트 `shared/` — `web/` 과 동일 레벨 (엔드포인트·스키마 등) */
+const rootSharedSrc = path.resolve(__dirname, '../../shared');
+
 function readYaml(file: string): Record<string, unknown> {
   if (!existsSync(file)) return {};
   const parsed = yaml.load(readFileSync(file, 'utf8'));
@@ -70,7 +67,7 @@ export default defineConfig(({ mode }) => {
     plugins: [react()],
     resolve: {
       alias: {
-        '@xfilecom/front-core': frontCoreSrc,
+        '@shared': rootSharedSrc,
         '__WEB_SHARED_WORKSPACE__': webSharedSrc,
       },
     },

package/template/web/shared/README.md

@@ -24,16 +24,15 @@ import { Shell } from '__WEB_SHARED_WORKSPACE__';
 
 새 파일을 앱에서 가져오려면 `package.json`의 **`exports`**에 서브패스를 추가하세요.
 
-## `@xfilecom/front-core`를 모노레포에서 고치는 경우
+## `@xfilecom/front-core`
 
-`web/client`·`web/admin`의 **Vite `resolve.alias`**가 형제 디렉터리의 `front-core/src`(xframe 모노레포 기준 `packages/front-core/src`)를 가리키도록 되어 있으면, npm `dist/`가 아니라 **로컬 소스**가 번들됩니다. dev 중 HMR로 반영되는 것이 정상입니다.
+`web/client`·`web/admin`·`web/shared`는 **`package.json` 의존성 + `node_modules`** 로 해석합니다(`tsconfig`·Vite에 `paths`/alias로 소스 경로를 강제하지 않음). 서브패스(`tokens.css` 등)는 패키지 `exports`를 따릅니다.
 
-스캐폴드만 복사한 프로젝트처럼 그 경로가 없으면 alias가 깨지므로, `package.json`의 `@xfilecom/front-core` 버전과 `npm run build`(해당 패키지)로 갱신하세요.
+로컬에서 코어 소스를 쓰려면 **`npm link @xfilecom/front-core`** 또는 `package.json`의 `file:../front-core` / `workspace:` 등으로 **설치 위치**를 바꾸는 방식을 권장합니다.
 
 ### `web/shared/tsconfig.json`에는 `paths`로 front-core를 붙이지 마세요
 
-`rootDir`가 `src`인데 `@xfilecom/front-core`를 `../../../.../front-core/src`로 매핑하면, TypeScript가 **rootDir 밖 소스**를 끌어와 `File is not under 'rootDir'` 오류가 납니다.  
-`web/shared` 패키지 타입체크는 **`node_modules`의 `@xfilecom/front-core`**에 맡기고, 로컬 소스 번들은 위 **Vite alias**(client/admin)만 사용하면 됩니다.
+`rootDir` 밖 소스를 끌어오면 `tsc`·에디터가 깨지기 쉽습니다. 타입은 **`node_modules/@xfilecom/front-core`**에 맡깁니다.
 
 ### `web/shared` CSS·TS가 수정해도 반영되지 않을 때
 

package/template/web/shared/package.json

@@ -19,7 +19,9 @@
   },
   "dependencies": {
     "@xfilecom/front-core": "__FRONT_CORE_SPEC__",
-    "zustand": "^5.0.3"
+    "axios": "^1.7.9",
+    "mobx": "^6.13.5",
+    "mobx-react-lite": "^4.0.7"
   },
   "peerDependencies": {
     "react": "^18.0.0",

package/template/web/shared/src/api/client.ts

@@ -0,0 +1,132 @@
+/**
+ * Axios — baseURL, 로깅 인터셉터, 전역 훅(onRequestStart/End), Bearer
+ */
+
+import axios, {
+  type AxiosError,
+  type AxiosResponse,
+  type InternalAxiosRequestConfig,
+} from 'axios';
+import { sessionStore } from '../store/session-store';
+
+const LOG_PREFIX = '[xframe/http]';
+
+export type OnRequestStart = () => void;
+export type OnRequestEnd = () => void;
+export type OnError = (message: string, code?: string | number) => void;
+
+let onRequestStart: OnRequestStart = () => {};
+let onRequestEnd: OnRequestEnd = () => {};
+let onError: OnError = () => {};
+
+export function setApiHooks(hooks: {
+  onRequestStart?: OnRequestStart;
+  onRequestEnd?: OnRequestEnd;
+  onError?: OnError;
+}) {
+  if (hooks.onRequestStart) onRequestStart = hooks.onRequestStart;
+  if (hooks.onRequestEnd) onRequestEnd = hooks.onRequestEnd;
+  if (hooks.onError) onError = hooks.onError;
+}
+
+export const apiClient = axios.create({
+  timeout: 30_000,
+  headers: { 'Content-Type': 'application/json', Accept: 'application/json' },
+});
+
+export function configureApi(options: { baseURL: string }) {
+  apiClient.defaults.baseURL = options.baseURL.replace(/\/$/, '');
+}
+
+export function getApiBaseUrl(): string {
+  return apiClient.defaults.baseURL ?? '';
+}
+
+type ExtConfig = InternalAxiosRequestConfig & { skipGlobalIndicator?: boolean };
+
+function logRequest(config: InternalAxiosRequestConfig) {
+  console.log(`${LOG_PREFIX} request`, {
+    method: config.method?.toUpperCase(),
+    url: config.url,
+    baseURL: config.baseURL,
+    params: config.params,
+    data: config.data,
+    headers: config.headers,
+  });
+}
+
+function logResponseSuccess(response: AxiosResponse) {
+  console.log(`${LOG_PREFIX} response`, {
+    status: response.status,
+    statusText: response.statusText,
+    url: response.config.url,
+    data: response.data,
+  });
+}
+
+function logResponseError(error: unknown) {
+  if (axios.isAxiosError(error)) {
+    console.log(`${LOG_PREFIX} response error`, {
+      message: error.message,
+      code: error.code,
+      status: error.response?.status,
+      statusText: error.response?.statusText,
+      url: error.config?.url,
+      data: error.response?.data,
+    });
+  } else {
+    console.log(`${LOG_PREFIX} response error`, error);
+  }
+}
+
+apiClient.interceptors.request.use(
+  (config: InternalAxiosRequestConfig) => {
+    logRequest(config);
+    const c = config as ExtConfig;
+    const token = sessionStore.token;
+    if (token && c.headers) {
+      c.headers.Authorization = `Bearer ${token}`;
+    }
+    if (c.data instanceof FormData && c.headers) {
+      delete c.headers['Content-Type'];
+    }
+    if (!c.skipGlobalIndicator) onRequestStart();
+    return c;
+  },
+  (err) => {
+    console.log(`${LOG_PREFIX} request error`, err);
+    return Promise.reject(err);
+  },
+);
+
+apiClient.interceptors.response.use(
+  (response: AxiosResponse) => {
+    const c = response.config as ExtConfig;
+    if (!c.skipGlobalIndicator) onRequestEnd();
+    logResponseSuccess(response);
+    return response;
+  },
+  (err: AxiosError) => {
+    const c = err.config as ExtConfig | undefined;
+    if (!c?.skipGlobalIndicator) onRequestEnd();
+    logResponseError(err);
+    const res = err?.response as
+      | { data?: { message?: unknown; error?: unknown; code?: string | number }; status?: number }
+      | undefined;
+    const raw = res?.data?.message ?? res?.data?.error ?? (err as Error)?.message ?? 'Request failed';
+    const message =
+      typeof raw === 'string'
+        ? raw
+        : Array.isArray(raw)
+          ? raw.map((x) => (typeof x === 'string' ? x : String(x))).join(', ')
+          : typeof raw === 'object' &&
+              raw != null &&
+              'message' in raw &&
+              typeof (raw as { message: unknown }).message === 'string'
+            ? (raw as { message: string }).message
+            : JSON.stringify(raw);
+    const code = res?.status ?? (res?.data?.code as string | number | undefined);
+    onError(message, code);
+    return Promise.reject(err);
+  },
+);

package/template/web/shared/src/api/methods/health.method.ts

@@ -0,0 +1,14 @@
+import type { CommonEnvelope, HealthData } from '../../types/api';
+import type { ApiMethodConfig, ApiMethodStore } from '../types';
+import { healthEndpoint } from '@shared/endpoint';
+
+/** GET /health — params·body 없음, 스토어는 validate/post 에서 사용 가능 */
+export const healthMethod: ApiMethodConfig<void, CommonEnvelope<HealthData>, ApiMethodStore> = {
+  schema: {},
+  endpoint: healthEndpoint,
+  ui: {
+    showIndicator: false,
+    showErrorToast: true,
+    unwrapDataArray: false,
+  },
+};

package/template/web/shared/src/api/methods/index.ts

@@ -0,0 +1,31 @@
+/**
+ * 화면별 workflow registry — 새 method 는 *.method.ts 추가 후 여기 등록
+ */
+
+import type { ParamsSchema } from '../../params/types';
+import { healthMethod } from './health.method';
+
+export type {
+  ApiMethodConfig,
+  ApiMethodStore,
+  ApiMethodEndpointCall,
+  CoreSdkWrapped,
+  ExecuteContext,
+  ApiMethodUiConfig,
+  ScreenMeta,
+  ScreenAuthType,
+} from '../types';
+
+export const methods = {
+  health: healthMethod,
+} as const;
+
+/** ParamStore 초기 스키마 — 화면명 → 필드 → value + valid 규칙 */
+export const screenParamSchemas: ParamsSchema = {
+  /** 예시: 검색어 (선택) — execute 전 validate 에서 isScreenValid 로 검사 가능 */
+  demo: {
+    q: { value: '', valid: [] },
+  },
+};
+
+export type MethodName = keyof typeof methods;