@xfilecom/xframe 0.1.33 → 0.1.35

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

@@ -16,6 +16,9 @@ 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'));
@@ -71,6 +74,7 @@ export default defineConfig(({ mode }) => {
     resolve: {
       alias: {
         '@xfilecom/front-core': frontCoreSrc,
+        '@shared': rootSharedSrc,
         '__WEB_SHARED_WORKSPACE__': webSharedSrc,
       },
     },

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;

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

@@ -0,0 +1,65 @@
+/**
+ * EndpointDef — path `:param` 치환, query/body, skipGlobalIndicator
+ */
+
+import type { EndpointDef } from '@shared/endpoint';
+import { apiClient } from './client';
+
+function buildPath(path: string, params?: Record<string, string>): string {
+  if (!params) return path;
+  let out = path;
+  for (const [k, v] of Object.entries(params)) {
+    out = out.replace(`:${k}`, encodeURIComponent(String(v)));
+  }
+  return out;
+}
+
+function buildQuery(query?: Record<string, string | number | boolean | undefined>): string {
+  if (!query) return '';
+  const search = new URLSearchParams();
+  for (const [k, v] of Object.entries(query)) {
+    if (v !== undefined && v !== '') search.set(k, String(v));
+  }
+  const s = search.toString();
+  return s ? `?${s}` : '';
+}
+
+export interface RequestTransportOptions<T = unknown> {
+  params?: Record<string, string>;
+  query?: Record<string, string | number | boolean | undefined>;
+  body?: T;
+  skipGlobalIndicator?: boolean;
+}
+
+export async function sendRequest<T = unknown, R = unknown>(
+  endpoint: EndpointDef,
+  options: RequestTransportOptions<T> = {},
+): Promise<R> {
+  const { params, query, body, skipGlobalIndicator } = options;
+  const url = buildPath(endpoint.path, params) + buildQuery(query);
+  const config: {
+    method: string;
+    url: string;
+    data?: T;
+    skipGlobalIndicator?: boolean;
+  } = {
+    method: endpoint.method,
+    url,
+    skipGlobalIndicator,
+  };
+  if (
+    body !== undefined &&
+    (endpoint.method === 'POST' || endpoint.method === 'PUT' || endpoint.method === 'PATCH')
+  ) {
+    config.data = body;
+  }
+  const axiosConfig = {
+    ...config,
+    ...(endpoint.timeoutMs != null ? { timeout: endpoint.timeoutMs } : {}),
+  } as Parameters<typeof apiClient.request>[0];
+
+  const response = await apiClient.request<R>(axiosConfig);
+  const raw = response.data;
+  const shaped = endpoint.post ? endpoint.post(raw) : raw;
+  return shaped as R;
+}

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

@@ -0,0 +1,80 @@
+/**
+ * methods.ts / RootStore.execute — RootStore 직접 참조 없이 순환 방지
+ */
+
+import type { EndpointDef } from '@shared/endpoint';
+import type { ParamScreenSchema, ParamsSchema } from '../params/types';
+import type { ParamStore } from '../params/param-store';
+import type { SessionStore } from '../store/session-store';
+
+/** methods 콜백에서 받는 store — RootStore 가 이 형태를 만족 */
+export interface ApiMethodStore {
+  paramStore: ParamStore;
+  sessionStore: SessionStore;
+}
+
+export type { ParamsSchema, ParamScreenSchema };
+
+export type CoreSdkWrapped<T> = {
+  data?: T[] | T;
+  code?: number;
+  error?: unknown;
+  success?: boolean;
+  message?: string;
+};
+
+export interface ExecuteContext {
+  redirectTo?: string;
+  navigate?: (path: string, options?: { replace?: boolean }) => void;
+}
+
+export interface ApiMethodUiConfig {
+  indicatorMessage?: string;
+  successMessage?: string;
+  errorMessage?: string;
+  showIndicator?: boolean;
+  showSuccessToast?: boolean;
+  showErrorToast?: boolean;
+  unwrapDataArray?: boolean;
+}
+
+export type ScreenAuthType = 'guest' | 'protected';
+
+export interface ScreenMeta {
+  path: string;
+  auth: ScreenAuthType;
+  index?: boolean;
+  page: string;
+  bottomNav?: boolean;
+  label?: string;
+}
+
+export interface ApiMethodEndpointCall<TPayload = unknown, TStore = ApiMethodStore> {
+  endpoint: EndpointDef;
+  body?: (stores: TStore, payload?: TPayload) => unknown;
+  query?: (
+    stores: TStore,
+    payload?: TPayload,
+  ) => Record<string, string | number | boolean | undefined>;
+  params?: (stores: TStore, payload?: TPayload) => Record<string, string>;
+}
+
+export interface ApiMethodConfig<TPayload = unknown, TResult = unknown, TStore = ApiMethodStore> {
+  endpoint?: EndpointDef;
+  endpoints?: ApiMethodEndpointCall<TPayload, TStore>[];
+  schema: ParamScreenSchema;
+  screen?: ScreenMeta;
+  ui?: ApiMethodUiConfig;
+  body?: (stores: TStore, payload?: TPayload) => unknown;
+  query?: (
+    stores: TStore,
+    payload?: TPayload,
+  ) => Record<string, string | number | boolean | undefined>;
+  params?: (stores: TStore, payload?: TPayload) => Record<string, string>;
+  validate?: (stores: TStore, payload?: TPayload) => boolean;
+  post?: (result: TResult, stores: TStore, payload?: TPayload) => void;
+  send?: (store: TStore) => Promise<unknown> | unknown;
+  redirectPath?:
+    | string
+    | ((result: TResult, payload?: TPayload, ctx?: ExecuteContext) => string);
+}

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

@@ -0,0 +1,45 @@
+/**
+ * RootStore 컨텍스트 — useStore / useParamStore / useSendMessage 등
+ * (싱글톤 rootStore 이므로 Provider 없이도 rootStore 직접 import 가능)
+ */
+
+import React, { createContext, useCallback, useContext } from 'react';
+import type { EndpointDef } from '@shared/endpoint';
+import type { SendMessageOptions } from '../types/ui';
+import { rootStore } from '../store/root-store';
+
+type RootStoreApi = typeof rootStore;
+
+const StoreContext = createContext<RootStoreApi | null>(null);
+
+export function useStore(): RootStoreApi {
+  const ctx = useContext(StoreContext);
+  if (!ctx) throw new Error('StoreProvider is required');
+  return ctx;
+}
+
+export function StoreProvider({ children }: { children: React.ReactNode }) {
+  return <StoreContext.Provider value={rootStore}>{children}</StoreContext.Provider>;
+}
+
+export function useSendMessage() {
+  const store = useStore();
+  return useCallback(
+    function sendMessage<T = unknown, R = unknown>(endpoint: EndpointDef, options?: SendMessageOptions<T>) {
+      return store.sendMessage<T, R>(endpoint, options ?? {});
+    },
+    [store],
+  );
+}
+
+export function useParamStore() {
+  return useStore().paramStore;
+}
+
+export function useSessionStore() {
+  return useStore().sessionStore;
+}
+
+export function useRootStore(): RootStoreApi {
+  return useStore();
+}

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

@@ -0,0 +1,23 @@
+import { reaction } from 'mobx';
+import { useSyncExternalStore } from 'react';
+import { rootStore } from '../store/root-store';
+
+/**
+ * Zustand 스타일 셀렉터 — RootStore(MobX) 구독
+ * 예: `useAppStore((s) => s.lastHealthAt)`, `useAppStore((s) => s.setLastHealthAt)`
+ */
+export function useAppStore<T>(selector: (store: typeof rootStore) => T): T {
+  return useSyncExternalStore(
+    (onChange) => {
+      const dispose = reaction(
+        () => selector(rootStore),
+        () => {
+          onChange();
+        },
+      );
+      return () => dispose();
+    },
+    () => selector(rootStore),
+    () => selector(rootStore),
+  );
+}

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

@@ -1,16 +1,25 @@
 import { useEffect, useState } from 'react';
+import { configureApi } from '../api/client';
 import { fetchHealth } from '../methods/health';
 import { safeJsonStringify } from '../utils/safeJsonStringify';
-import { useAppStore } from '../stores/appStore';
+import { useAppStore } from './useAppStore';
 
-export function useHealthStatus(apiBaseUrl: string) {
+/**
+ * @param apiBaseUrl 선택 — 넘기면 `configureApi` 로 baseURL 갱신. 앱 entry 에서 이미 `configureApi` 했다면 생략 가능.
+ */
+export function useHealthStatus(apiBaseUrl?: string) {
   const setLastHealthAt = useAppStore((s) => s.setLastHealthAt);
   const [text, setText] = useState('loading…');
   const [error, setError] = useState<string | null>(null);
 
   useEffect(() => {
+    if (apiBaseUrl != null && apiBaseUrl !== '') {
+      configureApi({ baseURL: apiBaseUrl });
+    }
     let cancelled = false;
-    fetchHealth(apiBaseUrl)
+    setError(null);
+    setText('loading…');
+    fetchHealth()
       .then((body) => {
         if (!cancelled) {
           setText(safeJsonStringify(body, 2));

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

@@ -1,8 +1,60 @@
 export { Shell, type ShellProps } from './components/Shell';
 export { useHealthStatus } from './hooks/useHealthStatus';
-export { useAppStore } from './stores/appStore';
+export { useAppStore } from './hooks/useAppStore';
+export {
+  StoreProvider,
+  useStore,
+  useRootStore,
+  useSendMessage,
+  useParamStore,
+  useSessionStore,
+} from './context/StoreProvider';
+
+export { configureApi, getApiBaseUrl, setApiHooks, apiClient } from './api/client';
+export { sendRequest, type RequestTransportOptions } from './api/request';
+export type { EndpointDef, HttpMethod } from '@shared/endpoint';
+export { healthEndpoint, appMetaEndpoint, unwrapResponseData } from '@shared/endpoint';
+export type {
+  ApiMethodConfig,
+  ApiMethodStore,
+  ApiMethodEndpointCall,
+  CoreSdkWrapped,
+  ExecuteContext,
+  ApiMethodUiConfig,
+  ScreenMeta,
+  ScreenAuthType,
+} from './api/types';
+export {
+  methods,
+  screenParamSchemas,
+  type MethodName,
+} from './api/methods';
+
+export {
+  rootStore,
+  RootStore,
+  sessionStore,
+  SessionStore,
+  apiCacheStore,
+  ApiCacheStore,
+  observer,
+} from './store';
+
+/** 이전 `appStore` 싱글톤 명칭 호환 */
+export { rootStore as appStore } from './store';
+
+export { ParamStore, type ParamStoreOptions, type ParamFieldState } from './params/param-store';
+export type { ParamsSchema, ParamScreenSchema, ParamFieldDef, ValidRule } from './params/types';
+
 export { fetchHealth } from './methods/health';
 export { getJson } from './lib/http';
 export { safeJsonStringify } from './utils/safeJsonStringify';
 export { FALLBACK_API_BASE_URL } from './constants/app';
 export type { CommonEnvelope, HealthData } from './types/api';
+export type {
+  ToastSeverity,
+  ToastItem,
+  ApiErrorItem,
+  IndicatorState,
+  SendMessageOptions,
+} from './types/ui';

package/template/web/shared/src/lib/http.ts

@@ -1,7 +1,10 @@
-export async function getJson<T>(url: string, init?: RequestInit): Promise<T> {
-  const res = await fetch(url, { ...init, headers: { Accept: 'application/json', ...init?.headers } });
-  if (!res.ok) {
-    throw new Error(`HTTP ${res.status} ${res.statusText}`);
-  }
-  return res.json() as Promise<T>;
+import type { AxiosRequestConfig } from 'axios';
+import { apiClient } from '../api/client';
+
+export async function getJson<T>(url: string, config?: AxiosRequestConfig): Promise<T> {
+  const res = await apiClient.get<T>(url, {
+    ...config,
+    headers: { Accept: 'application/json', ...config?.headers },
+  });
+  return res.data;
 }

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

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