@xfilecom/xframe 0.1.36 → 0.1.38

package/defaults.json

@@ -1,4 +1,4 @@
 {
-  "backendCore": "^1.0.16",
-  "frontCore": "^0.2.22"
+  "backendCore": "^1.0.18",
+  "frontCore": "^0.2.24"
 }

package/package.json

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

package/template/shared/endpoint/endpoint.ts

@@ -44,12 +44,13 @@ export const healthEndpoint: EndpointDef = {
   path: '/health',
   /** health 는 인디케이터 없이 조용히 호출하는 경우가 많음 */
   showIndicator: false,
+  post: unwrapResponseData,
 };
 
 export const appMetaEndpoint: EndpointDef = {
   method: 'GET',
   path: '/app-meta',
-  post: unwrapResponseData,
+  /** 공통 `{ code, data, error }` 는 axios 인터셉터에서 `data` 로 치환 */
   showIndicator: false,
   timeoutMs: 10_000,
 };

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

@@ -1,10 +1,10 @@
 import { Badge, Text } from '@xfilecom/front-core';
-import { Shell, useHealthStatus } from '__WEB_SHARED_WORKSPACE__';
+import { safeJsonStringify, Shell, useHealthStatus } from '__WEB_SHARED_WORKSPACE__';
 
 const title = import.meta.env.VITE_APP_TITLE || '__PACKAGE_NAME__ (admin)';
 
 export function App() {
-  const { text, error } = useHealthStatus();
+  const { data } = useHealthStatus();
 
   return (
     <Shell
@@ -18,15 +18,9 @@ export function App() {
         </>
       }
     >
-      {error ? (
-        <Text as="pre" variant="body" style={{ color: 'var(--xfc-warning)', margin: 0, whiteSpace: 'pre-wrap' }}>
-          {error}
-        </Text>
-      ) : (
-        <Text as="pre" variant="small" style={{ margin: 0, overflow: 'auto' }}>
-          {text}
-        </Text>
-      )}
+      <Text as="pre" variant="small" style={{ margin: 0, overflow: 'auto' }}>
+        {data != null ? safeJsonStringify(data, 2) : '—'}
+      </Text>
     </Shell>
   );
 }

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

@@ -1,6 +1,6 @@
 import { useState } from 'react';
 import { Badge, Button, Stack, Text } from '@xfilecom/front-core';
-import { Shell, useHealthStatus } from '__WEB_SHARED_WORKSPACE__';
+import { safeJsonStringify, Shell, useHealthStatus } from '__WEB_SHARED_WORKSPACE__';
 import { FrontCoreShowcase } from './FrontCoreShowcase';
 
 const title = import.meta.env.VITE_APP_TITLE || '__PACKAGE_NAME__';
