@xfilecom/xframe 0.1.35 → 0.1.37

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.15",
-  "frontCore": "^0.2.21"
+  "backendCore": "^1.0.17",
+  "frontCore": "^0.2.23"
 }

package/package.json

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

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/endpoint.ts

@@ -49,7 +49,7 @@ export const healthEndpoint: EndpointDef = {
 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/tsconfig.json

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

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

@@ -7,12 +7,6 @@ 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');
 
@@ -70,7 +64,6 @@ export default defineConfig(({ mode }) => {
     plugins: [react()],
     resolve: {
       alias: {
-        '@xfilecom/front-core': frontCoreSrc,
         '@shared': rootSharedSrc,
         '__WEB_SHARED_WORKSPACE__': webSharedSrc,
       },

package/template/web/client/tsconfig.json

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

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

@@ -7,12 +7,6 @@ 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');
 
@@ -73,7 +67,6 @@ 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/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({
@@ -104,28 +123,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/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

@@ -4,6 +4,11 @@
 
 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,
@@ -53,8 +58,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;
@@ -94,6 +105,9 @@ export class RootStore {
         runInAction(() => this._endRequest());
       },
       onError: () => {},
+      onCommonBusinessError: (message) => {
+        runInAction(() => this.addToast(message, 'error'));
+      },
     });
   }
 
@@ -225,7 +239,7 @@ export class RootStore {
         }
         return result;
       } catch (e) {
-        if (showErrorToast) {
+        if (showErrorToast && !(e instanceof CommonResponseRejectedError)) {
           runInAction(() => this.addToast(getErrorMessage(e), 'error'));
         }
         throw e;
@@ -344,7 +358,9 @@ export class RootStore {
       return data;
     } catch (e) {
       runInAction(() => {
-        if (showErrorToast) this.addToast(getErrorMessage(e), 'error');
+        if (showErrorToast && !(e instanceof CommonResponseRejectedError)) {
+          this.addToast(getErrorMessage(e), 'error');
+        }
       });
       throw e;
     } finally {