@@ -9,7 +9,7 @@ type Tab = 'api' | 'atoms';
 
 export function App() {
   const [tab, setTab] = useState<Tab>('atoms');
-  const { text, error } = useHealthStatus();
+  const { data } = useHealthStatus();
 
   return (
     <Shell
@@ -44,13 +44,9 @@ export function App() {
 
         {tab === 'atoms' ? (
           <FrontCoreShowcase />
-        ) : error ? (
-          <Text as="pre" variant="body" style={{ color: 'var(--xfc-warning)', margin: 0, whiteSpace: 'pre-wrap' }}>
-            {error}
-          </Text>
         ) : (
           <Text as="pre" variant="small" style={{ margin: 0, overflow: 'auto' }}>
-            {text}
+            {data != null ? safeJsonStringify(data, 2) : '—'}
           </Text>
         )}
       </Stack>

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

@@ -1,5 +1,6 @@
 /**
  * Axios — baseURL, 로깅 인터셉터, 전역 훅(onRequestStart/End), Bearer
+ * HTTP 200/201 본문이 `{ code, data, error }` 이면 code 검사 후 data 로 치환 또는 토스트+reject
  */
 
 import axios, {
@@ -8,25 +9,43 @@ import axios, {
   type InternalAxiosRequestConfig,
 } from 'axios';
 import { sessionStore } from '../store/session-store';
+import {
+  applyCommonResponseEnvelope,
+  CommonResponseRejectedError,
+  formatCommonErrorField,
+  isCommonResponsePayload,
+} from './commonResponse';
 
 const LOG_PREFIX = '[xframe/http]';
 
 export type OnRequestStart = () => void;
 export type OnRequestEnd = () => void;
 export type OnError = (message: string, code?: string | number) => void;
+export type OnCommonBusinessError = (message: string, appCode: number) => void;
 
 let onRequestStart: OnRequestStart = () => {};
 let onRequestEnd: OnRequestEnd = () => {};
 let onError: OnError = () => {};
+let onCommonBusinessError: OnCommonBusinessError = () => {};
+
+export { CommonResponseRejectedError } from './commonResponse';
+export {
+  COMMON_RESPONSE_SUCCESS_CODE,
+  formatCommonErrorField,
+  isCommonResponsePayload,
+} from './commonResponse';
 
 export function setApiHooks(hooks: {
   onRequestStart?: OnRequestStart;
   onRequestEnd?: OnRequestEnd;
   onError?: OnError;
+  /** HTTP 정상(2xx)인데 body.code !== 0 일 때 (토스트 등) */
+  onCommonBusinessError?: OnCommonBusinessError;
 }) {
   if (hooks.onRequestStart) onRequestStart = hooks.onRequestStart;
   if (hooks.onRequestEnd) onRequestEnd = hooks.onRequestEnd;
   if (hooks.onError) onError = hooks.onError;
+  if (hooks.onCommonBusinessError) onCommonBusinessError = hooks.onCommonBusinessError;
 }
 
 export const apiClient = axios.create({
@@ -56,11 +75,13 @@ function logRequest(config: InternalAxiosRequestConfig) {
 }
 
 function logResponseSuccess(response: AxiosResponse) {
+  const body = response.data;
+  const data = isCommonResponsePayload(body) ? body.data : body;
   console.log(`${LOG_PREFIX} response`, {
     status: response.status,
     statusText: response.statusText,
     url: response.config.url,
-    data: response.data,
+    data,
   });
 }
 
@@ -104,28 +125,37 @@ apiClient.interceptors.response.use(
     const c = response.config as ExtConfig;
     if (!c.skipGlobalIndicator) onRequestEnd();
     logResponseSuccess(response);
+    try {
+      applyCommonResponseEnvelope(response, onCommonBusinessError);
+    } catch (e) {
+      return Promise.reject(e);
+    }
     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 resData = err.response?.data;
+    let raw: unknown =
+      isCommonResponsePayload(resData) ? resData.error : undefined;
+    if (raw === undefined) {
+      raw =
+        (err.response?.data as { message?: unknown; error?: unknown } | undefined)?.message ??
+        (err.response?.data as { message?: unknown; error?: unknown } | undefined)?.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);
+          : formatCommonErrorField(raw);
+    const code =
+      err.response?.status ??
+      (isCommonResponsePayload(resData) ? resData.code : undefined) ??
+      (err.response?.data as { code?: string | number } | undefined)?.code;
     onError(message, code);
     return Promise.reject(err);
   },

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

@@ -0,0 +1,80 @@
+/**
+ * 서버 공통 본문: HTTP 200/201 + body `{ code, data, error }`
+ * — 비즈니스 실패는 code !== 0 (HTTP는 정상).
+ */
+
+import type { AxiosResponse } from 'axios';
+
+/** 백엔드와 동일한 “성공” 코드 */
+export const COMMON_RESPONSE_SUCCESS_CODE = 0 as const;
+
+export class CommonResponseRejectedError extends Error {
+  readonly appCode: number;
+  readonly payload: unknown;
+
+  constructor(message: string, appCode: number, payload: unknown) {
+    super(message);
+    this.name = 'CommonResponseRejectedError';
+    this.appCode = appCode;
+    this.payload = payload;
+  }
+}
+
+export function isCommonResponsePayload(
+  body: unknown,
+): body is { code: number; data: unknown; error?: unknown } {
+  if (body === null || typeof body !== 'object') return false;
+  const b = body as Record<string, unknown>;
+  return typeof b.code === 'number' && 'data' in b;
+}
+
+function extractMessageString(value: unknown): string | null {
+  if (value == null) return null;
+  if (typeof value === 'string') return value;
+  if (Array.isArray(value)) {
+    const first = value.find((x) => typeof x === 'string');
+    return first ?? (value.map((x) => (typeof x === 'string' ? x : String(x))).join(', ') || null);
+  }
+  if (typeof value === 'object' && 'message' in value) {
+    const inner = (value as { message: unknown }).message;
+    return extractMessageString(inner);
+  }
+  return null;
+}
+
+/** `error` 필드를 사용자용 문구로 */
+export function formatCommonErrorField(error: unknown): string {
+  const extracted = extractMessageString(error);
+  if (extracted) return extracted;
+  if (typeof error === 'string') return error;
+  if (error != null && typeof error === 'object') {
+    try {
+      return JSON.stringify(error);
+    } catch {
+      return 'Request failed';
+    }
+  }
+  return 'Request failed';
+}
+
+export type OnCommonBusinessError = (message: string, appCode: number) => void;
+
+/**
+ * 성공 인터셉터에서 호출: 공통 래핑이면 code 검사 후 data 로 치환하거나 reject.
+ */
+export function applyCommonResponseEnvelope(
+  response: AxiosResponse,
+  onBusinessError: OnCommonBusinessError,
+): unknown {
+  const body = response.data;
+  if (!isCommonResponsePayload(body)) {
+    return response;
+  }
+  if (body.code !== COMMON_RESPONSE_SUCCESS_CODE) {
+    const msg = formatCommonErrorField(body.error);
+    onBusinessError(msg, body.code);
+    throw new CommonResponseRejectedError(msg, body.code, body);
+  }
+  response.data = body.data;
+  return response;
+}

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

@@ -1,9 +1,9 @@
-import type { CommonEnvelope, HealthData } from '../../types/api';
+import type { 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> = {
+export const healthMethod: ApiMethodConfig<void, HealthData, ApiMethodStore> = {
   schema: {},
   endpoint: healthEndpoint,
   ui: {

package/template/web/shared/src/context/StoreProvider.tsx

@@ -1,9 +1,13 @@
 /**
  * RootStore 컨텍스트 — useStore / useParamStore / useSendMessage 등
  * (싱글톤 rootStore 이므로 Provider 없이도 rootStore 직접 import 가능)
+ *
+ * 최상위 레이어: HTTP 로딩 바(`indicator`) · `rootStore.toasts` → ToastList
  */
 
 import React, { createContext, useCallback, useContext } from 'react';
+import { ToastList } from '@xfilecom/front-core';
+import { observer } from 'mobx-react-lite';
 import type { EndpointDef } from '@shared/endpoint';
 import type { SendMessageOptions } from '../types/ui';
 import { rootStore } from '../store/root-store';
@@ -12,6 +16,34 @@ type RootStoreApi = typeof rootStore;
 
 const StoreContext = createContext<RootStoreApi | null>(null);
 
+const GlobalHttpIndicatorView = observer(function GlobalHttpIndicatorView() {
+  if (!rootStore.indicator.loading) return null;
+  return (
+    <div
+      className="xfc-global-http-indicator"
+      role="progressbar"
+      aria-busy="true"
+      aria-label="Loading"
+    />
+  );
+});
+
+const GlobalToastStackView = observer(function GlobalToastStackView() {
+  const entries = rootStore.toasts.map((t) => ({
+    id: t.id,
+    severity: t.severity,
+    message: t.message,
+  }));
+  return (
+    <ToastList
+      toasts={entries}
+      onDismiss={(id) => {
+        rootStore.removeToast(id);
+      }}
+    />
+  );
+});
+
 export function useStore(): RootStoreApi {
   const ctx = useContext(StoreContext);
   if (!ctx) throw new Error('StoreProvider is required');
@@ -19,7 +51,13 @@ export function useStore(): RootStoreApi {
 }
 
 export function StoreProvider({ children }: { children: React.ReactNode }) {
-  return <StoreContext.Provider value={rootStore}>{children}</StoreContext.Provider>;
+  return (
+    <StoreContext.Provider value={rootStore}>
+      <GlobalHttpIndicatorView />
+      <GlobalToastStackView />
+      {children}
+    </StoreContext.Provider>
+  );
 }
 
 export function useSendMessage() {

package/template/web/shared/src/hooks/useAppStore.ts

@@ -5,6 +5,7 @@ import { rootStore } from '../store/root-store';
 /**
  * Zustand 스타일 셀렉터 — RootStore(MobX) 구독
  * 예: `useAppStore((s) => s.lastHealthAt)`, `useAppStore((s) => s.setLastHealthAt)`
+ * (프로토타입 메서드는 분리 시 this 가 깨지므로, 콜백으로 쓸 메서드는 스토어에서 화살표 필드로 두거나 `bind` 하세요.)
  */
 export function useAppStore<T>(selector: (store: typeof rootStore) => T): T {
   return useSyncExternalStore(

package/template/web/shared/src/hooks/useHealthStatus.ts

@@ -1,38 +1,34 @@
-import { useEffect, useState } from 'react';
+import { useEffect } from 'react';
 import { configureApi } from '../api/client';
 import { fetchHealth } from '../methods/health';
-import { safeJsonStringify } from '../utils/safeJsonStringify';
+import { rootStore } from '../store/root-store';
 import { useAppStore } from './useAppStore';
 
 /**
  * @param apiBaseUrl 선택 — 넘기면 `configureApi` 로 baseURL 갱신. 앱 entry 에서 이미 `configureApi` 했다면 생략 가능.
+ * `data`·`error` 는 `rootStore` 에 저장·`runInAction`; 로딩 표시는 `StoreProvider` 전역 바 + `indicator`(axios).
  */
 export function useHealthStatus(apiBaseUrl?: string) {
-  const setLastHealthAt = useAppStore((s) => s.setLastHealthAt);
-  const [text, setText] = useState('loading…');
-  const [error, setError] = useState<string | null>(null);
+  const data = useAppStore((s) => s.healthData);
+  const error = useAppStore((s) => s.healthError);
 
   useEffect(() => {
     if (apiBaseUrl != null && apiBaseUrl !== '') {
       configureApi({ baseURL: apiBaseUrl });
     }
     let cancelled = false;
-    setError(null);
-    setText('loading…');
+    rootStore.applyHealthFetchStart();
     fetchHealth()
       .then((body) => {
-        if (!cancelled) {
-          setText(safeJsonStringify(body, 2));
-          setLastHealthAt(Date.now());
-        }
+        if (!cancelled) rootStore.applyHealthFetchSuccess(body);
       })
-      .catch((e: Error) => {
-        if (!cancelled) setError(e.message);
+      .catch((e: unknown) => {
+        if (!cancelled) rootStore.applyHealthFetchFailure(e);
       });
     return () => {
       cancelled = true;
     };
-  }, [apiBaseUrl, setLastHealthAt]);
+  }, [apiBaseUrl]);
 
-  return { text, error };
+  return { data, error };
 }

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

@@ -10,7 +10,16 @@ export {
   useSessionStore,
 } from './context/StoreProvider';
 
-export { configureApi, getApiBaseUrl, setApiHooks, apiClient } from './api/client';
+export {
+  configureApi,
+  getApiBaseUrl,
+  setApiHooks,
+  apiClient,
+  CommonResponseRejectedError,
+  COMMON_RESPONSE_SUCCESS_CODE,
+  formatCommonErrorField,
+  isCommonResponsePayload,
+} from './api/client';
 export { sendRequest, type RequestTransportOptions } from './api/request';
 export type { EndpointDef, HttpMethod } from '@shared/endpoint';
 export { healthEndpoint, appMetaEndpoint, unwrapResponseData } from '@shared/endpoint';

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

@@ -1,8 +1,8 @@
 import { sendRequest } from '../api/request';
 import { healthEndpoint } from '@shared/endpoint';
-import type { CommonEnvelope, HealthData } from '../types/api';
+import type { HealthData } from '../types/api';
 
 /** 직접 호출용 (토스트 없음) — UI 훅은 보통 이 함수 사용 */
-export async function fetchHealth(): Promise<CommonEnvelope<HealthData>> {
-  return sendRequest<unknown, CommonEnvelope<HealthData>>(healthEndpoint, {});
+export async function fetchHealth(): Promise<HealthData> {
+  return sendRequest<unknown, HealthData>(healthEndpoint, {});
 }

package/template/web/shared/src/store/root-store.ts

@@ -2,8 +2,14 @@
  * Root store — session, param, cache, indicator, execute/sendMessage (business-promotion 패턴 축소판)
  */
 
+import axios from 'axios';
 import { makeAutoObservable, runInAction } from 'mobx';
 import { setApiHooks } from '../api/client';
+import {
+  CommonResponseRejectedError,
+  formatCommonErrorField,
+  isCommonResponsePayload,
+} from '../api/commonResponse';
 import { sendRequest } from '../api/request';
 import type {
   ApiMethodConfig,
@@ -23,6 +29,7 @@ import { sessionStore } from './session-store';
 import { ParamStore } from '../params/param-store';
 import type { ApiErrorItem, IndicatorState, SendMessageOptions, ToastItem } from '../types/ui';
 import type { ToastSeverity } from '../types/ui';
+import type { HealthData } from '../types/api';
 
 function genId() {
   return `id_${Date.now()}_${Math.random().toString(36).slice(2, 9)}`;
@@ -53,8 +60,14 @@ function extractMessageString(value: unknown): string | null {
 }
 
 function getErrorMessage(e: unknown): string {
-  const err = e as { response?: { data?: { message?: unknown; error?: unknown } }; message?: string };
-  const raw = err?.response?.data?.message ?? err?.response?.data?.error ?? err?.message;
+  if (e instanceof CommonResponseRejectedError) return e.message;
+  const err = e as { response?: { data?: unknown }; message?: string };
+  const resData = err?.response?.data;
+  if (isCommonResponsePayload(resData)) {
+    return formatCommonErrorField(resData.error);
+  }
+  const d = resData as { message?: unknown; error?: unknown } | undefined;
+  const raw = d?.message ?? d?.error ?? err?.message;
   const extracted = extractMessageString(raw);
   if (extracted) return extracted;
   if (raw != null && typeof raw === 'string') return raw;
@@ -77,6 +90,10 @@ export class RootStore {
   /** 데모·useHealthStatus 용 타임스탬프 */
   lastHealthAt: number | null = null;
 
+  /** `/health` 성공 본문 (axios 공통 래핑 제거 후) */
+  healthData: HealthData | null = null;
+  healthError: string | null = null;
+
   constructor() {
     makeAutoObservable(this);
     this.sessionStore.registerLogoutCallback(() => {
@@ -93,7 +110,12 @@ export class RootStore {
         if (this._multiEndpointBatch) return;
         runInAction(() => this._endRequest());
       },
-      onError: () => {},
+      onError: (message) => {
+        runInAction(() => this.addToast(message, 'error'));
+      },
+      onCommonBusinessError: (message) => {
+        runInAction(() => this.addToast(message, 'error'));
+      },
     });
   }
 
@@ -109,9 +131,31 @@ export class RootStore {
     return this._toasts;
   }
 
-  setLastHealthAt(t: number) {
+  /** useAppStore 셀렉터로 넘길 때 this 유지 */
+  setLastHealthAt = (t: number) => {
     this.lastHealthAt = t;
-  }
+  };
+
+  /** 로딩 표시는 `indicator`(axios 훅) — 여기선 에러만 초기화 */
+  applyHealthFetchStart = () => {
+    runInAction(() => {
+      this.healthError = null;
+    });
+  };
+
+  applyHealthFetchSuccess = (data: HealthData) => {
+    runInAction(() => {
+      this.healthError = null;
+      this.healthData = data;
+      this.lastHealthAt = Date.now();
+    });
+  };
+
+  applyHealthFetchFailure = (err: unknown) => {
+    runInAction(() => {
+      this.healthError = getErrorMessage(err);
+    });
+  };
 
   private _startRequest() {
     this._requestDepth++;
@@ -225,7 +269,11 @@ export class RootStore {
         }
         return result;
       } catch (e) {
-        if (showErrorToast) {
+        if (
+          showErrorToast &&
+          !(e instanceof CommonResponseRejectedError) &&
+          !axios.isAxiosError(e)
+        ) {
           runInAction(() => this.addToast(getErrorMessage(e), 'error'));
         }
         throw e;
@@ -344,7 +392,13 @@ export class RootStore {
       return data;
     } catch (e) {
       runInAction(() => {
-        if (showErrorToast) this.addToast(getErrorMessage(e), 'error');
+        if (
+          showErrorToast &&
+          !(e instanceof CommonResponseRejectedError) &&
+          !axios.isAxiosError(e)
+        ) {
+          this.addToast(getErrorMessage(e), 'error');
+        }
       });
       throw e;
     } finally {

package/template/web/shared/src/styles/app.css

@@ -67,4 +67,27 @@
   border-bottom: 1px solid var(--xfc-border-header);
 }
 
+/* apiClient 진행 중 — StoreProvider 가 `rootStore.indicator.loading` 과 연동 */
+.xfc-global-http-indicator {
+  position: fixed;
+  top: 0;
+  left: 0;
+  right: 0;
+  height: 3px;
+  z-index: 99999;
+  background: var(--xfc-accent, var(--xfc-border));
+  pointer-events: none;
+  animation: xfc-global-http-pulse 0.9s ease-in-out infinite;
+}
+
+@keyframes xfc-global-http-pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.45;
+  }
+}
+
 /* —— front-core atoms 추가 오버라이드는 xfc-theme.css 또는 여기 (app이 마지막 로드) —— */